Registry / serialization / csscolorparser

csscolorparser

library1.0.3jsnpmunverified

csscolorparser is a lightweight JavaScript utility designed to parse CSS color strings into an RGBA array. It was initially released in 2012 and has not seen updates since version 1.0.3, published approximately 9 years ago. The package directly exports a single function, `parseCSSColor`, which takes a string (e.g., 'rgba(255, 128, 12, 0.5)', '#fff', 'slateblue') and returns a four-element array `[R, G, B, A]` where R, G, B are integers (0-255) and A is a float (0-1), or `null` for invalid input. Its primary differentiator is its simplicity and lack of dependencies, but its age means it only supports older CSS Color Module Level 3/4 formats and lacks support for newer specifications like HWB, LAB, LCH, Oklab, Oklch, or the `color()` function. It operates as a CommonJS module with interop for ESM.

serialization

npm install csscolorparser

github ↗package ↗

INSTALL

IMPORT

SIG · CSSCOLORPARSER

csscolorparser

serializationjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseCSSColor

✓ import parseCSSColor from 'csscolorparser';

✗ import { parseCSSColor } from 'csscolorparser';

The package exports a single function as its default, so named imports are incorrect. For CommonJS, use `const parseCSSColor = require('csscolorparser');`.

Demonstrates importing the default `parseCSSColor` function and using it to parse various valid and invalid CSS color strings, logging the RGBA array or null.

import parseCSSColor from 'csscolorparser'; console.log(parseCSSColor('rgba(255, 128, 12, 0.5)')); // Expected: [ 255, 128, 12, 0.5 ] console.log(parseCSSColor('#fff')); // Expected: [ 255, 255, 255, 1 ] console.log(parseCSSColor('slateblue')); // Expected: [ 106, 90, 205, 1 ] console.log(parseCSSColor('hsla(900, 15%, 90%, 0.5)')); // Expected: [ 226, 233, 233, 0.5 ] console.log(parseCSSColor('invalid-color-string')); // Expected: null console.log(parseCSSColor('rgb(100% 0% 0%)')); // Expected: [255, 0, 0, 1] (Supports percentages) console.log(parseCSSColor('hsl(240, 100%, 50%)')); // Expected: [0, 0, 255, 1]

Debug

Known issues

breakingThe package is explicitly noted to be 'not spec compliant' for certain `hsl` and `hsla` inputs. For example, `hsl(900, 0.15, 90%)` is parsed, but the `0.15` saturation is non-standard. Always validate outputs against current CSS specifications.

fix

Manually validate results or use a more actively maintained CSS color parser for strict spec compliance.

affects: >=1.0.0

gotchaThe parser returns `null` for `hsla(H, S, L)` without an explicit alpha channel (e.g., `hsla(900, 15%, 90%)`), even though the CSS spec defaults alpha to 1 in such cases. Explicitly use `hsla(H, S, L, 1)` or `hsl(H, S, L)` if you intend for full opacity.

fix

Always provide an explicit alpha value for `hsla` if expecting a non-null output, or use `hsl()` for opaque colors. Example: `parseCSSColor('hsla(900, 15%, 90%, 1)')`.

affects: >=1.0.0

breakingThis library has not been updated in approximately 9 years. It does not support newer CSS Color Module Level 4 and 5 syntaxes such as `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`, or `color-mix()` functions, which are now widely supported in modern browsers.

fix

For modern CSS color parsing capabilities, consider actively maintained alternatives like `@csstools/css-color-parser` or `color.js`.

affects: <=1.0.3

gotchaHex color strings must start with a `#` symbol. Inputs like `'ffffff'` will return `null` instead of parsing as a white color.

fix

Ensure all hexadecimal color strings include the leading `#` symbol. Example: `parseCSSColor('#ffffff')`.

affects: >=1.0.0

gotchaThe `parseCSSColor` function uses `module.exports = parseCSSColor` as its export mechanism, making it a CommonJS module with a default export. While ESM `import parseCSSColor from 'csscolorparser';` works due to Node.js's CJS-ESM interop, importing via named imports (`import { parseCSSColor } from 'csscolorparser';`) will fail.

fix

Use a default import for ESM (`import parseCSSColor from 'csscolorparser';`) or `require()` for CommonJS (`const parseCSSColor = require('csscolorparser');`).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'parseCSSColor')

Attempting to use `parseCSSColor` when it hasn't been correctly imported or when attempting a named import from a default-exported CommonJS module.

fix

Ensure the import statement is `import parseCSSColor from 'csscolorparser';` for ESM or `const parseCSSColor = require('csscolorparser');` for CommonJS. Do not use `import { parseCSSColor } from 'csscolorparser';`.

console.log(parseCSSColor('ffffff')) outputs 'null' but I expected white.

The parser strictly expects hex color strings to be prefixed with a `#`.

fix

Add the `#` prefix to all hexadecimal color strings: `parseCSSColor('#ffffff')`.

console.log(parseCSSColor('hsla(120, 50%, 50%)')) outputs 'null' but I expected green.

The `hsla()` function requires an explicit alpha channel value (even for opaque colors) to be parsed by this library, unlike the CSS specification which defaults it to `1`.

fix

Provide an explicit alpha value: `parseCSSColor('hsla(120, 50%, 50%, 1)')` or use `hsl()` which implicitly has alpha `1`: `parseCSSColor('hsl(120, 50%, 50%)')`.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/deanm/css-color-parser-js ↗

packagehttps://www.npmjs.com/package/csscolorparser ↗