API Reference

Complete reference for all map components and their props.

Note: 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.

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

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
</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).
`styles`	`{ light?: string \| StyleSpecification; dark?: string \| StyleSpecification }`	`—`	Custom map styles for light and dark themes. Overrides the default Carto base map tiles.

useMap

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

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.
`onDrag`	`(lngLat: {lng, lat}) => void`	`—`	Callback during marker drag.
`onDragEnd`	`(lngLat: {lng, lat}) => void`	`—`	Callback when marker drag ends.

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

The className from MapLibre's PopupOptions is excluded to prevent style conflicts. Use the component's own className prop to style the popup content. MapLibre's default popup styles are reset via CSS.

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

The className from MapLibre's PopupOptions is excluded to prevent style conflicts. Use the component's own className prop to style the tooltip content. MapLibre's default popup styles are reset via CSS.

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

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

MapRoute

Renders a line/route on the map connecting coordinate points. Must be used inside Map.

Prop	Type	Default	Description
`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.

PreviousInstallation NextBasic Map