lokesh/color-thief

Color Thief

Extract dominant colors and palettes from images in the browser and Node.js.

Install

npm install colorthief

Or load directly from a CDN:

<script src="https://unpkg.com/colorthief@3/dist/umd/color-thief.global.js"></script>

Quick Start

import { getColorSync, getPaletteSync, getSwatches } from 'colorthief';

// Dominant color
const color = getColorSync(img);
color.hex();      // '#e84393'
color.css();      // 'rgb(232, 67, 147)'
color.isDark;     // false
color.textColor;  // '#000000'

// Palette
const palette = getPaletteSync(img, { colorCount: 6 });
palette.forEach(c => console.log(c.hex()));

// Semantic swatches (Vibrant, Muted, DarkVibrant, etc.)
const swatches = await getSwatches(img);
swatches.Vibrant?.color.hex();

Features

• TypeScript — full type definitions included
• Browser + Node.js — same API, both platforms
• Sync & async — synchronous browser API, async for Node.js
• Live extraction — observe() watches video, canvas, or img elements and emits palette updates reactively
• Worker friendly — runs inside your own Web Worker via ImageBitmap or OffscreenCanvas
• Progressive extraction — 3-pass refinement for instant rough results
• OKLCH quantization — perceptually uniform palettes via colorSpace: 'oklch'
• Semantic swatches — Vibrant, Muted, DarkVibrant, DarkMuted, LightVibrant, LightMuted
• Rich Color objects — .hex(), .rgb(), .hsl(), .oklch(), .css(), contrast ratios, text color recommendations
• WCAG contrast — color.contrast.white, color.contrast.black, color.contrast.foreground
• AbortSignal — cancel in-flight extractions
• CLI — colorthief photo.jpg with JSON, CSS, and ANSI output
• Zero runtime dependencies

API at a Glance

Options

Color Object

Region extraction

Pass a region to sample only part of the image. Coordinates are fractions of the image size (0–1) measured from the top-left, so a region is resolution-independent — the same values work for a thumbnail and the full-size original.

// Colors from the bottom third — e.g. for a gradient that overlaps the
// bottom of the image
const palette = await getPalette(img, {
    region: { x: 0, y: 0.66, width: 1, height: 0.34 },
});

// Center crop
const color = await getColor(img, {
    region: { x: 0.25, y: 0.25, width: 0.5, height: 0.5 },
});

Works everywhere an option object does: getColor, getPalette, getSwatches, getPaletteProgressive, the *Sync functions, observe(), and the CLI — in both browser and Node. A region that runs past the right or bottom edge is clamped to the image; out-of-range or zero-sized values throw.

Browser

import { getColorSync, getPaletteSync } from 'colorthief';

const img = document.querySelector('img');
const color = getColorSync(img);
console.log(color.hex());

const palette = getPaletteSync(img, { colorCount: 5 });

Accepts HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, ImageData, ImageBitmap, and OffscreenCanvas.

Wide-gamut (Display P3)

By default colors are read and reported in sRGB. For P3-tagged / wide-gamut images, pass gamut to preserve the extra saturation:

// Force P3: read the image through a P3 canvas, report P3 colors
const palette = await getPalette(img, { gamut: 'display-p3' });
palette[0].css();            // 'color(display-p3 0.92 0.2 0.14)'
palette[0].gamut;            // 'display-p3'

// Auto: report P3 only when the image actually uses out-of-sRGB colors,
// otherwise behave exactly like sRGB
const auto = await getPalette(img, { gamut: 'auto' });

.rgb(), .array(), and .hex() always return sRGB (gamut-mapped when the color is P3), so existing rgb(...) strings keep working. The wide-gamut values live in .css() and .oklch(); use .rgb('display-p3') for the raw P3 components. Falls back to sRGB where P3 canvas support is unavailable. Node output is sRGB for now.

Live extraction with observe()

import { observe } from 'colorthief';

// Watch a video and update ambient lighting as it plays
const controller = observe(videoElement, {
    throttle: 200,    // ms between updates
    colorCount: 5,
    onChange(palette) {
        updateAmbientBackground(palette);
    },
});

