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