Version: v3.x

Child components

MapContainer required

Child components can only be used as descendants 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: LatLngBounds, opacity: number and zIndex: number props.

const bounds = new LatLngBounds([40.712216, -74.22655], [40.773941, -74.12544])

<ImageOverlay
  url="http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg"
  bounds={bounds}
  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" />

Prop	Type	Required	Mutable	Behavior
`attribution`	`string`	No	Yes	Attribution
`children`	`ReactNode`	No	Yes	ParentComponent
`draggable`	`boolean`	No	Yes
`eventHandlers`	`LeafletEventHandlerFnMap`	No	Yes	Evented
`icon`	`Leaflet.Icon`	No	Yes
`opacity`	`number`	No	Yes
`pane`	`string`	No	No	Pane
`position`	`LatLngExpression`	Yes	Yes
`ref`	`RefObject<Leaflet.Marker>`	No	Yes	Referenceable
`zIndexOffset`	`number`	No	Yes

Prop	Type	Required	Mutable	Behavior
`attributes`	`Record<string, string>`	No	No
`attribution`	`string`	No	Yes	Attribution
`children`	`ReactNode`	No	Yes	ParentComponent
`pane`	`string`	No	No	Pane
`ref`	`RefObject<Leaflet.SVGOverlay>`	No	Yes	Referenceable

Prop	Type	Required	Mutable	Behavior
`collapsed`	`boolean`	No	Yes
`eventHandlers`	`LeafletEventHandlerFnMap`	No	Yes	Evented
`position`	`ControlPosition`	No	Yes
`ref`	`RefObject<Leaflet.Control.Layers>`	No	Yes	Referenceable

Prop	Type	Required	Mutable	Behavior
`checked`	`boolean`	No	Yes
`children`	`ReactNode`	No	Yes	ParentComponent
`name`	`string`	Yes	No

Props​

Behaviors​

Referenceable behavior​

ParentComponent behavior​

Evented behavior​

Attribution behavior​

Pane behavior​

Path behavior​

MediaOverlay behavior​

CircleMarker behavior​

GridLayer behavior​

Control behavior​

UI layers​

Marker​

Popup​

Tooltip​

Raster layers​

TileLayer​

WMSTileLayer​

ImageOverlay​

VideoOverlay​

Vector layers​

Circle​

CircleMarker​

Polyline​

Polygon​

Rectangle​

SVGOverlay​

Other layers​

LayerGroup​

FeatureGroup​

GeoJSON​

Controls​

ZoomControl​

AttributionControl​

LayersControl​

LayersControl.BaseLayer​

LayersControl.Overlay​

ScaleControl​

Other​

Pane​

Props

Behaviors

Referenceable behavior

ParentComponent behavior

Evented behavior

Attribution behavior

Pane behavior

Path behavior

MediaOverlay behavior

CircleMarker behavior

GridLayer behavior

Control behavior

UI layers

Marker

Popup

Tooltip

Raster layers

TileLayer

WMSTileLayer

ImageOverlay

VideoOverlay

Vector layers

Circle

CircleMarker

Polyline

Polygon

Rectangle

SVGOverlay

Other layers

LayerGroup

FeatureGroup

GeoJSON

Controls

ZoomControl

AttributionControl

LayersControl

LayersControl.BaseLayer

LayersControl.Overlay

ScaleControl

Other

Pane