Reference

Complete reference for all map components and their props.

Tip: This library is built on top of Mapbox GL JS. Most components extend the native Mapbox options. Refer to the Mapbox Map API for additional configuration options.

Component Anatomy

All components you can use and combine to build your map.

<Map>
  {/* Markers */}
  <MapMarker coordinates={[lng, lat]}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  {/* Popup */}
  <MapPopup coordinates={[lng, lat]} />

  {/* Controls */}
  <MapControls position="bottom-right">
    <MapZoom />
    <MapOrientation />
    <MapGeolocate />
    <MapFullscreen />
  </MapControls>

  {/* Features */}
  <MapMiniMap />
  <MapLine coordinates={[[lng, lat], ...]} />
  <MapPolygon coordinates={[[lng, lat], ...]} />
  <MapLineAnimated id="route" path={[[lng, lat], ...]} />
  <MapLineRadial id="radial" origin={[lng, lat]} destinations={[[lng, lat], ...]} />
  <MapArcAnimated id="arc" origin={[lng, lat]} destination={[lng, lat]} />
  <MapAnimatedPolygon id="zone" coordinates={[[lng, lat], ...]} />
  <MapCircleCluster data={geoJsonData} />
  <MapAnimatedPulse id="pulse" size={100} coordinates={[lng, lat]} />
  <MapImage id="overlay" url="..." coordinates={[...]} />
  <MapRasterVideo id="video" urls={[...]} coordinates={[...]} />
  <MapBlurArea coordinates={[[lng, lat], ...]} />
  <MapRain />
</Map>

Map

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

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

Prop	Type	Default	Description
`accessToken`	`string`	`—`	Mapbox access token. Required.
`children`	`ReactNode`	`—`	Child components (markers, popups, controls, features).
`center`	`[number, number]`	`[0, 0]`	Initial map center [longitude, latitude].
`zoom`	`number`	`2`	Initial zoom level.
`bearing`	`number`	`0`	Map bearing (rotation) in degrees.
`pitch`	`number`	`0`	Map pitch (tilt) in degrees.
`projection`	`string`	`"mercator"`	Map projection: mercator, globe, albers, equalEarth, equirectangular, lambertConformalConic, naturalEarth, winkelTripel.
`style`	`string`	`—`	Map style URL (e.g., 'mapbox://styles/mapbox/streets-v12'). Overrides theme-based styles.
`styles`New	`MapThemeStyles`	`defaultMapStyles`	Theme-aware styles object. Use presets: defaultMapStyles, standardMapStyles, streetsMapStyles, outdoorsMapStyles, satelliteMapStyles, navigationMapStyles.
`minZoom`	`number`	`0`	Minimum zoom level constraint.
`maxZoom`	`number`	`22`	Maximum zoom level constraint.
`maxBounds`	`[[number, number], [number, number]]`	`—`	Restrict map panning to a geographic area [southwest, northeast].
`loader`	`ReactNode`	`—`	Custom loading component shown while map initializes.
`showLoader`New	`boolean`	`—`	Controls loader visibility. When true, forces loader. When false, hides. When undefined, uses internal loading state.
`autoRotate`New	`boolean`	`false`	Enables automatic rotation. Only works with projection="globe".
`rotateSpeed`New	`number`	`3`	Rotation speed in degrees per second when autoRotate is enabled.

MapControls

Container for map control components. Accepts composable control components as children (MapZoom, MapOrientation, MapGeolocate, MapFullscreen). 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.
`children`	`ReactNode`	`—`	Control components (MapZoom, MapOrientation, MapGeolocate, MapFullscreen).
`className`	`string`	`—`	Additional CSS classes for the controls container.

MapZoom

Zoom in and zoom out control buttons. Must be used inside MapControls.

No props required.

MapOrientation

Compass control that shows map orientation and resets bearing to north when clicked. Must be used inside MapControls.

No props required.

