Maps

Display a full-screen map.

Example

Install @ink/maps. The map fills the content area; place it as the only child of Screen.

import { Screen } from "ink";
import { MapView } from "@ink/maps";

export default function BusMap() {
  return <Screen title="Bus location">
    <MapView
      initialCentre={{ latitude: 51.5074, longitude: -0.1278 }}
      initialZoom={14}
      markers={[{
        id: "bus", latitude: 51.5074,
        longitude: -0.1278, label: "Bus",
      }]}
    />
  </Screen>;
}

A map of central London with a bus marker.

Appearance

The default map follows Ink’s colour scheme and keeps the screen background while loading.

Markers and movement

Markers have a stable id, latitude, longitude and optional label. onMarkerPress(id) handles taps. Updating markers does not reset the camera.

initialCentre and initialZoom apply on mount. Use useMap() and pass its result as controller to move the camera later:

await map.moveTo({ centre: { latitude, longitude }, zoom: 14 });

onCameraIdle({ centre, zoom }) reports the settled view. Zoom ranges from 0 to 22 and defaults to 14.

Map sources

The default OpenFreeMap styles need no credentials. Use an HTTPS MapLibre styleURL for another source. Attribution stays visible.

Markers, gestures and camera movement are supported. Offline regions, routing, geocoding, clustering and React content inside markers are not. Cached tiles do not guarantee offline access. Location permission is only needed when reading the device’s position.