image-color-scheme

Detect the color scheme of an image ("dark" | "light" | "grayscale" | "color"). Works in browsers, Node.js, and edge runtimes.

Install

ES Module

npm install image-color-scheme

API

Browser

import { getImageColorScheme } from "image-color-scheme";

getImageColorScheme(image, options);

• image: Input image source (CanvasImageSource: can be img or svg element).
• options?: Optional options object.
  • context: Custom CanvasRenderingContext2D.
  • canvasSize: Canvas resolution, default: 16.
  • Plus all core options below.

Core (Node / Edge / Browser)

Runtime-agnostic function that works with raw RGBA pixel data. Import from image-color-scheme/core to avoid any DOM dependencies.

import { getColorSchemeFromPixels } from "image-color-scheme/core";

getColorSchemeFromPixels(data, options);

• data: Flat RGBA pixel data (ArrayLike<number>), same layout as ImageData.data. Works with Uint8ClampedArray, Uint8Array, Buffer, or plain arrays.
• options?: Optional options object.

Options

• sampleCount: Number of pixel samples, default: 35.
• colorThreshold: Normalized saturation value to consider a pixel as colorful (0-1), default: 0.2.
• colorAggregate: Detect color using all sampled pixels, boolean, default: false.
  • false: Only one sampled pixel needs to be saturated for the scheme to return "color".
  • true: Majority of sampled pixels need to be saturated for the scheme to return "color".

Return

• "dark": Image is only dark grayscale pixels.
• "light": Image is only light grayscale pixels.
• "grayscale": Image has light and dark grayscale pixels.
• "color": Image has colored pixels (see colorAggregate option for specifics).

Example Usage

The most common use case for this utility is to invert an icon to contrast with the page theme. This is useful for dynamically-fetched images which would otherwise require manual configuration based on their color scheme.

Here's how I do this in React & CSS Modules:

React

import { ImageColorScheme, getImageColorScheme } from "image-color-scheme";
import styles from "./InvertingIcon.module.css";

export const InvertingIcon = () => {
  const [colorScheme, setColorScheme] = useState<ImageColorScheme>("color");

  return (
    <img
      src="/some-image.png"
      className={styles[colorScheme]}
      onLoad={(e) => {
        setColorScheme(getImageColorScheme(e.currentTarget));
      }}
    />
  );
};

CSS

If the icon color scheme matches the theme, invert the icon to maximize contrast:

@media (prefers-color-scheme: dark) {
  .dark {
    filter: invert(1);
  }
}

@media (prefers-color-scheme: light) {
  .light {
    filter: invert(1);
  }
}

This will not invert colored icons as they are detected as "color" scheme.

Server-side

Use image-color-scheme/core with any image decoding library. Image to RGBA conversion is left to the user since the best tool varies by runtime (sharp, jimp, Cloudflare Image Resizing, etc.).

import { getColorSchemeFromPixels } from "image-color-scheme/core";
import sharp from "sharp";

const { data } = await sharp("icon.png")
  .resize(16, 16)
  .ensureAlpha()
  .raw()
  .toBuffer({ resolveWithObject: true });

const scheme = getColorSchemeFromPixels(data);
// → "dark" | "light" | "grayscale" | "color"