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).

https://api.maproll.io/map.svg?scope=world&data=US:A,CN:B,RU:A,DE:C,FR:B,BR:A,IN:C,GB:B&theme=light&colorScale=categorical&legendTitle=Group
Categorical color scale

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.
  • 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