# @asamuzakjp/css-color

> CSS color - Resolve and convert CSS colors.

Latest version **7.0.0** (published 2026-08-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install @asamuzakjp/css-color
pnpm add @asamuzakjp/css-color
yarn add @asamuzakjp/css-color
bun add @asamuzakjp/css-color
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2026-08-16 |
| First published | 2024-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 5 |
| Unpacked size | 344 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | asamuzaK |
| Maintainers | asamuzakjp |

## Links

- npm: https://www.npmjs.com/package/@asamuzakjp/css-color
- Repository: https://github.com/asamuzaK/cssColor
- Homepage: https://github.com/asamuzaK/cssColor#readme
- Issues: https://github.com/asamuzaK/cssColor/issues
- npm.io page: https://npm.io/package/@asamuzakjp/css-color

## Dependencies (5)

- [lru-cache](https://npm.io/package/lru-cache.md) ^11.5.2
- [@csstools/css-calc](https://npm.io/package/@csstools/css-calc.md) ^3.3.0
- [@csstools/css-tokenizer](https://npm.io/package/@csstools/css-tokenizer.md) ^4.0.0
- [@csstools/css-color-parser](https://npm.io/package/@csstools/css-color-parser.md) ^4.2.0
- [@csstools/css-parser-algorithms](https://npm.io/package/@csstools/css-parser-algorithms.md) ^4.0.0

## Recent versions

- 7.0.0 (latest) — 2026-08-16
- 2.8.3 (legacy) — 2025-01-15
- 2.8.3-b.2 (next) — 2025-01-12
- 6.0.7 — 2026-08-08
- 6.0.6 — 2026-08-08
- 6.0.5 — 2026-07-12
- 6.0.4 — 2026-06-28
- 6.0.3 — 2026-06-20
- 6.0.2 — 2026-05-20
- 6.0.1 — 2026-05-02
- 6.0.0 — 2026-05-02
- 5.1.11 — 2026-04-15
- 5.1.10 — 2026-04-11
- 5.1.9 — 2026-04-09
- 5.1.8 — 2026-04-07
- … 65 more at https://npm.io/package/@asamuzakjp/css-color/versions

## README

# CSS color

[![build](https://github.com/asamuzaK/cssColor/actions/workflows/node.js.yml/badge.svg)](https://github.com/asamuzaK/cssColor/actions/workflows/node.js.yml)
[![CodeQL](https://github.com/asamuzaK/cssColor/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/asamuzaK/cssColor/actions/workflows/github-code-scanning/codeql)
[![npm (scoped)](https://img.shields.io/npm/v/@asamuzakjp/css-color)](https://www.npmjs.com/package/@asamuzakjp/css-color)

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

```console
npm i @asamuzakjp/css-color
```

## Quick Start

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

### Samples

1. Resolve complex modern CSS colors:

```javascript
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 calc():

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

3. Convert between color spaces:

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

4. Validate colors and gradients:

```javascript
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.

<!-- prettier-ignore -->
| Function | Returns | Options | Description |
| :-------------- | :-------------- | :-------------- | :-------------- |
| `convert.colorToHex(value, opt?)` | `string \| null` | `opt.alpha` `<boolean>`<br>_(+ 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.

<!-- prettier-ignore -->
| Function | Returns | Options (`opt`) | Description |
| :-------------- | :-------------- | :-------------- | :-------------- |
| `utils.cssCalc(value, opt?)` | `string` | `opt.dimension`<br>_(+ see `resolve` options)_ | Resolves CSS `calc()` expressions. |
| `utils.cssVar(value, opt?)` | `string` | `opt.customProperty`<br>_(+ 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`<br>_(+ see `resolve` options)_ | Converts an absolute or relative CSS length to pixels. |
| `utils.splitValue(value, opt?)` | `string[]` | `opt.delimiter` `<string>`<br>`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:

- [csstools/postcss-plugins](https://github.com/csstools/postcss-plugins)
- [lru-cache](https://github.com/isaacs/node-lru-cache)

---

Copyright (c) 2024 [asamuzaK (Kazz)](https://github.com/asamuzaK/)

---
_Source: https://npm.io/package/@asamuzakjp/css-color · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._