image-color-scheme

Calculate the color scheme from an image ("dark" | "light" | "grayscale" | "color").

Install

ES Module

npm install image-color-scheme

API

getImageColorScheme(image, options);

• image: Input image source (CanvasImageSource: can be img or svg element).
• options?: Optional options object.

Options

• context: Custom CanvasRenderingContext2D.
• sampleCount: Number of pixel samples, default: 23.
• canvasSize: Canvas resolution, default: 16.
• colorThreshold: Normalized saturation value to consider a pixel as colorful (0-1), default: 0.1.
• 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.