Child components

MapContainer required

Child components can only be used as decendants of a MapContainer component.

Props

Child components in React Leaflet use their props as options when creating the corresponding Leaflet instance, as described in Leaflet's documentation.

By default these props should be treated as immutable, only the props explicitely documented as mutable in this page will affect the Leaflet element when changed.

Behaviors

Child components in React Leaflet support common behaviors described below, implementing logic related to React or Leaflet.

Referenceable behavior

Makes the Leaflet instance for the given component accessible with the useRef() hook.

function MyComponent() {
const circleRef = useRef()
useEffect(() => {
const radius = circleRef.current.getRadius()
})
return <Circle ref={cicleRef} center={[50.5, 30.5]} radius={200} />
}

ParentComponent behavior

The component will render its mutable React children components, based on the children?: ReactNode prop.

<Marker position={[50.5, 30.5]}>
<Popup>Hello world</Popup>
</Marker>

Evented behavior

Adds support for the eventHandlers?: LeafletEventHandlerFnMap prop, adding and removing event listeners.

<Marker
position={[50.5, 30.5]}
eventHandlers={{
click: () => {
console.log('marker clicked')
},
}}
/>

Attribution behavior

Applies to layer components, making their attribution prop mutable.

<GeoJSON attribution="&copy; credits due..." data={...} />

Pane behavior

Applies to layer components, adding support for the pane prop or context from a Pane component ancestor.

<Circle center={[50.5, 30.5]} radius={200} pane="my-existing-pane" />
<Pane name="custom" style={{ zIndex: 100 }}>
<Circle center={[50.5, 30.5]} radius={200} />
</Pane>

Path behavior

Applies to vector layer components, adding support for a pathOptions: PathOptions mutable prop.

<Circle center={[50.5, 30.5]} radius={200} pathOptions={{ color: 'blue' }} />

MediaOverlay behavior

Applies to components using Leaflet's ImageOverlay class, adding support for mutable bounds: LatLngBoundsExpression, opacity: number and zIndex: number props.

<ImageOverlay
url="http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg"
bounds={[
[40.712216, -74.22655],
[40.773941, -74.12544],
]}
opacity={0.5}
zIndex={10}
/>

CircleMarker behavior

Applies to components using Leaflet's CircleMarker class, adding support for mutable center: LatLngExpression and radius: number props.

<Circle center={[50.5, 30.5]} radius={200} />

GridLayer behavior

Applies to components using Leaflet's GridLayer class, adding support for mutable opacity: number and zIndex: number props.

<TileLayer url="..." opacity={0.5} zIndex={10} />

Control behavior

Applies to control components, making their position: ControlPosition prop mutable.

<ZoomControl position="bottomleft" />

UI layers

Marker

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
draggablebooleanNoYes
eventHandlersLeafletEventHandlerFnMapNoYesEvented
iconLeaflet.IconNoYes
opacitynumberNoYes
panestringNoNoPane
positionLatLngExpressionYesYes
refRefObject<Leaflet.Marker>NoYesReferenceable
zIndexOffsetnumberNoYes

Popup

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
onClose() => voidNoYes
onOpen() => voidNoYes
panestringNoNoPane
positionLatLngExpressionNoYes
refRefObject<Leaflet.Popup>NoYesReferenceable

Tooltip

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
onClose() => voidNoYes
onOpen() => voidNoYes
panestringNoNoPane
positionLatLngExpressionNoYes
refRefObject<Leaflet.Tooltip>NoYesReferenceable

Raster layers

TileLayer

Leaflet reference

Props

PropTypeRequiredMutableBehavior
eventHandlersLeafletEventHandlerFnMapNoYesEvented
opacitynumberNoYesGridLayer
panestringNoNoPane
refRefObject<Leaflet.TileLayer>NoYesReferenceable
urlstringYesNo
zIndexnumberNoYesGridLayer

WMSTileLayer

Leaflet reference

Props

PropTypeRequiredMutableBehavior
eventHandlersLeafletEventHandlerFnMapNoYesEvented
opacitynumberNoYesGridLayer
panestringNoNoPane
paramsWMSParamsNoYes
refRefObject<Leaflet.TileLayer.WMS>NoYesReferenceable
urlstringYesNo
zIndexnumberNoYesGridLayer

