Skip to main content

Color Overrides

Color overrides let you pin a specific hex color to one or more regions. The override wins over whatever color the scale would have assigned — the region still participates in binning, but its fill is fixed.

Use this when a region needs to stand out for categorical reasons unrelated to its value: a company's home country, a disputed territory, a brand-color highlight.

Examples​

Two overrides, one scale-derived​

Romania is forced red, Germany forced green, France follows the scale normally.

https://api.maproll.io/map.svg?scope=world&data=RO:1:%23ff0000,DE:2:%2300ff00,FR:3&theme=light
Color overrides on two regions

All overrides, legend off​

All regions in flat brand colors — no scale involved.

https://api.maproll.io/map.svg?scope=world&data=US:1:%231d4ed8,GB:1:%23dc2626,FR:1:%2316a34a,DE:1:%23ca8a04&theme=light&legend=false
All-override brand-color render, legend hidden

Parameters​

Color overrides are not a top-level parameter — they are embedded in the region data.

GET — data= syntax​

Append a third colon-delimited field to any id:value pair:

data=RO:120:%23ff0000,DE:95,FR:40:%2300ff00

# must be URL-encoded as %23. The color is optional per pair — omit it to let the scale decide.

POST — regions[].color​

{
  "scope": "world",
  "regions": [
    { "id": "RO", "value": 120, "color": "#ff0000" },
    { "id": "DE", "value": 95 },
    { "id": "FR", "value": 40, "color": "#00ff00" }
  ],
  "theme": "light"
}

POST — CSV body with color column​

id,value,color
RO,120,#ff0000
DE,95,
FR,40,#00ff00

The color column is only honored when the header contains the word color. A blank cell falls back to the scale.

FieldTypeNotes
colorstring6-digit hex only: #rrggbb. 3-digit shorthand, RGBA, and named colors are rejected.

Notes​

  • Strict 6-digit hex. #fff, rgba(...), and red are all rejected with a 400 error.
  • The override wins over the scale, regardless of the region's value. The value still influences the scale (and therefore neighboring regions' colors), but the overridden region always renders in the specified color.
  • The legend does not show overrides. The legend reflects scale stops only. This is intentional — overridden regions carry meaning outside the scale.
  • Patterns take precedence over color overrides. If a region has both a color and a pattern, the color becomes the pattern's foreground. See Patterns.
  • A region with a color but no value acts as a color-pinned highlight — it is not included in scale binning.
  • Data Input — full data= syntax reference
  • Patterns — SVG pattern fills; color overrides become the pattern foreground
  • Color Scales — how the scale-derived fill is computed when no override is present