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

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

npm i @asamuzakjp/css-color

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

1. 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)'

2. Resolve with Custom Properties and complex calc():

const resolvedVar = resolve('hsl(calc(var(--base-hue) + 0.25turn) 50% 50%)', {
  customProperty: { '--base-hue': '180deg' },
  format: 'specifiedValue'
});
// => 'hsl(270, 50%, 50%)'

3. Convert between color spaces:

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

4. 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

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

A collection of color conversion utilities.

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

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

• csstools/postcss-plugins
• lru-cache

Copyright (c) 2024 asamuzaK (Kazz)