chroma.js

chroma.js is a small-ish zero-dependency JavaScript library (13.5kB) for all kinds of color conversions and color scales.

Quick-start

Here are a couple of things chroma.js can do for you:

read colors from a wide range of formats
analyze and manipulate colors
convert colors into wide range of formats
linear and bezier interpolation in different color spaces

Here's an example for a simple read / manipulate / output chain:


xxxxxxxxxx
 
chroma('pink').darken().saturate(2).hex()
"#ff6d93"

Aside from that, chroma.js can also help you generate nice colors using various methods, for instance to be used in color palette for maps or data visualization.


xxxxxxxxxx
 
chroma.scale(['#fafa6e', '#2A4858'])
    .mode('lch').colors(6)
['#fafa6e','#9cdf7c','#4abd8c','#00968e','#106e7c','#2a4858']

chroma.js has a lot more to offer, but that's the gist of it.

Installation

For Node.js: Install the chroma-js npm module using your favorite package manager:


AخA
 
npm install chroma-js
# pnpm add chroma-js
# yarn add chroma-js

Then import the module into your JavaScript:


xxxxxxxxxx
 
import chroma from 'chroma-js';

If you just want to use parts of chroma.js and not bundle the entire package, you can import directly from chroma-js/src/* to benefit from treeshaking. For instance, the following import would only result in a 1.24kB bundle increase:


xxxxxxxxxx
 
import deltaE from 'chroma-js/src/utils/deltaE.js

And for browsers, download chroma.min.js or use the hosted version on unpkg.com.

You can also just import chroma.js as ES module, as demonstrated in this StackBlitz.

To use chroma.js in Observable notebooks, you can import it like this:


xxxxxxxxxx
 
import { chroma } from "@gka/chroma-js"

The interactive documentation continues below (and there's a static version, too) for usage examples. Or use it from SASS using chromatic-sass!

API

chroma

(color)

The first step is to get your color into chroma.js. That's what the generic constructor chroma() does. This function attempts to guess the format of the input color for you. For instance, it will recognize any named color from the W3CX11 specification:


xxxxxxxxxx
 
chroma('hotpink')
#ff69b4

If there's no matching named color, chroma.js checks for a hexadecimal string. It ignores case, the # sign is optional, and it can recognize the shorter three letter format as well. So, any of these are valid hexadecimal representations: #ff3399, FF3399, #f39, etc.


xxxxxxxxxx
 
chroma('#ff3399');
chroma('F39');
#ff3399
#ff3399

In addition to hex strings, hexadecimal numbers (in fact, just any number between 0 and 16777215) will be recognized, too.


xxxxxxxxxx
 
chroma(0xff3399)
#ff3399

You also can pass RGB values individually. Each parameter must be within 0..255. You can pass the numbers as individual arguments or as an array.


xxxxxxxxxx
 
chroma(0xff, 0x33, 0x99);
chroma(255, 51, 153);
chroma([255, 51, 153]);
#ff3399
#ff3399
#ff3399

You can construct colors from different color spaces by passing the name of color space as the last argument. Here we define the same color in HSL by passing the hue angle (0-360) and percentages for saturation and l*ightness:


xxxxxxxxxx
 
chroma(330, 1, 0.6, 'hsl')
#ff3399

New (since 2.0): you can also construct colors by passing an plain JS object with attributes corresponding to a color space supported by chroma.js:


xxxxxxxxxx
 
chroma({ h:120, s:1, l:0.75});
chroma({ l:80, c:25, h:200 });
chroma({ c:1, m:0.5, y:0, k:0.2});
#80ff80
#85d4d5
#0066cc

chroma.valid

Also new: you can use chroma.valid to try if a color argument can be correctly parsed as color by chroma.js:


xxxxxxxxxx
 
chroma.valid('red');
chroma.valid('bread');
chroma.valid('#F0000D');
chroma.valid('#FOOOOD');
true
false
true
false

chroma.hsl

(hue, saturation, lightness)

Alternatively, every color space has its own constructor function under the chroma namespace. For a list of all supported color spaces, check the appendix.


xxxxxxxxxx
 
chroma.hsl(330, 1, 0.6)
#ff3399

chroma.hsv

(hue, saturation, value)

chroma.lab

(Lightness, a, b)

CIE Lab color space. To calculate the lightness value of a color, the CIE Lab color space uses a reference white point. This reference white point defines what is considered to be "white" in the color space. By default chroma.js is using the D65 reference point.


xxxxxxxxxx
 
chroma.lab(40, -20, 50);
chroma.lab(50, -20, 50);
chroma.lab(80, -20, 50);
#536600
#6e7f15
#c0cf66

chroma.setLabWhitePoint

(whitePoint)

Sets the current CIE Lab white reference point.

Possible values:


`D50`	Represents the color temperature of daylight at 5000K.
`D55`	Represents mid-morning or mid-afternoon daylight at 5500K.
`D65`	Represents average daylight at 6500K.
`A`	Represents the color temperature of a typical incandescent light bulb at approximately 2856K.
`B`	Represents noon daylight with a color temperature of approximately 4874K.
`C`	Represents average or north sky daylight; it's a theoretical construct, not often used in practical applications.
`F2`	Represents cool white fluorescent light.
`F7`	This is a broad-band fluorescent light source with a color temperature of approximately 6500K.
`F11`	This is a narrow tri-band fluorescent light source with a color temperature of approximately 4000K.
`E`	Represents an equal energy white point, where all wavelengths in the visible spectrum are equally represented.


xxxxxxxxxx
 
chroma('hotpink').lab();
chroma.setLabWhitePoint('F2');
chroma('hotpink').lab();
[65.49,64.24,-10.65]
 
[66.28,61.45,-8.62]

chroma.getLabWhitePoint

Returns the name of the currently set CIE Lab white reference point.


xxxxxxxxxx
 
chroma.getLabWhitePoint();
"D65"

chroma.lch

(Lightness, chroma, hue)

The range for lightness and chroma depend on the hue, but go roughly from 0..100-150. The range for hue is 0..360.


xxxxxxxxxx
 
chroma.lch(80, 40, 130);
chroma(80, 40, 130, 'lch');
#aad28c
#aad28c

chroma.hcl

(hue, chroma, lightness)

You can use hcl instead of Lch. Lightness and hue channels are switched to be more consistent with HSL.


xxxxxxxxxx
 
chroma.hcl(130, 40, 80);
chroma(130, 40, 80, 'hcl');
#aad28c
#aad28c

chroma.oklab

(Lightness, a, b)

Oklab color space


xxxxxxxxxx
 
chroma.oklab(0.4,-0.2,0.5);
chroma.oklab(0.5,-0.2,0.5);
chroma.oklab(0.8,-0.2,0.5);
#624400
#806100
#d9c500

chroma.oklch

(Lightness, chromacity, hue)


xxxxxxxxxx
 
chroma.oklch(0.5, 0.2, 240);
chroma(0.8, 0.12, 60, 'oklch');
#0069c7
#f6ab6b

chroma.cmyk

(cyan, magenta, yellow, black)

Each between 0 and 1.


xxxxxxxxxx
 
chroma.cmyk(0.2, 0.8, 0, 0);
chroma(0.2, 0.8, 0, 0, 'cmyk');
#cc33ff
#cc33ff

chroma.gl

(red, green, blue, [alpha])

GL is a variant of RGB(A), with the only difference that the components are normalized to the range of 0..1.


xxxxxxxxxx
 
chroma.gl(0.6, 0, 0.8);
chroma.gl(0.6, 0, 0.8, 0.5);
chroma(0.6, 0, 0.8, 'gl');
#9900cc
#9900cc80
#9900cc

chroma.temperature

(K)

Returns a color from the color temperature scale. Based on Neil Bartlett's implementation.


xxxxxxxxxx
 
chroma.temperature(2000); // candle light
chroma.temperature(3500); // sunset
chroma.temperature(6500); // daylight
#ff8b14
#ffc38a
#fffafe

The effective temperature range goes from 0 to about 30000 Kelvin,


xxxxxxxxxx
 
f = function(i) {
    return chroma.temperature(i * 30000)
}
00.51

chroma.mix

(color1, color2, ratio=0.5, mode='lrgb')

Mixes two colors. The mix ratio is a value between 0 and 1.


xxxxxxxxxx
 
chroma.mix('red', 'blue');
chroma.mix('red', 'blue', 0.25);
chroma.mix('red', 'blue', 0.75);
#b400b4
#dd0080
#8000dd

The color mixing produces different results based the color space used for interpolation.


xxxxxxxxxx
 
chroma.mix('red', 'blue', 0.5, 'rgb');
chroma.mix('red', 'blue', 0.5, 'hsl');
chroma.mix('red', 'blue', 0.5, 'lab');
chroma.mix('red', 'blue', 0.5, 'lch');
chroma.mix('red', 'blue', 0.5, 'lrgb');
#800080
#ff00ff
#ca0088
#fa0080
#b400b4

chroma.average

(colors, mode='lrgb', weights=[])

Similar to chroma.mix, but accepts more than two colors. Simple averaging of R,G,B components and the alpha channel.


xxxxxxxxxx
 
colors = ['#ddd', 'yellow', 'red', 'teal'];
chroma.average(colors); // lrgb
chroma.average(colors, 'rgb');
chroma.average(colors, 'lab');
chroma.average(colors, 'lch');
['#dddddd','#ffff00','#ff0000','#008080']
#d3b480
#b79757
#d3a96a
#ef9e4e

Also works with alpha channels.


xxxxxxxxxx
 
chroma.average(['red', 'rgba(0,0,0,0.5)']).css();
"rgb(180 0 0 / 0.75)"

As of version 2.1 you can also provide an array of weights to
compute a weighted average of colors.


xxxxxxxxxx
 
colors = ['#ddd', 'yellow', 'red', 'teal'];
chroma.average(colors, 'lch'); // unweighted
chroma.average(colors, 'lch', [1,1,2,1]);
chroma.average(colors, 'lch', [1.5,0.5,1,2.3]);
['#dddddd','#ffff00','#ff0000','#008080']
#ef9e4e
#f98841
#ae9e52

chroma.blend

(color1, color2, mode)

Blends two colors using RGB channel-wise blend functions. Valid blend modes are multiply, darken, lighten, screen, overlay, burn, and dodge.


xxxxxxxxxx
 
chroma.blend('4CBBFC', 'EEEE22', 'multiply');
chroma.blend('4CBBFC', 'EEEE22', 'darken');
chroma.blend('4CBBFC', 'EEEE22', 'lighten');
#47af22
#4cbb22
#eeeefc

chroma.random

()

Creates a random color by generating a random hexadecimal string.


xxxxxxxxxx
 
chroma.random();
chroma.random();
chroma.random();
#11c986
#066db9
#1c055c

chroma.contrast

(color1, color2)

Computes the WCAG contrast ratio between two colors. A minimum contrast of 4.5:1 is recommended to ensure that text is still readable against a background color.


xxxxxxxxxx
 
// contrast smaller than 4.5 = too low
chroma.contrast('pink', 'hotpink');
// contrast greater than 4.5 = high enough
chroma.contrast('pink', 'purple');
1.721
6.124

chroma.contrastAPCA

(text, background)

New (3.1): Computes the APCA contrast ratio of a text color against its background color. The basic idea is that you check the contrast between the text and background color and then use this lookup table to find the minimum font size you're allowed to use (given the font weight and purpose of the text).


xxxxxxxxxx
 
chroma.contrastAPCA('hotpink', 'pink');
chroma.contrastAPCA('purple', 'pink');
23.746
62.534

Read more about how to interpret and use this metric at APCA Readability Criterion. Please note that the APCA algorithm is still in beta and may change be subject to changes in the future.

chroma.distance

(color1, color2, mode='lab')

Computes the Euclidean distance between two colors in a given color space (default is Lab).


xxxxxxxxxx
 
chroma.distance('#fff', '#ff0', 'rgb');
chroma.distance('#fff', '#f0f', 'rgb');
chroma.distance('#fff', '#ff0');
chroma.distance('#fff', '#f0f');
255
255
96.948
122.163

chroma.deltaE

(color1, color2, Kl=1, Kc=1, Kh=1)

Computes color difference as developed by the International Commission on Illumination (CIE) in 2000. The implementation is based on the formula from Bruce Lindbloom. Resulting values range from 0 (no difference) to 100 (maximum difference), and are a metric for how the human eye percieves color difference. The optional parameters Kl, Kc, and Kh may be used to adjust weightings of lightness, chroma, and hue.


xxxxxxxxxx
 
chroma.deltaE('#ededee', '#ededee');
chroma.deltaE('#ededee', '#edeeed');
chroma.deltaE('#ececee', '#eceeec');
chroma.deltaE('#e9e9ee', '#e9eee9');
chroma.deltaE('#e4e4ee', '#e4eee4');
chroma.deltaE('#e0e0ee', '#e0eee0');
chroma.deltaE('#000000', '#ffffff');
0
1.321
2.602
6.221
11.598
15.391
100

chroma.brewer

chroma.brewer is an map of ColorBrewer palettes that are included in chroma.js for convenience. chroma.scale uses the colors to construct.


xxxxxxxxxx
 
chroma.brewer.OrRd
['#fff7ec','#fee8c8','#fdd49e','#fdbb84','#fc8d59','#ef6548','#d7301f','#b30000','#7f0000']

Note that chroma.js only includes the 9-step versions of the palettes (11 steps for the diverging palettes). So, for instance, if you use chroma.js to construct a 5-color palette, they will be different from the "official" 5-color palettes in ColorBrewer (which have lower contrast).


xxxxxxxxxx
 
chroma.scale('RdBu').colors(5);
// offical 5-color RdBu:
['#ca0020', '#f4a582', '#f7f7f7', '#92c5de', '#0571b0']
['#67001f','#e58368','#f7f7f7','#6bacd1','#053061']
['#ca0020','#f4a582','#f7f7f7','#92c5de','#0571b0']

One way to compensate for this would be to "slice off" the extreme colors:


xxxxxxxxxx
 
chroma
    .scale(chroma.brewer.RdBu.slice(1,-1))
    .colors(5);
['#b2182b','#f4a582','#f7f7f7','#92c5de','#2166ac']

Of course you can also just construct the scale from the official 5-step colors that you can copy and paste from colorbrewer2.org:


xxxxxxxxxx
 
chroma.scale(['#ca0020', '#f4a582', '#f7f7f7', '#92c5de', '#0571b0'])
00.51

You can access a list of all available palettes via Object.keys(chroma.brewer):


xxxxxxxxxx
 
Object.keys(chroma.brewer)
// ['OrRd', 'PuBu', 'BuPu', 'Oranges', 'BuGn', 'YlOrBr', 'YlGn', 'Reds', 'RdPu', 'Greens', 'YlGnBu', 'Purples', 'GnBu', 'Greys', 'YlOrRd', 'PuRd', 'Blues', 'PuBuGn', 'Viridis', 'Spectral', 'RdYlGn', 'RdBu', 'PiYG', 'PRGn', 'RdYlBu', 'BrBG', 'RdGy', 'PuOr', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1']

chroma.limits

(data, mode, n)

A helper function that computes class breaks for you, based on data. It supports the modes equidistant (e), quantile (q), logarithmic (l), and k-means (k). Let's take a few numbers as sample data.


xxxxxxxxxx
 
var data = [2.0,3.5,3.6,3.8,3.8,4.1,4.3,4.4,
            4.6,4.9,5.2,5.3,5.4,5.7,5.8,5.9,
            6.2,6.5,6.8,7.2,8];

equidistant breaks are computed by dividing the total range of the data into _n_ groups of equal size.


xxxxxxxxxx
 
chroma.limits(data, 'e', 4);
[2,3.5,5,6.5,8]

In the quantile mode, the input domain is divided by quantile ranges.


xxxxxxxxxx
 
chroma.limits(data, 'q', 4);
[2,4.1,5.2,5.9,8]

logarithmic breaks are equidistant breaks but on a logarithmic scale.


xxxxxxxxxx
 
chroma.limits(data, 'l', 4);
[2,2.83,4,5.66,8]

k-means break is using the 1-dimensional k-means clustering algorithm to find (roughly) _n_ groups of "similar" values. Note that this k-means implementation does not guarantee to find exactly _n_ groups.


xxxxxxxxxx
 
chroma.limits(data, 'k', 4);
[2,8]

color

color.alpha

(a)

Get and set the color opacity using color.alpha.


xxxxxxxxxx
 
chroma('red').alpha(0.5);
chroma('rgba(255,0,0,0.35)').alpha();
#ff000080
0.35

color.darken

(value=1)

Once loaded, chroma.js can change colors. One way we already saw above, you can change the lightness.


xxxxxxxxxx
 
chroma('hotpink').darken();
chroma('hotpink').darken(2);
chroma('hotpink').darken(2.6);
#c93384
#930058
#74003f

color.brighten

(value=1)

Similar to darken, but the opposite direction


xxxxxxxxxx
 
chroma('hotpink').brighten();
chroma('hotpink').brighten(2);
chroma('hotpink').brighten(3);
#ff9ce6
#ffd1ff
#ffffff

color.saturate

(value=1)

Changes the saturation of a color by manipulating the Lch chromaticity.


xxxxxxxxxx
 
chroma('slategray').saturate();
chroma('slategray').saturate(2);
chroma('slategray').saturate(3);
#4b83ae
#0087cd
#008bec

color.desaturate

(value=1)

Similar to saturate, but the opposite direction.


xxxxxxxxxx
 
chroma('hotpink').desaturate();
chroma('hotpink').desaturate(2);
chroma('hotpink').desaturate(3);
#e77dae
#cd8ca8
#b199a3

color.mix

(targetcolor, ratio=0.5, mode='lrgb')

Mix this color with a target color. The mix ratio is a value between 0 and 1. This is the same as chroma.mix but with the first parameter already set. As such, the color space used can be adjusted.


xxxxxxxxxx
 
chroma('hotpink').mix('blue');
chroma('hotpink').mix('blue', 0.25);
chroma('hotpink').mix('blue', 0.75, 'lab');
#b44add
#dd5bc9
#811ced

color.shade

(ratio=0.5, mode='lrgb')

Produce a shade of the color. This is syntactic sugar for color.mix with a target color of black.


xxxxxxxxxx
 
chroma('hotpink').shade(0.25);
chroma('hotpink').shade(0.5);
chroma('hotpink').shade(0.75);
#dd5b9c
#b44a7f
#80355a

color.tint

(ratio=0.5, mode='lrgb')

Produce a tint of the color. This is syntactic sugar for color.mix with a target color of white.


xxxxxxxxxx
 
chroma('hotpink').tint(0.25);
chroma('hotpink').tint(0.5);
chroma('hotpink').tint(0.75);
#ff9dc9
#ffc3dd
#ffe3ee

color.set

(channel, value)

Changes a single channel and returns the result a new chroma object.


xxxxxxxxxx
 
// change hue to 0 deg (=red)
chroma('skyblue').set('hsl.h', 0);
// set chromaticity to 30
chroma('hotpink').set('lch.c', 30);
#eb8787
#ce8ca9

Relative changes work, too:


xxxxxxxxxx
 
// half Lab lightness
chroma('orangered').set('lab.l', '*0.5');
// double Lch saturation
chroma('darkseagreen').set('lch.c', '*2');
#a10000
#63c56c

color.get

(channel)

Returns a single channel value.


xxxxxxxxxx
 
chroma('orangered').get('lab.l');
chroma('orangered').get('hsl.l');
chroma('orangered').get('rgb.g');
57.582
0.5
69

color.luminance

([lum, mode='rgb'])

If called without arguments color.luminance returns the relative brightness, according to the WCAG definition. Normalized to 0 for darkest black and 1 for lightest white.


xxxxxxxxxx
 
chroma('white').luminance();
chroma('aquamarine').luminance();
chroma('hotpink').luminance();
chroma('darkslateblue').luminance();
chroma('black').luminance();
1
0.808
0.347
0.066
0

chroma.js also allows you to adjust the luminance of a color. The source color will be interpolated with black or white until the correct luminance is found.


xxxxxxxxxx
 
// set lumincance to 50% for all colors
chroma('white').luminance(0.5);
chroma('aquamarine').luminance(0.5);
chroma('hotpink').luminance(0.5);
chroma('darkslateblue').luminance(0.5);
#bcbcbc
#67ceab
#ff9dce
#bcb8d5

By default, this interpolation is done in RGB, but you can interpolate in different color spaces by passing them as second argument:


xxxxxxxxxx
 
chroma('aquamarine').luminance(0.5); // rgb
chroma('aquamarine').luminance(0.5, 'lab');
chroma('aquamarine').luminance(0.5, 'hsl');
#67ceab
#69ceac
#00d68e

color.hex

(mode='auto|rgb|rgba|argb')

Finally, chroma.js allows you to output colors in various color spaces and formats. Most often you will want to output the color as hexadecimal string.


xxxxxxxxxx
 
chroma('orange').hex()
"#ffa500"

Note that as of version 1.4.0 the default mode is "auto" which means that the hex string will include the alpha channel if it's less than 1. If you don't want the alpha channel to be included you must explicitly set the mode to "rgb" now:


xxxxxxxxxx
 
chroma('orange').hex();
chroma('orange').alpha(0.5).hex();
chroma('orange').alpha(0.5).hex('rgb');
"#ffa500"
"#ffa50080"
"#ffa500"

You can use .hex('argb') in case you need to encode the color with the alpha channel as first byte rather than the last:


xxxxxxxxxx
 
chroma('orange').hex('argb');; // '#ffffa500'
"#ffffa500"

color.name

Returns the named color. Falls back to hexadecimal RGB string, if the color isn't present.


xxxxxxxxxx
 
chroma('#ffa500').name();
chroma('#ffa505').name();
"orange"
"#ffa505"

color.css

Returns a CSS string representation that can be used as CSS-color definition.


xxxxxxxxxx
 
chroma('teal').css();
chroma('teal').alpha(0.5).css();
"rgb(0 128 128)"
"rgb(0 128 128 / 0.5)"

By default chroma is using the rgb() color space, but you can pass a color space name as first argument. Accepted color spaces are rgb, hsl, lab, lch, oklab, and oklch.


xxxxxxxxxx
 
chroma('teal').css('hsl');
chroma('teal').css('lab');
chroma('teal').css('oklch');
"hsl(180deg 100% 25.1%)"
"lab(47.99% -30.39 -8.98)"
"oklch(54.31% 0.09 194.76deg)"

color.rgb

(round=true)

Returns an array with the red, green, and blue component, each as number within the range 0..255. Chroma internally stores RGB channels as floats but rounds the numbers before returning them. You can pass false to prevent the rounding.


xxxxxxxxxx
 
chroma('orange').rgb();
chroma('orange').darken().rgb();
chroma('orange').darken().rgb(false);
[255,165,0]
[198,118,0]
[198.05,118.11,0]

color.rgba

(round=true)

Just like color.rgb but adds the alpha channel to the returned array.


xxxxxxxxxx
 
chroma('orange').rgba();
chroma('hsla(20, 100%, 40%, 0.5)').rgba();
[255,165,0,1]
[204,68,0,0.5]

color.hsl

Returns an array with the hue, saturation, and lightness component. Hue is the color angle in degree (0..360), saturation and lightness are within 0..1. Note that for hue-less colors (black, white, and grays), the hue component will be NaN.


xxxxxxxxxx
 
chroma('orange').hsl();
chroma('white').hsl();
[38.82,1,0.5,1]
[NaN,0,1,1]

color.hsv

Returns an array with the hue, saturation, and value components. Hue is the color angle in degree (0..360), saturation and value are within 0..1. Note that for hue-less colors (black, white, and grays), the hue component will be NaN.


xxxxxxxxxx
 
chroma('orange').hsv();
chroma('white').hsv();
[38.82,1,1]
[NaN,0,1]

color.hsi

Returns an array with the hue, saturation, and intensity components, each as number between 0 and 255. Note that for hue-less colors (black, white, and grays), the hue component will be NaN.


xxxxxxxxxx
 
chroma('orange').hsi();
chroma('white').hsi();
[39.64,1,0.55]
[NaN,0,1]

color.lab

Returns an array with the L, a, and b components.


xxxxxxxxxx
 
chroma('orange').lab()
[74.94,23.93,78.95]

color.lch

Returns an array with the Lightness, chroma, and hue components.


xxxxxxxxxx
 
chroma('skyblue').lch()
[79.21,25.94,235.11]

color.hcl

Alias of lch, but with the components in reverse order.


xxxxxxxxxx
 
chroma('skyblue').hcl()
[235.11,25.94,79.21]

color.oklab

Returns an array with the L, a, and b components in the OKLab color space.


xxxxxxxxxx
 
chroma('orange').oklab()
[0.79,0.06,0.16]

color.oklch

Returns an array with the Lightness, chroma, and hue components in the OKLch color space.


xxxxxxxxxx
 
chroma('skyblue').oklch()
[0.81,0.08,225.74]

color.num

Returns the numeric representation of the hexadecimal RGB color.


xxxxxxxxxx
 
chroma('#000000').num();
chroma('#0000ff').num();
chroma('#00ff00').num();
chroma('#ff0000').num();
0
255
65280
16711680

color.temperature

Estimate the temperature in Kelvin of any given color, though this makes the only sense for colors from the temperature gradient above.


xxxxxxxxxx
 
chroma('#ff3300').temperature();
chroma('#ff8a13').temperature();
chroma('#ffe3cd').temperature();
chroma('#cbdbff').temperature();
chroma('#b3ccff').temperature();
1000
2000
4999
10115
15169

color.gl

Like RGB, but in the channel range of [0..1] instead of [0..255]


xxxxxxxxxx
 
chroma('33cc00').gl();
[0.2,0.8,0,1]

color.clipped

When converting colors from CIELab color spaces to RGB the color channels get clipped to the range of [0..255]. Colors outside that range may exist in nature but are not displayable on RGB monitors (such as ultraviolet). you can use color.clipped to test if a color has been clipped or not.


xxxxxxxxxx
 
[c = chroma.hcl(50, 40, 20), c.clipped()];
[c = chroma.hcl(50, 40, 40), c.clipped()];
[c = chroma.hcl(50, 40, 60), c.clipped()];
[c = chroma.hcl(50, 40, 80), c.clipped()];
[c = chroma.hcl(50, 40, 100), c.clipped()];
[#581d00,true]
[#904c2d,false]
[#c97e5c,false]
[#ffb38f,true]
[#ffebc5,true]

As a bonus feature you can access the unclipped RGB components using color._rgb._unclipped.


xxxxxxxxxx
 
chroma.hcl(50, 40, 100).rgb();
chroma.hcl(50, 40, 100)._rgb._unclipped;
[255,235,197]
[322.65,235.24,196.7,1]

color scales

chroma.scale

(colors=['white', 'black'])

A color scale, created with chroma.scale, is a function that maps numeric values to a color palette. The default scale has the domain 0..1 and goes from white to black.


xxxxxxxxxx
 
f = chroma.scale();
f(0.25);
f(0.5);
f(0.75);
00.51
#bfbfbf
#808080
#404040

You can pass an array of colors to chroma.scale. Any color that can be read by chroma() will work here, too. If you pass more than two colors, they will be evenly distributed along the gradient.


xxxxxxxxxx
 
chroma.scale(['yellow', '008ae5']);
chroma.scale(['yellow', 'red', 'black']);
00.51
00.51

scale.domain

(domain)

You can change the input domain to match your specific use case.


xxxxxxxxxx
 
// default domain is [0,1]
chroma.scale(['yellow', '008ae5']);
// set domain to [0,100]
chroma.scale(['yellow', '008ae5']).domain([0,100]);
00.51
050100

You can use the domain to set the exact positions of each color.


xxxxxxxxxx
 
// default domain is [0,1]
chroma.scale(['yellow', 'lightgreen', '008ae5'])
    .domain([0,0.25,1]);
00.51

scale.mode

(mode)

As with chroma.mix, the result of the color interpolation will depend on the color mode in which the channels are interpolated. The default mode is RGB:


xxxxxxxxxx
 
chroma.scale(['yellow', '008ae5']);
00.51

This is often fine, but sometimes, two-color RGB gradients goes through kind of grayish colors, and Lab interpolation produces better results:


xxxxxxxxxx
 
chroma.scale(['yellow', 'navy']);
chroma.scale(['yellow', 'navy']).mode('lab');
00.51
00.51

Also note how the RGB interpolation can get very dark around the center. You can achieve better results using linear RGB interpolation:


xxxxxxxxxx
 
chroma.scale(['#f00', '#0f0']);
chroma.scale(['#f00', '#0f0']).mode('lrgb');
00.51
00.51

Other useful interpolation modes could be HSL or Lch, though both tend to produce too saturated / glowing gradients.


xxxxxxxxxx
 
chroma.scale(['yellow', 'navy']).mode('lab');
chroma.scale(['yellow', 'navy']).mode('hsl');
chroma.scale(['yellow', 'navy']).mode('lch');
00.51
00.51
00.51

scale.gamma

Gamma-correction can be used to "shift" a scale's center more the the beginning (gamma < 1) or end (gamma > 1), typically used to "even" the lightness gradient. Default is 1.


xxxxxxxxxx
 
chroma.scale('YlGn').gamma(0.5);
chroma.scale('YlGn').gamma(1);
chroma.scale('YlGn').gamma(2);
00.51
00.51
00.51

scale.correctLightness

This makes sure the lightness range is spread evenly across a color scale. Especially useful when working with multi-hue color scales, where simple gamma correction can't help you very much.


x
 
chroma.scale(['black', 'red', 'yellow', 'white']);
chroma.scale(['black', 'red', 'yellow', 'white'])
    .correctLightness();
00.51
00.51

scale.cache

(true|false)

By default chroma.scale instances will cache each computed value => color pair. You can turn off the cache by setting


xxxxxxxxxx
 
chroma.scale(['yellow', '008ae5']).cache(false);
00.51

scale.padding

(pad)

Reduces the color range by cutting of a fraction of the gradient on both sides. If you pass a single number, the same padding will be applied to both ends.


xxxxxxxxxx
 
chroma.scale('RdYlBu');
chroma.scale('RdYlBu').padding(0.15);
chroma.scale('RdYlBu').padding(0.3);
chroma.scale('RdYlBu').padding(-0.15);
00.51
00.51
00.51
00.51

Alternatively you can specify the padding for each sides individually by passing an array of two numbers.


xxxxxxxxxx
 
chroma.scale('OrRd');
chroma.scale('OrRd').padding([0.2, 0]);
00.51
00.51

scale.colors

(num, format='hex')

You can call scale.colors(n) to quickly grab n equi-distant colors from a color scale. If called with no arguments, scale.colors returns the original array of colors used to create the scale.


xxxxxxxxxx
 
chroma.scale('OrRd').colors(5);
chroma.scale(['white', 'black']).colors(12);
['#fff7ec','#fdd49e','#fc8d59','#d7301f','#7f0000']
['#ffffff','#e8e8e8','#d1d1d1','#b9b9b9','#a2a2a2','#8b8b8b','#747474','#5d5d5d','#464646','#2e2e2e','#171717','#000000']

If you want to return chroma instances just pass null as format.

scale.classes

(numOrArray)

If you want the scale function to return a distinct set of colors instead of a continuous gradient, you can use scale.classes. If you pass a number the scale will broken into equi-distant classes:


xxxxxxxxxx
 
// continuous
chroma.scale('OrRd');
// class breaks
chroma.scale('OrRd').classes(5);
chroma.scale('OrRd').classes(8);
00.51
00.51
00.51

You can also define custom class breaks by passing them as array:


xxxxxxxxxx
 
chroma.scale('OrRd').classes([0,0.3,0.55,0.85,1]);
00.51

scale.nodata

(color)

When you pass a non-numeric value like null or undefined to a chroma.scale, "#cccccc" is returned as fallback or "no data" color. You can change the no-data color:


xxxxxxxxxx
 
chroma.scale('OrRd')(null);
chroma.scale('OrRd')(undefined);
chroma.scale('OrRd').nodata('#eee')(null);
#cccccc
#cccccc
#eeeeee

chroma.brewer

chroma.js includes the definitions from ColorBrewer2.org. Read more about these colors in the corresponding paper by Mark Harrower and Cynthia A. Brewer.


xxxxxxxxxx
 
chroma.scale('YlGnBu');
chroma.scale('Spectral');
00.51
00.51

To reverse the colors you could simply reverse the domain:


xxxxxxxxxx
 
chroma.scale('Spectral').domain([1,0]);
00.51

You can access the colors directly using chroma.brewer.


xxxxxxxxxx
 
chroma.brewer.OrRd
['#fff7ec','#fee8c8','#fdd49e','#fdbb84','#fc8d59','#ef6548','#d7301f','#b30000','#7f0000']

chroma.bezier

(colors)

chroma.bezier returns a function that bezier-interpolates between colors in Lab space. The input range of the function is [0..1].


xxxxxxxxxx
 
// linear interpolation
chroma.scale(['yellow', 'red', 'black']);
// bezier interpolation
chroma.bezier(['yellow', 'red', 'black']);
00.51
00.51

You can convert an bezier interpolator into a chroma.scale instance


xxxxxxxxxx
 
chroma.bezier(['yellow', 'red', 'black'])
    .scale()
    .colors(5);
['#ffff00','#f5a900','#bf5e0b','#6c280e','#000000']

cubehelix

chroma.cubehelix

(start=300, rotations=-1.5, hue=1, gamma=1, lightness=[0,1])

Dave Green's cubehelix color scheme!!


xxxxxxxxxx
 
// use the default helix...
chroma.cubehelix();
// or customize it
chroma.cubehelix()
    .start(200)
    .rotations(-0.5)
    .gamma(0.8)
    .lightness([0.3, 0.8]);
00.51
00.51

cubehelix.start

(hue)

start color for hue rotation, default=300


xxxxxxxxxx
 
chroma.cubehelix().start(300);
chroma.cubehelix().start(200);
00.51
00.51

cubehelix.rotations

(num)

number (and direction) of hue rotations (e.g. 1=360°, 1.5=540°`), default=-1.5


xxxxxxxxxx
 
chroma.cubehelix().rotations(-1.5);
chroma.cubehelix().rotations(0.5);
chroma.cubehelix().rotations(3);
00.51
00.51
00.51

cubehelix.hue

(numOrRange)

hue controls how saturated the colour of all hues are. either single value or range, default=1


xxxxxxxxxx
 
chroma.cubehelix();
chroma.cubehelix().hue(0.5);
chroma.cubehelix().hue([1,0]);
00.51
00.51
00.51

cubehelix.gamma

(factor)

gamma factor can be used to emphasise low or high intensity values, default=1


xxxxxxxxxx
 
chroma.cubehelix().gamma(1);
chroma.cubehelix().gamma(0.5);
00.51
00.51

cubehelix.lightness

(range)

lightness range: default: [0,1] (black -> white)


xxxxxxxxxx
 
chroma.cubehelix().lightness([0,1]);
chroma.cubehelix().lightness([1,0]);
chroma.cubehelix().lightness([0.3,0.7]);
00.51
00.51
00.51

cubehelix.scale

You can call cubehelix.scale() to use the cube-helix through the chroma.scale interface.


xxxxxxxxxx
 
chroma.cubehelix()
    .start(200)
    .rotations(-0.35)
    .gamma(0.7)
    .lightness([0.3, 0.8])
  .scale() // convert to chroma.scale
    .correctLightness()
    .colors(5);
['#46799d','#4f98a1','#64b69d','#94d09d','#d6e2bc']

Changelog

3.1.2

fixed a bug in Lch interpolation of hue-less colors

3.1.1

fix: allow deep-imports in vite projects

3.1.0

feat: parse 'transparent' as black with 0% opacity - resolves #280
make it easier to access colorbrewer palette names - resolves #314
docs: explain differences to official colorbrewer scales - resolves #316
fix: correct parsing of modern css colors with percentage alpha - resolves #297
fix: css output for hue-less colors in lch() and oklch() - resolves #357

3.0.0

🎉 NEW: Add support for modern CSS color spaces. This means you can now export and parse CSS colors in lab(), lch(), oklab(), oklch() space.
🎉 NEW: you can now control the standard white reference point for the CIE Lab and CIE Lch color spaces via setLabWhitePoint.
Breaking: color.css() will no longer return legacy CSS colors like rgb(255, 255, 0) but use modern CSS colors like rgb(255 255 0) instead.
fix: you can now use chroma.js both via the default export as well as named exports in ES6.
fix: switch to W3C implementation of OKLab color space

2.6.0

🎉 NEW: add color.shade(), color.tint().
fix: remove false w3c color cornflower

2.5.0

refactored code base to ES6 modules

2.4.0

add support for Oklab and Oklch color spaces

2.3.0

use binom of degree n in chroma.bezier

2.2.0

use Delta e2000 for chroma.deltaE #269

2.0.3

hsl2rgb will, like other x2rgb conversions now set the default alpha to 1

2.0.2

use a more mangle-safe check for Color class constructor to fix issues with uglifyjs and terser

2.0.1

added chroma.valid() for checking if a color can be parsed by chroma.js

2.0.0

chroma.js has been ported from CoffeeScript to ES6! This means you can now import parts of chroma in your projects!
changed HCG input space from [0..360,0..100,0..100] to [0..360,0..1,0..1] (to be in line with HSL)
added new object unpacking (e.g. hsl2rgb({h,s,l}))
changed default interpolation to lrgb in mix/interpolate and average.
if colors can't be parsed correctly, chroma will now throw Errors instead of silently failing with console.errors

1.4.1

chroma.scale() now interprets null as NaN and returns the fallback color. Before it had interpreted null as 0
added scale.nodata() to allow customizing the previously hard-coded fallback (aka "no data") color #cccccc

1.4.0

color.hex() now automatically sets the mode to 'rgba' if the colors alpha channel is < 1. so chroma('rgba(255,0,0,.5)').hex() will now return "#ff000080" instead of "#ff0000". if this is not what you want, you must explicitly set the mode to rgb using .hex("rgb").
bugfix in chroma.average in LRGB mode (#187)
chroma.scale now also works with just one color (#180)