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>>