Skip to main content

Legend

The legend explains the color ramp used in a choropleth map. It can be shown or hidden, given a custom heading, and rendered in one of three layouts depending on the map's shape and the nature of the data.

Examples​

Vertical (default) — stacked swatches

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40&legendTitle=GDP&legendLayout=vertical
World choropleth with a vertical legend stacked in the bottom-right

Horizontal — swatches in a row

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40&legendTitle=GDP&legendLayout=horizontal
World choropleth with a horizontal legend row at the bottom-right

Continuous — smooth gradient bar

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80&legendTitle=GDP&legendLayout=continuous
World choropleth with a continuous gradient legend bar and min/mid/max labels

Parameters​

ParamTypeDefaultAllowedNotes
legendbooleantruetrue / falseShow or hide the legend entirely.
legendTitlestring—Up to 64 charactersHeading text above the legend. Omit for no heading.
legendLayoutstringverticalvertical / horizontal / continuousControls the visual shape of the legend.

Notes​

Vertical stacks swatch-and-label rows from bottom to top (low values at the bottom — the standard cartographic convention). Works for any number of bins and aspect ratio.

Horizontal arranges swatches left to right with labels underneath. A good choice for wide, banner-aspect maps where vertical real-estate is limited.

Continuous renders a single <linearGradient> bar with three labels: minimum (left), midpoint (centre), maximum (right). The midpoint label is omitted when fewer than three stops exist. This layout works best with sequential or diverging color scales where bin boundaries are not meaningful — it communicates "low to high" without implying discrete steps.

Continuous + categorical — using legendLayout=continuous with colorScale=categorical does not make sense semantically. The renderer will fall back to discrete swatches in that case.

Legend and logo stacking. When logo=true, the legend's vertical position is shifted upward automatically so the legend and wordmark stack rather than overlap. All three layouts respect this shift.

No legend with no data. When a map is rendered without any data= or regions= values (highlight-only mode), the legend is not shown regardless of the legend parameter, because there is no scale to describe.