Skip to main content
Version: v5.x (next)

Core API

Interfaces and types​

ControlledLayer​

type ControlledLayer = {
  addLayer(layer: Layer): void
  removeLayer(layer: Layer): void
}

LeafletContextInterface​

type LeafletContextInterface = Readonly<{
  map: Map
  layerContainer?: ControlledLayer | LayerGroup
  layersControl?: Control.Layers
  overlayContainer?: Layer
  pane?: string
}>

LeafletElement​

type LeafletElement<T, C = any> = Readonly<{
  instance: T
  context: LeafletContextInterface
  container?: C | null
}>

ElementHook​

type ElementHook<E, P> = (
  props: P,
  context: LeafletContextInterface,
) => MutableRefObject<LeafletElement<E>>

DivOverlay​

type DivOverlay = Popup | Tooltip

SetOpenFunc​

type SetOpenFunc = (open: boolean) => void

DivOverlayLifecycleHook​

type DivOverlayLifecycleHook<E, P> = (
  element: LeafletElement<E>,
  context: LeafletContextInterface,
  props: P,
  setOpen: SetOpenFunc,
) => void

DivOverlayHook​

type DivOverlayHook<E extends DivOverlay, P> = (
  useElement: ElementHook<E, P>,
  useLifecycle: DivOverlayLifecycleHook<E, P>,
) => (props: P, setOpen: SetOpenFunc) => ReturnType<ElementHook<E, P>>

EventedProps​

type EventedProps = {
  eventHandlers?: LeafletEventHandlerFnMap
}

LayerProps​

interface LayerProps extends EventedProps, LayerOptions {}

PathProps​

interface PathProps extends EventedProps {
  pathOptions?: PathOptions
}

CircleMarkerProps​

interface CircleMarkerProps extends CircleMarkerOptions, PathProps {
  center: LatLngExpression
  children?: ReactNode
}

MediaOverlayProps​

interface MediaOverlayProps extends ImageOverlayOptions, EventedProps {
  bounds: LatLngBoundsExpression
}

PropsWithChildren​

type PropsWithChildren = {
  children?: ReactNode
}

EventedWithChildrenProps​

interface EventedWithChildrenProps extends EventedProps, PropsWithChildren {}

PathWithChildrenProps​

interface PathWithChildrenProps extends PathProps, PropsWithChildren {}

Utilities​

createElementObject​

Type parameters

  1. T: Leaflet's element class type
  2. C = any: the element's container, if relevant

Arguments

  1. instance: t
  2. context: LeafletContextInterface
  3. container?: C

Returns LeafletElement<T, C>

extendContext​

Arguments

  1. source: LeafletContextInterface
  2. extra: Partial<LeafletContextInterface>

Returns LeafletContextInterface

Context​

LeafletContext​

React Context used by React Leaflet, implementing the LeafletContextInterface

createLeafletContext​

Arguments

  1. map: Map

Returns LeafletContextInterface

useLeafletContext​

React Hook returning the LeafletContext. Calling this hook will throw an error if the context is not provided.

Hook factories​

The following functions return React hooks for specific purposes.

createElementHook​

Type parameters

  1. E: Leaflet's element class type
  2. P: the component's props
  3. C = any: the element's container, if relevant

Arguments

  1. createElement: (props: P, context: LeafletContextInterface) => LeafletElement<E>
  2. updateElement?: (instance: E, props: P, prevProps: P) => void

Returns ElementHook<E, P>

createControlHook​

Type parameters

  1. E extends Control: Leaflet's element class type
  2. P extends ControlOptions: the component's props

Arguments

  1. useElement: ElementHook<E, P>

Returns ElementHook<E, P>

createDivOverlayHook​

Type parameters

  1. E extends DivOverlay: Leaflet's element class type
  2. P extends EventedProps: the component's props

Arguments

  1. useElement: ElementHook<E, P>
  2. useLifecycle: DivOverlayLifecycleHook<E, P>

Returns ElementHook<E, P>

createLayerHook​

Type parameters

  1. E extends Layer: Leaflet's element class type
  2. P extends LayerProps: the component's props

Arguments

  1. useElement: ElementHook<E, P>

Returns ElementHook<E, P>

createPathHook​

Type parameters

  1. E extends FeatureGroup | Path: Leaflet's element class type
  2. P extends PathProps: the component's props

Arguments

  1. useElement: ElementHook<E, P>

