Chroma.js

Common errors

• ReferenceError: require is not defined

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

• Uncaught TypeError: chroma.scale is not a function

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

• color.css() output is 'oklab(...)' but I expected 'rgb(...)'

  cause After v3.0.0, `color.css()` defaults to modern CSS color space outputs (e.g., `oklab()`, `lch()`) instead of legacy `rgb()` or `rgba()`.
  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).

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Refer to the official GitHub repository and Discord channel for the most up-to-date information on the project's status and development.

Install

• npm install chroma-js npm
• yarn add chroma-js yarn
• pnpm add chroma-js pnpm

Imports

• chroma
  wrong:

  const chroma = require('chroma-js');

  correct:

  import chroma from 'chroma-js';

  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.
• ChromaStatic

  import type { ChromaStatic } from 'chroma-js';

  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.
• Color

  import type { Color } from 'chroma-js';

  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.

Quickstart

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.

import chroma from 'chroma-js';

// --- Basic color manipulation ---
const initialColor = '#D4F880';
const colorInstance = chroma(initialColor);

// Darken and get hex string
const darkenedHex = colorInstance.darken().hex();
console.log(`Original: ${initialColor}, Darkened: ${darkenedHex}`); // Expected: #D4F880, #a1c550

// Lighten and get RGB array
const lightenedRgb = colorInstance.brighten(0.5).rgb();
console.log(`Lightened RGB: [${lightenedRgb.join(', ')}]`);

// --- Working with color scales ---
const scale1 = chroma.scale(['white', 'red']);
const intermediateColor1 = scale1(0.5).hex();
console.log(`Linear scale (white to red) at 0.5: ${intermediateColor1}`); // Expected: #FF7F7F

// Custom domain and mode
const myValues = [0, 10, 50, 100];
const customScale = chroma.scale(['lightyellow', 'navy'])
                          .domain(myValues, 5, 'quantiles')
                          .mode('lab'); // Lab interpolation for smoother transitions

// Get a color from the custom scale
const colorFromCustomScale = customScale(25).hex();
console.log(`Custom scale (quantiles, lab mode) at 25: ${colorFromCustomScale}`);

// Transparent color parsing (v3.1.0+)
const transparentColor = chroma('transparent').css();
console.log(`Transparent color parsed: ${transparentColor}`); // Expected: rgba(0,0,0,0) (or similar modern CSS format)`