fast-average-color

fast-average-color is a lightweight library designed to calculate the average or dominant color of images or videos in a browser environment. It is optimized for speed and supports various input types including images, videos, canvases, and raw pixel data.

Key Features

• High Performance: Optimized for speed.
• Multiple Algorithms: Supports simple, sqrt (default), and dominant algorithms.
• Versatile Inputs: Works with HTMLImageElement, video, HTMLCanvasElement, OffscreenCanvas, ImageBitmap, VideoFrame, and raw pixel arrays (Uint8Array, Uint8ClampedArray, or arrays of numbers).
• Advanced Capabilities: Supports transparency (PNG, SVG), specific resource regions, and Web Workers.
• Small Footprint: Small bundle size and supports tree shaking.

The fast-average-color library provides three different algorithms to calculate the average color of an image. You can specify which algorithm to use by passing the algorithm option to the getColor method.

Available algorithms:

• sqrt (default): Uses a square root approach for color calculation.
• simple: A simpler, faster averaging method.
• dominant: A more complex algorithm designed to find the most dominant color in an image.

const fac = new FastAverageColor();
console.log(fac.getColor(image, {algorithm: 'dominant'});

In a CommonJS environment, import the FastAverageColor class from the package.

'use strict';

const FastAverageColor = require('fast-average-color').FastAverageColor;
const fac = new FastAverageColor();

fac.getColorAsync(container.querySelector('img'))
    .then(color => {
        container.style.backgroundColor = color.rgba;
        container.style.color = color.isDark ? '#fff' : '#000';
    })
    .catch(e => {
        console.log(e);
    });

To use fast-average-color in your project, install it using npm:

npm i fast-average-color

In ES Modules or TypeScript environments, use a named import for FastAverageColor.

import { FastAverageColor } from 'fast-average-color';

const fac = new FastAverageColor();
fac.getColorAsync(container.querySelector('img'))
    .then(color => {
        container.style.backgroundColor = color.rgba;
        container.style.color = color.isDark ? '#fff' : '#000';
    })
    .catch(e => {
        console.log(e);
    });

To contribute to or develop the fast-average-color project locally, clone the repository, install the dependencies using npm i, and run the test suite using npm test to ensure the environment is correctly configured.

git clone git@github.com:fast-average-color/fast-average-color.git ./fast-average-color
cd ./fast-average-color

npm i
npm test

You can use the library directly in the browser by including the minified script from unpkg. The FastAverageColor class is available on the global scope. Use getColorAsync() to extract color information from an image element.

<script src="https://unpkg.com/fast-average-color/dist/index.browser.min.js"></script>
<script>
    const fac = new FastAverageColor();
    const container = document.querySelector('.image-container');

    fac.getColorAsync(container.querySelector('img'))
        .then(color => {
            container.style.backgroundColor = color.rgba;
            container.style.color = color.isDark ? '#fff' : '#000';
        })
        .catch(e => {
            console.log(e);
        });
</script>

The FastAverageColorResult is the standard output format for color extraction. It provides the color in multiple formats and metadata about its brightness.

Fields:

• value: The color as an array of 4 numbers [r, g, b, a] (0-255).
• rgb: A CSS-compatible string: rgb(r,g,b).
• rgba: A CSS-compatible string: rgba(r,g,b,a) (where a is 0-1).
• hex: The color in hex format (e.g., #RRGGBB).
• hexa: The color in hex format including alpha (e.g., #RRGGBBAA).
• isDark: true if the color is considered dark.
• isLight: true if the color is considered light.
• error: An Error object if the operation failed, otherwise undefined.

The FastAverageColorResource type defines the valid inputs that can be passed to the library for color extraction. Supported types include:

• HTMLImageElement
• HTMLVideoElement
• HTMLCanvasElement
• OffscreenCanvas
• ImageBitmap
• VideoFrame
• null (which typically triggers the use of defaultColor)

When attempting to extract colors from images hosted on a different origin, you may encounter a SecurityError: The operation is insecure. This happens because using images from external origins without CORS approval 'taints' the canvas, preventing data extraction.

To prevent this, ensure the image element has the crossorigin attribute set to "anonymous" before loading the source.