Skip to main content

Color Scales

maproll supports three color scale modes. Pick the one that matches the nature of your data: sequential for ordered magnitudes, diverging for values that span a zero midpoint, and categorical for unordered groups.

The scale is orthogonal to the theme — you can pair any scale with any theme.

Examples​

Sequential (default)​

Values from low to high, binned across the theme's sequential ramp. Default classification is quantile — each color step holds roughly the same number of regions.

https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,IN:80,BR:60,RU:120,DE:95,FR:40&theme=light&colorScale=sequential&legendTitle=GDP
Sequential color scale

Diverging​

Symmetric around zero. Values above zero pull toward one end of the ramp; values below zero pull toward the other. The midpoint is always anchored at zero.

https://api.maproll.io/map.svg?scope=world&data=US:5,CA:-3,MX:1,BR:-2,RU:-5,CN:8,IN:-1,AU:3,FR:-4,DE:6&theme=light&colorScale=diverging&legendTitle=%CE%94%25
Diverging color scale

Categorical​

Each distinct value receives its own color from the theme's categorical palette, in the order the values first appear. Useful for nominal groupings (region type, political alignment, tier).

Categorical works with either numeric codes (US:1,CN:2) or — more commonly — meaningful text labels (US:NATO,CN:BRICS). When you pass string labels via data=, the renderer auto-selects colorScale=categorical, so the colorScale=categorical query param is optional in that case.

https://api.maproll.io/map.svg?scope=world&data=US:NATO,GB:NATO,FR:NATO,DE:NATO,CN:BRICS,RU:BRICS,IN:BRICS,BR:BRICS&theme=light&legendTitle=Bloc
Categorical color scale with text-label buckets

Parameters​

ParamTypeDefaultAllowedNotes
colorScalestringsequentialsequential, diverging, categoricalGET query param or JSON body field.

Notes​

  • Sequential uses the classification strategy (quantile, jenks, equal, or custom breaks) to bin values across the ramp. See Classification.
  • Diverging ignores classification. It maps the range [-absMax, +absMax] linearly across the ramp, where absMax = max(|min value|, |max value|). This keeps the legend visually symmetric even when positive and negative values are unequal in magnitude.
  • Categorical ignores classification and breaks. It assigns each distinct value a color from the ramp in first-appearance order, cycling the palette if there are more categories than ramp stops.
  • Auto-selection on GET: when any data= pair has a string value (e.g. US:NATO) and you don't pass colorScale= explicitly, the renderer picks categorical automatically. Pass colorScale=sequential or colorScale=diverging to override this — string values are then filtered out and only numeric pairs render.
  • The classification param has no effect on diverging or categorical scales.
  • For diverging, a dataset where all values are the same sign still works — the legend will show one side of the ramp unused.
  • Classification — quantile, jenks, equal, custom breaks (sequential only)
  • Color Overrides — override specific regions regardless of scale
  • Themes — each theme ships its own sequential, diverging, and categorical ramps
  • Legend — vertical, horizontal, and continuous legend layouts