CSS color

May 18, 2026 · View on GitHub

A robust and modern library to resolve, parse, and convert CSS colors. Supports the latest CSS Color Module Level 4 & 5 specifications.

Features

Modern CSS Color Support: Accurately resolves color-mix(), color(), modern color spaces (oklch, oklab, lch, lab, hwb, etc.), and relative colors (lab(from red l a b), color(from red xyz-d50 x y z)).
Deep Resolution: Deeply resolves var() and calc() functions embedded within color values.
Gradient Parsing: Supports parsing and validation for linear-gradient, radial-gradient, and conic-gradient.
Comprehensive Color Conversion: Highly accurate converters between HEX, HSL, HWB, LAB, LCH, Oklab, Oklch, RGB, and XYZ color spaces.
Bonus Utilities: Includes convenient functions to validate colors or gradients, extract CSS variables, and safely split CSS values.
Used in jsdom: Adopted as the CSS color parser and resolver for jsdom.
Pure ESM with TypeScript Ready: Native ESM (type: "module") with comprehensive TypeScript definitions.

Install

npm i @asamuzakjp/css-color

Quick Start

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

Samples

Resolve complex modern CSS colors:

const resolvedMix = 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)'

Resolve with Custom Properties and calc():

const resolvedVar = resolve('hsl(calc(var(--base-hue) * 3) 100% 50% / .5)', {
  customProperty: { '--base-hue': '210deg' }
});
// => 'rgba(128, 0, 255, 0.5)'

Convert between color spaces:

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

Validate colors and gradients:

const isColor = utils.isColor('light-dark(red, blue)');
// => true

const isGradient = utils.isGradient(
  'conic-gradient(from 0.5turn at 50% 50%, red, blue)'
);
// => true

API Reference

`resolve(color, opt?)`

Resolves a CSS color string into its computed or specified value. System colors are not supported.

color <string>: The CSS color value to resolve.
opt <object> (optional):
- opt.currentColor: Color to use for the currentcolor keyword.
- opt.customProperty: Object containing -- prefixed keys and their values, or a callback(propertyName) function to dynamically resolve CSS variables.
- opt.dimension: Object mapping units (e.g., em, rem, vw) to pixel numbers, or a callback(unit) function for dynamic length resolution.
- opt.format: Output format. Options: computedValue (default), specifiedValue, hex, hexAlpha.
- opt.colorScheme: normal (default), light, or dark (useful for light-dark() resolution).

`convert`

A collection of color conversion utilities.

Function	Returns	Options	Description
`convert.colorToHex(value, opt?)`	`string \| null`	`opt.alpha` `<boolean>` (+ see `resolve` options)	Returns `#rrggbb` or `#rrggbbaa` (if `opt.alpha` is true).
`convert.colorToHsl(value, opt?)`	`number[]`	See `resolve` options	Converts to HSL channels: `[h, s, l, alpha]`
`convert.colorToHwb(value, opt?)`	`number[]`	See `resolve` options	Converts to HWB channels: `[h, w, b, alpha]`
`convert.colorToLab(value, opt?)`	`number[]`	See `resolve` options	Converts to CIE LAB channels: `[l, a, b, alpha]`
`convert.colorToLch(value, opt?)`	`number[]`	See `resolve` options	Converts to CIE LCH channels: `[l, c, h, alpha]`
`convert.colorToOklab(value, opt?)`	`number[]`	See `resolve` options	Converts to Oklab channels: `[l, a, b, alpha]`
`convert.colorToOklch(value, opt?)`	`number[]`	See `resolve` options	Converts to Oklch channels: `[l, c, h, alpha]`
`convert.colorToRgb(value, opt?)`	`number[]`	See `resolve` options	Converts to sRGB channels: `[r, g, b, alpha]`
`convert.colorToXyz(value, opt?)`	`number[]`	See `resolve` options	Converts to CIE XYZ channels (defaults to D65): `[x, y, z, alpha]`
`convert.colorToXyzD50(value, opt?)`	`number[]`	See `resolve` options	Converts to CIE XYZ channels with D50 white point.

`utils`

Helpful internal tools exposed for advanced usage, parsing, and validation.

Function	Returns	Options (`opt`)	Description
`utils.cssCalc(value, opt?)`	`string`	`opt.dimension` (+ see `resolve` options)	Resolves CSS `calc()` expressions.
`utils.cssVar(value, opt?)`	`string`	`opt.customProperty` (+ see `resolve` options)	Resolves CSS `var()` expressions.
`utils.extractDashedIdent(value)`	`string[]`	None	Extracts custom property names (dashed-ident tokens) from a value.
`utils.isColor(value, opt?)`	`boolean`	See `resolve` options	Returns `true` if the string is a valid CSS color.
`utils.isGradient(value, opt?)`	`boolean`	See `resolve` options	Returns `true` if the string is a valid CSS gradient.
`utils.resolveGradient(value, opt?)`	`string`	See `resolve` options	Resolves CSS gradient strings.
`utils.resolveLengthInPixels(value, unit, opt?)`	`number`	`opt.dimension` (+ see `resolve` options)	Converts an absolute or relative CSS length to pixels.
`utils.splitValue(value, opt?)`	`string[]`	`opt.delimiter` `<string>` `opt.preserveComment` `<boolean>`	Safely splits a CSS value by a specified delimiter ( , `,`, `/`).

Acknowledgments

The following resources have been of great help in the development of this library: