Color Thief
A JavaScript library that pulls dominant colors and palettes out of images, in browsers and Node.js.
- Stars
- 13.7k
- Forks
- 1.3k
- Licence
- MIT
- Language
- TypeScript
- Last update
- 3 months ago
- Type
- Library
What it is
Color Thief reads an image and reports its main colors, such as a dominant color or a set of palette colors. It works in a web page on images, canvases, and videos, and in Node.js on file paths and Buffers. Developers use it to theme interfaces or backgrounds based on a picture.
- Pick a dominant color from a product photo and use it as a page accent
- Extract a six-color palette from an uploaded image with getPalette
- Sample only the bottom third of an image with the region option
- Watch a video element and update a background as it plays using observe()
- Run the CLI on a photo with npx colorthief-cli photo.jpg
Great for
- Web developers who want an image-based accent or background color
- Node.js developers generating color data from image files
- Teams building live ambient lighting or theming from video or canvas
- Developers who need WCAG contrast values for text on extracted colors
Not ideal for
- People who want a finished app with no coding: the README describes a library API and a CLI, not a graphical tool
- Projects needing exact color science for print: the README describes sRGB and OKLCH quantization but does not claim print accuracy
- Anyone needing Node output in wide-gamut color: the README says Node output is sRGB for now
How to get it
- 1
Install with a package manager
You'll need: Node.js (version not stated in the README excerpt)
Install the library
npm install colorthief - 2
Run it
- Install the package with npm install colorthief.
- Import getColor or getPalette from 'colorthief'.
- Pass an image element in the browser or a file path in Node.js.
- Read the result with .hex() or .css().
- 3
Get the most out of it
- Use colorSpace: 'oklch' (the default) for perceptually uniform palettes, as described in the README.
- Use the region option to sample a sub-rectangle and ignore unwanted areas.
- Use getSwatches for named roles such as Vibrant and DarkMuted.
- Use getPaletteProgressive for a fast rough result before a full pass.
Downloads
Strengths
- Same API across browser and Node.js, per the README
- Zero runtime dependencies, according to the README
- Ships TypeScript type definitions
Trade-offs
- Node.js image decoding relies on sharp, which adds a native dependency to that setup
- Some features, such as observe() and the sync functions, are browser only
- The worker option is deprecated and ignored as of v3, so worker use requires following the documented ImageBitmap pattern
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.