Installation
+npm i @rtcoder/dominant-colorImports
+Use ESM in modern apps:
+import { getDominantColor, getDominantColorAsync } from '@rtcoder/dominant-color';CommonJS consumers can use require:
const { getDominantColor } = require('@rtcoder/dominant-color');Usage
+Promise-based API:
+const img = document.querySelector('img');
+
+const result = await getDominantColorAsync(img, {
+ colorFormat: 'hex',
+ colorQuantization: 'median-cut',
+ colorsPaletteLength: 6,
});
-Config options
-| Name | -Type | -Default value | -Description | -
|---|---|---|---|
downScaleFactor |
- number | -1 | -factor of scale down of image, recommended to use for many large images | -
skipPixels |
- number | -0 | -when larger than 0, skips every n pixels of while determine dominant color, recommended to use for large - images - | -
colorsPaletteLength |
- number | -5 | -length of returned palette of colors | -
paletteWithCountOfOccurrences |
- boolean | -false | -determines whether to return colors with the number of occurrences | -
colorFormat |
- string | -‘rgb’ | -defines the format of the returned colors, available values are ‘rgb’, ‘hsl’ and ‘hex’ | -
callback |
- function | -[empty function] | -callback function | -
Interfaces
-type ColorFormat = 'rgb' | 'hsl' | 'hex';
+console.log(result.dominant, result.colorsPalette);Callback API:
+getDominantColor(img, {
+ colorFormat: 'rgb',
+ callback: (dominant, colorsPalette) => {
+ console.log(dominant, colorsPalette);
+ },
+ errorCallback: (error) => {
+ console.error(error);
+ },
+});Image sources
+
+
+
+
+ DOM and canvas
+HTMLImageElement, HTMLCanvasElement, and ImageBitmap can be passed directly.
+
+ Files and URLs
+Use URL strings, Blob, or File. Blob object URLs are created and revoked internally.
Options
+
+
+
+
+
+ | Name | +Type | +Default | +Description | +
|---|---|---|---|
downScaleFactor |
+ number | +1 | +Scales the source down before sampling. Useful for large images. | +
skipPixels |
+ number | +0 | +Skips every n pixels while reading image data. | +
colorsPaletteLength |
+ number | +5 | +Maximum number of colors returned in the palette. | +
colorQuantization |
+ 'exact' | 'bucket' | 'median-cut' |
+ 'exact' |
+ Controls palette extraction. median-cut is best for balanced photo palettes. |
+
colorBucketSize |
+ number | +24 | +Bucket size used by colorQuantization: 'bucket'. |
+
colorGroupingThreshold |
+ number | +0 | +Groups nearby RGB values after counting or quantization. | +
paletteWithCountOfOccurrences |
+ boolean | +false | +Returns palette entries as { color, count }. |
+
colorFormat |
+ 'rgb' | 'hsl' | 'hex' |
+ 'rgb' |
+ Formats the dominant color and palette colors. | +
callback |
+ function | +empty function | +Receives dominant and colorsPalette. |
+
errorCallback |
+ function | +empty function | +Receives image loading, canvas, and processing errors. | +
Types
+type ColorFormat = 'rgb' | 'hsl' | 'hex';
+type ColorQuantization = 'exact' | 'bucket' | 'median-cut';
+type DominantColorSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | string | Blob;
interface PrimaryColor {
color: string;
count: number;
}
-interface DominantColorOptions {
- downScaleFactor: number;
- skipPixels: number;
- colorsPaletteLength: number;
- paletteWithCountOfOccurrences: boolean;
- colorFormat: ColorFormat;
- callback: DominantColorCallback;
+interface DominantColorResult {
+ dominant: string;
+ colorsPalette: string[] | PrimaryColor[];
}
-type DominantColorCallback = (dominant: string, colorsPalette: (string[]) | (PrimaryColor[])) => void;
-
-function getDominantColor(element: HTMLImageElement, options: Partial<DominantColorOptions>): void
-
+ 
+ 
+