@types/chroma-js

property brewer

brewer: Record<BrewerPaletteName, string[]>;

• chroma.brewer is an map of ColorBrewer palettes that are included in chroma.js for convenience. Chroma.scale uses the colors to construct. 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).

property getLabWhitePoint

getLabWhitePoint: () => WhitePoint;

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

  Example 1

  chroma.getLabWhitePoint() // "D65"

property setLabWhitePoint

setLabWhitePoint: (whitePoint: WhitePoint) => void;

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

  Example 1

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

method average

average: (
    colors: ChromaInput[],
    mode?: InterpolationMode,
    weights?: number[]
) => Color;

• Similar to mix, but accepts more than two colors. Simple averaging of R,G,B components and the alpha channel. mode defaults to 'lrgb'. You can also provide an array of weights to compute a weighted average of colors.

  Example 1

  colors = ['#ddd', 'yellow', 'red', 'teal']
  chroma.average(colors) // #d3b480
  chroma.average(colors, 'rgb') // #b79757
  chroma.average(colors, 'lab') // #d3a96a
  chroma.average(colors, 'lch') // #ef9e4e
  chroma.average(colors, 'lch', [1,1,2,1]) // #f98841
  chroma.average(colors, 'lch', [1.5,0.5,1,2.3]) // #ae9e52

method bezier

bezier: (colors: string[]) => { (t: number): Color; scale(): Scale };

• Returns a function that [bezier-interpolates]https://www.vis4.net/blog/posts/mastering-multi-hued-color-scales/ between colors in Lab space. The input range of the function is [0..1]. You can convert a bezier interpolator into a chroma.scale instance.

method blend

blend: (
    color1: ChromaInput,
    color2: ChromaInput,
    blendMode:
        | 'multiply'
        | 'darken'
        | 'lighten'
        | 'screen'
        | 'overlay'
        | 'burn'
        | 'dodge'
) => Color;

• Blends two colors using RGB channel-wise blend functions.

  Example 1

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

method cmyk

cmyk: (cyan: number, magenta: number, yellow: number, black: number) => Color;

• Each between 0 and 1.

method contrast

contrast: (color1: ChromaInput, color2: ChromaInput) => number;

