chroma.ts
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.10 • Public • Published

    Travis npm David

    chroma.ts

    TypeScript rewrite of chroma-js. Includes:

    • Proper ES module support.
    • Included typings generated from the source.
    • A number of bugfixes.
    • No more NaN values.
    • Exceptions on invalid inputs.
    • Better inline documentation.
    • Smaller (11.26 KB gzipped).

    Installation

    npm install --save chroma.ts
    

    Usage

    // in TypeScript / using ES modules
    import * as chroma from 'chroma.ts'
    
    // commonjs
    const chroma = require('chroma.ts')
    
    chroma.css('powderblue') // create a color
        .darker(2) // transform it
        .gl() // output it

    Alternatively, you can include the UMD bundle in a script tag and use the chroma global.

    API

    .color(red255: number, green255: number, blue255: number, alpha1: number = 1): Color src

    example chroma.color(99, 99, 44, 0.7)

    .color(x: Chromable, format?: ColorFormat): Color src

    example chroma.color('mediumorchid') // a css string
    example chroma.color([56, 203, 30]) // a RGB triple
    example chroma.color(0x4b0082) // a hex num
    example chroma.color([30, 0.8, 0.3], 'hsl') // explicit format

    .color(colorname: typeof [object Object], format?: undefined | "name"): Color src

    This overload allows VS Code to suggest color names when you type color('.

    .color(channel0: number, channel1: number, channel2: number, format: ColorFormat): Color src

    example chroma.color(30, 0.8, 0.3, 'hsl')

    .color(channel0: number, channel1: number, channel2: number, channel3: number, format: ColorFormat): Color src

    example chroma.color(0.3, 0.8, 0.3, 1, 'gl')

    type Chromable = number | string | Color | number[]

    A Chromable is any value which can be converted to a color. For ease of use, most functions accept these instead of only Color values.

    interface Color

    color.mix(col2: Chromable, f: number, m: InterpolationMode = "rgb"): Color src

    @see [[mix]]

    color.rgb(doRound: boolean = true, clamp_: boolean = true): RGB src

    color.rgba(doRound: boolean = true, clamp_: boolean = true): RGBA src

    color.hex(mode: "rgb" | "rgba" | "argb" = "rgb"): string src

    Return a hex-string representation of this color.

    @see #num for a hex-number representation.

    example chroma.color('yellow').alpha(0.7).hex() "#ffff00"
    example chroma.color('yellow').alpha(0.7).hex('rgba') "#ffff00b3"
    example chroma.color('yellow').alpha(0.7).hex('argb') "#b3ffff00"

    color.hsl(): HSL src

    Returns the [HSL] representation of this color. hue will always be in [0;360). Values are never NaN.

    example chroma.color('purple').hsl() [300, 1, ~0.25]

    color.hsv(): HSV src

    Returns the [HSL] representation of this color. hue will always be in [0;360). Values are never NaN.

    example chroma.color('purple').hsv() [300, 1, ~0.5]

    color.hcg(): HCG src

    Returns the [HSL] representation of this color. hue will always be in [0;360). Values are never NaN.

    example chroma.color('purple').hcg() [300, ~0.5, 0]

    color.css(mode: "rgb" | "hsl" = "rgb"): string src

    Returns a CSS rgb(...) or hsl(...) string representation that can be used as CSS-color definition. The alpha value is not output if it 1.

    example chroma.color('teal').css() "rgb(0,128,128)"
    example chroma.color('teal').alpha(0.5).css() "rgba(0,128,128,0.5)"
    example chroma.color('teal').css('hsl') "hsl(180,100%,25.1%)"

    color.name(closest: true): string src

    color.name(closest: false | true = false): string | undefined src

    Get the name of a color. By default, this method will try to match the color exactly (comparing rounded RGB values). Pass true to return the name of the color which is closest to this in CIELAB color space. CIELAB is used as it is perceptually uniform.

    example chroma.color('#ff0000').name() "red"
    example chroma.color('#ff0001').name()
    example chroma.color('#ff0001').name(true) "red"

    color.cmyk(): CMYK src

    Get the CMYK representation of this color.

    example chroma.color('red').cmyk() [0, 1, 1, 0]

    color.gl(): GL src

    Returns the [GL] representation of this color.

    example chroma.color('33cc00').gl() [0.2, 0.8, 0, 1]

    color.luminance(): number src

    Get luminance of the color. This is equal to the Y channel of the XYZ color space.

    example chroma.color('black').luminance() 0
    example chroma.color('white').luminance() ~1
    example chroma.color('red').luminance() ~0.21

    @see https://en.wikipedia.org/wiki/Relative\_luminance

    color.luminance(lum1: number): this src

    Return a new [Color] with lum1 by linearly interpolating this with white (when increasing the luminance) or black (otherwise) in the [XYZ] color space.

    @see https://en.wikipedia.org/wiki/Relative\_luminance

    example // Approximately doubling the luminance of red
    example chroma.color('red').luminance(0.4) // "Vivid Tangerine"

    color.temperature(): number src

    Get color temperature of this color in Kelvin. This only makes sense for colors close to those output by kelvin

    example [c = chroma.color('#ff3300'), c.temperature()] [, 943]
    example [c = chroma.color('#ffe3cd'), c.temperature()] [, 4998]
    example [c = chroma.color('#b3ccff'), c.temperature()] [, 15169]

    color.set(modeAndChannel: string, value: number | ((channel: number) => number)): Color src

    Returns a new [Color] with a channel changed.

    example chroma.color('skyblue').set('hsl.h', 0) // change hue to 0 deg (=red)
    example chroma.color('hotpink').set('lch.c', 30) // set chromaticity to 30
    example chroma.color('orangered').set('lab.l', x => x / 2) // half Lab lightness
    example chroma.color('darkseagreen').set('lch.c', x => x * 2) // double Lch saturation

    color.clipped(): boolean src

    Returns whether this color is outside the RGB color cube and will be clipped/clamped when calling .rgb()

    example [c = chroma.lch( 20, 40, 50), c.clipped()] [, true]
    example [c = chroma.lch( 40, 40, 50), c.clipped()] [, false]
    example [c = chroma.lch( 60, 40, 50), c.clipped()] [, false]
    example [c = chroma.lch( 80, 40, 50), c.clipped()] [, true]
    example [c = chroma.lch(100, 40, 50), c.clipped()] [, true]

    color.textColor(): Color src

    Returns black or white, whichever has the highest contrast to this. In the readme you should see the result of this.

    example chroma.color('red')
    example chroma.color('yellow')

    color.alpha(): number src

    Get alpha value of color.

    example chroma.rgb(0, 0, 255, 0.5).alpha() 0.5

    color.alpha(alpha1: number): Color src

    Return new [Color] with given alpha value.

    example chroma.color('green').alpha(0.3)
    example chroma.color('green').alpha(0.3).hex('rgba') "#0080004d"

    color.darker(amount: number = 1): Color src

    color.brighter(amount: number = 1): Color src

    example chroma.color('hotpink')
    example chroma.color('hotpink').brighter()
    example chroma.color('hotpink').brighter(2)
    example chroma.color('hotpink').brighter(3)

    color.saturate(amount: number = 1): Color src

    Returns a new [Color] with increased saturation.

    example chroma.color('slategray')
    example chroma.color('slategray').saturate()
    example chroma.color('slategray').saturate(2)
    example chroma.color('slategray').saturate(3)

    color.desaturate(amount: number = 1): Color src

    Equivalent to saturate(-amount).

    @see #saturate

    color.premultiplied(): Color src

    color.hsi(): HSI src

    Returns the [HSI] representation of this color. hue will always be in [0; 360). Values are never NaN.

    example chroma.color('purple').hsi() [300, 1, ~0.33]

    color.lab(): RGB src

    Returns the [LAB] representation of this color.

    example chroma.color('purple').lab() [~29.78, ~58.93, ~-36.49]

    color.num(mode: "rgb" | "rgba" | "argb" = "rgb"): number src

    Return a hex-num of this color.

    @see #num for a hex-number representation.

    example chroma.color('yellow').alpha(0.7).hex() "#ffff00"
    example chroma.color('yellow').alpha(0.7).hex('rgba') "#ffff00b3"
    example chroma.color('yellow').alpha(0.7).hex('argb') "#b3ffff00"

    color.lch(): LCH src

    Returns the [LCH] representation of this color. hue will always be in [0; 360). Values are never NaN.

    example chroma.color('purple').lch() [~29.78, ~69.31, ~328.23]

    color.xyz(): XYZ src

    Returns the [XYZ] representation of this color. hue will always be in [0; 360). Values are never NaN.

    example chroma.color('purple').xyz() [~0.13, ~0.06, ~0.21]

    color.equals(color: Color): boolean src

    Whether this Color is identical (strict equality of r, g, b, a) to color.

    color.hashCode(): number src

    color.toSource(): string src

    example chroma.color('red').toSource() "chroma.rgb(255, 0, 0)"
    example chroma.rgb(-2, 100.02, 200, 0.5).toSource() "chroma.rgb(-2, 100.02, 200, 0.5)"

    color.toString(): string src

    color.kelvin(): number src

    namespace black

    example chroma.black

    namespace white

    example chroma.black

    .cubehelix(start: number = 300, rotations: number = -1.5, hue: number | [number, number] = 1, gamma: number = 1, lightness: number | [number, number] = [0, 1]): CubeHelix src

    Return a new [[CubeHelix]].

    example chroma.cubehelix() // use the default helix
    example chroma.cubehelix().start(200).rotations(-0.5).gamma(0.8).lightness([0.3, 0.8])

    interface CubeHelix

    Dave Green's cubehelix color scheme!

    A CubeHelix is a function defined on [0, 1] which returns colors.

    cubehelix(f: number): Color src

    Dave Green's cubehelix color scheme!

    A CubeHelix is a function defined on [0, 1] which returns colors.

    cubehelix.start(): number src

    cubehelix.start(s: number): this src

    cubehelix.rotations(): number src

    cubehelix.rotations(r: number): this src

    cubehelix.gamma(): number src

    cubehelix.gamma(g: number): this src

    cubehelix.hue(): [number, number] src

    cubehelix.hue(h: number | [number, number]): this src

    cubehelix.lightness(): [number, number] src

    cubehelix.lightness(h: number | [number, number]): this src

    cubehelix.scale(): Scale src

    Convert to a [[Scale]].

    example chroma.cubehelix().scale().correctLightness().domain(2, 22)

    cubehelix.at(fract: number): Color src

    .random(randomSource: random = Math.random): Color src

    Create a new random [Color] from a random point in the RGB color space.

    .mix(col1: Chromable, col2: Chromable, f: number = 0.5, m: InterpolationMode = "rgb"): Color src

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

    example chroma.mix('red', 'blue')
    example chroma.mix('red', 'blue', 0.25)
    example chroma.mix('red', 'blue', 0.75)
    example chroma.mix('red', 'blue', 0.5, 'rgb')
    example chroma.mix('red', 'blue', 0.5, 'hsl')
    example chroma.mix('red', 'blue', 0.5, 'lab')
    example chroma.mix('red', 'blue', 0.5, 'lch')
    example chroma.mix('red', 'blue', 0.5, 'lrgb')

    .css(cssString: string): Color src

    Parse a CSS color. See MDN for all the possible variants.

    example chroma.css('hsl(2rad 90% 50% / 0.9)')
    example chroma.css('laserlemon')

    .cmyk(cmyk: CMYK): Color src

    example chroma.cmyk(0.2, 0.8, 0, 0)
    example chroma.color(0.2, 0.8, 0, 0, 'cmyk')

    .cmyk(cyan1: number, magenta1: number, yellow1: number, key1: number): Color src

    .gl(gl: RGBA | RGB): Color src

    example chroma.gl(1, 1, 0, 1)

    .gl(red1: number, green1: number, blue1: number, alpha1: number): Color src

    example chroma.gl([1, 0, 1, 0.5])

    .hcg(hcg: HCG): Color src

    .hcg(h: number, c: number, g: number, alpha1: number = 1): Color src

    .lch(lch: LCH): Color src

    .lch(h: number, c: number, l: number, alpha1: number = 1): Color src

    .hsi(hsi: HSI): Color src

    .hsi(h: number, s: number, i: number, alpha1: number = 1): Color src

    .hsl(hsl: HSL): Color src

    .hsl(hueDegrees: number, saturation1: number, lightness1: number, alpha1: number = 1): Color src

    example chroma.hsl(30, 1, 0.5)
    example chroma.hsl(30, 0.6, 0.5)

    .hsv(hsv: LAB): Color src

    .hsv(h: number, s: number, v: number): Color src

    .kelvin(temperature: number): Color src

    example chroma.kelvin(2000) // candle light
    example chroma.kelvin(3500) // sunset
    example chroma.kelvin(6500) // daylight
    example x0_1 => chroma.kelvin(x0_1 * 30000) // effective range: [0; 30000]

    .lab(lab: LAB): Color src

    .lab(lightness1: number, a1: number, b: number, alpha1: number = 1): Color src

    .num(num: number): Color src

    example chroma.num(0x663399) // rebeccapurple

    .rgb(rgb: RGBA | RGB): Color src

    .rgb(red255: number, green255: number, blue255: number, alpha1: number = 1): Color src

    example chroma.rgb(0, 100, 200)

    .xyz(xyz: XYZ): Color src

    .xyz(x1: number, y1: number, z1: number, alpha1: number = 1): Color src

    .average(chromables: Chromable[], mode: InterpolationMode = "rgb"): Color src

    Similar to mix, but accepts more than two colors.

    example colors = ['#ddd', 'yellow', 'red', 'teal'] [, , , ]
    example chroma.average(colors) // default = 'rgb'
    example chroma.average(colors, 'lab')
    example chroma.average(colors, 'lch')
    example chroma.average(colors, 'lrgb')
    example chroma.average(['red', 'rgba(0,0,0,0.5)']).css() "rgba(128,0,0,0.75)"

    .bezier(chromables: Chromable[]): (t: number) => Color src

    example chroma.scale('black', 'red', 'gold') // linear interpolation
    example chroma.bezier('black', 'red', 'gold') // bezier interpolation

    .bezier(...chromables: Chromable[]): (t: number) => Color src

    .blend(bottom: Chromable, top: Chromable, mode: BlendMode): Color src

    Blends two colors using RGB channel-wise blend functions.

    example chroma.blend('4CBBFC', 'EEEE22', 'multiply')
    example chroma.blend('4CBBFC', 'EEEE22', 'darken')
    example chroma.blend('4CBBFC', 'EEEE22', 'lighten')

    type BlendMode = typeof [object Object]

    .scale(colors: Chromable[] | typeof [object Object] | ((f: number) => Color)): Scale src

    example scale = chroma.scale(['yellow', '008ae5'])
    example scale(0.25)
    example scale(0.5)
    example scale(0.75)
    example chroma.scale('Viridis')

    .scale(...colors: Chromable[]): Scale src

    interface Scale<T>

    A color scale, created with scale, is a function that maps numeric values to a color palette.

    The type parameter describes the output type and can be changed with out(). Defaults to Color objects.

    example chroma.scale('Purples')
    example chroma.scale('Purples')(0.4)

    scale(val: number): T src

    A color scale, created with scale, is a function that maps numeric values to a color palette.

    The type parameter describes the output type and can be changed with out(). Defaults to Color objects.

    example chroma.scale('Purples')
    example chroma.scale('Purples')(0.4)

    scale.classes(): number[] src

    Get the current scale classes.

    scale.classes(classes: number | number[]): this src

    Make the scale return a number of distint color instead of a continuous gradient. If you pass a number the scale will broken into equi-distant classes:

    example chroma.scale('OrRd') // continous
    example chroma.scale('OrRd').classes(5) // equidistant classes
    example chroma.scale('OrRd').classes(8)
    example chroma.scale('OrRd').classes([0, 6, 11, 17, 20]) // also sets domain

    scale.domain(): number[] src

    Get the domain.

    example chroma.scale("red", "white", "blue").domain(0, 20).domain() [0, 10, 20]

    scale.domain(start: number, end: number): this src

    Set the domain interval on which the scale is defined. Colors are distributed equidistantly along the interval.

    example chroma.scale("red", "white", "blue").domain(0, 100)(50)
    example chroma.scale("red", "white", "blue").domain(0, 0.25, 1).domain(0, 100).domain() [0, 50, 100]

    scale.domain(...domain: number[]): this src

    Set the domain interval and the individual positions of the colors. The number of passed values must match the number of colors which define the scale. Not valid if the scale is defined by a function.

    example scale = chroma.scale("red", "white", "blue").domain(0, 25, 100)
    example scale(25)
    example scale(100)
    example scale(50)

    scale.mode(): InterpolationMode src

    Get the interpolation mode used when calculating colors.

    scale.mode(mode: InterpolationMode): this src

    Set the interpolation mode used when calculating colors. The defaut mode is "rgb". See also {@link chroma#mix}

    example chroma.scale("red", "green").mode("lab")
    example chroma.scale("red", "green").mode("lrgb")

    scale.out<M>(outputFormat: M): Scale src

    Set the output format return by this(x) and this.colors(n).

    example chroma.scale("red", "white").out("hex")(0) "#ff0000"
    example chroma.scale("red", "white").out("num").colors(2) [, ]

    scale.correctLightness(enableCorrectLightness: boolean = true): this src

    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.

    example chroma.scale('black','red','yellow','white')
    example chroma.scale('black','red','yellow','white').correctLightness()

    scale.padding(): [number, number] src

    Get the padding.

    scale.padding(paddingLeft: number, paddingRight: number = paddingLeft): this src

    Set the padding. Positive values will "cut off" the ends of gradient, while negative values will add a section of constant color at the ends.

    example chroma.scale("red", "white").padding(0.2)
    example chroma.scale("red", "white").padding(0.1)(0)
    example chroma.scale("red", "white").padding(-0.1)(0)

    scale.colors<M>(numColors?: undefined | number, format: M = "hex" as any): Array src

    Get a number of equidistant colors.

    example chroma.scale('OrRd').colors(5) [, , , , ]
    example chroma.scale(['white', 'black']).colors(12) [, , , , , , , , , , , ]

    scale.cache(): boolean src

    Get whether the cache is enabled. Defaults to true.

    scale.cache(enableCache: boolean): this src

    Enable or disable the cache.

    scale.gamma(): number src

    Get the current gamma value. Defaults to 1.

    scale.gamma(gamma: number): this src

    Set the gamma value. 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.

    example chroma.scale('YlGn').gamma(0.5)
    example chroma.scale('YlGn').gamma(1)
    example chroma.scale('YlGn').gamma(2)

    namespace scales

    scales.cool(): Scale src

    example chroma.scales.cool()

    scales.hot(): Scale src

    example chroma.scales.hot()

    .contrast(a: Chromable, b: Chromable): number src

    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.

    .distance(a: Chromable, b: Chromable, mode: ColorMode = "lab"): number src

    Compute the euclidean distance between two colors in a given color space.

    example chroma.distance('#fff', '#ff0', 'rgb') 255
    example chroma.distance('#fff', '#f0f', 'rgb') 255
    example chroma.distance('#fff', '#ff0') ~96.95
    example chroma.distance('#fff', '#f0f') ~122.16

    .deltaE(reference: Chromable, sample: Chromable, L: number = 1, C: number = 1): number src

    Computes color difference as developed by the Colour Measurement Committee of the Society of Dyers and Colourists (CMC) in 1984. The implementation is adapted from Bruce Lindbloom. The parameters L and C are weighting factors for lightness and chromaticity.

    example [r = '#ededee', s = '#edeeed', chroma.deltaE(r, s)] [, , ~1.64]
    example [r = '#ececee', s = '#eceeec', chroma.deltaE(r, s)] [, , ~3.16]
    example [r = '#e9e9ee', s = '#e9eee9', chroma.deltaE(r, s)] [, , ~7.36]
    example [r = '#e4e4ee', s = '#e4eee4', chroma.deltaE(r, s)] [, , ~14.84]
    example [r = '#e0e0ee', s = '#e0eee0', chroma.deltaE(r, s)] [, , ~21.32]

    .analyze(data: number[]): DataInfo src

    .limits(data: number[] | DataInfo, mode: LimitsMode = "e", num: number = 7): number[] src

    type ColorMode = "rgb" | "cmyk" | "lab" | "hsv" | "hsi" | "hcg" | "hsl" | "gl" | "lch" | "xyz"

    type InterpolationMode = "rgb" | "lab" | "hsv" | "hsi" | "hcg" | "hsl" | "lch" | "xyz" | "lrgb" | "num"

    type ColorFormat = ColorMode | "hex" | "num" | "name" | "kelvin" | "css"

    License

    The original chroma-js library is released under the BSD license.

    The included brewer colors are released under the Apache 2.0 license.

    chroma.ts modifications are also released under the BSD license.

    Keywords

    none

    Install

    npm i chroma.ts

    DownloadsWeekly Downloads

    311

    Version

    1.0.10

    License

    ISC

    Unpacked Size

    747 kB

    Total Files

    25

    Last publish

    Collaborators

    • narida