Anatomy

Import the Map component and compose overlays with dot notation.

Map is a subpath-only import (@heroui-pro/react/map) because it depends on the optional maplibre-gl peer. It is not exported from the package root, so SSR apps that don't use it never need maplibre-gl installed.

import {Map} from "@heroui-pro/react/map";

const styles = {
  dark: "https://tiles.openfreemap.org/styles/dark",
  light: "https://tiles.openfreemap.org/styles/positron",
};

<Map center={[-122.3927, 37.7816]} styles={styles} zoom={13.25}>
  <Map.Route coordinates={route} />
  <Map.Marker latitude={37.79519} longitude={-122.39385}>
    <Map.MarkerContent>
      <Map.MarkerDot color="#22c55e" />
      <Map.MarkerLabel>Start</Map.MarkerLabel>
    </Map.MarkerContent>
    <Map.MarkerTooltip>Ferry Building</Map.MarkerTooltip>
  </Map.Marker>
  <Map.Popup latitude={37.79519} longitude={-122.39385}>
    Pickup ready
  </Map.Popup>
  <Map.Controls>
    <Map.ZoomControl />
    <Map.CompassControl />
  </Map.Controls>
</Map>;

The examples above use OpenFreeMap for Positron (light) and Dark (dark). Its public instance requires no API key or registration, so these snippets run as-is.

Live Visitors

Property Listings

Live Tracking

Store Locator

Fleet Dispatch

Coverage Zones

Heatmap

Flight Paths

Incident Monitor

Style

Map uses MapLibre GL internally, but it does not ship a tile provider or basemap style. Pass mapStyle for a single MapLibre-compatible style URL/object, or styles for separate light and dark styles. These demos pass OpenFreeMap Positron and OpenFreeMap Dark through styles.

Any MapLibre-compatible provider works — MapTiler, Stadia Maps, Protomaps, or CARTO. Check each provider's terms before shipping: most require an API key on their style URLs, and a keyed provider will watermark tiles with something like "API KEY REQUIRED" when the key is missing. That watermark comes from the tile provider, not from HeroUI Pro, and is unrelated to your HeroUI Pro registry tokens.

CSS Classes

Element Classes

.map — MapLibre container and positioning root.
.map__marker — Marker host element.
.map__marker-content — React-rendered marker content.
.map__default-marker — Default marker dot.
.map__marker-label — Marker label.
.map__popup-content — Popup content wrapper.
.map__tooltip — Marker tooltip.
.map__controls — Controls container.
.map__control-group — Grouped control surface.
.map__control-button — Single control button.

CSS Variables

--map-control-size — Control button size.
--map-control-offset — Controls offset from map edges.
--map-popup-max-width — Popup and tooltip max width.
--map-marker-color — Default marker fill color.
--map-marker-ring-color — Default marker ring color.
--map-route-color — Default route stroke color.
--map-route-width — Default route stroke width.
--map-route-opacity — Default route stroke opacity.

API Reference

Map

The root map container. Renders a MapLibre map with HeroUI themed controls and overlays.

Prop	Type	Default	Description
`center`	`[number, number]`	—	Initial center as `[longitude, latitude]`.
`zoom`	`number`	—	Initial zoom level.
`mapStyle`	`string \| StyleSpecification`	—	Single MapLibre-compatible style URL/object. Overrides `styles`.
`styles`	`{ light?: MapStyleOption; dark?: MapStyleOption }`	—	Theme-aware style URLs or objects.
`theme`	`"light" \| "dark"`	detected	Force the map style theme.
`viewport`	`Partial<MapViewport>`	—	Controlled viewport state.
`onViewportChange`	`(viewport: MapViewport) => void`	—	Fired as the map moves.
`isLoading`	`boolean`	`false`	Shows the loading veil over the map.
`workerUrl`	`string`	—	Explicit MapLibre worker URL for bundlers that cannot resolve it.

Also supports MapLibre MapOptions except container and style.

Map.Marker

Adds a React-rendered marker at a longitude/latitude.

Prop	Type	Default	Description
`latitude`	`number`	—	Marker latitude.
`longitude`	`number`	—	Marker longitude.
`draggable`	`boolean`	`false`	Allows dragging the marker.
`onClick`	`(event: MouseEvent) => void`	—	Fired when the marker is clicked.
`onDragEnd`	`({ lat, lng }) => void`	—	Fired after a draggable marker moves.

Marker Parts

Map.MarkerContent — Renders marker content into the MapLibre marker element.
Map.MarkerDot — Renders the default marker dot. Customize with className, style, color, or ringColor.
Map.MarkerLabel — Adds a marker label with position="top" | "bottom".
Map.MarkerTooltip — Shows a lightweight tooltip on hover.
Map.MarkerPopup — Attaches a MapLibre popup to a marker.

Map.MarkerDot

Renders the default marker visual. Use it inside Map.MarkerContent when you want the built-in marker style plus labels or other custom content.

Prop	Type	Default	Description
`color`	`string`	—	Overrides `--map-marker-color`.
`ringColor`	`string`	—	Overrides `--map-marker-ring-color`.

Map.Popup

Renders a standalone popup at a longitude/latitude.

Prop	Type	Default	Description
`latitude`	`number`	—	Popup latitude.
`longitude`	`number`	—	Popup longitude.
`closeButton`	`boolean`	`false`	Shows the HeroUI close button.
`onClose`	`() => void`	—	Fired when the popup closes.

Map.Controls

Positions map controls in a corner.

Prop	Type	Default	Description
`position`	`"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`	`"bottom-right"`	Controls placement.

Use Map.ZoomControl, Map.CompassControl, Map.LocateControl, Map.FullscreenControl, Map.ControlGroup, Map.ControlButton, and Map.ControlSeparator inside Map.Controls.

Map.Route

Draws a GeoJSON line layer from coordinates.

Map.Route does not calculate navigation paths or snap points to roads. Pass the route geometry from your routing provider, such as Google Routes, Mapbox Directions, OSRM, Valhalla, or your own routing service.

Prop	Type	Default	Description
`coordinates`	`[number, number][]`	—	Route coordinates as `[longitude, latitude]`.
`color`	`string`	CSS var	Route stroke color.
`width`	`number`	CSS var	Route stroke width.
`opacity`	`number`	CSS var	Route stroke opacity.
`dashArray`	`[number, number]`	—	Optional dashed route pattern.

Map.Arc

Draws curved connection lines between points. Each datum needs id, from, and to.

Map.ClusterLayer

Draws clustered points from a GeoJSON point collection or GeoJSON URL.

Usage