Map

pro

Map wraps MapLibre with markers, popups, routes, arcs, and point clustering, themed to match the rest of the UI.

Installation

Add this component with the NateUI CLI.

npx nateui@latest add Map

pnpm dlx nateui@latest add Map

yarn dlx nateui@latest add Map

Examples

40.71, -74.01 · zoom 11.0

API

Map

Prop	Description	Type	Default
`children`	Markers, popups, routes, arcs, and cluster layers.	`ReactNode`	—
`theme`	Tile style to use.	`'light' \| 'dark'`	app's `ConfigProvider` mode
`styles`	Override the default tile style URL per theme.	`{ light?: MapStyleOption; dark?: MapStyleOption }`	OpenFreeMap positron/dark
`viewport`	Controlled camera. Pair with `onViewportChange` (see Controlled Viewport).	`Partial<MapViewport>`	—
`onViewportChange`	Called on pan/zoom/rotate with the new camera state.	`(viewport: MapViewport) => void`	—
`loading`	Shows a centered spinner overlay.	`boolean`	`false`
`ref`	Exposes the underlying `maplibregl.Map` instance.	`Ref<MapRef \| null>`	—
`className`	Class names applied to the map's root element.	`string`	—
`center`	Initial camera center (uncontrolled).	`LngLatTuple`	—
`zoom`	Initial zoom level (uncontrolled).	`number`	—
`bearing`	Initial map rotation, in degrees (uncontrolled).	`number`	`0`
`pitch`	Initial camera tilt, in degrees (uncontrolled).	`number`	`0`
`interactive`	Disables all pan/zoom/rotate gestures when `false`.	`boolean`	`true`
`attributionControl`	Shows the map data attribution badge.	`boolean`	`true`
`...mapOptions`	The rest of MapLibre's own `MapOptions` — see MapLibre's docs.	`Omit<maplibregl.MapOptions, 'container' \| 'style'>`	—

Map.Marker

Prop	Description	Type	Default
`longitude`	Marker position.	`number`	—
`latitude`	Marker position.	`number`	—
`children`	Marker visual and any attached `Map.MarkerPopup` / `Map.MarkerTooltip` / `Map.MarkerLabel`.	`ReactNode`	—
`onClick`	Fired on marker click.	`(event: MouseEvent) => void`	—
`onMouseEnter` / `onMouseLeave`	Fired on hover.	`(event: MouseEvent) => void`	—
`onDragStart` / `onDrag` / `onDragEnd`	Fired while dragging, when `draggable` is set.	`(lngLat: { lng: number; lat: number }) => void`	—
`...markerOptions`	The rest of MapLibre's own `MarkerOptions` (`draggable`, `offset`, `rotation`, `anchor`, `color`, …).	`Omit<maplibregl.MarkerOptions, 'element'>`	—

Map.MarkerContent

The default pin visual — a small primary-colored dot. Not required; Map.Marker's children accepts any node.

Prop	Description	Type	Default
`children`	Content rendered inside the dot.	`ReactNode`	—
`className`	Class names applied to the dot.	`string`	—

Map.MarkerPopup

Click-to-open popup attached to a marker. Must be rendered inside Map.Marker.

Prop	Description	Type	Default
`children`	Popup content.	`ReactNode`	—
`closeButton`	Shows a close button in the corner.	`boolean`	`false`
`className`	Class names applied to the popup body.	`string`	—
`...popupOptions`	The rest of MapLibre's own `PopupOptions` (`offset`, `maxWidth`, `anchor`, …).	`Omit<maplibregl.PopupOptions, 'closeButton'>`	—

Map.MarkerTooltip

Hover-to-show tooltip attached to a marker. Must be rendered inside Map.Marker.

Prop	Description	Type	Default
`children`	Tooltip content.	`ReactNode`	—
`className`	Class names applied to the tooltip body.	`string`	—
`...popupOptions`	The rest of MapLibre's own `PopupOptions`, minus `closeButton` and `closeOnClick`.	`Omit<maplibregl.PopupOptions, 'closeButton' \| 'closeOnClick'>`	—

Map.MarkerLabel

Small always-visible caption positioned above or below a marker.

Prop	Description	Type	Default
`children`	Label content.	`ReactNode`	—
`position`	Side of the marker the label sits on.	`'top' \| 'bottom'`	`'top'`
`className`	Class names applied to the label.	`string`	—

A standalone popup at its own coordinate, not attached to a marker.

Prop	Description	Type	Default
`longitude`	Popup position.	`number`	—
`latitude`	Popup position.	`number`	—
`children`	Popup content.	`ReactNode`	—
`closeButton`	Shows a close button in the corner.	`boolean`	`false`
`onClose`	Called when the popup closes.	`() => void`	—
`className`	Class names applied to the popup body.	`string`	—
`...popupOptions`	The rest of MapLibre's own `PopupOptions`, minus `closeButton`.	`Omit<maplibregl.PopupOptions, 'closeButton'>`	—

