chroma-js

library3.2.0jsnpmunverified

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.

serialization data

npm install chroma-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CHROMA-JS

chroma-js

serializationjavascriptv3.2.0

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.

chroma

✓ import chroma from 'chroma-js';

✗ const chroma = require('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.

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)`

Debug

Known issues

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

affects: >=2.5.0

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

affects: >=3.0.0

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

affects: >=3.2.0

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

affects: *

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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(...)'

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

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gka/chroma.js ↗

packagehttps://www.npmjs.com/package/chroma-js ↗

homepagehttps://www.chroma-js.com/ ↗