Returns ElementHook<E, P>

Lifecycle hooks​

These hooks implement specific pieces of logic used by multiple components.

useEventHandlers​

This hook adds support for the eventHandlers prop, adding and removing event listeners as needed.

Arguments

  1. element: LeafletElement<Evented>
  2. eventHandlers: LeafletEventHandlerFnMap | null | undefined

Returns void

useLayerLifecycle​

This hook adds support for adding and removing the layer to/from its parent container or the map.

Arguments

  1. element: LeafletElement<Layer>
  2. context: LeafletContextInterface

Returns void

usePathOptions​

This hook adds support for the pathOptions prop, updating the layer as needed.

Arguments

  1. element: LeafletElement<FeatureGroup | Path>
  2. props: PathProps

Returns void

Update functions​

Shared update logic for different components.

updateCircle​

Updates the circle's center and radius if the props change.

Type parameters

  1. E extends CircleMarker: Leaflet's element class type
  2. P extends CircleMarkerProps: the component's props

Arguments

  1. layer: E
  2. props: P
  3. prevProps: P

Returns void

updateGridLayer​

Updates the layer's opacity and zIndex if the props change.

Type parameters

  1. E extends GridLayer: Leaflet's element class type
  2. P extends GridLayerOptions: the component's props

Arguments

  1. layer: E
  2. props: P
  3. prevProps: P

Returns void

updateMediaOverlay​

Updates the overlay's bounds, opacity and zIndex if the props change.

Type parameters

  1. E extends ImageOverlay | SVGOverlay | VideoOverlay: Leaflet's element class type
  2. P extends MediaOverlayProps: the component's props

Arguments

  1. overlay: E
  2. props: P
  3. prevProps: P

Returns void

DOM interactions​

Utility functions to change the class of a HTMLElement.

addClassName​

Arguments

  1. element: HTMLElement
  2. className: string

Returns void

removeClassName​

Arguments

  1. element: HTMLElement
  2. className: string

Returns void

updateClassName​

Arguments

  1. element?: HTMLElement
  2. prevClassName?: string
  3. nextClassName?: string

Returns void

Component factories​

These functions create components from the provided element hook.

createContainerComponent​

Type parameters

  1. E: Leaflet's element class type
  2. P extends PropsWithChildren: the component's props

Arguments

  1. useElement: ElementHook<E, P>

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createDivOverlayComponent​

Type parameters

  1. E extends DivOverlay: Leaflet's element class type
  2. P extends PropsWithChildren: the component's props

Arguments

  1. useElement: ReturnType<DivOverlayHook<E, P>>

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createLeafComponent​

Type parameters

  1. E: Leaflet's element class type
  2. P: the component's props

Arguments

  1. useElement: ElementHook<E, P>

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

High-level component factories​

These functions combine hooks and component factories to provide high-level factories for common component types.

createControlComponent​

Type parameters

  1. E extends Control: Leaflet's element class type
  2. P extends ControlOptions: the component's props

Arguments

  1. createInstance: (props: P) => E

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createLayerComponent​

Type parameters

  1. E extends Layer: Leaflet's element class type
  2. P extends EventedWithChildrenProps: the component's props

Arguments

  1. createElement: (props: P, context: LeafletContextInterface) => LeafletElement<E>
  2. updateElement?: (instance: E, props: P, prevProps: P) => void

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createOverlayComponent​

Type parameters

  1. E extends DivOverlay: Leaflet's element class type
  2. P extends EventedWithChildrenProps: the component's props

Arguments

  1. createElement: (props: P, context: LeafletContextInterface) => LeafletElement<E>
  2. useLifecycle: DivOverlayLifecycleHook<E, P>

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createPathComponent​

Type parameters

  1. E extends FeatureGroup | Path: Leaflet's element class type
  2. P extends PathWithChildrenProps: the component's props

Arguments

  1. createElement: (props: P, context: LeafletContextInterface) => LeafletElement<E>
  2. updateElement?: (instance: E, props: P, prevProps: P) => void

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>

createTileLayerComponent​

Type parameters

  1. E extends Layer: Leaflet's element class type
  2. P extends EventedProps: the component's props

Arguments

  1. createElement: (props: P, context: LeafletContextInterface) => LeafletElement<E>
  2. updateElement?: (instance: E, props: P, prevProps: P) => void

Returns ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<E>>