MapGeolocate

Geolocate control to find and fly to user's current location. Must be used inside MapControls.

Prop	Type	Default	Description
`onLocate`	`(coords: { longitude: number; latitude: number }) => void`	`—`	Callback with user coordinates when located.

MapFullscreen

Fullscreen toggle control. Must be used inside MapControls.

No props required.

MapMarker

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

Extends MarkerOptions from Mapbox GL (excluding element).

Prop	Type	Default	Description
`coordinates`	`[number, number]`	`—`	Coordinates [longitude, latitude] 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: LngLatCoordinates) => void`	`—`	Callback when marker drag starts (requires draggable: true).
`onDrag`	`(lngLat: LngLatCoordinates) => void`	`—`	Callback during marker drag (requires draggable: true).
`onDragEnd`	`(lngLat: LngLatCoordinates) => 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 Mapbox GL (excluding className and closeButton).

The className and closeButton from Mapbox's PopupOptions are excluded to prevent style conflicts. Use the component's own props to style the popup. Mapbox'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 Mapbox GL (excluding className, closeButton, and closeOnClick as tooltips auto-dismiss on hover out).

The className from Mapbox's PopupOptions is excluded to prevent style conflicts. Use the component's own className prop to style the tooltip content. Mapbox'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 Mapbox GL (excluding className and closeButton).

Prop	Type	Default	Description
`coordinates`	`[number, number]`	`—`	Coordinates [longitude, latitude] 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.

MapLine

Renders a line 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.

MapPolygonNew

Renders a filled polygon on the map. Must be used inside Map.

Prop	Type	Default	Description
`coordinates`	`[number, number][]`	`—`	Array of [longitude, latitude] coordinate pairs defining the polygon vertices.
`fillColor`	`string`	`"#3b82f6"`	Fill color of the polygon.
`fillOpacity`	`number`	`0.4`	Fill opacity (0 to 1).
`strokeColor`	`string`	`"#3b82f6"`	Stroke/outline color.
`strokeWidth`	`number`	`2`	Stroke width in pixels.
`strokeOpacity`	`number`	`1`	Stroke opacity (0 to 1).
`dashArray`	`[number, number]`	`—`	Dash pattern [dash length, gap length] for dashed strokes.

MapCircleCluster

Renders clustered point data using Mapbox 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: MapCircleCluster<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.

MapAnimatedPulse

Renders an animated pulsing dot at specified coordinates. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the pulse animation.
`size`	`number`	`—`	Pulse size in pixels.
`coordinates`	`[number, number]`	`—`	Coordinates [longitude, latitude] for pulse position.
`color`	`string`	`"rgba(0, 100, 255, 1)"`	Inner circle color.
`pulseColor`	`string`	`"rgba(0, 100, 255, 0.8)"`	Outer pulsing circle color.
`duration`	`number`	`1000`	Animation duration in milliseconds.

MapAnimatedPolygonNew

Renders an animated polygon with drawing outline and fill effects. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the polygon.
`coordinates`	`[number, number][]`	`—`	Array of [longitude, latitude] pairs defining polygon vertices.
`strokeColor`	`string`	`"#3b82f6"`	Color of the polygon outline.
`strokeWidth`	`number`	`2`	Width of the polygon outline in pixels.
`strokeOpacity`	`number`	`1`	Opacity of the polygon outline (0-1).
`fillColor`	`string`	`"#3b82f6"`	Color of the polygon fill.
`fillOpacity`	`number`	`0.3`	Target opacity of the polygon fill (0-1).
`duration`	`number`	`2000`	Duration of outline drawing animation in milliseconds.
`fillDuration`	`number`	`1000`	Duration of fill animation in milliseconds.
`animationMode`	`"draw" \| "fill" \| "draw-then-fill"`	`"draw-then-fill"`	Animation sequence mode.
`autoStart`	`boolean`	`true`	Start animation automatically on mount.
`loop`	`boolean`	`false`	Loop the animation continuously.
`loopDelay`	`number`	`1000`	Delay before restarting loop in milliseconds.
`onDrawComplete`	`() => void`	`—`	Callback when outline drawing completes.
`onFillComplete`	`() => void`	`—`	Callback when fill animation completes.
`onComplete`	`() => void`	`—`	Callback when entire animation completes.

