Colors, colorscales & colorbars

Holochart colors work like Plotly's: any CSS color string for one color, a colorway that gives each trace its default color, and colorscales that map numbers to colors. This page covers all three, plus the palettes and scales that ship with Holochart and how to add your own.

Color formats

Every color attribute accepts a CSS color string: a name ('tomato'), hex ('#1f77b4', '#1f77b480' with alpha), rgb()/rgba(), hsl()/hsla(), or 'transparent'. Holochart stores colors in canonical rgb()/rgba() form in fullLayout/fullData, so the same color written two ways compares equal. Attributes marked arrayOk (such as marker.color) also take one color per point.

Colorways and qualitative palettes

layout.colorway is the list of default trace colors, used in trace order and cycled when there are more traces than colors. The default look (the holochart template) has eight colors: red #ea2a37, blue #5e74d5, indigo #9962c0, emerald #118e36, orange #cc540a, teal #128b8b, gold #997600 and magenta #b8267e. plotly-classic (Plotly's look) uses D3's category10, the same as Plotly.js, and every other theme sets its own.

import { colorways, QUALITATIVE } from '@mk7s/holochart';

createChart(el, {
  data,
  layout: { colorway: QUALITATIVE.Bold }, // or colorways.get('Bold')
});

QUALITATIVE holds every palette of plotly.py's plotly.colors.qualitative: Plotly, D3, G10, T10, Alphabet, Dark24, Light24, Set1–3, Pastel1–2, Dark2, Antique, Bold, Pastel, Prism, Safe, Vivid, Accent and Paired. colorways.register(name, colors) adds your own, and colorways.get(name) looks any of them up by name (case-insensitive). layout.colorway also takes a palette's name: colorway: 'Bold'. Swatches are in the reference.

Colorscales

A colorscale maps numbers to colors. Pass numbers to a color attribute that supports colorscales (marker.color, marker.line.color) and name the scale:

const temperature = [12.5, 17.1, 21.8, 26.4];

const trace = {
  type: 'scatter',
  mode: 'markers',
  x: [1, 2, 3, 4],
  y: [3, 1, 4, 2],
  marker: { color: temperature, colorscale: 'Viridis', showscale: true },
};

colorscale takes:

• a name, matched case-insensitively: 'Viridis', 'thermal', 'RdBu', …;
• a reversed name: add _r ('Viridis_r'), or set reversescale: true;
• a list of colors, spread evenly from 0 to 1: ['#000', 'orange', '#fff']. A plain list needs autocolorscale: false next to it: without that, the list is ignored and the automatic colorscale is drawn. Names and stops don't need it;
• [position, color] stops from 0 to 1: [[0, 'navy'], [0.8, 'gold'], [1, 'white']].

The domain is the data's extent unless you set cmin/cmax; cmid makes an automatic domain symmetric around a value (for diverging data). Traces that set the same coloraxis ('coloraxis', 'coloraxis2', …) share one scale, one domain and one colorbar through layout.coloraxis.

When colorscale is not given (autocolorscale), the scale is picked from the sign of the domain: layout.colorscale.sequential for values ≥ 0, sequentialminus for values ≤ 0, and diverging for domains that cross 0. In the default look, brighter means further from zero:

• sequential is a "neon plasma" ramp, from a deep violet (which still shows on the background) through violet, magenta and orange to pale yellow;
• sequentialminus mirrors it in cool hues, pale cyan at the most negative value fading to a dark blue at zero;
• diverging has a muted #4b475c midpoint, blue to cyan for negative values and magenta to orange for positive ones.

With plotly-classic (or template: 'none') they are Plotly's Reds, Blues and RdBu, and other themes set their own (plotly uses Plasma, simple_white Viridis).

Loading example…

Loading source…

scatter/colorscale

Built-in colorscales

Every scale of plotly.py's plotly.colors is built in: the plotly.js scales, Plotly3, Viridis, Cividis, Inferno, Magma, Plasma and Turbo; ColorBrewer's sequential and diverging scales; all of cmocean and CARTO; and the cyclical Twilight, IceFire, Edge, Phase, HSV, mrybm and mygbm. That is 94 names, 188 with their _r variants. The reference shows all of them.

A few names exist twice in plotly.py: plotly.colors.sequential.Blues is ColorBrewer's 9-class scale, but the string 'Blues' has always meant plotly.js's older scale. Holochart keeps Plotly's meaning for the string (so charts look the same as in Plotly) and exports the other lists as values: COLORBREWER_SEQUENTIAL.Blues, SEQUENTIAL.Viridis, and so on.

Bundle size

The full @mk7s/holochart bundle registers every scale and palette. With the runtime and individual traces only (a partial bundle), only the names every bundle has are available until you call registerBuiltinColors() once, or register just the scales you use: colors.register('tempo', CMOCEAN_SEQUENTIAL.tempo). The data is tree-shaken otherwise, so a scatter-only page does not ship a hundred colorscales.

Your own colorscales

import { colors } from '@mk7s/holochart';

colors.register('Brand', ['#0b1f3a', '#1d6fa5', '#9ad0ec']);
colors.register('Traffic', [
  [0, 'seagreen'],
  [0.6, 'gold'],
  [1, 'crimson'],
]);

// Then, anywhere: marker: { color: values, colorscale: 'Brand' }  (or 'Brand_r')

Registering a name that exists replaces it (names are case-insensitive). register returns a function that unregisters the scale. colors.get(name) returns a scale's stops, colors.names() lists every name, and colors.reverse(stops) mirrors a scale.

Interpolation spaces

Between stops, Plotly interpolates colors in sRGB, and so does Holochart by default. sRGB midpoints of distant colors are often dull or dark (red to blue passes through a muddy purple). layout.colorscaleInterpolation picks another space for every colorscale in the chart:

Value	Space
rgb	sRGB, as Plotly (default)
oklab	Oklab: perceptually even steps
lab	CIE L*a*b* (D65)
hcl	CIE LCh: Lab in polar form, hue along the shorter arc; keeps saturation

createChart(el, { data, layout: { colorscaleInterpolation: 'oklab' } });

The space is baked into the colorscale texture on the GPU, the colorbar and hover colors alike, so everything matches. For example, the midpoint of black and white is rgb(128,128,128) in sRGB, rgb(99,99,99) in Oklab and rgb(119,119,119) in Lab (Lab and Oklab put perceptual middle gray darker). The same ramps in each space:

Scale	rgb	oklab	lab	hcl
red → blue
black → yellow
RdBu (plotly.js)

Colorbars

marker.showscale: true draws a colorbar for the trace's colorscale (a color axis draws one for all its traces). marker.colorbar takes the whole axis tick API (dtick, tickformat, ticksuffix, …) plus title, orientation ('v' or 'h'), thickness, len, position (x, y, anchors and refs) and outline/border/background styling. Themes style colorbars too: plotly removes the outline and ticks, simple_white draws outside ticks.

Swatches

Colorscales & palettes shows every built-in colorscale and palette with a swatch drawn from its stops. That page is generated from the color registries, and it also lists the names that have two definitions and which one a name resolves to.

Not supported

• Holochart has no colorblind-safety checker: nothing warns when adjacent colorway colors are hard to tell apart under deuteranopia. The Safe palette and the accessibility guide cover colorblind-safe colors.

See also: Styling & themes, Themes & templates, and the colorscales gallery.