@ltcode/color-extractor

Extract dominant colors from images easily using JavaScript/TypeScript. Compatible with Node.js and Browsers!

Installation

npm install @ltcode/color-extractor

Usage

📦 Node.js

import { extractColors } from '@ltcode/color-extractor';

// Extract 5 dominant colors in hexadecimal format
const colors = await extractColors('path/to/image.jpg');
console.log(colors); // ['#ff8040', '#2a5d84', '#f4e8d0', ...]

🌐 Browser

import { extractColors } from '@ltcode/color-extractor';

// File upload
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const colors = await extractColors(file);
  console.log(colors);
});

// HTML image element
const img = document.querySelector('img');
const colors = await extractColors(img);

// Canvas
const canvas = document.querySelector('canvas');
const colors = await extractColors(canvas);

// Image URL (with CORS)
const colors = await extractColors('https://example.com/image.jpg');

Advanced Options

import { extractColors, extractDominantColor } from '@ltcode/color-extractor';

// Extract only the dominant color
const dominantColor = await extractDominantColor('image.jpg');

// Custom options
const colors = await extractColors('image.jpg', {
  maxColors: 8,        // Maximum number of colors (default: 5)
  quality: 5,          // Analysis quality (default: 10)
  format: 'rgb',       // Format: 'hex', 'rgb', 'hsl'
  ignoreLightColors: true,  // Ignore light colors
  ignoreDarkColors: false   // Ignore dark colors
});

Using with Buffer (Node.js)

import fs from 'fs/promises';
import { extractColors } from '@ltcode/color-extractor';

const imageBuffer = await fs.readFile('image.jpg');
const colors = await extractColors(imageBuffer);

Drag & Drop in Browser

const dropZone = document.getElementById('dropZone');

dropZone.addEventListener('drop', async (e) => {
  e.preventDefault();
  const files = e.dataTransfer.files;
  
  if (files.length > 0) {
    const colors = await extractColors(files[0]);
    displayColors(colors);
  }
});

API

extractColors(input, options?)

• input:
  • Node.js: string (file path) | Buffer
  • Browser: string (URL) | File | HTMLImageElement | HTMLCanvasElement | ImageData
• options: ColorExtractionOptions - Configuration options
• Returns: Promise<ColorResult[]> - Array of colors

extractDominantColor(input, options?)

• input: Same as extractColors
• options: ColorExtractionOptions - Configuration options
• Returns: Promise<ColorResult | null> - Dominant color

extractPalette(input, options?)

Alias for extractColors - extracts complete color palette.

Options (ColorExtractionOptions)

{
  maxColors?: number;        // Maximum colors (default: 5)
  quality?: number;          // Quality 1-50 (default: 10)
  format?: 'hex'|'rgb'|'hsl'; // Output format (default: 'hex')
  ignoreLightColors?: boolean; // Ignore light colors
  ignoreDarkColors?: boolean;  // Ignore dark colors
}

Supported Environments

• ✅ Node.js 18+ (ES Modules)
• ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
• ✅ Bundlers (Webpack, Vite, Rollup, Parcel)

Image Formats

• Node.js: PNG, JPEG (basic implementation)
• Browser: All formats supported by the browser

Browser Demo

Check out the interactive demo to test in your browser!

Examples

See more examples in the GitHub repository

License

MIT