chroma.js
Color manipulation library for JavaScript. Handles conversions, scales, blending, and WCAG contrast calculations.
Setup
# Install chroma.js — works in Node and browser.
npm install chroma-js
npm install -D @types/chroma-js
Basic Color Operations
// src/colors/basics.ts — Create colors, convert between spaces, adjust properties.
import chroma from "chroma-js";
// Parse from any format
const red = chroma("#ff0000");
const blue = chroma("rgb(0, 0, 255)");
const green = chroma(120, 1, 0.5, "hsl");
// Convert between formats
console.log(red.hex()); // "#ff0000"
console.log(red.rgb()); // [255, 0, 0]
console.log(red.hsl()); // [0, 1, 0.5]
console.log(red.lab()); // [53.23, 80.11, 67.22]
// Adjust properties
const lighter = red.brighten(2);
const muted = red.desaturate(1.5);
const translucent = red.alpha(0.5);
Generating Color Scales
// src/colors/scales.ts — Build continuous color scales for data visualization.
// Scales interpolate between stops and can output any number of discrete colors.
import chroma from "chroma-js";
// Two-stop scale
const heatScale = chroma.scale(["#fafa6e", "#2A4858"]).mode("lch");
console.log(heatScale(0.5).hex()); // midpoint color
// Multi-stop diverging scale
const diverging = chroma
.scale(["#d73027", "#ffffbf", "#1a9850"])
.mode("lab")
.domain([-1, 0, 1]);
// Generate 7 discrete colors from a scale
const palette = chroma.scale(["#fce4ec", "#880e4f"]).colors(7);
Accessible Contrast Checking
// src/colors/accessibility.ts — Check WCAG contrast ratios between foreground
// and background colors. Returns ratio and pass/fail for AA and AAA.
import chroma from "chroma-js";
export function checkContrast(fg: string, bg: string) {
const contrast = chroma.contrast(fg, bg);
return {
ratio: Math.round(contrast * 100) / 100,
aa: contrast >= 4.5,
aaLarge: contrast >= 3,
aaa: contrast >= 7,
};
}
// Find the best text color for a given background
export function autoTextColor(bg: string): string {
return chroma(bg).luminance() > 0.45 ? "#000000" : "#ffffff";
}
Palette Generation
// src/colors/palette.ts — Generate harmonious palettes from a base color
// using color theory (complementary, triadic, analogous).
import chroma from "chroma-js";
export function generatePalette(base: string, type: "complementary" | "triadic" | "analogous") {
const [h, s, l] = chroma(base).hsl();
const shifts: Record<string, number[]> = {
complementary: [0, 180],
triadic: [0, 120, 240],
analogous: [-30, 0, 30],
};
return shifts[type].map((shift) =>
chroma.hsl((h + shift + 360) % 360, s, l).hex()
);
}
// Bezier interpolation for smoother multi-color palettes
const smooth = chroma.bezier(["#f00", "#ff0", "#0f0"]).scale().colors(9);
Mixing and Blending
// src/colors/blending.ts — Mix two colors in a given color space.
// LAB mixing produces more perceptually uniform results than RGB.
import chroma from "chroma-js";
const mixed = chroma.mix("#ff0000", "#0000ff", 0.5, "lab");
console.log(mixed.hex()); // perceptual midpoint
// Average multiple colors
const avg = chroma.average(["#ddd", "#ff0", "#09f"], "lab");