DOCSEARCHbyAlgolia
Submit Docs

color-convert

repository·master·Indexed 21 days ago

https://github.com/qix-/color-convert

A utility library for converting colors between various color spaces including RGB, HSL, HSV, HWB, XYZ, LAB, CMYK, and others. It features a property-access API (convert.[from].[to]), automatic routing through intermediate models, and support for both rounded and raw floating-point results.

Tokens
1.3K
Snippets
5
Records
6
Agent score
24%

What's inside color-convert

  2. Use the color-convert API for color conversions

    master

    The API follows a property-access pattern: convert.[from].[to](args).

    Supported color models include rgb, hsl, hsv, hwb, cmyk, ansi, ansi16, hex, and CSS keywords.

    Key Features

    • Rounding: By default, conversion results are rounded. To get unrounded (raw) floating-point results, append .raw to the function call.
    • Channel Metadata: Every 'from' object has a .channels property indicating the number of expected input channels (excluding alpha).
    • Array Support: For functions accepting multiple arguments, you can pass an array of values instead of individual arguments (this does not apply to single-value inputs like hex or keyword).
    • Automatic Routing: If a direct conversion between two models is not defined, the library automatically routes the conversion through intermediate models (e.g., XYZ -> RGB -> CMYK). Note that multi-step conversions may result in precision loss.
    import convert from 'color-convert';

// Basic conversion
convert.rgb.hsl(140, 200, 100);             // [96, 48, 59]
convert.keyword.rgb('blue');                // [0, 0, 255]

// Accessing channel counts
const rgbChannels = convert.rgb.channels;     // 3

// Using .raw for unrounded results
convert.hex.lab.raw('DEADBF');             // [ 75.56213190997677, 20.653827952644754, -2.290532499330533 ]

// Passing arguments as an array
convert.rgb.hex([123, 45, 67]);             // '7B2D43'

  3. Understand color space scales and full-scale values

    master

    Conversions in color-convert rely on agreed-upon 'full-scale' values for each channel. When working with these color spaces, keep these scales in mind:

    Color SpaceChannelFull-scale value
    rgbr, g, b255
    hslh, s, l360, 100, 100
    hsvh, s, v360, 100, 100
    hwbh, w, b360, 100, 100
    xyzx, y, z94, 99, 108
    labl, a, b100, (-86 to 98), (-108 to 94)
    lchl, c, h100, 133, 360
    oklabl, a, b100, (-23 to 28), (-31 to 20)
    oklchl, c, h100, 32, 360
    cmykc, m, y, k100, 100, 100, 100
    hexhex0xffffff
    keywordnameany key from color-name
    apple0, 1, 265535, 65535, 65535
    graygray100

  4. Use the color-convert API for color space conversions

    master

    The color-convert library provides a hierarchical API for converting colors between different color spaces. The API is structured as convert.[fromModel].[toModel](args).

    • fromModel: The source color space (e.g., rgb, hsl, hsv, hwb, xyz, lab).
    • toModel: The target color space.
    • args: An array of numbers representing the color components (e.g., [r, g, b] or [h, s, l]).

    By default, conversion methods return rounded integer values. If you require high-precision floating-point results, use the .raw property on the conversion function.

    import convert from 'color-convert';

// Standard usage (returns rounded integers)
const rgb = convert.hsl.rgb([360, 100, 50]);

// High-precision usage (returns raw floating-point values)
const rgbRaw = convert.hsl.rgb.raw([360, 100, 50]);

  5. Access high-precision color values via .raw()

    master

    Standard conversion methods in color-convert automatically round the resulting color components to the nearest integer. To bypass rounding and obtain the exact floating-point values, call the .raw property attached to the conversion function.

    Example: convert.[fromModel].[toModel].raw(args)

    import convert from 'color-convert';

// Rounded result
const rounded = convert.rgb.hsl([255, 0, 0]);

// Precise floating-point result
const precise = convert.rgb.hsl.raw([255, 0, 0]);

  6. Inspect color space channels and labels

    master

    Each source color model object (e.g., convert.rgb, convert.hsl) contains metadata describing its structure. You can access these properties to understand the expected input/output format:

    • channels: An array representing the number of components in the color model.
    • labels: An array of strings representing the names of the color components (e.g., ['r', 'g', 'b']).
    import convert from 'color-convert';

console.log(convert.rgb.channels); // e.g., [3]
console.log(convert.rgb.labels);   // e.g., ['r', 'g', 'b']