{"id":10703,"library":"culori","title":"Culori Color Library","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Evercoder/culori","tags":["javascript","blend","ciede2000","cielab","color","color-difference","cubehelix","din99","gradients"],"install":[{"cmd":"npm install culori","lang":"bash","label":"npm"},{"cmd":"yarn add culori","lang":"bash","label":"yarn"},{"cmd":"pnpm add culori","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const converter = require('culori').converter;","symbol":"converter","correct":"import { converter } from 'culori';"},{"note":"Color space functions and accessors like `rgb` are typically lowercase named exports. Using incorrect casing (e.g., `RGB`) will result in an undefined import.","wrong":"import { RGB } from 'culori';","symbol":"rgb","correct":"import { rgb } from 'culori';"},{"note":"Most utility functions and core features are named exports from the `culori` package, not default exports. Attempting a default import will fail.","wrong":"import interpolate from 'culori';","symbol":"interpolate","correct":"import { interpolate } from 'culori';"},{"note":"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.","wrong":"import { oklch } from 'culori/css';","symbol":"oklch","correct":"import { oklch } from 'culori';"}],"quickstart":{"code":"import { converter, rgb, oklch, interpolate, inGamut, clampGamut } from 'culori';\n\n// 1. Convert colors between different color spaces\nconst parse = converter(); // Creates a universal color parser/converter\nconst redRgbString = 'rgb(255, 0, 0)';\nconst redOklch = parse(redRgbString, 'oklch');\nconsole.log(`Red in Oklch: { l: ${redOklch.l.toFixed(3)}, c: ${redOklch.c.toFixed(3)}, h: ${redOklch.h?.toFixed(2) || 'N/A'} }`);\n\n// 2. Interpolate between two colors in the Oklch space\nconst color1 = { mode: 'oklch', l: 0.5, c: 0.1, h: 60 }; // Yellow-ish\nconst color2 = { mode: 'oklch', l: 0.8, c: 0.15, h: 280 }; // Purple-ish\nconst interpolateOklch = interpolate([color1, color2], 'oklch');\nconst midColor = interpolateOklch(0.5); // Get the color at 50% interpolation\nconsole.log(`Interpolated mid-color (Oklch): { l: ${midColor.l.toFixed(3)}, c: ${midColor.c.toFixed(3)}, h: ${midColor.h?.toFixed(2) || 'N/A'} }`);\n\n// 3. Check if a color is within a specific gamut (e.g., sRGB)\nconst brightGreen = { mode: 'rgb', r: 0, g: 1.5, b: 0.5 }; // Out of gamut\nconst isBrightGreenInSrgb = inGamut('rgb')(brightGreen);\nconsole.log(`Is bright green {r:0, g:1.5, b:0.5} in sRGB gamut? ${isBrightGreenInSrgb}`);\n\n// 4. Clamp a color to a specific gamut (sRGB)\nconst clampedGreen = clampGamut('rgb')(brightGreen);\nconsole.log(`Clamped green to sRGB: rgb(${Math.round(clampedGreen.r * 255)}, ${Math.round(clampedGreen.g * 255)}, ${Math.round(clampedGreen.b * 255)})`);\n\n// 5. Create an Oklch color and convert it to an sRGB string for CSS output\nconst cssBlue = oklch(70, 0.15, 240); // A light blue Oklch color\nconst toRgbString = converter('rgb'); // Get a converter that outputs RGB objects\nconst cssBlueRgb = toRgbString(cssBlue);\nconst cssOutput = `rgb(${Math.round(cssBlueRgb.r * 255)}, ${Math.round(cssBlueRgb.g * 255)}, ${Math.round(cssBlueRgb.b * 255)})`;\nconsole.log(`Oklch color ${JSON.stringify(cssBlue)} as CSS RGB string: ${cssOutput}`);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Culori 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=4.0.2"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":">=4.0.2"},{"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.","message":"In 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.","severity":"gotcha","affected_versions":">=3.3.0 <4.0.0"},{"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.","message":"Versions 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.","severity":"gotcha","affected_versions":">=3.1.2 <4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'l')"},{"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.","cause":"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)`).","error":"SyntaxError: Malformed color string"},{"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.","cause":"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.","error":"Module not found: Error: Can't resolve 'culori/css'"},{"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';`.","cause":"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.","error":"Build error: 'x' is not exported from 'culori'"}],"ecosystem":"npm"}