• Computes the WCAG contrast ratio between two colors. A minimum contrast of 4.5:1 is recommended https://www.w3.org/TR/WCAG20-TECHS/G18.html to ensure that text is still readable against a background color.

  Example 1

  chroma.contrast('pink', 'hotpink') // 1.721
  chroma.contrast('pink', 'purple') // 6.124

  `

method contrastAPCA

contrastAPCA: (text: ChromaInput, background: ChromaInput) => number;

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

  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.

  Example 1

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

method cubehelix

cubehelix: () => Cubehelix;

method deltaE

deltaE: (
    color1: ChromaInput,
    color2: ChromaInput,
    Kl?: number,
    Kc?: number,
    Kh?: number
) => number;

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

  Example 1

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

method distance

distance: (
    color1: ChromaInput,
    color2: ChromaInput,
    format?: ColorFormat
) => number;

• Computes the eucledian distance between two colors in a given color format (default is 'lab'). https://en.wikipedia.org/wiki/Euclidean_distance#Three_dimensions

  Example 1

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

method gl

gl: (red: number, green: number, blue: number, alpha?: number) => Color;

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

method hcl

hcl: (hue: number, chroma: number, lightness: number, alpha?: number) => Color;

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

method hsl

hsl: (
    hue: number,
    saturation: number,
    lightness: number,
    alpha?: number
) => Color;

method hsv

hsv: (hue: number, saturation: number, value: number, alpha?: number) => Color;

method lab

lab: (lightness: number, a: number, b: number, alpha?: number) => Color;

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

method lch

lch: (lightness: number, chroma: number, hue: number, alpha?: number) => Color;

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

method limits

limits: (data: number[], mode: 'e' | 'q' | 'l' | 'k', n: number) => number[];

• A helper function that computes class breaks for you, based on data. It supports the modes: - e: equidistant - breaks are computed by dividing the total range of the data into _n_ groups of equal size. - q: quantile - the input domain is divided by quantile ranges. - l: logarithmic - breaks are equidistant breaks but on a logarithmic scale. - k: 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.

  Example 1

  const 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]
  chroma.limits(data, 'e', 4) // [2,3.5,5,6.5,8]
  chroma.limits(data, 'q', 4) // [2,4.1,5.2,5.9,8]
  chroma.limits(data, 'l', 4) // [2,2.83,4,5.66,8]
  chroma.limits(data, 'k', 4) // [2,8]

method mix

mix: (
    color1: ChromaInput,
    color2: ChromaInput,
    ratio?: number,
    mode?: InterpolationMode
) => Color;

• Mixes two colors. The mix ratio is a value between 0 and 1. The color mixing produces different results based the mode used for interpolation. Defaults to lrgb.

  Example 1

  chroma.mix([0,0,0], 'blue') // #0000b4
  chroma.mix('red', 'blue', 0.25) // #dd0080
  chroma.mix('red', 'blue', 0.75) // #8000dd
  chroma.mix('red', 'blue', 0.5, 'rgb') // #800080
  chroma.mix('red', 'blue', 0.5, 'hsl') // #ff00ff
  chroma.mix('red', 'blue', 0.5, 'lab') // #ca0088
  chroma.mix('red', 'blue', 0.5, 'lch') // #fa0080
  chroma.mix('red', 'blue', 0.5, 'lrgb') // #b400b4

method oklab

oklab: (lightness: number, a: number, b: number, alpha?: number) => Color;

• Oklab color space

method oklch

oklch: (
    lightness: number,
    chromaticity: number,
    hue: number,
    alpha?: number
) => Color;

method random

random: () => Color;

• Creates a random color by generating a random hexadecimal string.

method rgb

rgb: (red: number, green: number, blue: number, alpha?: number) => Color;

method scale

scale: (colors?: BrewerPaletteName | ChromaInput[]) => Scale;

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

method temperature

temperature: (K: number) => Color;

• Returns a color from the color temperature scale. light 2000K, bright sunlight 6000K. Based on Neil Bartlett's implementation. The effective temperature range goes from 0 to about 30000 Kelvin

  Example 1

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

method valid

valid: (color: any) => boolean;

• Test if a color argument can be correctly parsed as color by chroma.js

  Example 1

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

call signature

(color: ChromaInput): Color;

• Attempts to guess the format of the input color for you. For instance, it will recognize any named color from the W3CX11 specification. 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.

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

call signature

(a: number, b: number, c: number, format?: ColorFormat): Color;

• Create a color in the specified color format using a, b and c as values. The color format defaults to "rgb".

call signature

(a: number, b: number, c: number, d: number, format?: ColorFormat): Color;

• Create a color in the specified color format using a, b, c, and d as values. The color format defaults to "rgb".

call signature

(rgbArray: [number, number, number]): Color;

• Create a color from an array of RGB values. Each parameter must be within 0..255.

call signature

(colorObject: { [key: string]: number }): Color;

• Create a color from an object with attributes corresponding to a color format.

property clipped

clipped: () => boolean;

• Test if a color has been clipped or not. Colors generated from CIELab color space may have their RGB channels 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).

  Example 1

  chroma.hcl(50, 40, 20).clipped() // true

property cmyk

cmyk: () => ColorFormats['cmyk'];

• Returns an array with the cyan, magenta, yellow, and key (black) components, each as a normalized value between 0 and 1.

  Example 1

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

  typescript

property gl

gl: () => ColorFormats['gl'];

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

  Example 1

  chroma('#33cc00').gl() // [0.2,0.8,0,1]

property hcl

hcl: () => ColorFormats['hcl'];

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

  Example 1

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

property hsi

hsi: () => ColorFormats['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.

  Example 1

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

property hsl

hsl: () => ColorFormats['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.

  Example 1

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

property hsv

hsv: () => ColorFormats['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.

  Example 1

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

property lab

lab: () => ColorFormats['lab'];

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

  Example 1

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

property lch

lch: () => ColorFormats['lch'];

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

  Example 1

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

property oklab

oklab: () => ColorFormats['oklab'];

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

  Example 1

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

property oklch

oklch: () => ColorFormats['oklch'];

• Returns an array with the **Lightness**, **chroma**, and **hue** components in the OKLch

  Example 1

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

property rgb

rgb: (round?: boolean) => ColorFormats['rgb'];

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

  Example 1

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

property rgba

rgba: (round?: boolean) => [number, number, number, number];

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

  Example 1

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

property shade

shade: (ratio?: number, mode?: InterpolationMode) => Color;

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

  Example 1

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

property tint

tint: (ratio?: number, mode?: InterpolationMode) => Color;

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

  Example 1

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

method alpha

alpha: { (): number; (a: number): Color };

• Get and set the color opacity.

  Example 1

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

method brighten

brighten: (value?: number) => Color;

• Increases the lightness of the color. value defaults to 1.

  Example 1

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

method css

css: (mode?: 'rgb' | 'hsl' | 'lab' | 'lch' | 'oklab' | 'oklch') => string;

• Returns a CSS string representation that can be used as CSS-color definition. mode defaults to rgb

  Example 1

  chroma('teal').css() // rgb(0 128 128)
  chroma('teal').alpha(0.5).css() // rgb(0 128 128 / 0.5)
  chroma('teal').css('hsl') // hsl(180deg 100% 25.1%)
  chroma('teal').css('lab') // lab(47.99% -30.39 -8.98)
  chroma('teal').css('oklch') // oklch(54.31% 0.09 194.76deg)

method darken

darken: (value?: number) => Color;

• Decreases the lightness of the color. value defaults to 1.

  Example 1

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

method desaturate

desaturate: (value?: number) => Color;

• Similar to saturate, but the opposite direction.

  Example 1

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

method get

get: (channel: string) => number;

• Returns a single channel value.

  Example 1

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

method hex

hex: (mode?: 'auto' | 'rgb' | 'rgba' | 'argb') => string;

• Get color as hexadecimal string. 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"

  Example 1

  chroma('orange').hex() // #ffa500
  chroma('orange').alpha(0.5).hex() // #ffa50080
  chroma('orange').alpha(0.5).hex('rgb') // #ffa500
  chroma('orange').alpha(0.5).hex('argb') // #80ffa500

method luminance

luminance: { (): number; (value: number, mode?: InterpolationMode): Color };

• Relative brightness, according to the [WCAG]http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef definition. Normalized to 0 for darkest black and 1 for lightest white.

• Set luminance of color. The source color will be interpolated with black or white until the correct luminance is found. The color space used defaults to RGB.

method mix

mix: (targetColor: ChromaInput, ratio?: number, format?: ColorFormat) => Color;

• 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 format used can be adjusted.

  Example 1

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

method name

name: () => string;

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

  Example 1

  chroma('#ffa500').name() // orange
  chroma('#ffa505').name() // #ffa505

method num

num: () => number;

• Returns the numeric representation of the hexadecimal RGB color.

  Example 1

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

method saturate

saturate: (value?: number) => Color;

• Changes the saturation of a color by manipulating the Lch chromacity.

  Example 1

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

method set

set: (channel: string, value: number | string) => Color;

• Changes a single channel and returns the result a new chroma object. Also works with relative changes

  Example 1

  ```typescript chroma('skyblue').set('hsl.h', 0) // #eb8787 chroma('hotpink').set('lch.c', 30) // #ce8ca9 chroma('orangered').set('lab.l', '*0.5') // #a10000 chroma('darkseagreen').set('lch.c', '*2') // #63c56c

