Chromancy — Steal colors from any image

Installation

Chromancy is a browser-only library with zero dependencies. Install via npm or your favorite package manager.

# npm
npm install chromancy

# yarn
yarn add chromancy

# pnpm
pnpm add chromancy

Import the functions you need:

import { chromancy, chromancyBatch, clearCache } from 'chromancy';
// or
const { chromancy } = require('chromancy');

chromancy() Main

The primary function for extracting colors from a single image. Pass an HTMLImageElement or a URL string.

Promise<ChromancyResult>

const result = await chromancy(source, options?);

// With an image element
const img = document.getElementById('my-image');
const result = await chromancy(img, { paletteSize: 5 });

// With a URL string
const result = await chromancy('https://example.com/photo.jpg', {
  outputFormat: 'hex',
  paletteSize: 3,
});

Parameters

Parameter	Type	Description
`source`	`HTMLImageElement \| string`	An image element or a URL string pointing to the image.
`options`	`ChromancyOptions`	Optional configuration object (see Options).

chromancyBatch()

Analyzes multiple images in parallel. Returns an array of results in the same order as the input sources.

Promise<ChromancyResult[]>

import { chromancyBatch } from 'chromancy';

const results = await chromancyBatch([
  'https://example.com/1.jpg',
  'https://example.com/2.jpg',
  'https://example.com/3.jpg',
], { paletteSize: 5 });

// results[0] -> result for 1.jpg
// results[1] -> result for 2.jpg
// results[2] -> result for 3.jpg

clearCache()

Clears the internal URL result cache. Use this when you want to force re-analysis of previously fetched images.

import { clearCache } from 'chromancy';

// First call — analyzes the image
await chromancy('https://example.com/photo.jpg');

// Second call — returns cached result instantly
await chromancy('https://example.com/photo.jpg');

// Clear cache when needed
clearCache();

Utilities

rgbToHex()

Converts an RGB string to a Hex string.

import { rgbToHex } from 'chromancy';

rgbToHex('rgb(128, 64, 32)');
// -> "#804020"

rgbToHsl()

Converts an RGB string to an HSL string.

import { rgbToHsl } from 'chromancy';

rgbToHsl('rgb(128, 64, 32)');
// -> "hsl(20, 43%, 31%)"

rgbToObject()

Converts an RGB string to an { r, g, b } object.

import { rgbToObject } from 'chromancy';

rgbToObject('rgb(128, 64, 32)');
// -> { r: 128, g: 64, b: 32 }

Options

Option	Type	Default	Description
`maxSize`	`number`	`100`	Maximum width or height (in pixels) to resize the image for analysis.
`quantizationLevel`	`number`	`32`	Color quantization level. Lower = more color bins (finer detail). Higher = less precision.
`sampleRate`	`number`	`0.1`	Fraction of pixels to sample (0 to 1). 0.5 = half of pixels.
`paletteSize`	`number`	`5`	Number of distinct colors in the palette. Set to 0 to disable.
`colorScale`	`number`	`0`	Normalizes and scales color intensity. 0 = no scaling.
`outputFormat`	`string`	`'rgb'`	Output format: `'rgb'`, `'hex'`, `'hsl'`, or `'object'`.

Output Formats

// RGB (default)
const rgb = await chromancy(url, { paletteSize: 3 });
// rgb.averageColor  -> "rgb(128,64,32)"

// Hex
const hex = await chromancy(url, { paletteSize: 3, outputFormat: 'hex' });
// hex.averageColor  -> "#804020"

// HSL
const hsl = await chromancy(url, { paletteSize: 3, outputFormat: 'hsl' });
// hsl.averageColor  -> "hsl(20,43%,31%)"

// Object
const obj = await chromancy(url, { paletteSize: 3, outputFormat: 'object' });
// obj.averageColor  -> { r: 128, g: 64, b: 32 }

TypeScript

Chromancy ships with built-in TypeScript definitions.

import { chromancy, ChromancyOptions, ChromancyResult } from 'chromancy';

const options: ChromancyOptions = {
  maxSize: 150,
  quantizationLevel: 16,
  sampleRate: 0.2,
  paletteSize: 5,
  outputFormat: 'hex',
};

const result: ChromancyResult = await chromancy('https://example.com/photo.jpg', options);

// ChromancyResult shape:
//   averageColor:  string
//   dominantColor: string
//   palette:       string[]
//   properties:    { brightness, warmth, saturation, contrast }

Next.js / SSR

Because Chromancy requires the browser's DOM, use dynamic import with ssr: false:

'use client';
import { useRef, useEffect } from 'react';

export default function ImageAnalyzer() {
  const imageRef = useRef<HTMLImageElement>(null);

  useEffect(() => {
    async function analyze() {
      if (!imageRef.current) return;
      const { chromancy } = await import('chromancy');
      const result = await chromancy(imageRef.current, { maxSize: 150, paletteSize: 5 });
      document.body.style.backgroundColor = result.dominantColor;
    }
    analyze();
  }, []);

  return (
    <img
      ref={imageRef}
      src="/your-image.jpg"
      alt="Sample"
      style={{ maxWidth: '100%', height: 'auto' }}
    />
  );
}

Browser Support

Chromancy uses browser DOM APIs (canvas, document) and works in all modern browsers.

Chrome	Firefox	Safari	Edge
60+	60+	12+	79+

Note: Cross-origin images require proper CORS headers. The library will throw an error if the image cannot be loaded due to CORS restrictions.