Guide · Open source

How to use color-thief: extract palettes from images in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Color Thief is a JavaScript library that reads an image and reports its main colors, either a single dominant color or a palette. It runs in the browser on images, canvases, and videos, and in Node.js on file paths and Buffers. This guide shows you how to install it, extract colors in both environments, and use the options and color properties that matter for theming interfaces.

Color Thieflokesh/color-thief · ★ 13.7k · MIT Install options & downloads

Quick start

1Install the package. Run npm install colorthief in your project folder. Make sure Node.js is available.
2Choose your environment. Use the browser functions with image, canvas, or video elements, or the async functions in Node.js with file paths or Buffers.
3Import the functions you need. Import getColor, getPalette, or getSwatches from 'colorthief'. Sync variants are browser only.
4Pass the source and options. Give the function your image and optional settings such as colorCount, quality, or region.
5Read the Color object. Call hex(), css(), or textColor on the result to apply the color to your interface.
6Check contrast before using text colors. Use the contrast property, which gives WCAG ratios for white, black, and foreground, to confirm readability.

Install colorthief with npm

Color Thief is distributed as the npm package colorthief. Install it in your project with the package manager command below. The README lists Node.js as the prerequisite, but does not state a minimum version, so check the project documentation for compatibility with your setup.

If you do not use a bundler, the README also shows loading the library directly from a CDN with a script tag pointing at the UMD build on unpkg.

npm install colorthief

Get a dominant color from an image in the browser

In a web page, pass an image element to getColorSync for a synchronous dominant color, or to getColor for the async version. The result is a Color object with methods such as hex() and css(), plus properties such as isDark and textColor.

Browser sources include HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, ImageData, ImageBitmap, and OffscreenCanvas.

hex() returns a string like '#e84393'
css() returns a string like 'rgb(232, 67, 147)'
textColor returns '#ffffff' or '#000000' as a recommended text color
isDark and isLight return booleans

import { getColorSync, getPaletteSync } from 'colorthief';

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

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

Get a palette and semantic swatches

Use getPaletteSync or getPalette with a colorCount option to set how many colors you receive. The option accepts values from 2 to 20 and defaults to 10.

getSwatches returns named swatches such as Vibrant, Muted, DarkVibrant, DarkMuted, LightVibrant, and LightMuted. Each swatch can be empty, so use optional chaining when you read it.

import { getPalette, getSwatches } from 'colorthief';

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

const swatches = await getSwatches(img);
swatches.Vibrant?.color.hex();

Use color-thief in Node.js

In Node.js, use the async functions getColor and getPalette. They accept a file path or a Buffer. The README notes that image decoding uses sharp.

For command-line use, the README shows the colorthief-cli package, which bundles sharp so it works without extra setup. The README excerpt is truncated before the full list of CLI commands, so check the project's README for the flags it supports.

Pass a file path string such as '/path/to/image.jpg'
Pass a Buffer, for example from a file you have already read

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 });

Tune extraction with options

Several options change what gets sampled. quality sets the sampling rate, where 1 reads every pixel and 10 reads every 10th pixel, and it defaults to 10. colorSpace defaults to 'oklch' and can also be 'rgb'. ignoreWhite defaults to true, so white pixels are skipped.

The region option samples only part of the image. Its values are fractions from 0 to 1 measured from the top-left, so the same values work for a thumbnail and a full-size original. This is useful for a gradient that overlaps the bottom of an image.

colorCount: number of palette colors, 2 to 20, default 10
quality: sampling rate, default 10
colorSpace: 'oklch' (default) or 'rgb'
region: { x, y, width, height } as 0 to 1 fractions
signal: an AbortSignal to cancel extraction
gamut: 'srgb' (default), 'display-p3', or 'auto' (browser only)

const palette = await getPalette(img, {
    region: { x: 0, y: 0.66, width: 1, height: 0.34 },
});

Keep live video or canvas colors updated

The observe function watches a video, canvas, or img element and calls your onChange callback with new palettes. For images it uses a MutationObserver to detect src changes. For video and canvas it polls with requestAnimationFrame, limited by a throttle value in milliseconds. observe is browser only.

To keep work off the main thread, the README recommends running Color Thief inside your own Web Worker and passing it an ImageBitmap. The worker: true option is deprecated and ignored as of v3.

import { observe } from 'colorthief';

const controller = observe(videoElement, {
    throttle: 200,
    colorCount: 5,
    onChange(palette) {
        updateAmbientBackground(palette);
    },
});

controller.stop();

What people use it for

Setting an accent color on a product card based on the photo's dominant color
Choosing a page or banner background from an image's bottom third using region
Updating ambient lighting or background colors while a video plays with observe()
Generating palette data for image files on a Node.js server
Picking a legible text color for content placed over an extracted background

Frequently asked questions

Is color-thief free to use?

The README states the package is licensed under MIT. Check the LICENSE file in the repository for the full terms before you use it in a commercial project.

How do I install color-thief?

Run npm install colorthief in your project. The README also shows loading the library from a CDN script tag if you are not using a package manager.

Does color-thief work in Node.js?

Yes. In Node.js you use getColor and getPalette with a file path or Buffer, and image decoding uses sharp. The README notes that Node output is sRGB for now.

Can color-thief run without writing code?

Not really. The README describes a library API and a CLI, not a graphical tool. The colorthief-cli package lets you run it from the terminal with npx colorthief-cli photo.jpg.

How does color-thief compare to node-vibrant?

Both extract colors from images, and node-vibrant is listed as a comparable project. This guide does not include benchmarks, so test both on your own images to see which output suits your use case.

Why does my color look different from the original photo?

By default colors are read and reported in sRGB, and the default quantization is OKLCH. For wide-gamut images you can set gamut to 'display-p3', but the README does not claim print accuracy, so do not rely on it for print color matching.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Color Thief suits web and Node.js developers who want image-based accent colors, backgrounds, or live theming, and it includes contrast values for readable text. It is not a finished app, and it is not a tool for exact print color work, so pick another option if you need a graphical editor or print-accurate color science.

Install options & downloads