@asamuzakjp/css-color

CSS color

Resolve and convert CSS colors.

Install

npm i @asamuzakjp/css-color

Usage

import { convert, resolve, utils } from '@asamuzakjp/css-color';

const resolvedValue = resolve(
  'color-mix(in oklab, lch(67.5345 42.5 258.2), color(srgb 0 0.5 0))'
);
// 'oklab(0.620754 -0.0931934 -0.00374881)'

const convertedValue = convert.colorToHex('lab(46.2775% -47.5621 48.5837)');
// '#008000'

const result = utils.isColor('green');
// 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.

      const opt = {
        customProperty: {
          '--some-color': '#008000',
          '--some-length': '16px'
        }
      };
      

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

      const node = document.getElementById('foo');
      const opt = {
        customProperty: {
          callback: node.style.getPropertyValue
        }
      };
      

  • 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

      const opt = {
        dimension: {
          em: 12,
          rem: 16,
          vw: 10.24
        }
      };
      

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

      const opt = {
        dimension: {
          callback: unit => {
            switch (unit) {
              case 'em':
                return 12;
              case 'rem':
                return 16;
              case 'vw':
                return 10.24;
              default:
                return;
            }
          }
        }
      };
      

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