Create a Gradient Line Using an Expression in Maptoolkit Maps JS
The line-gradient paint property in Maptoolkit Maps JS uses an interpolate expression to map positions along a line (from 0 at the start to 1 at the end) to color values. The source must have lineMetrics: true enabled for the gradient to work correctly. Use this to color-code routes by speed, elevation, or any continuous metric that varies along a path.
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
center: [-77.035, 38.875],
zoom: 12,
attributionControl: { compact: false }
});
map.addControl(new maptoolkit.NavigationControl(), 'top-right');
const geojson = {
type: 'FeatureCollection',
features: [{
type: 'Feature',
properties: {},
geometry: {
type: 'LineString',
coordinates: [
[-77.044211, 38.852924],
[-77.045659, 38.860158],
[-77.044232, 38.862326],
[-77.040879, 38.865454],
[-77.039936, 38.867698],
[-77.040338, 38.86943],
[-77.04264, 38.872528],
[-77.03696, 38.878424],
[-77.032309, 38.87937],
[-77.030056, 38.880945],
[-77.027645, 38.881779],
[-77.026946, 38.882645],
[-77.026942, 38.885502],
[-77.028054, 38.887449],
[-77.02806, 38.892088],
[-77.03364, 38.892108],
[-77.033643, 38.899926]
]
}
}]
};
map.on('load', () => {
map.addSource('line', {
type: 'geojson',
lineMetrics: true,
data: geojson
});
map.addLayer({
id: 'line',
type: 'line',
source: 'line',
paint: {
'line-color': 'red',
'line-width': 14,
'line-gradient': [
'interpolate', ['linear'], ['line-progress'],
0, 'blue',
0.1, 'royalblue',
0.3, 'cyan',
0.5, 'lime',
0.7, 'yellow',
1, 'red'
]
},
layout: {
'line-cap': 'round',
'line-join': 'round'
}
});
});<!DOCTYPE html>
<html lang="en">
<head>
<title>Create a Gradient Line Using an Expression - Maptoolkit Maps JS</title>
<meta property="og:description" content="Style a line with a color gradient using a line-gradient expression." />
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.css" />
<style>
html, body { width: 100%; height: 100%; margin: 0; padding: 0; }
#map { width: 100%; height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
center: [-77.035, 38.875],
zoom: 12,
attributionControl: { compact: false }
});
map.addControl(new maptoolkit.NavigationControl(), 'top-right');
const geojson = {
type: 'FeatureCollection',
features: [{
type: 'Feature',
properties: {},
geometry: {
type: 'LineString',
coordinates: [
[-77.044211, 38.852924],
[-77.045659, 38.860158],
[-77.044232, 38.862326],
[-77.040879, 38.865454],
[-77.039936, 38.867698],
[-77.040338, 38.86943],
[-77.04264, 38.872528],
[-77.03696, 38.878424],
[-77.032309, 38.87937],
[-77.030056, 38.880945],
[-77.027645, 38.881779],
[-77.026946, 38.882645],
[-77.026942, 38.885502],
[-77.028054, 38.887449],
[-77.02806, 38.892088],
[-77.03364, 38.892108],
[-77.033643, 38.899926]
]
}
}]
};
map.on('load', () => {
map.addSource('line', {
type: 'geojson',
lineMetrics: true,
data: geojson
});
map.addLayer({
id: 'line',
type: 'line',
source: 'line',
paint: {
'line-color': 'red',
'line-width': 14,
'line-gradient': [
'interpolate', ['linear'], ['line-progress'],
0, 'blue',
0.1, 'royalblue',
0.3, 'cyan',
0.5, 'lime',
0.7, 'yellow',
1, 'red'
]
},
layout: {
'line-cap': 'round',
'line-join': 'round'
}
});
});
</script>
</body>
</html>Use the prompt below with any LLM to get the same result. Make sure the Maptoolkit MCP server is connected first — check out AI Integration & MCP to get started.
How it works
line-gradient colours a line along its own length. The expression reads
['line-progress'], which runs from 0 at the start of the line to 1 at the end, and
interpolates colours between stops on that range.
It has two hard requirements that produce no error when missed. The source needs
lineMetrics: true, because without it the renderer never computes progress along the line
and the gradient silently does nothing. And line-gradient cannot be used with a
data-driven line-color: the two are mutually exclusive.
Because progress is relative, the gradient always spans the whole feature. Colouring by real distance or by elevation means splitting the line into segments and colouring each.
Next steps
A gradient is only worth having if it encodes something. Progress along a route is the free version; the useful ones colour by elevation, speed or surface, which means splitting the line into segments carrying those values and colouring each.
The Elevation API supplies heights for a route, which makes a gradient from green to red by gradient the obvious next build for anything outdoor. A legend is what makes it readable.