MapMiniMapUpdated

Displays an overview minimap showing the current viewport context. Must be used inside Map.

Prop	Type	Default	Description
`position`	`"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`	`"bottom-right"`	Position of the minimap on the map.
`width`	`number`	`200`	Minimap width in pixels.
`height`	`number`	`150`	Minimap height in pixels.
`zoomOffset`	`number`	`-4`	Zoom offset relative to main map.
`style`	`string`	`—`	Custom map style URL for the minimap. Overrides theme-based styles.
`styles`New	`MapThemeStyles`	`—`	Theme-aware styles object with light/dark variants. Automatically switches based on theme.
`boxColor`	`string`	`"#3b82f6"`	Color of the viewport box outline.
`boxBorderWidth`	`number`	`2`	Width of the viewport box border.
`rounded`New	`number \| "full" \| "none"`	`8`	Border radius in pixels, "full" for circular, or "none".
`draggable`New	`boolean`	`false`	Allow users to drag the minimap anywhere within the map.

MapBlurAreaNew

Renders blur effect overlays on specified areas of the map. Supports single or multiple areas. Must be used inside Map.

Prop	Type	Default	Description
`coordinates`	`[number, number][]`	`—`	Array of [longitude, latitude] coordinate pairs defining a single blur area.
`areas`	`BlurAreaConfig[]`	`—`	Array of blur area configs for multiple regions. Each config: { coordinates, blur?, backgroundColor?, rounded? }.
`blur`	`number`	`8`	Default blur intensity in pixels.
`backgroundColor`	`string`	`—`	Default background color overlay (e.g., "rgba(0,0,0,0.3)").
`rounded`	`number \| "full"`	`0`	Default border radius in pixels or "full" for circular.
`blockInteraction`	`boolean`	`false`	Prevent map interactions on blur areas.

MapLineAnimated

Renders an animated line that draws progressively along the route. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the animated line.
`path`	`Array<[number, number]>`	`—`	Array of [longitude, latitude] coordinate pairs.
`color`	`string`	`"#3b82f6"`	Line color.
`width`	`number`	`4`	Line width in pixels.
`opacity`	`number`	`1`	Line opacity (0 to 1).
`dashArray`	`[number, number]`	`—`	Dash pattern [dash length, gap length] for dashed lines.
`duration`	`number`	`3000`	Animation duration in milliseconds.
`showMarker`	`boolean`	`true`	Whether to show a marker moving along the line.
`markerColor`	`string`	`"#3b82f6"`	Marker color.
`markerIcon`	`ReactNode`	`—`	Custom marker icon (React component).
`markerBorderless`	`boolean`	`false`	Remove border/outline from marker.
`autoStart`	`boolean`	`true`	Auto-start animation on mount.
`loop`	`boolean`	`false`	Loop animation continuously.
`onComplete`	`() => void`	`—`	Callback when animation completes.

MapLineRadialNew

