lokesh/color-thief

★ 13,573TypeScriptAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((color-thief))
    What it does
      Dominant color
      Color palette
      Named swatches
    Environments
      Browser
      Node.js
      CLI
    Features
      Web Worker mode
      Live video observation
      Accessibility contrast
    Output formats
      Hex code
      RGB object
      HSL
      CSS string

mindmap root((color-thief)) What it does Dominant color Color palette Named swatches Environments Browser Node.js CLI Features Web Worker mode Live video observation Accessibility contrast Output formats Hex code RGB object HSL CSS string

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Extract the dominant color from a product image to automatically set the background or accent color of its card on a web page

USE CASE 2

Generate a color palette from a user-uploaded photo to create a custom theme for their profile or workspace

USE CASE 3

Build a reactive ambient background effect by watching a video element and updating a glow color as the scene changes

USE CASE 4

Use the CLI tool to extract colors from image files and output CSS custom properties for a design token pipeline

Tech stack

TypeScriptJavaScriptNode.jsWeb Worker

Getting it running

Difficulty · easy Time to first run · 5min

In plain English

Color Thief is a JavaScript library that analyzes an image and extracts its most prominent color or a palette of multiple colors. It works in web browsers and in Node.js server environments using the same API. The project is written in TypeScript, which means it ships with complete type definitions, and it has no external runtime dependencies. The core use cases are straightforward. You pass an image element, a canvas, a video, a file path, or a raw buffer to the library, and it returns color information in several formats: a hex code like #e84393, an RGB object, an HSL value, or a CSS-ready string. You can request either the single dominant color or a full palette of up to 20 colors. The library also provides named swatches labeled Vibrant, Muted, DarkVibrant, DarkMuted, LightVibrant, and LightMuted, which describe the role a color plays in the image rather than just its raw value. A few additional features stand out. The library can run color extraction off the main browser thread using a Web Worker, which prevents the calculation from making the page feel slow. It also supports progressive extraction, a three-pass process that delivers a rough palette almost immediately and refines it in subsequent passes. A live observation mode watches a video or canvas element and emits updated palettes as the content changes, which is useful for reactive backgrounds or ambient lighting effects. Each color object carries contrast ratio information against white and black backgrounds, following web accessibility guidelines, and includes a recommended text color for readability. A command-line tool is also included, so you can extract colors from image files directly in a terminal and receive output as JSON, CSS custom properties, or colored terminal swatches. Installation is via npm. The library can also be loaded directly from a CDN for browser use without any build step.

Copy-paste prompts

Prompt 1

Using color-thief in Node.js, write a script that reads all .jpg files in a folder and outputs a JSON file mapping each filename to its dominant hex color and a recommended text color for readability

Prompt 2

Using color-thief in a browser, extract a 6-color palette from a user-uploaded image and display each color as a swatch showing its hex value and whether white or black text is more readable on it

Prompt 3

Set up color-thief with a Web Worker to extract a palette from a large hero image without blocking the page scroll, then apply the dominant color as a CSS variable on the body element

Prompt 4

Use color-thief's live observation mode on an HTML video element to update a div background color in real time as the video plays, creating an ambient lighting effect

Open on GitHub → Explain another repo

← lokesh on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.