maplibre-isochrone-control

A MapLibre GL JS control plugin that lets users drag an isochrone marker onto the map to show a travel-time area.

Live demo

Install

npm install @maptoolkit/maplibre-isochrone-control maplibre-gl

Usage

import * as maplibregl from "maplibre-gl";
import { IsochroneControl } from "@maptoolkit/maplibre-isochrone-control";
import "@maptoolkit/maplibre-isochrone-control/style.css";

const map = new maplibregl.Map({ container: "map", style, center, zoom });
map.addControl(
  new IsochroneControl({
    apiKey: "YOUR_API_KEY",
    routingProfile: "foot",
    timeLimit: 10,
  }),
);

Drag the control's handle onto the map to drop a marker. The control requests the isochrone polygon for that point, draws it, and fits the map to its bounds. Drag the marker to reposition it, or click its remove button, to clear the isochrone.

By default the control is placed in the bottom-right corner; pass a position to addControl to change that:

map.addControl(new IsochroneControl(), "bottom-left");

Without a bundler

The package is ESM-only (no UMD/CJS build). Loading it straight from a CDN via a <script> tag works with an import map to resolve the bare maplibre-gl specifier:

<link href="https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css" rel="stylesheet" />
<link href="https://unpkg.com/@maptoolkit/maplibre-isochrone-control@^1.0.0/dist/maplibre-isochrone-control.css" rel="stylesheet" />

<script type="importmap">
  {
    "imports": {
      "maplibre-gl": "https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs"
    }
  }
</script>
<script type="module">
  import * as maplibregl from "maplibre-gl";
  import { IsochroneControl } from "https://unpkg.com/@maptoolkit/maplibre-isochrone-control@^1.0.0/dist/maplibre-isochrone-control.js";

  const map = new maplibregl.Map({ container: "map", style, center, zoom });
  map.addControl(new IsochroneControl());
</script>

Options

| Option | Type | Default | Description | | ---------------- | ----------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | provider | "maptoolkit" \| "graphhopper" \| IsochroneRequestFn | "maptoolkit" | Which routing backend to use, or a custom function that resolves to the isochrone's outer ring. | | apiUrl | string | maptoolkit routing API | Base URL of the routing API. Required when provider is "graphhopper". | | apiKey | string | — | API key for the routing backend. | | timeLimit | number | 10 | Travel time used for the isochrone calculation, in minutes. | | routingProfile | string | "foot" | Routing profile, passed through to the routing API as-is; "foot", "bike", and "car" additionally get a matching icon and tooltip text. | | fitBounds | boolean \| FitBoundsOptions | true | Whether the map fits to the isochrone's bounds once it loads. |

Custom provider

Pass a function as provider to fully control request building and response parsing for a backend that isn't built in:

new IsochroneControl({
  provider: async (lngLat, { routingProfile, timeLimit }, signal) => {
    const response = await fetch(`https://example.com/isochrone?lat=${lngLat.lat}&lng=${lngLat.lng}&profile=${routingProfile}&time=${timeLimit}`, { signal });
    const data = await response.json();
    return data.ring; // [[lng, lat], ...]
  },
});

Custom routing profiles

For a routingProfile other than "foot", "bike", or "car", the handle falls back to a generic icon and the tooltip is hidden (a IsochroneControl.Tooltip.<profile> warning is logged) unless you provide both yourself:

const map = new maplibregl.Map({
  container: "map",
  style,
  center,
  zoom,
  locale: {
    "IsochroneControl.Tooltip.scooter": "Drag me onto the map to show a {time}-min scooter area.",
  },
});

.maplibre-isochrone-control-chronee-scooter {
  background-image: url("scooter-icon.svg");
}

Methods

const control = new IsochroneControl();
map.addControl(control);

control.addToMap({ lng: 11.4, lat: 47.27 });
control.removeFromMap();

| Method | Description | | ------------------ | -------------------------------------------------------------------------------------------------------- | | addToMap(lngLat) | Drops the marker at lngLat and requests/draws its isochrone, same as dragging the handle onto the map. | | removeFromMap() | Removes the marker and isochrone layer, same as clicking the remove button. |

Styling

Appearance is controlled via CSS custom properties on .maplibregl-map, defined in style.css. That's the map container MapLibre itself creates, and an ancestor of both the toolbar handle and the dropped marker (which isn't nested inside .maplibre-isochrone-control), so overriding them there themes both consistently:

.maplibregl-map {
  --isochrone-control-color-bg: #e2e7fd;
  --isochrone-control-color-accent: #0074d9;
}

See src/style.css for the full list of --isochrone-control-* variables.

License

maplibre-isochrone-control is open-source under the BSD 3-Clause License.