Renders animated curved lines spreading from a central origin to multiple destinations. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the radial lines.
`origin`	`[number, number]`	`—`	Origin coordinates [longitude, latitude].
`destinations`	`RadialDestination[]`	`—`	Array of destinations. Each can be [lng, lat] or { coordinates, color?, label? }.
`color`	`string`	`"#3b82f6"`	Default line color.
`width`	`number`	`2`	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.
`curvature`	`number \| "auto"`	`0.3`	Curve intensity (0-1) or "auto" to calculate based on distance.
`curveSegments`	`number`	`50`	Number of segments for smooth curves.
`duration`	`number`	`2000`	Animation duration per line in milliseconds.
`staggerDelay`	`number`	`200`	Delay between starting each line animation.
`autoStart`	`boolean`	`true`	Start animation automatically on mount.
`loop`	`boolean`	`false`	Loop the animation continuously.
`loopDelay`	`number`	`1000`	Delay before restarting loop in milliseconds.
`showOriginMarker`	`boolean`	`true`	Show marker at origin point.
`originMarkerColor`	`string`	`"#ef4444"`	Origin marker color.
`originMarkerIcon`	`ReactNode`	`—`	Custom origin marker icon.
`originMarkerPulse`	`boolean`	`true`	Show pulse animation on origin marker.
`showDestinationMarkers`	`boolean`	`true`	Show markers at destination points.
`destinationMarkerColor`	`string`	`—`	Destination marker color (defaults to line color).
`destinationMarkerIcon`	`ReactNode`	`—`	Custom destination marker icon.
`showTravelingMarker`	`boolean`	`false`	Show marker traveling along the active line.
`travelingMarkerColor`	`string`	`—`	Traveling marker color (defaults to line color).
`travelingMarkerIcon`	`ReactNode`	`—`	Custom traveling marker icon.
`onLineComplete`	`(index: number, destination: [number, number]) => void`	`—`	Callback when a line animation completes.
`onComplete`	`() => void`	`—`	Callback when all line animations complete.

MapArcAnimatedNew

Renders an animated curved arc between two points. Useful for visualizing flights, deliveries, and point-to-point connections. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the arc.
`origin`	`[number, number]`	`—`	Starting point coordinates [longitude, latitude].
`destination`	`[number, number]`	`—`	Ending point coordinates [longitude, latitude].
`color`	`string`	`"#3b82f6"`	Arc line color.
`width`	`number`	`4`	Line width in pixels.
`opacity`	`number`	`1`	Line opacity (0 to 1).
`dashArray`	`[number, number]`	`—`	Dash pattern [dash length, gap length] for dashed arcs.
`height`	`number`	`0.3`	Curve height multiplier (0 = straight line, higher = more curved).
`segments`	`number`	`50`	Number of segments for curve smoothness.
`duration`	`number`	`2000`	Animation duration in milliseconds.
`autoStart`	`boolean`	`true`	Start animation automatically on mount.
`loop`	`boolean`	`false`	Loop the animation continuously.
`loopDelay`	`number`	`500`	Delay before restarting loop in milliseconds.
`showMarker`	`boolean`	`true`	Show traveling marker at the arc tip during animation.
`markerColor`	`string`	`—`	Traveling marker color (defaults to arc color).
`showOriginMarker`	`boolean`	`true`	Show marker at the origin point.
`originMarkerColor`	`string`	`—`	Origin marker color (defaults to arc color).
`showDestinationMarker`	`boolean`	`true`	Show marker at destination when animation completes.
`destinationMarkerColor`	`string`	`—`	Destination marker color (defaults to arc color).
`onComplete`	`() => void`	`—`	Callback when animation completes.

MapCompareUpdated

Displays two maps side-by-side for visual comparison. This component creates its own map instances and does not require a parent Map component.

Prop	Type	Default	Description
`accessToken`	`string`	`—`	Mapbox access token. Required.
`beforeStyle`	`string`	`—`	Map style for the before (left/top) map.
`afterStyle`	`string`	`—`	Map style for the after (right/bottom) map.
`center`	`[number, number]`	`[0, 0]`	Initial map center [longitude, latitude].
`zoom`	`number`	`2`	Initial zoom level.
`bearing`	`number`	`0`	Map bearing (rotation) in degrees.
`pitch`	`number`	`0`	Map pitch (tilt) in degrees.
`projection`	`"globe" \| "mercator" \| "naturalEarth" \| "equalEarth" \| "winkelTripel"`	`—`	Map projection type.
`defaultSize`	`number`	`50`	Initial split position as percentage (0-100).
`orientation`New	`"horizontal" \| "vertical"`	`"horizontal"`	Compare layout direction. Horizontal shows left/right, vertical shows top/bottom.
`showLabels`New	`boolean`	`false`	Show Before/After or Top/Bottom labels on each map panel.
`loader`	`ReactNode`	`—`	Custom loading component.

