Line gradient

Colour a line along its own length, start to finish, with line-gradient over line-progress. Good for showing direction, progress along a trip or a value that changes along a path, with one line and no splitting.

import { createMap } from "@mapmap/maps";

const map = createMap({
  container: "map",
  apiKey: "snk_...",
  attributionPosition: "bottom-left",
  center: [-0.17, 51.2],
  zoom: 8.6,
});
await map.whenReady();

map.map.addSource("trip", {
  type: "geojson",
  // line-progress only exists when the source computes line metrics.
  lineMetrics: true,
  data: {
    type: "Feature",
    properties: {},
    geometry: {
      type: "LineString",
      coordinates: [
        [-0.1278, 51.5074], [-0.1043, 51.4613], [-0.1340, 51.3720],
        [-0.1621, 51.2465], [-0.1872, 51.1137], [-0.1426, 50.9970],
        [-0.1372, 50.8225],
      ],
    },
  },
});

// Slots arrive in the SDK 0.17: map.slot("middle") replaces "road-labels".
map.map.addLayer({
  id: "trip",
  type: "line",
  source: "trip",
  layout: { "line-cap": "round", "line-join": "round" },
  paint: {
    "line-width": 6,
    // Stops must be strictly ascending: 0, then 0.5, then 1.
    "line-gradient": [
      "interpolate", ["linear"], ["line-progress"],
      0,   "#1a6bff",
      0.5, "#7b4dff",
      1,   "#e63946",
    ],
  },
}, "road-labels");

Worth knowing

line-gradient stops must be strictly ascending. Two stops at the same progress, or one out of order, makes MapLibre reject the whole expression and the line disappears with no error on the map.
lineMetrics: true goes on the GeoJSON source, not the layer. Without it line-progress has no value and the gradient never draws.
line-gradient cannot be combined with line-dasharray or line-pattern on the same layer. Draw a second layer if you need both.

Add your own data Next: Image overlay