{"id":10625,"library":"chroma-js","title":"Chroma.js","description":"Chroma.js is a lightweight, zero-dependency JavaScript library for comprehensive color conversions and generating sophisticated color scales. Currently at v3.2.0, the library sees a consistent, though not rapid, release cadence, addressing bugs and introducing new features periodically. Its core strength lies in supporting a wide array of color models including RGB, HSL, HSV, Lab, Lch, Oklab, and Oklch, alongside modern CSS color syntax. Key differentiators include its powerful color scale generation capabilities, allowing for custom domains, quantile-based scaling, logarithmic scales, and improved interpolation modes like Lab/Lch for visually smoother transitions, distinguishing it from simpler color utilities. It also provides access to Color Brewer palettes.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"git://github.com/gka/chroma.js","tags":["javascript","color"],"install":[{"cmd":"npm install chroma-js","lang":"bash","label":"npm"},{"cmd":"yarn add chroma-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add chroma-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"As of v2.5.0, Chroma.js primarily ships as an ES module. Direct `require()` statements may not work in Node.js environments without transpilation or specific build configurations, leading to 'require is not defined' errors in pure ESM projects.","wrong":"const chroma = require('chroma-js');","symbol":"chroma","correct":"import chroma from 'chroma-js';"},{"note":"This type import is for explicit TypeScript typing of the default `chroma` object and its static methods (e.g., `chroma.scale`). Most users will rely on type inference.","symbol":"ChromaStatic","correct":"import type { ChromaStatic } from 'chroma-js';"},{"note":"Use this type to annotate variables that hold a `Color` object instance returned by `chroma(color)` or a method like `color.darken()`. This enhances type safety when manipulating color objects.","symbol":"Color","correct":"import type { Color } from 'chroma-js';"}],"quickstart":{"code":"import chroma from 'chroma-js';\n\n// --- Basic color manipulation ---\nconst initialColor = '#D4F880';\nconst colorInstance = chroma(initialColor);\n\n// Darken and get hex string\nconst darkenedHex = colorInstance.darken().hex();\nconsole.log(`Original: ${initialColor}, Darkened: ${darkenedHex}`); // Expected: #D4F880, #a1c550\n\n// Lighten and get RGB array\nconst lightenedRgb = colorInstance.brighten(0.5).rgb();\nconsole.log(`Lightened RGB: [${lightenedRgb.join(', ')}]`);\n\n// --- Working with color scales ---\nconst scale1 = chroma.scale(['white', 'red']);\nconst intermediateColor1 = scale1(0.5).hex();\nconsole.log(`Linear scale (white to red) at 0.5: ${intermediateColor1}`); // Expected: #FF7F7F\n\n// Custom domain and mode\nconst myValues = [0, 10, 50, 100];\nconst customScale = chroma.scale(['lightyellow', 'navy'])\n                          .domain(myValues, 5, 'quantiles')\n                          .mode('lab'); // Lab interpolation for smoother transitions\n\n// Get a color from the custom scale\nconst colorFromCustomScale = customScale(25).hex();\nconsole.log(`Custom scale (quantiles, lab mode) at 25: ${colorFromCustomScale}`);\n\n// Transparent color parsing (v3.1.0+)\nconst transparentColor = chroma('transparent').css();\nconsole.log(`Transparent color parsed: ${transparentColor}`); // Expected: rgba(0,0,0,0) (or similar modern CSS format)`","lang":"typescript","description":"This quickstart demonstrates basic color creation, manipulation (darken, brighten), and the creation of linear and custom-domain color scales with different interpolation modes, including modern CSS color handling."},"warnings":[{"fix":"Migrate `require('chroma-js')` statements to `import chroma from 'chroma-js';`. Ensure your project's `package.json` specifies `\"type\": \"module\"` for ESM, or use a bundler that correctly handles ESM.","message":"Beginning with v2.5.0, Chroma.js was refactored to primarily use ES modules. This change impacts how the library is imported, especially in Node.js environments that expect CommonJS modules.","severity":"breaking","affected_versions":">=2.5.0"},{"fix":"Update your code to expect modern CSS color string outputs from `color.css()`. If you require legacy CSS formats, consider manually formatting the RGB/RGBA values.","message":"As of v3.0.0, the `color.css()` method no longer returns legacy CSS color formats (e.g., `rgb(255, 255, 0)`). Instead, it outputs modern CSS color spaces like `lab()`, `lch()`, `oklab()`, `oklch()` by default.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review usage of `scale.domain` and `scale.range` in versions `>=3.2.0` to ensure they align with the updated behavior of returning all scaled positions. Test your color scales thoroughly.","message":"In v3.2.0, the `scale.domain` function was updated to return all scaled positions rather than only `[min, max]`. This fix might subtly change the interpolation or how you interact with the domain if your code relied on the previous, potentially limited, return value.","severity":"gotcha","affected_versions":">=3.2.0"},{"fix":"Refer to the official GitHub repository and Discord channel for the most up-to-date information on the project's status and development.","message":"Users sometimes perceive the project as inactive due to periods with fewer commits. However, the author clarifies that the library is stable and maintained, with bugs fixed and new features introduced when appropriate, rather than constant cosmetic changes.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const chroma = require('chroma-js');` to `import chroma from 'chroma-js';`. Ensure your `package.json` has `\"type\": \"module\"` if in a pure ESM Node.js environment.","cause":"Attempting to use CommonJS `require()` syntax in an ES module context or a Node.js project configured for ESM after Chroma.js moved to ES modules in v2.5.0.","error":"ReferenceError: require is not defined"},{"fix":"Verify `import chroma from 'chroma-js';` is correct. If using CommonJS, ensure your setup correctly transpiles or handles ESM. Check that `chroma-js` is installed correctly.","cause":"Incorrect import of the `chroma` object, possibly due to a default export issue or CJS/ESM mismatch, leading to `chroma` being `undefined` or not the expected object.","error":"Uncaught TypeError: chroma.scale is not a function"},{"fix":"Adapt your code to parse or expect modern CSS color strings. If legacy `rgb()/rgba()` is strictly needed, you might need to format the color components manually (e.g., `chroma(color).rgb().join(',')` for RGB values).","cause":"After v3.0.0, `color.css()` defaults to modern CSS color space outputs (e.g., `oklab()`, `lch()`) instead of legacy `rgb()` or `rgba()`.","error":"color.css() output is 'oklab(...)' but I expected 'rgb(...)'"}],"ecosystem":"npm"}