Extract Colors

Extract color palettes from images.
Simple use, tree shaking, fast process and no dependencies for browser. Need image reader dependence for node.js

Website | Demo | Guide

Install

For browser

npm install --save extract-colors

For node.js

Need to install an ImageData extractor like get-pixels

npm install --save extract-colors get-pixels

Usage

Browser example

import { extractColors } from "extract-colors";

const src = "my-image.jpg";

extractColors(src).then(console.log).catch(console.error);

You can use different types for src param (String for a path of image, HTMLImageElement or ImageData).

Node.js example

const path = require("path");
const getPixels = require("get-pixels");
const { extractColors } = require("extract-colors");

const src = path.join(__dirname, "./my-image.jpg");

getPixels(src, (err, pixels) => {
  if (!err) {
    const data = [...pixels.data];
    const [width, height] = pixels.shape;

    extractColors({ data, width, height }).then(console.log).catch(console.log);
  }
});

This example use get-pixels but you can change the lib. Just send the ImageData object to extractColors(imageData).

ExtractorOptions

const options = {
  pixels: 64000,
  distance: 0.2,
  colorValidator: (red, green, blue, alpha = 255) => alpha > 250,
  defaultColors: ["dominants", "accents"],
};

extractColors(src, options).then(console.log).catch(console.error);

pixels
Total pixel number of the resized picture for calculation
Type: Integer
Default: 64000

fastDistance
From 0 to 1 is the RGB color distance to not have near colors (1 distance is between white and black). Increase the value accelerate the calculation and reduce the output list of colors.
Type: Number
Default: distance / 2 or 0.2

distance
Minimum distance between two colors otherwise the colors will be merged (from 0 to 1). Calculation with the Lab* CIE deltaE color distance.
Type: Number
Default: fastDistance * 2 or 0.22

colorValidator
Test function to enable only some colors
Type: Function
Default: (red, green, blue, alpha = 255) => alpha > 250

crossOrigin
Only for browser, can be 'Anonymous' to avoid client side CORS (the server side images need authorizations too)
Type: String
Default: ""

requestMode
Only for Web Workers in browser: it's used to determine if cross-origin requests lead to valid responses, and which properties of the response are readable
Type: String
Default: cors

colorClassifications
List of classified types of colors
Type: String[]
Default: [ "dominants", "accents", "dominantsLight", "dominantsMidtone", "dominantsDark", "accentsLight", "accentsMidtone", "accentsDark", "dullests", "vivids", "dullestsLight", "dullestsMidtone", "dullestsDark", "vividsLight", "vividsMidtone", "vividsDark", "lightests", "midtones", "darkests", "warmest", "coolest", "warmestLight", "warmestMidtone", "warmestDark", "coolestLight", "coolestMidtone", "coolestDark" ]

defaultColors
Default classified colors if no colors founds in the image
Type: Boolean or { [colorClassifications]?: Boolean, Number or () => Number } Default: false

defaultMainColor Default classified color if no colors found in the image and if defaultColors is not false
Type: Number
Default: 0x0077ff

Return of the promise

List colors and colors classified with the followed properties:

{
  // List of cleaned colors
  list: [
    {
      hex: number,​​ // from 0x000000 to 0xFFFFFF
      hexString: "#858409", // from "#000000" to "#FFFFFF"
      area: number, // from 0 to 1
      rgb: [number, number, number], // RGB colors (from 0 to 255 by chanel)
      hsl: [number, number, number], // HSL colors (from 0 to 1 by chanel)
      ecHsl: [number, number, number], // Fake HSL calculated from CIELAB colors (from 0 to 1 by chanel)
      lab: [number, number, number], // CIELAB colors
      count: number // number of pixel near of this color or near colors (determined with distance and fastDistance)
    },
    ...
  ],
  dominants: [...], // List of dominants cleaned colors
  accents: [...], // List of accents cleaned colors
  ...
}

Colors details

License

MIT

Copyright (c) 2025-present, Damien Doussaud