Skip to main content

Themes

A theme is a named color palette that bundles the map background, the default land fill, border strokes, text colors, and the choropleth ramp (sequential, diverging, and categorical). Picking a theme sets the entire visual identity of the map with a single URL parameter.

There are six themes: three with light backgrounds and three with dark backgrounds.

Examples​

All examples use the same data so the palettes are directly comparable.

light — white background, green sequential ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=light
World map — light theme

light-blue — off-white background, blue sequential ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=light-blue
World map — light-blue theme

light-mono — near-white background, greyscale ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=light-mono
World map — light-mono theme

dark — navy background, amber sequential ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=dark
World map — dark theme

dark-blue — deep-blue background, blue sequential ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=dark-blue
World map — dark-blue theme

dark-mono — near-black background, greyscale ramp

https://api.maproll.io/map.svg?scope=world&data=US:5,CN:4,IN:3,BR:2,RU:1&theme=dark-mono
World map — dark-mono theme

Parameters​

ParamTypeDefaultAllowedNotes
themestringdarklight, light-blue, light-mono, dark, dark-blue, dark-monoCase-sensitive. Returns 400 if unrecognised.

Picking a theme​

light — best for print, editorial contexts, and embedding on white-background pages. Sequential ramp is green; diverging extremes are red/blue.

light-blue — same white-family background as light but with a blue sequential ramp. Works well for data that reads as "volume" or "flow" (traffic, imports, connectivity).

light-mono — greyscale background, land, and sequential ramp. Useful for publications that print in black-and-white, or for accessibility contexts where color cannot be the sole differentiator. Note that only the sequential ramp is greyscale: colorScale=diverging and colorScale=categorical fall back to the same colored ramps the other light themes use.

dark — navy background with an amber sequential ramp. The strongest visual contrast of the six themes; stands out in dark-mode dashboards and slide decks.

dark-blue — consistent blue across background, land, and ramp. Works well when the map is a supporting visual on a dark-branded page and you want tonal coherence.

dark-mono — near-black background with a grey sequential ramp. The most minimal option; lets annotations, markers, and routes carry the visual weight. As with light-mono, the diverging and categorical ramps are the shared colored ones, not greyscale.

Notes​

  • Ramps are tuned for contrast against the theme's land color, so the lowest-value region is always visually distinct from a no-data region. The enforced thresholds are: every sequential stop and both diverging extremes at a WCAG contrast ratio of at least 1.4:1 against land, and the diverging midpoint at least 1.15:1 (deliberately subtler — the midpoint should read as "neutral").
  • Sequential and diverging ramps are 7 stops each; the categorical palette is 8 stops.
  • The diverging and categorical ramps are shared: all three light themes use the same pair, and all three dark themes use another. Only the sequential ramp is unique per theme.
  • The highlight color (used in regions-only mode, when no data= values are provided) is theme-specific: #2563eb for light, #60a5fa for dark, and so on.
  • Passing an unknown theme name returns 400 with {"error":"invalid_theme", ...}.