// Stop when done
controller.stop();

Works with <video>, <canvas>, and <img> elements. For images, it uses a MutationObserver to detect src changes. For video and canvas, it polls using requestAnimationFrame with throttle.

Web Workers

To keep extraction off the main thread, run Color Thief inside your own worker and hand it an ImageBitmap. Bitmaps are transferable, so the pixels move without being copied, and decoding, sampling, and quantization all happen off-thread.

// main.js
const bitmap = await createImageBitmap(await (await fetch(url)).blob());
const worker = new Worker('./palette-worker.js', { type: 'module' });
worker.postMessage({ bitmap }, [bitmap]); // transferred, not cloned
worker.onmessage = (e) => render(e.data.palette);

// palette-worker.js
import { getPalette } from 'colorthief';

self.onmessage = async ({ data }) => {
    const palette = await getPalette(data.bitmap, { colorCount: 5 });
    // Color objects don't survive structured clone — send plain data
    self.postMessage({ palette: palette.map((c) => c.hex()) });
};

Deprecated: the worker: true option is ignored as of v3 and will be removed in v4, along with the isWorkerSupported, extractInWorker, and terminateWorker exports from colorthief/internals. It only moved quantization off-thread while leaving decoding, pixel sampling, and the structured clone of the pixel array on the main thread — and serializing that array cost several times more than the quantization it saved. It also quantized in RGB while the default path uses OKLCH, so worker: true returned different colors. Calls that pass it now go through the normal pipeline and log a one-time warning.

Node.js

import { getColor, getPalette } from 'colorthief';

const color = await getColor('/path/to/image.jpg');
console.log(color.hex());

const palette = await getPalette(Buffer.from(data), { colorCount: 5 });

Accepts file paths and Buffers. Uses sharp for image decoding.

CLI

Quick start

npx colorthief-cli photo.jpg

The colorthief-cli package bundles everything needed (including sharp for image decoding), so it works immediately with no extra setup.

Commands

# Dominant color
colorthief-cli photo.jpg

# Color palette
colorthief-cli palette photo.jpg

# Semantic swatches
colorthief-cli swatches photo.jpg

Output formats

# Default: ANSI color swatches
colorthief-cli photo.jpg
# ▇▇ #e84393

# JSON with full color data
colorthief-cli photo.jpg --json

# CSS custom properties
colorthief-cli palette photo.jpg --css
# :root {
#     --color-1: #e84393;
#     --color-2: #6c5ce7;
# }

Options

colorthief-cli palette photo.jpg --count 5        # Number of colors (2-20)
colorthief-cli photo.jpg --quality 1              # Sampling quality (1=best)
colorthief-cli photo.jpg --color-space rgb        # Color space (rgb or oklch)
colorthief-cli photo.jpg --region 0,0.66,1,0.34   # Sample the bottom third

--region takes x,y,width,height as fractions of the image size (0–1), the same as the region option.

Stdin is supported — use - or pipe directly:

cat photo.jpg | colorthief-cli -

Multiple files are supported. Output is prefixed with filenames, and --json wraps results in an object keyed by filename.

Note: If you already have colorthief and sharp installed in a project, you can also use colorthief directly as the command name (without the -cli suffix).

Links

• Demo page & live examples
• Changelog
• Roadmap
• GitHub
• npm

Contributing

npm run build          # Build all dist formats
npm run test           # Run all tests (Mocha + Cypress)
npm run test:node      # Node tests only
npm run test:browser   # Browser tests (requires npm run dev)
npm run dev            # Start local server on port 8080

Releasing

# 1. Make sure you're on master with a clean working tree
git status

# 2. Add the new version's entry to CHANGELOG.md and commit it

# 3. Run the full test suite
npm run build
npm run test:node
npm run test:browser   # requires npm run dev in another terminal

# 4. Preview what will be published
npm pack --dry-run

# 5. Tag and publish
npm version <major|minor|patch>   # bumps version, creates git tag
npm publish                       # builds via prepublishOnly, then publishes
git push && git push --tags

License

MIT - Lokesh Dhakar