API Reference

Complete reference for all map components and their props.

This library is built on top of MapLibre GL JS. Most components extend the native MapLibre options. Refer to the MapLibre Map API for additional options not listed here.

Component Anatomy

All parts of the component that you can use and combine to build your map.

TypeScript

<Map>
  <MapMarker longitude={...} latitude={...}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
  <MapClusterLayer data={...} />
</Map>

Map

The root container component that initializes MapLibre GL and provides context to child components. Automatically handles theme switching between light and dark modes.

Extends MapOptions from MapLibre GL (excluding container and style).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Child components (markers, popups, controls, routes).
`theme`	`"light" \| "dark"`	`—`	Theme for the map. If not provided, automatically detects from document class or system preference.
`styles`	`{ light?: string \| StyleSpecification; dark?: string \| StyleSpecification }`	`—`	Custom map styles for light and dark themes. Overrides the default Carto base map tiles.
`projection`	`ProjectionSpecification`	`—`	Map projection type. Use { type: "globe" } for 3D globe view.

useMap

A hook that provides access to the MapLibre map instance and loading state. Must be used within a Map component.

TypeScript

const { map, isLoaded } = useMap();

Returns map (MapLibre.Map) and isLoaded (boolean) tells you if the map is loaded and ready to use.

MapControls

Renders map control buttons (zoom, compass, locate, fullscreen). Must be used inside Map.

Prop	Type	Default	Description
`position`	`"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`	`"bottom-right"`	Position of the controls on the map.
`showZoom`	`boolean`	`true`	Show zoom in/out buttons.
`showCompass`	`boolean`	`false`	Show compass button to reset bearing.
`showLocate`	`boolean`	`false`	Show locate button to find user's location.
`showFullscreen`	`boolean`	`false`	Show fullscreen toggle button.
`className`	`string`	`—`	Additional CSS classes for the controls container.
`onLocate`	`(coords: { longitude: number; latitude: number }) => void`	`—`	Callback with user coordinates when located.

MapMarker

A container for marker-related components. Provides context for its children and handles marker positioning.

Extends MarkerOptions from MapLibre GL (excluding element).

Prop	Type	Default	Description
`longitude`	`number`	`—`	Longitude coordinate for marker position.
`latitude`	`number`	`—`	Latitude coordinate for marker position.
`children`	`ReactNode`	`—`	Marker subcomponents (MarkerContent, MarkerPopup, etc).
`onClick`	`(e: MouseEvent) => void`	`—`	Callback when marker is clicked.
`onMouseEnter`	`(e: MouseEvent) => void`	`—`	Callback when mouse enters marker.
`onMouseLeave`	`(e: MouseEvent) => void`	`—`	Callback when mouse leaves marker.
`onDragStart`	`(lngLat: {lng, lat}) => void`	`—`	Callback when marker drag starts (requires draggable: true).
`onDrag`	`(lngLat: {lng, lat}) => void`	`—`	Callback during marker drag (requires draggable: true).
`onDragEnd`	`(lngLat: {lng, lat}) => void`	`—`	Callback when marker drag ends (requires draggable: true).

MarkerContent

Renders the visual content of a marker. Must be used inside MapMarker. If no children provided, renders a default blue dot marker.

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Custom marker content. Defaults to a blue dot.
`className`	`string`	`—`	Additional CSS classes for the marker container.

MarkerPopup

Renders a popup attached to the marker that opens on click. Must be used inside MapMarker.

Extends PopupOptions from MapLibre GL (excluding className and closeButton).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Popup content.
`className`	`string`	`—`	Additional CSS classes for the popup container.
`closeButton`	`boolean`	`false`	Show a close button in the popup.

MarkerTooltip

Renders a tooltip that appears on hover. Must be used inside MapMarker.

Extends PopupOptions from MapLibre GL (excluding className, closeButton, and closeOnClick as tooltips auto-dismiss on hover out).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Tooltip content.
`className`	`string`	`—`	Additional CSS classes for the tooltip container.

MarkerLabel

Renders a text label above or below the marker. Must be used inside MarkerContent.

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Label text content.
`className`	`string`	`—`	Additional CSS classes for the label.
`position`	`"top" \| "bottom"`	`"top"`	Position of the label relative to the marker.

MapPopup

A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside Map.

Extends PopupOptions from MapLibre GL (excluding className and closeButton).

Prop	Type	Default	Description
`longitude`	`number`	`—`	Longitude coordinate for popup position.
`latitude`	`number`	`—`	Latitude coordinate for popup position.
`onClose`	`() => void`	`—`	Callback when popup is closed.
`children`	`ReactNode`	`—`	Popup content.
`className`	`string`	`—`	Additional CSS classes for the popup container.
`closeButton`	`boolean`	`false`	Show a close button in the popup.

