Skip to content

Color scales

Every colormap that ships with matplotlib is available by name, plus your own. Use them wherever a chart maps a number to a color: heatmaps, choropleths, point maps, treemaps colored by change and word clouds.

plot({ type: 'heatmap', data, x: 'hour', y: 'day', value: 'trips', colorScale: 'viridis' });
plot({ type: 'choropleth', geo: 'chile', data, key: 'region', value: 'change', colorScale: 'RdBu' });
plot({ ...spec, colorScale: 'magma_r' });                       // _r reverses any map
plot({ ...spec, colorScale: ['#FFF7EC', '#FC8D59', '#7F0000'] }); // your own stops
plot({ ...spec, colorScale: { name: 'coolwarm', mid: 100 } });    // diverging around 100
  • Names are case-insensitive ('rdbu' works) and _r reverses any map.
  • Diverging maps center themselves: on 0 when the data crosses zero, otherwise on the middle of the data. Set mid (or midpoint) to choose the center.
  • Your own scale is a list of two or more colors, evenly spaced from low to high, or { colors, reverse, mid }.
  • Interpolation happens in OKLab, so steps look even. The stops were sampled from matplotlib 3.9 and stay within 2 ΔE (×100) of the original.
  • cmap and colormap are aliases of colorScale. The older ramp option still works.

Classes

Give breaks and the scale becomes discrete classes: a value falls in class i when breaks[i-1] ≤ v < breaks[i].

plot({ ...spec, colorScale: { colors: ['#2166AC', '#92C5DE', '#F7F7F7', '#F4A582', '#B2182B'], breaks: [-1, -0.25, 0.25, 1] } });
plot({ ...spec, colorScale: { name: 'Blues', breaks: [10, 20, 40] } });   // 4 classes sampled from Blues

colors needs one more entry than breaks (or give name and it is sampled). Works in heatmaps, choropleths and treemaps colored by change (breaks as fractions: 0.1 is 10%). The legend becomes a stepped key, one swatch per class, with the breaks written under it through format. A mismatch between breaks and colors is a lint error with the fix.

A value equal to a break goes to the class above it. closed: "right" puts it in the class below (breaks[i-1] < v ≤ breaks[i]), as in a key that reads "up to 10". Repeated breaks (quantiles of data with ties) are merged: the class between them would be empty, so it and its color drop out (lint says so).

Categorical palettes

palette takes a list of colors, a plotagents palette, or one of matplotlib's qualitative maps:

plot({ ...spec, palette: 'tab10' });
plot({ ...spec, palette: 'Set2' });
plot({ ...spec, palette: 'viridis' });   // a continuous map, sampled into distinct colors

The default palette is validated for color-vision deficiencies; lint checks any other palette you bring (see Themes).

Which one?

DataUseAvoid
Ordered values, low → highviridis, cividis, magma, Blues, YlGnBujet, rainbow, hsv (they invent edges where the data has none)
Values around a meaningful center (0, a target, an average)RdBu, coolwarm, PuOr, BrBGa sequential map
Angles, hours of the day, monthstwilight, hsva sequential map
Categoriespalette: 'tab10', 'Set2', 'Dark2'any continuous map as colorScale

lint flags the rainbow maps with a suggestion, and refuses a qualitative map used as a continuous scale.

All scales

Sequential

viridis
plasma
inferno
magma
cividis
Greys
Purples
Blues
Greens
Oranges
Reds
YlOrBr
YlOrRd
OrRd
PuRd
RdPu
BuPu
GnBu
PuBu
YlGnBu
PuBuGn
BuGn
YlGn
binary
gist_yarg
gist_gray
gray
bone
pink
spring
summer
autumn
winter
cool
Wistia
hot
afmhot
gist_heat
copper
ocean
gist_earth
terrain
gist_stern
gnuplot
gnuplot2
CMRmap
cubehelix
brg
gist_rainbow
rainbow
jet
turbo
nipy_spectral
gist_ncar

Diverging

PiYG
PRGn
BrBG
PuOr
RdGy
RdBu
RdYlBu
RdYlGn
Spectral
coolwarm
bwr
seismic

Cyclic

twilight
twilight_shifted
hsv

Qualitative (for palette)

Pastel1
Pastel2
Paired
Accent
Dark2
Set1
Set2
Set3
tab10
tab20
tab20b
tab20c

The list is also available in code: colorScaleNames() returns the names grouped by kind, and resolveColorScale(name) returns { name, stops, kind }.

Edit this page on GitHub