Map.Controls

Floating zoom / compass / locate / fullscreen button cluster.

Prop	Description	Type	Default
`position`	Corner of the map the cluster docks to.	`'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`	`'bottom-right'`
`showZoom`	Shows zoom in/out buttons.	`boolean`	`true`
`showCompass`	Shows a button that resets bearing and pitch.	`boolean`	`false`
`showLocate`	Shows a button that flies to the user's current location.	`boolean`	`false`
`showFullscreen`	Shows a button that toggles fullscreen.	`boolean`	`false`
`onLocate`	Called with the resolved coordinates after a successful locate.	`(coords: { longitude: number; latitude: number }) => void`	—
`className`	Class names applied to the control cluster.	`string`	—

Map.Route

A plain polyline between coordinates.

Prop	Description	Type	Default
`coordinates`	Line waypoints, in order. Needs at least 2 points.	`LngLatTuple[]`	—
`color`	Line color.	`string`	theme `--nui-primary`
`width`	Line width, in pixels.	`number`	`3`
`opacity`	Line opacity.	`number`	`1`
`dashArray`	Dash pattern as `[dash, gap]`.	`[number, number]`	—
`interactive`	Attaches `onClick` / `onMouseEnter` / `onMouseLeave`.	`boolean`	`false`
`onClick` / `onMouseEnter` / `onMouseLeave`	Fired when `interactive` is `true`.	`() => void`	—
`beforeId`	Insert this layer before an existing layer id.	`string`	—

Map.Arc

Curved lines between point pairs, for flight-path / network-style visualizations.

Prop	Description	Type	Default
`data`	Arc endpoints.	`MapArcDatum[]`	—
`curvature`	How much the arc bows away from a straight line.	`number`	`0.2`
`samples`	Points used to draw the curve — higher is smoother.	`number`	`64`
`paint`	MapLibre line paint override.	`LinePaint`	theme `--nui-primary`
`layout`	MapLibre line layout override.	`LineLayout`	—
`hoverPaint`	Paint applied to an arc while hovered (`interactive` only).	`LinePaint`	—
`interactive`	Attaches hover state and `onClick` / `onHover`.	`boolean`	`false`
`onClick` / `onHover`	Fired when `interactive` is `true`.	`(event: MapArcEvent \| null) => void`	—
`beforeId`	Insert this layer before an existing layer id.	`string`	—

Map.ClusterLayer

Groups nearby GeoJSON points into clusters that expand as you zoom in.

Prop	Description	Type	Default
`data`	Point features to cluster, or a URL to load them from.	`string \| GeoJSON.FeatureCollection<GeoJSON.Point>`	—
`clusterMaxZoom`	Zoom level above which points no longer cluster.	`number`	`14`
`clusterRadius`	Cluster grouping radius, in pixels.	`number`	`50`
`clusterPaint`	MapLibre paint override for cluster circles.	`CirclePaint`	theme `--nui-primary`
`clusterCountPaint`	MapLibre paint override for the cluster count label.	`SymbolPaint`	—
`pointPaint`	MapLibre paint override for individual (non-clustered) points.	`CirclePaint`	theme `--nui-primary`
`onClusterClick`	Fired on cluster click. Also auto-zooms to expand the cluster.	`(event: { clusterId: number; coordinates: LngLatTuple; originalEvent }) => void`	—
`onPointClick`	Fired on an individual point click.	`(event: { feature; coordinates: LngLatTuple; originalEvent }) => void`	—
`beforeId`	Insert these layers before an existing layer id.	`string`	—

useMap

Returns the shared map context. Must be called within Map.

function useMap(): {
  map: maplibregl.Map | null;
  isLoaded: boolean;
  isStyleLoaded: boolean;
}

Types

type MapViewport = {
  center: [longitude: number, latitude: number];
  zoom: number;
  bearing: number;
  pitch: number;
}
 
type MapStyleOption = string | maplibregl.StyleSpecification
 
type LngLatTuple = [longitude: number, latitude: number]
 
type MapArcDatum = {
  id: string | number;
  from: LngLatTuple;
  to: LngLatTuple;
}
 
type MapArcEvent<T = MapArcDatum> = {
  arc: T;
  longitude: number;
  latitude: number;
  originalEvent: maplibregl.MapMouseEvent;
}

LinePaint, LineLayout, CirclePaint, SymbolPaint, and SymbolLayout are MapLibre's own style-spec paint/layout types, re-exported as-is — see MapLibre's style spec rather than a NateUI-defined shape.

Installation

Examples

Static Preview

Popups & Labels

Controls

Route

Arc

Cluster Layer

Controlled Viewport

API

Map