MapRoute

Renders a line/route on the map connecting coordinate points. Must be used inside Map. Supports click and hover interactions for building route selection UIs.

Prop	Type	Default	Description
`id`	`string`	`undefined (auto-generated)`	Optional unique identifier for the route layer. Auto-generated if not provided.
`coordinates`	`[number, number][]`	`—`	Array of [longitude, latitude] coordinate pairs.
`color`	`string`	`"#4285F4"`	Line color (CSS color value).
`width`	`number`	`3`	Line width in pixels.
`opacity`	`number`	`0.8`	Line opacity (0 to 1).
`dashArray`	`[number, number]`	`—`	Dash pattern [dash length, gap length] for dashed lines.
`onClick`	`() => void`	`—`	Callback when the route line is clicked.
`onMouseEnter`	`() => void`	`—`	Callback when mouse enters the route line.
`onMouseLeave`	`() => void`	`—`	Callback when mouse leaves the route line.
`interactive`	`boolean`	`true`	Whether the route is interactive (shows pointer cursor on hover).

MapClusterLayer

Renders clustered point data using MapLibre GL's native clustering. Automatically groups nearby points into clusters that expand on click. Must be used inside Map. Supports a generic type parameter for typed feature properties: MapClusterLayer<MyProperties>.

Prop	Type	Default	Description
`data`	`string \| GeoJSON.FeatureCollection`	`—`	GeoJSON FeatureCollection data or URL to fetch GeoJSON from.
`clusterMaxZoom`	`number`	`14`	Maximum zoom level to cluster points on.
`clusterRadius`	`number`	`50`	Radius of each cluster when clustering points (in pixels).
`clusterColors`	`[string, string, string]`	`["#51bbd6", "#f1f075", "#f28cb1"]`	Colors for cluster circles: [small, medium, large] based on point count.
`clusterThresholds`	`[number, number]`	`[100, 750]`	Point count thresholds for color/size steps: [medium, large].
`pointColor`	`string`	`"#3b82f6"`	Color for unclustered individual points.
`onPointClick`	`(feature: GeoJSON.Feature, coordinates: [number, number]) => void`	`—`	Callback when an unclustered point is clicked.
`onClusterClick`	`(clusterId: number, coordinates: [number, number], pointCount: number) => void`	`—`	Callback when a cluster is clicked. If not provided, zooms into the cluster.

API Reference

Complete reference for all map components and their props.

This library is built on top of MapLibre GL JS. Most components extend the native MapLibre options. Refer to the MapLibre Map API for additional options not listed here.

Component Anatomy

All parts of the component that you can use and combine to build your map.

TypeScript

<Map>
  <MapMarker longitude={...} latitude={...}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
  <MapClusterLayer data={...} />
</Map>

Map

The root container component that initializes MapLibre GL and provides context to child components. Automatically handles theme switching between light and dark modes.

Extends MapOptions from MapLibre GL (excluding container and style).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Child components (markers, popups, controls, routes).
`theme`	`"light" \| "dark"`	`—`	Theme for the map. If not provided, automatically detects from document class or system preference.
`styles`	`{ light?: string \| StyleSpecification; dark?: string \| StyleSpecification }`	`—`	Custom map styles for light and dark themes. Overrides the default Carto base map tiles.
`projection`	`ProjectionSpecification`	`—`	Map projection type. Use { type: "globe" } for 3D globe view.

useMap

A hook that provides access to the MapLibre map instance and loading state. Must be used within a Map component.

TypeScript

const { map, isLoaded } = useMap();

Returns map (MapLibre.Map) and isLoaded (boolean) tells you if the map is loaded and ready to use.

MapControls

Renders map control buttons (zoom, compass, locate, fullscreen). Must be used inside Map.

Prop	Type	Default	Description
`position`	`"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`	`"bottom-right"`	Position of the controls on the map.
`showZoom`	`boolean`	`true`	Show zoom in/out buttons.
`showCompass`	`boolean`	`false`	Show compass button to reset bearing.
`showLocate`	`boolean`	`false`	Show locate button to find user's location.
`showFullscreen`	`boolean`	`false`	Show fullscreen toggle button.
`className`	`string`	`—`	Additional CSS classes for the controls container.
`onLocate`	`(coords: { longitude: number; latitude: number }) => void`	`—`	Callback with user coordinates when located.

MapMarker

A container for marker-related components. Provides context for its children and handles marker positioning.

Extends MarkerOptions from MapLibre GL (excluding element).