method temperature

temperature: () => number;

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

  Example 1

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

property cmyk

cmyk: [number, number, number, number];

property gl

gl: [number, number, number, number];

property hcg

hcg: [number, number, number];

property hcl

hcl: [number, number, number];

property hsi

hsi: [number, number, number];

property hsl

hsl: [number, number, number];

property hsv

hsv: [number, number, number];

property lab

lab: [number, number, number];

property lch

lch: [number, number, number];

property oklab

oklab: [number, number, number];

property oklch

oklch: [number, number, number];

property rgb

rgb: [number, number, number];

method gamma

gamma: (g: number) => Cubehelix;

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

method lightness

lightness: (l: number[]) => Cubehelix;

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

method rotations

rotations: (r: number) => Cubehelix;

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

method scale

scale: () => Scale;

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

method start

start: (s: number) => Cubehelix;

• Set start color for hue rotation, default=300

method cache

cache: (use: boolean) => boolean;

method classes

classes: (c: number | number[]) => this;

• 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. You can also define custom class breaks by passing them as array

method colors

colors: {
    (
        c: number | undefined,
        format:
            | undefined
            | null
            | 'alpha'
            | 'darken'
            | 'brighten'
            | 'saturate'
            | 'desaturate'
    ): Color[];
    (c: number, format: 'luminance' | 'temperature'): number[];
    <K extends keyof ColorFormats>(c: number, format: K): ColorFormats[K][];
    (c: number, format?: 'hex' | 'name'): string[];
};

• You can call scale.colors(n) to quickly grab c 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.

method correctLightness

correctLightness: (enable?: boolean) => this;

method domain

domain: { (): number[]; (d?: number[], n?: number, mode?: string): this };

method gamma

gamma: (g: number) => this;

method mode

mode: (mode: InterpolationMode) => this;

method out

out: {
    (format: null): Scale;
    <K extends keyof ColorFormats>(format: K): Scale<ColorFormats[K]>;
    (format: 'hex'): Scale<string>;
};

• Set out format for scale() call. Passing null will result in a scale which outputs colors.

method padding

padding: (p: number | number[]) => this;

call signature

(c: string[]): Scale;

call signature

(value: number | null | undefined): OutType;