ImageOverlay

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
boundsLatLngBoundsExpressionYesYesMediaOverlay
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
opacitynumberNoYesMediaOverlay
refRefObject<Leaflet.ImageOverlay>NoYesReferenceable
urlstringYesYes
zIndexnumberNoYesMediaOverlay

VideoOverlay

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
boundsLatLngBoundsExpressionYesYesMediaOverlay
eventHandlersLeafletEventHandlerFnMapNoYesEvented
playbooleanNoYes
refRefObject<Leaflet.VideoOverlay>NoYesReferenceable
urlstring, string[] or HTMLVideoElementYesYes
zIndexnumberNoYesMediaOverlay

Vector layers

Circle

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
centerLatLngExpressionYesYes
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
pathOptionsPathOptionsNoYesPath
radiusnumberYesYes
refRefObject<Leaflet.Circle>NoYesReferenceable

CircleMarker

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
centerLatLngExpressionYesYes
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
pathOptionsPathOptionsNoYesPath
radiusnumberYesYes
refRefObject<Leaflet.CircleMarker>NoYesReferenceable

Polyline

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
pathOptionsPathOptionsNoYesPath
positionsLatLngExpression[] or LatLngExpression[][]YesYes
refRefObject<Leaflet.Polyline>NoYesReferenceable

Polygon

Leaflet reference

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
pathOptionsPathOptionsNoYesPath
positionsLatLngExpression[], LatLngExpression[][] or LatLngExpression[][][]YesYes
refRefObject<Leaflet.Polygon>NoYesReferenceable

Rectangle

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
boundsLatLngBoundsExpressionYesYes
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
pathOptionsPathOptionsNoYesPath
refRefObject<Leaflet.Rectangle>NoYesReferenceable

SVGOverlay

Leaflet reference

Props

The attributes must be valid SVGSVGElement properties.

PropTypeRequiredMutableBehavior
attributesRecord<string, string>NoNo
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
panestringNoNoPane
refRefObject<Leaflet.SVGOverlay>NoYesReferenceable

Other layers

LayerGroup

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
refRefObject<Leaflet.LayerGroup>NoYesReferenceable

FeatureGroup

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
refRefObject<Leaflet.FeatureGroup>NoYesReferenceable

GeoJSON

Leaflet reference

Props

PropTypeRequiredMutableBehavior
attributionstringNoYesAttribution
childrenReactNodeNoYesParentComponent
dataGeoJsonObjectYesNo
eventHandlersLeafletEventHandlerFnMapNoYesEvented
panestringNoNoPane
refRefObject<Leaflet.GeoJSON>NoYesReferenceable

Controls

ZoomControl

Leaflet reference

Props

PropTypeRequiredMutableBehavior
eventHandlersLeafletEventHandlerFnMapNoYesEvented
positionControlPositionNoYes
refRefObject<Leaflet.Control.Zoom>NoYesReferenceable

AttributionControl

Leaflet reference

Props

PropTypeRequiredMutableBehavior
eventHandlersLeafletEventHandlerFnMapNoYesEvented
positionControlPositionNoYes
refRefObject<Leaflet.Control.Attribution>NoYesReferenceable

LayersControl

Leaflet reference

Props

PropTypeRequiredMutableBehavior
collapsedbooleanNoYes
eventHandlersLeafletEventHandlerFnMapNoYesEvented
positionControlPositionNoYes
refRefObject<Leaflet.Control.Layers>NoYesReferenceable

LayersControl.BaseLayer

Props

PropTypeRequiredMutableBehavior
checkedbooleanNoYes
childrenReactNodeNoYesParentComponent
namestringYesNo

LayersControl.Overlay

Props

PropTypeRequiredMutableBehavior
checkedbooleanNoYes
childrenReactNodeNoYesParentComponent
namestringYesNo

ScaleControl

Leaflet reference

Props

PropTypeRequiredMutableBehavior
eventHandlersLeafletEventHandlerFnMapNoYesEvented
positionControlPositionNoYes
refRefObject<Leaflet.Control.ScaleNoYesReferenceable

Other

Pane

Leaflet reference

Props

caution

The name prop must be unique to the pane and different from the default Leaflet pane names

PropTypeRequiredMutableBehavior
childrenReactNodeNoYesParentComponent
classNamestringNoNo
namestringYesNo
panestringNoNoPane
styleCSSPropertiesNoNo