Prop	Type	Default	Description
`longitude`	`number`	`—`	Longitude coordinate for marker position.
`latitude`	`number`	`—`	Latitude coordinate for marker position.
`children`	`ReactNode`	`—`	Marker subcomponents (MarkerContent, MarkerPopup, etc).
`onClick`	`(e: MouseEvent) => void`	`—`	Callback when marker is clicked.
`onMouseEnter`	`(e: MouseEvent) => void`	`—`	Callback when mouse enters marker.
`onMouseLeave`	`(e: MouseEvent) => void`	`—`	Callback when mouse leaves marker.
`onDragStart`	`(lngLat: {lng, lat}) => void`	`—`	Callback when marker drag starts (requires draggable: true).
`onDrag`	`(lngLat: {lng, lat}) => void`	`—`	Callback during marker drag (requires draggable: true).
`onDragEnd`	`(lngLat: {lng, lat}) => void`	`—`	Callback when marker drag ends (requires draggable: true).

MarkerContent

Renders the visual content of a marker. Must be used inside MapMarker. If no children provided, renders a default blue dot marker.

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Custom marker content. Defaults to a blue dot.
`className`	`string`	`—`	Additional CSS classes for the marker container.

MarkerPopup

Renders a popup attached to the marker that opens on click. Must be used inside MapMarker.

Extends PopupOptions from MapLibre GL (excluding className and closeButton).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Popup content.
`className`	`string`	`—`	Additional CSS classes for the popup container.
`closeButton`	`boolean`	`false`	Show a close button in the popup.

MarkerTooltip

Renders a tooltip that appears on hover. Must be used inside MapMarker.

Extends PopupOptions from MapLibre GL (excluding className, closeButton, and closeOnClick as tooltips auto-dismiss on hover out).

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Tooltip content.
`className`	`string`	`—`	Additional CSS classes for the tooltip container.

MarkerLabel

Renders a text label above or below the marker. Must be used inside MarkerContent.

Prop	Type	Default	Description
`children`	`ReactNode`	`—`	Label text content.
`className`	`string`	`—`	Additional CSS classes for the label.
`position`	`"top" \| "bottom"`	`"top"`	Position of the label relative to the marker.

MapPopup

A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside Map.

Extends PopupOptions from MapLibre GL (excluding className and closeButton).

Prop	Type	Default	Description
`longitude`	`number`	`—`	Longitude coordinate for popup position.
`latitude`	`number`	`—`	Latitude coordinate for popup position.
`onClose`	`() => void`	`—`	Callback when popup is closed.
`children`	`ReactNode`	`—`	Popup content.
`className`	`string`	`—`	Additional CSS classes for the popup container.
`closeButton`	`boolean`	`false`	Show a close button in the popup.

MapRoute

Renders a line/route on the map connecting coordinate points. Must be used inside Map. Supports click and hover interactions for building route selection UIs.

Prop	Type	Default	Description
`id`	`string`	`undefined (auto-generated)`	Optional unique identifier for the route layer. Auto-generated if not provided.
`coordinates`	`[number, number][]`	`—`	Array of [longitude, latitude] coordinate pairs.
`color`	`string`	`"#4285F4"`	Line color (CSS color value).
`width`	`number`	`3`	Line width in pixels.
`opacity`	`number`	`0.8`	Line opacity (0 to 1).
`dashArray`	`[number, number]`	`—`	Dash pattern [dash length, gap length] for dashed lines.
`onClick`	`() => void`	`—`	Callback when the route line is clicked.
`onMouseEnter`	`() => void`	`—`	Callback when mouse enters the route line.
`onMouseLeave`	`() => void`	`—`	Callback when mouse leaves the route line.
`interactive`	`boolean`	`true`	Whether the route is interactive (shows pointer cursor on hover).

MapClusterLayer

Prop	Type	Default	Description
`data`	`string \| GeoJSON.FeatureCollection`	`—`	GeoJSON FeatureCollection data or URL to fetch GeoJSON from.
`clusterMaxZoom`	`number`	`14`	Maximum zoom level to cluster points on.
`clusterRadius`	`number`	`50`	Radius of each cluster when clustering points (in pixels).
`clusterColors`	`[string, string, string]`	`["#51bbd6", "#f1f075", "#f28cb1"]`	Colors for cluster circles: [small, medium, large] based on point count.
`clusterThresholds`	`[number, number]`	`[100, 750]`	Point count thresholds for color/size steps: [medium, large].
`pointColor`	`string`	`"#3b82f6"`	Color for unclustered individual points.
`onPointClick`	`(feature: GeoJSON.Feature, coordinates: [number, number]) => void`	`—`	Callback when an unclustered point is clicked.
`onClusterClick`	`(clusterId: number, coordinates: [number, number], pointCount: number) => void`	`—`	Callback when a cluster is clicked. If not provided, zooms into the cluster.