MapImage

Overlays an image on the map at specified coordinates. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the image layer.
`url`	`string`	`—`	Image URL to display.
`coordinates`	`[[number, number], [number, number], [number, number], [number, number]]`	`—`	Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft] as [lng, lat] pairs.
`opacity`	`number`	`1`	Image opacity (0 to 1).

MapRasterVideo

Overlays video content on the map at specified coordinates. Must be used inside Map.

Prop	Type	Default	Description
`id`	`string`	`—`	Unique identifier for the video layer.
`urls`	`string[]`	`—`	Array of video URLs (provide multiple formats for browser compatibility).
`coordinates`	`[[number, number], [number, number], [number, number], [number, number]]`	`—`	Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft] as [lng, lat] pairs.
`opacity`	`number`	`1`	Video opacity (0 to 1).
`autoplay`	`boolean`	`false`	Auto-play video on load.
`loop`	`boolean`	`true`	Loop video playback.
`muted`	`boolean`	`true`	Mute video audio.

MapRain

Adds an animated rain weather effect overlay to the map. Requires Mapbox GL JS v3.9 or higher. Must be used inside Map.

This component requires Mapbox GL JS v3.9+. Use the createZoomInterpolation helper to create zoom-based effects.

Prop	Type	Default	Description
`density`	`number \| any[]`	`0.5`	Rain density (0-1) or Mapbox expression for zoom-based density.
`intensity`	`number`	`1.0`	Rain intensity (0-1).
`color`	`string`	`"#a8adbc"`	Rain droplet color.
`opacity`	`number`	`0.7`	Rain opacity (0-1).
`vignette`	`number \| any[]`	`1.0`	Vignette effect strength (0-1) or Mapbox expression.
`vignetteColor`	`string`	`"#464646"`	Vignette color.
`direction`	`[number, number]`	`[0, 80]`	Wind direction [x, y].
`dropletSize`	`[number, number]`	`[2.6, 18.2]`	Droplet size range [min, max].
`distortionStrength`	`number`	`0.7`	Distortion strength (0-1).
`centerThinning`	`number`	`0`	Center thinning effect (0 = full screen).

MarkerAvatar

Renders an avatar image with optional status indicator. Must be used inside MarkerContent.

Prop	Type	Default	Description
`src`	`string`	`—`	Image source URL.
`alt`	`string`	`—`	Alt text for the image.
`size`	`number`	`40`	Size of the avatar in pixels.
`online`	`boolean`	`—`	Show online status indicator.
`statusColor`	`"green" \| "red" \| "yellow" \| "blue"`	`"green"`	Status indicator color.
`className`	`string`	`—`	Additional CSS classes for the avatar container.

Helper Functions

createZoomInterpolation

Creates a Mapbox zoom-based interpolation expression for dynamic effects. Useful for rain density and vignette that scale with zoom level.

import { Map, MapRain, createZoomInterpolation } from "@/registry/map";

export function RainMapExample() {
  // Gradually increase rain density from zoom 11 to 13
  const density = createZoomInterpolation(0.8, 11, 13);
  const vignette = createZoomInterpolation(0.5, 11, 13);

  return (
    <Map
      accessToken={process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN!}
      center={[-74.006, 40.7128]}
      zoom={12}
    >
      <MapRain
        density={density}
        vignette={vignette}
        intensity={1.0}
        color="#a8adbc"
      />
    </Map>
  );
}

← PreviousHooks Next →Map