Map

Map draws flat map tiles and places MapMarker and MapPopup children by latitude and longitude. Drag to pan, scroll or pinch to zoom at the pointer, double-click to zoom in. Tiles are plain images on a Web Mercator grid, so it adds no dependency; the default tiles are OpenStreetMap's, which suit development and light use. For production traffic bring your own provider with tileUrl (see Tiles below).

Markers

Three types, each with Default, Hover and Selected states that match the Figma Map Marker set. Hover works on every marker (the one under the pointer rises above its neighbours); selected is yours to set. The pin is anchored at its tip, the dot and cluster at their centre.

Popup

A card that opens above a place. The description, the close button and the pointer are each optional, and it takes children for actions.

Controls

Zoom buttons are on by default (Default, Hover and Disabled states, matching Map Control Button); add locate for a button that centres on the user. The same buttons are exported as MapControls and MapControlButton for custom overlays.

Dark mode

The map follows the page's theme, so under .dark its tiles are darkened to near-black land with blue water and roads darker than the land (tune it with --map-tile-filter). Markers, controls and popups re-theme with the tokens. Use the moon button on any preview here to see it, or pass theme="dark" to make one map dark on a light page, as below. For a provider's own dark style, give tileUrlDark.

Live data

Keep positions in state, update them when your feed delivers (WebSocket, server-sent events, polling), and give the markers glide of about the interval between updates: they slide to each new place instead of jumping, and a popup that points at one follows it. Here a new position arrives every two seconds; toggle glide to compare.

Many places

Don't map thousands of MapMarkers yourself. MapClusterLayer groups nearby places into counted clusters that zoom to their places when clicked, regroups as you zoom, and renders only what is in view. This map has 2,000 places; a zoom step takes about 5 ms with 10,000.

Tiles and attribution

Any raster tile server works: give its {z}/{x}/{y} template and the credit it requires. OpenStreetMap's own servers are for light use; their usage policy asks heavier sites to use a provider or host their own tiles.

// Any {z}/{x}/{y} raster tile server. Pass its attribution too.
<Map
  tileUrl="https://api.maptiler.com/maps/streets-v2/{z}/{x}/{y}.png?key=YOUR_KEY"
  attribution={<>© MapTiler © OpenStreetMap contributors</>}
/>

Your own overlays

Inside a Map, useMapContext() projects places into the map's pixels and can move the view.

import { useMapContext } from '@sakaniui/react';

function Boundary({ corners }: { corners: LatLng[] }) {
  const { project, flyTo, fitBounds } = useMapContext();   // inside <Map>
  const points = corners.map(project);                      // container pixels, or null when far off-screen
  /* draw anything you like at those pixels */
  return <button onClick={() => fitBounds(corners)}>Fit</button>;
}

Globe

MapGlobe is a 3D dotted globe for places in the world as a whole: offices, customers, routes. It is a canvas with an orthographic projection and a small Natural Earth land mask, so it adds no dependency. It spins on its own, can be dragged, pauses offscreen, and stays still under reduced motion. It has no background of its own: it takes the colour of whatever it sits on.

Globe variants

land dots the continents; ocean dots the sea and leaves the land dark. Atmosphere, markers and arcs are each optional (Figma: Show atmosphere, Show markers, Show arcs).

Globe markers: hover and select

Markers have Default, Hover (a soft halo), Selected (a larger halo) and Active (a pulse) states. Hovering one stops the spin so it can be clicked, and a marker with a label shows its name in a small card while hovered or selected. Labelled markers are also reachable with Tab.

Globe in dark

It follows the page's theme like everything else. theme="dark" draws light dots for a globe that sits on a dark surface inside a light page.

Interaction

Accessibility

• The map is a labelled region you can focus: arrow keys pan and + / - zoom, and the zoom buttons are real buttons with focus rings.
• Give every MapMarker a label. Markers with onClick are buttons (aria-pressed follows selected); the rest are images with that name.
• Popups are dialogs: Escape closes them when they have onClose.
• Reduced motion turns off pan inertia, the zoom easing, glide and the globe's spin.
• A map is hard to use without a pointer, so offer the places in a list or table next to it. The globe is decorative unless it has onMarkerClick: then labelled markers get a hidden button each.

Map props

MapMarker props

MapPopup props

MapClusterLayer props

MapGlobe props