@kausal/mapboxgl-legend
v1.7.2
Published
Mapbox-GL plugin that automatically draws a legend from layer styles
Downloads
30
Readme
mapboxgl-legend
Add a legend to a mapbox-gl map by parsing layer layout & paint expressions.
Properties currently supported:
*-color
*-radius
*-image
*-pattern
Expressions currently supported:
match
interpolate
step
- literals
Get started
Install npm package
npm install mapboxgl-legend
Add legend control to map
import LegendControl from 'mapboxgl-legend';
import 'mapboxgl-legend/dist/style.css';
const legend = new LegendControl();
map.addControl(legend, 'bottom-left');
Add layers as usual, and the legend will be autogenerated
map.addLayer({
id: 'density',
type: 'circle',
source: 'demographic',
paint: {
'circle-radius': [
'interpolate', ['linear'],
['to-number', ['get', 'density']],
100, 10,
200, 17,
500, 30,
1000, 50,
2000, 75
],
'circle-color': [
'match',
['get', 'ethnicity'],
'White', '#f1e8c8',
'Black', '#443722',
'Hispanic', '#aa9761',
'Asian', '#e8e59d',
/* other */ '#ccc'
]
},
});
Options
A few options can be passed on legend initialization.
| option | type | default | description |
| --- | --- | --- | --- |
| collapsed | Boolean | false
| Set legend panels collapsed on load |
| toggler | Boolean | false
| Add button to show and hide layers |
| layers | Array[string], Object | undefined
| List of layers to be added. If undefined all layers will be added |
The layers option is an array of the layers' ids, or strings casted as regex that match the layers' ids. It can also be an object with keys being the layers' ids and values being an array of visible attributes, or true
if all visible.
const legend = new LegendControl({
// Show all properties in selected layers
layers: ['population', 'areas'],
layers: {
// Show all properties in this layer
areas: true,
// Show only selected properties in this layer
population: ['circle-radius'],
},
})
There are also a few options that be defined as a per-layer basis using the style metadata
object.
| option | type | description | | --- | --- | --- | | name | String | Set the panel title name | | unit | String | Add a unit to all labels | | labels | Object | Map a value to a text that replaces it as a label |
Metadata provides an extra layer of control by hiding items that have a label set to false
, except on step expressions.
map.addLayer({
id: 'density',
type: 'circle',
source: 'demographic',
paint: { /* ... */ },
metadata: {
name: 'Population Density',
unit: 'k/km²',
labels: {
10: 'Custom label for value 10',
other: '< 1k/km²',
an_item_to_hide: false,
}
}
});
For pairs labels, such as in step
expressions, it is possible to labelize by using the serialized array of steps as a key
matadata: {
labels: {
'0,10': 'Group A',
'10,20': 'Group B',
},
}
Handle layers
Layers can be added or removed from legend at any moment by using legend.addLayers()
with same format as layers
option and legend.removeLayers([layerIds])
.
Styles
Legend defaults to a simple design inspired by standard mapbox-gl controls, but can be tunned by changing CSS variables. Check default values in /src/styles/_variables.scss
Development
Create a .env
file and set your Mapbox token as VITE_MAPBOX_TOKEN
.
Run the development server with the command
npm run dev