CSS color

Resolve and convert CSS colors.

Install

1npm i @asamuzakjp/css-color

Usage

1import { convert, resolve, utils } from '@asamuzakjp/css-color';
2
3const resolvedValue = resolve(
4  'color-mix(in oklab, lch(67.5345 42.5 258.2), color(srgb 0 0.5 0))'
5);
6// 'oklab(0.620754 -0.0931934 -0.00374881)'
7
8const convertedValue = convert.colorToHex('lab(46.2775% -47.5621 48.5837)');
9// '#008000'
10
11const result = utils.isColor('green');
12// true

resolve(color, opt)

resolves CSS color

Parameters

• color string color value
  • system colors are not supported
• opt object? options (optional, default {})
  • opt.currentColor string?
    • color to use for currentcolor keyword
    • if omitted, it will be treated as a missing color, i.e. rgb(none none none / none)
  • opt.customProperty object?
    • custom properties
    • pair of -- prefixed property name as a key and it's value, e.g.

      1const opt = {
      2  customProperty: {
      3    '--some-color': '#008000',
      4    '--some-length': '16px'
      5  }
      6};

    • and/or callback function to get the value of the custom property, e.g.

      1const node = document.getElementById('foo');
      2const opt = {
      3  customProperty: {
      4    callback: node.style.getPropertyValue
      5  }
      6};

  • opt.dimension object?
    • dimension, e.g. for converting relative length to pixels
    • pair of unit as a key and number in pixels as it's value, e.g. suppose 1em === 12px, 1rem === 16px and 100vw === 1024px, then

      1const opt = {
      2  dimension: {
      3    em: 12,
      4    rem: 16,
      5    vw: 10.24
      6  }
      7};

    • and/or callback function to get the value as a number in pixels, e.g.

      1const opt = {
      2  dimension: {
      3    callback: unit => {
      4      switch (unit) {
      5        case 'em':
      6          return 12;
      7        case 'rem':
      8          return 16;
      9        case 'vw':
      10          return 10.24;
      11        default:
      12          return;
      13      }
      14    }
      15  }
      16};

  • opt.format string?
    • output format, one of below
      • computedValue (default), computed value of the color
      • specifiedValue, specified value of the color
      • hex, hex color notation, i.e. #rrggbb
      • hexAlpha, hex color notation with alpha channel, i.e. #rrggbbaa

Returns string? one of rgba?(), #rrggbb(aa)?, color-name, color(color-space r g b / alpha), color(color-space x y z / alpha), (ok)?lab(l a b / alpha), (ok)?lch(l c h / alpha), '(empty-string)', null

• in computedValue, values are numbers, however rgb() values are integers
• in specifiedValue, returns empty string for unknown and/or invalid color
• in hex, returns null for transparent, and also returns null if any of r, g, b, alpha is not a number
• in hexAlpha, returns #00000000 for transparent, however returns null if any of r, g, b, alpha is not a number

convert

Contains various color conversion functions.

convert.numberToHex(value)

convert number to hex string

Parameters

• value number color value

Returns string hex string: 00..ff

convert.colorToHex(value, opt)

convert color to hex

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.alpha boolean? return in #rrggbbaa notation
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns string #rrggbb(aa)?

convert.colorToHsl(value, opt)

convert color to hsl

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [h, s, l, alpha]

convert.colorToHwb(value, opt)

convert color to hwb

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [h, w, b, alpha]

convert.colorToLab(value, opt)

convert color to lab

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [l, a, b, alpha]

convert.colorToLch(value, opt)

convert color to lch

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [l, c, h, alpha]

convert.colorToOklab(value, opt)

convert color to oklab

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [l, a, b, alpha]

convert.colorToOklch(value, opt)

convert color to oklch

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [l, c, h, alpha]

convert.colorToRgb(value, opt)

convert color to rgb

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [r, g, b, alpha]

convert.colorToXyz(value, opt)

convert color to xyz

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above
  • opt.d50 boolean? xyz in d50 white point

Returns Array<number> [x, y, z, alpha]

convert.colorToXyzD50(value, opt)

convert color to xyz-d50

Parameters

• value string color value
• opt object? options (optional, default {})
  • opt.customProperty object?
    • custom properties, see resolve() function above
  • opt.dimension object?
    • dimension, see resolve() function above

Returns Array<number> [x, y, z, alpha]

utils

Contains utility functions.

utils.isColor(color)

is valid color type

Parameters

• color string color value
  • system colors are not supported

Returns boolean

Acknowledgments

The following resources have been of great help in the development of the CSS color.

• csstools/postcss-plugins
• lru-cache

---

Copyright (c) 2024 asamuzaK (Kazz)