Map

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add map

Usage#

Give the map a height: it fills its box. MapLibre loads on the client after the first paint, so the frame shows the theme's land colour until the tiles fade in, and nothing renders on the server.

Anatomy#

import { Map, MapMarker, MapPin, MapControls, MapCorner } from "@/components/ui/map"

<Map>
  <MapMarker lngLat={…}>
    <MapPin />
  </MapMarker>
  <MapControls />
  <MapCorner>…</MapCorner>
</Map>

Theming#

The basemap is painted from the --map-* tokens, which mix the theme's own --background, --foreground, --info and --success. Light grounds get grey land under white streets; dark grounds flip it, with streets that brighten with their rank. Switch the theme and the map re-paints in place, without reloading tiles or touching your own layers. Re-tint one map with a utility, such as [--map-water:var(--purple)].

labels={false} and buildings={false} quieten it further, for a backdrop under your own data.

Pins#

MapMarker pins any React content to a coordinate and keeps it in your tree, so Context, state and events work as usual. MapPin is the canonical marker to put in it: a chip on the popover surface with the tone as a leading dot, or the dot alone without a label (name it with aria-label). It is a button only when it has something to do, an onClick or a Popover around it, so a pin that only marks a place stays out of the tab order. selected inverts it to ink.

Prices#

variant="price" turns the pin into the chip a map of stays or listings wears: the figure alone, bolder and in tabular figures, so a dozen of them read as numbers to compare. Open one and it inverts to ink; visited greys the ones already seen, so the eye moves on. The hovered, focused or selected pin rises above its neighbours, so a crowded cluster never buries the one you are looking at. Format the price yourself, with Intl.NumberFormat, and name the pin with the place and the price.

Emoji#

variant="emoji" marks a place by what it is instead of by a status: a café, a beach, a museum, for a map of things to do or a neighbourhood guide. The emoji takes the dot's place; beside a label it sits in its own circle, concentric with the chip, and without one it is the pin on its own (name it with aria-label). labelMinZoom sets the zoom a label shows from: further out the pin is its emoji alone and the name opens on hover and on focus. Give every pin the same zoom and the whole map changes detail at once: zoom in to read the names. The emoji is decorative: the label names the pin. selected and visited work as on every pin.

Symbols#

A dispatch, fleet or incident map marks things by what they are and how urgent, not by a name on a chip. Give MapPin an icon, a sprite src or a shape and it becomes a symbol: a circle with a category icon, a square for a fixed asset, a diamond for a numbered priority, a dot for a moving unit, a cross for a unit of another service. Fill it with a tone, or with any CSS color straight from your data: the icon's ink is picked by contrast (set ink to decide it yourself).

halo draws a still ring (glow, ring or dashed, for a unit in the air), pulse="ping" a slow live halo for units on duty and pulse="alert" a fast, strong one for a panic. caption puts a callsign beside the symbol or a title under it. label names the symbol for assistive tech, and selected grows it and rings it in ink. Click the symbols.

Three sizes: sm 22, md 28 and lg 36px for a shape that holds an icon, 12, 16 and 20px for a dot or a cross. Pass a sprite as src (a vehicle silhouette) and it takes the icon's place. The symbol's box is the shape alone, so MapMarker's default center anchor lands on its middle; the halo, the pulse and the caption spill over it. The pulses animate transform and opacity only and hold still under reduced motion, as a faint ring.

Your own layers#

useMap() hands any child the MapLibre instance. Add sources and layers once loaded is true and remove them on cleanup. MapLibre reads neither oklch() nor color-mix(), so useMapColor resolves a token to an rgb value it can paint, and resolves it again when the theme changes: set it in an effect and your route re-paints with the basemap. Switch the theme to see it. MapCorner floats your own parts, such as this ETA, in a corner, inset like the controls.

Controls#

MapControls is a floating vertical Toolbar: zoom, a compass that turns with the map and resets north and tilt, and locate, which asks for the visitor's position and flies there. position picks the corner; the tooltips open on the side away from the edge. This map starts rotated, so the compass is turned.

Any style#

mapStyle swaps the basemap for any MapLibre style, by URL or as an object: a provider's satellite tiles, your own design from Maputnik. The theming steps aside; pins, controls and useMap work the same.

API reference#

FAQ#