### Node.js Installation and Usage

Source: https://lokeshdhakar.com/projects/color-thief

Install sharp as a dependency and use the library in a Node.js environment.

```bash
npm install sharp
```

```javascript
import { getColor, getPalette } from 'colorthief'; const color = await getColor('photo.jpg'); console.log(color.hex()); const palette = await getPalette('photo.jpg', { colorCount: 5 }); palette.forEach(c => console.log(c.hex()));
```

--------------------------------

### Install Color Thief

Source: https://lokeshdhakar.com/projects/color-thief

Install the package via npm.

```bash
npm install colorthief
```

--------------------------------

### Install Color Thief via npm

Source: https://lokeshdhakar.com/projects/color-thief

Use this command to install the package as a dependency in your project.

```bash
$ npm i --save colorthief
```

--------------------------------

### Swatches API

Source: https://lokeshdhakar.com/projects/color-thief

Provides methods to get color swatches from an image, categorized by semantic roles like Vibrant, Muted, etc.

```APIDOC
## Swatches API

### Description

The `getSwatches()` and `getSwatchesSync()` methods return a `SwatchMap`, which is an object containing up to six semantic color roles. Each role can be either a `Swatch` object or `null` if no color matched that role.

### Methods

- `getSwatches(img)`: Asynchronously returns a `SwatchMap`.
- `getSwatchesSync(img)`: Synchronously returns a `SwatchMap`.

### SwatchMap Object

```javascript
{
  Vibrant:      Swatch | null,
  Muted:        Swatch | null,
  DarkVibrant:  Swatch | null,
  DarkMuted:    Swatch | null,
  LightVibrant: Swatch | null,
  LightMuted:   Swatch | null,
}
```

### Swatch Object

- **color** (`Color`): The extracted color for this role.
- **role** (`string`): The semantic role (e.g., 'Vibrant', 'Muted').
- **titleTextColor** (`Color`): Recommended color for title text.
- **bodyTextColor** (`Color`): Recommended color for body text.

### Example Usage

```javascript
const swatches = getSwatchesSync(img);

if (swatches.Vibrant) {
  document.body.style.background = swatches.Vibrant.color.css();
  document.body.style.color = swatches.Vibrant.bodyTextColor.css();
  title.style.color = swatches.Vibrant.titleTextColor.css();
}

if (swatches.DarkMuted) {
  sidebar.style.background = swatches.DarkMuted.color.css();
  sidebar.style.color = swatches.DarkMuted.bodyTextColor.css();
}
```

### Swatch Roles

- **Vibrant**: Bright, saturated colors. Good for primary accents.
- **Muted**: Desaturated, medium brightness. Good for backgrounds.
- **DarkVibrant**: Saturated and dark. Good for status bars, headers.
- **DarkMuted**: Desaturated and dark. Good for text backgrounds.
- **LightVibrant**: Saturated and light. Good for highlights, hover states.
- **LightMuted**: Desaturated and light. Good for card backgrounds, borders.
```

--------------------------------

### Observe Video Source for Palette Updates

Source: https://lokeshdhakar.com/projects/color-thief

Reactively watches a video source and gets palette updates on every frame. Works with `<video>`, `<canvas>`, and `<img>` elements. Use this for real-time color analysis of video streams.

```javascript
import { observe } from 'colorthief';
const controller = observe(videoElement, {
    throttle: 200,
    colorCount: 5,
    onChange(palette) {
        const [dominant] = palette;
        document.body.style.background = dominant.css();
    },
});

// Later — clean up
controller.stop();
```

--------------------------------

### Get Semantic Swatches

Source: https://lokeshdhakar.com/projects/color-thief

Classifies palette colors into six semantic roles (e.g., Vibrant, Muted). Each swatch includes text color recommendations for UI elements. Use this for creating harmonious UIs based on image content.

```javascript
import { getSwatchesSync } from 'colorthief';
const swatches = getSwatchesSync(img);

if (swatches.Vibrant) {
    header.style.background = swatches.Vibrant.color.css();
    header.style.color = swatches.Vibrant.titleTextColor.css();
}

if (swatches.DarkMuted) {
    sidebar.style.background = swatches.DarkMuted.color.css();
    sidebar.style.color = swatches.DarkMuted.bodyTextColor.css();
}
```

--------------------------------

### Apply Swatch colors to UI

Source: https://lokeshdhakar.com/projects/color-thief

Access properties of the Swatch object, such as color, bodyTextColor, and titleTextColor, to style UI elements. Use the .css() method to get valid CSS color strings.

```javascript
const swatches = getSwatchesSync(img); if (swatches.Vibrant) {
    document.body.style.background = swatches.Vibrant.color.css();
    document.body.style.color = swatches.Vibrant.bodyTextColor.css();
    title.style.color = swatches.Vibrant.titleTextColor.css();
}
if (swatches.DarkMuted) {
    sidebar.style.background = swatches.DarkMuted.color.css();
    sidebar.style.color = swatches.DarkMuted.bodyTextColor.css();
}
```

--------------------------------

### Get Dominant Color

Source: https://lokeshdhakar.com/projects/color-thief

Extracts the single dominant color from an image. Use this when you need a primary color representation.

```javascript
import { getColorSync } from 'colorthief';
const color = getColorSync(img);
color.hex(); // '#e84393'
color.css(); // 'rgb(232, 67, 147)'
```

--------------------------------

### Get SwatchMap synchronously

Source: https://lokeshdhakar.com/projects/color-thief

Use getSwatchesSync to retrieve a SwatchMap object synchronously from an image element. The SwatchMap contains colors for different semantic roles.

```javascript
const swatches = getSwatchesSync(img); // {
//   Vibrant:      Swatch | null,
//   Muted:        Swatch | null,
//   DarkVibrant:  Swatch | null,
//   DarkMuted:    Swatch | null,
//   LightVibrant: Swatch | null,
//   LightMuted:   Swatch | null,
// }
```

--------------------------------

### Get Color Palette

Source: https://lokeshdhakar.com/projects/color-thief

Extracts a multi-color palette from an image. Each color in the palette is a full Color object. Use this for generating themes or analyzing image color composition.

```javascript
import { getPaletteSync } from 'colorthief';
const palette = getPaletteSync(img, { colorCount: 8 });
palette.forEach(c => console.log(c.hex()));
```

--------------------------------

### Configuration and Utility Functions

Source: https://lokeshdhakar.com/projects/color-thief

Functions for global configuration and manual color object creation.

```APIDOC
## Global Configuration

### `configure(options)`

**Description**: Globally overrides the pixel loader and/or quantizer used by all extraction functions.

**Parameters**:
- `options.loader` (Custom pixel decoder) - Optional
- `options.quantizer` (Custom quantization algorithm) - Optional

**Returns**: `void`

## Color Object Factory

### `createColor(r, g, b, population, proportion?)`

**Description**: Factory function to manually create a Color object from RGB values.

**Parameters**:
- `r` (number) - RGB value (0–255) - Required
- `g` (number) - RGB value (0–255) - Required
- `b` (number) - RGB value (0–255) - Required
- `population` (number) - Pixel count for this color - Required
- `proportion` (number) - Fraction of total pixels (0–1) - Optional, Default: `0`

**Returns**: `Color` - A manually created Color object.
```

--------------------------------

### CLI Usage

Source: https://lokeshdhakar.com/projects/color-thief

Run color extraction directly from the terminal.

```bash
npx colorthief-cli photo.jpg
```

```bash
$ colorthief-cli photo.jpg
#c94f6e
```

```bash
$ colorthief-cli palette photo.jpg --count 3
#c94f6e
#5a8fa3
#d4a853
```

```bash
$ colorthief-cli swatches photo.jpg
Vibrant #e84393
Muted #a0b4c0
DarkVibrant #8b1a3a
DarkMuted #4a5568
LightVibrant #f6a5c1
LightMuted #d4d8dc
```

```bash
--json                # Full color data as JSON --css                 # CSS custom properties --count 5             # Number of palette colors (2-20) --quality 1           # Sampling quality (1 = every pixel) --color-space rgb     # Quantization space (rgb or oklch)
```

--------------------------------

### Handle Image Loading

Source: https://lokeshdhakar.com/projects/color-thief

Best practice for ensuring an image is loaded before attempting to extract colors.

```javascript
// BETTER
const colorThief = new ColorThief();
const img = document.querySelector('img');

if (img.complete) {
  colorThief.getColor(img);
} else {
  img.addEventListener('load', function() {
    colorThief.getColor(img);
  });
}
```

--------------------------------

### Load Color Thief via CDN

Source: https://lokeshdhakar.com/projects/color-thief

Include the UMD build directly in your HTML file from a CDN.

```xml
<script src="https://cdnjs.cloudflare.com/ajax/libs/color-thief/2.7.0/color-thief.umd.js"></script>
```

--------------------------------

### Browser Usage via Script Tag

Source: https://lokeshdhakar.com/projects/color-thief

Load the UMD build from a CDN to access the global ColorThief object.

```html
<script src="https://unpkg.com/colorthief@3/dist/umd/color-thief.global.js"></script> <script> const color = ColorThief.getColorSync(img);     console.log(color.hex()); </script>
```

--------------------------------

### Extract Colors in Node.js

Source: https://lokeshdhakar.com/projects/color-thief

Use getColor and getPalette with a file path. Both methods return a Promise.

```javascript
const img = resolve(process.cwd(), 'rainbow.png');

ColorThief.getColor(img)
    .then(color => { console.log(color) })
    .catch(err => { console.log(err) })

ColorThief.getPalette(img, 5)
    .then(palette => { console.log(palette) })
    .catch(err => { console.log(err) })
```

--------------------------------

### Observe API

Source: https://lokeshdhakar.com/projects/color-thief

Allows reactive observation of a live image source, providing color palettes on frame changes or updates.

```APIDOC
## Observe API

### Description

The `observe()` method reactively watches a live source (like a video or canvas) and fires a callback with a fresh color palette on every frame or change.

### Method

`observe(source, options)`

### Parameters

#### `source`

- **Type**: `HTMLVideoElement`, `HTMLCanvasElement`, `HTMLImageElement`, `string` (file path in Node.js), `Buffer` (in Node.js).
- **Description**: The image source to observe.

#### `options`

- **`onChange`** (function) - **Required**. Callback fired with `(palette: Color[]) => void` on each update.
- **`throttle`** (number) - Minimum milliseconds between updates. Default: `200`.
- **`colorCount`** (number) - Number of colors to extract (2–20). Default: `5`.
- **`quality`** (number) - Pixel sampling rate. Default: `10`.
- **`colorSpace`** (string) - Color space for extraction ('oklch' or 'rgb'). Default: `'oklch'`.
- **Other options**: Accepts all filter options like `ignoreWhite`, `whiteThreshold`, `alphaThreshold`, `minSaturation`.

### Return Value

- **ObserveController**: An object with a `stop()` method to clean up observation.

### ObserveController Methods

- `stop()`: Stops observing and cleans up event listeners and animation frames.

### Behavior by Source Type

- **HTMLVideoElement**: Extracts from the current frame on each `requestAnimationFrame` (throttled). Runs only while the video is playing. Also fires on `seeked`.
- **HTMLCanvasElement**: Polls on each `requestAnimationFrame` (throttled).
- **HTMLImageElement**: Extracts immediately if loaded, then watches for `src`/`srcset` attribute changes via `MutationObserver`. Also listens for the `load` event.

### Example Usage

```javascript
const controller = observe(videoElement, {
  throttle: 200,
  colorCount: 5,
  onChange(palette) {
    const [dominant] = palette;
    document.body.style.background = dominant.css();
    header.style.color = dominant.textColor;
  },
});

// To stop observing later:
controller.stop();
```

### Supported Source Types

#### Browser

- `HTMLImageElement`
- `HTMLCanvasElement`
- `HTMLVideoElement`
- `ImageData`
- `ImageBitmap`
- `OffscreenCanvas`

#### Node.js (requires `sharp`)

- `string` (file path)
- `Buffer`

**Note**: The synchronous API (`getColorSync`, `getPaletteSync`, `getSwatchesSync`) only accepts browser sources. Use the asynchronous API for Node.js.
```

--------------------------------

### Import with Bundler

Source: https://lokeshdhakar.com/projects/color-thief

Import or require the library when using a module bundler.

```javascript
import { getColor, getPalette } from 'colorthief';
```

```javascript
const { getColor, getPalette } = require('colorthief');
```

--------------------------------

### Browser Usage via ES Module

Source: https://lokeshdhakar.com/projects/color-thief

Import functions directly using ES modules.

```html
<script type="module"> import { getColorSync } from 'https://unpkg.com/colorthief@3/dist/index.js'; const img = document.querySelector('img');     img.addEventListener('load', () => { const color = getColorSync(img);         console.log(color.hex()); }); </script>
```

--------------------------------

### Color Object Properties and Conversions

Source: https://lokeshdhakar.com/projects/color-thief

Demonstrates the various properties and conversion methods available for each extracted color object. Use these to access RGB, HSL, hex, and other formats, as well as accessibility metadata.

```javascript
import { getColorSync } from 'colorthief';
const color = getColorSync(img);

color.rgb() // { r: 232, g: 67, b: 147 }
color.hex() // '#e84393'
color.hsl() // { h: 331, s: 77, l: 59 }
color.oklch() // { l: 0.64, c: 0.21, h: 353 }
color.css() // 'rgb(232, 67, 147)'
color.css('oklch') // 'oklch(0.64 0.21 353)'
color.textColor       // '#ffffff' or '#000000'
color.isDark          // true
color.contrast.white  // 3.42
color.contrast.black  // 6.14
```

```javascript
const palette = getPaletteSync(img, { colorCount: 8 });
palette.forEach(color => {
  console.log(color.hex(), color.proportion); // e.g. "#4a6741" 0.32
});
```

--------------------------------

### getPalette(image, [options])

Source: https://lokeshdhakar.com/projects/color-thief

Extracts a color palette from an image by clustering similar colors, returning an array of RGB arrays.

```APIDOC
## getPalette(image, [options])

### Description
Gets a palette from the image by clustering similar colors. Returns an array containing colors, each color being an array of three integers.

### Parameters
#### Path Parameters
- **image** (HTMLImageElement/HTMLCanvasElement/ImageData/ImageBitmap/String) - Required - In the browser, accepts image elements or canvas. In Node, accepts a path to the image file.

#### Request Body
- **options** (Object) - Optional - Configuration object including colorCount (2-20), quality, ignoreWhite, whiteThreshold, alphaThreshold, and minSaturation.
```

--------------------------------

### Options for Extraction Functions

Source: https://lokeshdhakar.com/projects/color-thief

Available options to customize color extraction behavior.

```APIDOC
## Extraction Options

All extraction functions accept an options object. The async API supports every option; the sync API omits `signal`, `worker`, and `loader`.

| Option | Type | Default | Description |
|---|---|---|---|
| `colorCount` | number | `10` | Number of colors in the palette (2–20). Used by `getPalette` and `getSwatches`. |
| `quality` | number | `10` | Pixel sampling rate. `1` samples every pixel (highest quality, slowest). `10` samples every 10th pixel. |
| `colorSpace` | string | `'oklch'` | `'oklch'` or `'rgb'`. OKLCH produces more perceptually uniform palettes. |
| `ignoreWhite` | boolean | `true` | Skip pixels that appear white during sampling. |
| `whiteThreshold` | number | `250` | RGB channel value (0–255) above which a pixel is considered white. |
| `alphaThreshold` | number | `125` | Alpha value (0–255) below which a pixel is considered transparent and skipped. |
| `minSaturation` | number | `0` | Minimum HSV saturation (0–1). Pixels below this saturation are skipped. |
| `signal` | AbortSignal | — | Cancel a running extraction. Async API only. |
| `worker` | boolean | `false` | Offload quantization to a Web Worker thread. Browser async API only. |
```

--------------------------------

### Import Color Thief as ES6 Module

Source: https://lokeshdhakar.com/projects/color-thief

Load the module in your HTML and use it within your application script.

```xml
<script type="module" src="app.js"></script>
```

```javascript
import ColorThief from './node_modules/colorthief/dist/color-thief.mjs'

const colorThief = new ColorThief();
const img = document.querySelector('img');

if (img.complete) {
  colorThief.getColor(img);
} else {
  img.addEventListener('load', function() {
    colorThief.getColor(img);
  });
}
```

--------------------------------

### Extract and Analyze Colors

Source: https://lokeshdhakar.com/projects/color-thief

Demonstrates extracting a color synchronously and accessing its format conversions, accessibility properties, and population data.

```javascript
const color = getColorSync(img); // Format conversions color.hex(); // '#e84393' color.rgb(); // { r: 232, g: 67, b: 147 } color.hsl(); // { h: 331, s: 77, l: 59 } color.oklch(); // { l: 0.64, c: 0.21, h: 353 } color.css(); // 'rgb(232, 67, 147)' color.css('oklch'); // 'oklch(0.64 0.21 353)' // Accessibility color.textColor; // '#ffffff' color.isDark; // true color.contrast.white; // 3.42 color.contrast.black; // 6.14 color.contrast.foreground.hex(); // '#ffffff' // Population color.population; // 14832 color.proportion; // 0.23
```

--------------------------------

### Observe video element for color changes

Source: https://lokeshdhakar.com/projects/color-thief

Use the observe function to reactively extract color palettes from a video element. The onChange callback is fired with the palette on each update. Remember to call controller.stop() to clean up.

```javascript
const controller = observe(videoElement, {
    throttle: 200,
    colorCount: 5,
onChange(palette) {
const [dominant] = palette;
        document.body.style.background = dominant.css();
        header.style.color = dominant.textColor;
    },
});
// Later — clean up
controller.stop();
```

--------------------------------

### Asynchronous Color and Palette Extraction

Source: https://lokeshdhakar.com/projects/color-thief

Uses asynchronous methods (`getColor`, `getPalette`) to keep the UI responsive during extraction. Pass `worker: true` to offload quantization to a Web Worker thread for maximum performance in browsers.

```javascript
import { getColor, getPalette } from 'colorthief';

const color = await getColor(img);
const palette = await getPalette(img, { colorCount: 6 });

// Offload to Web Worker (browser only)
const workerPalette = await getPalette(img, { colorCount: 6, worker: true });
```

--------------------------------

### Use Color Thief as a Global Variable

Source: https://lokeshdhakar.com/projects/color-thief

Initialize Color Thief and ensure the image is loaded before calling extraction methods.

```xml
<script src="node_modules/colorthief/dist/color-thief.umd.js"></script>
<script>
    const colorThief = new ColorThief();
    const img = document.querySelector('img');

    // Make sure image is finished loading
    if (img.complete) {
      colorThief.getColor(img);
    } else {
      img.addEventListener('load', function() {
        colorThief.getColor(img);
      });
    }
</script>
```

--------------------------------

### Configure Cross-Origin Images

Source: https://lokeshdhakar.com/projects/color-thief

Add the crossorigin attribute to images hosted on different domains to allow color extraction.

```xml
<img src="https://example.com/image.jpg" crossorigin="anonymous" />
```

--------------------------------

### Import Color Thief in Node.js

Source: https://lokeshdhakar.com/projects/color-thief

Import the module to access Color Thief functionality in a Node.js environment.

```javascript
const ColorThief = require('colorthief');
```

--------------------------------

### getColor(image, [options])

Source: https://lokeshdhakar.com/projects/color-thief

Extracts the dominant color from an image, returning an array of three integers representing RGB values.

```APIDOC
## getColor(image, [options])

### Description
Gets the dominant color from the image. Returns an array of three integers [R, G, B] or null.

### Parameters
#### Path Parameters
- **image** (HTMLImageElement/HTMLCanvasElement/ImageData/ImageBitmap/String) - Required - In the browser, accepts image elements or canvas. In Node, accepts a path to the image file.

#### Request Body
- **options** (Object) - Optional - Configuration object including quality, ignoreWhite, whiteThreshold, alphaThreshold, and minSaturation.
```

--------------------------------

### Convert RGB to Hex

Source: https://lokeshdhakar.com/projects/color-thief

Helper function to convert the default [r, g, b] array output into a hex string.

```javascript
const rgbToHex = (r, g, b) => '#' + [r, g, b].map(x => {
  const hex = x.toString(16)
  return hex.length === 1 ? '0' + hex : hex
}).join('')

rgbToHex(102, 51, 153); // #663399
```

--------------------------------

### Color Object Details

Source: https://lokeshdhakar.com/projects/color-thief

Properties and methods available on the Color objects returned by extraction functions.

```APIDOC
## Color Object

Every extracted color is a rich object with format conversions, accessibility metadata, and WCAG contrast ratios.

### Methods

| Method | Returns | Description |
|---|---|---|
| `rgb()` | `{ r, g, b }` | RGB values, each 0–255. |
| `hex()` | `string` | Hex string, e.g. `'#e84393'`. |
| `hsl()` | `{ h, s, l }` | Hue 0–360, saturation 0–100, lightness 0–100. |
| `oklch()` | `{ l, c, h }` | Lightness 0–1, chroma 0–0.4, hue 0–360. |
| `css(format?)` | `string` | CSS color string. Format: `'rgb'` (default), `'hsl'`, or `'oklch'`. |
| `array()` | `[r, g, b]` | RGB tuple as a three-element array. |
| `toString()` | `string` | Hex string. Allows direct use in template literals. |

### Properties

| Property | Type | Description |
|---|---|---|
| `textColor` | `string` | `'#ffffff'` or `'#000000'` — the recommended foreground text color for readability. |
| `isDark` | `boolean` | `true` if the color is perceptually dark (relative luminance ≤ 0.179). |
| `isLight` | `boolean` | `true` if the color is perceptually light. |
| `contrast` | `ContrastInfo` | WCAG contrast ratios. Contains `white` (number), `black` (number), and `foreground` (Color) — a Color object for readable text. |
| `population` | `number` | Relative pixel count from the quantizer. Higher values mean more dominant. |
| `proportion` | `number` | Fraction of total sampled pixels (0–1). |

### Example Usage
```javascript
const color = getColorSync(img);

// Format conversions
color.hex(); // '#e84393'
color.rgb(); // { r: 232, g: 67, b: 147 }
color.hsl(); // { h: 331, s: 77, l: 59 }
color.oklch(); // { l: 0.64, c: 0.21, h: 353 }
color.css(); // 'rgb(232, 67, 147)'
color.css('oklch'); // 'oklch(0.64 0.21 353)'

// Accessibility
color.textColor; // '#ffffff'
color.isDark; // true
color.contrast.white; // 3.42
color.contrast.black; // 6.14
color.contrast.foreground.hex(); // '#ffffff'

// Population
color.population; // 14832
color.proportion; // 0.23
```
```

--------------------------------

### Color Extraction Functions

Source: https://lokeshdhakar.com/projects/color-thief

Functions to extract dominant colors and palettes from image sources.

```APIDOC
## Asynchronous Color Extraction

### `getColor(source, options?)`

**Description**: Extracts the single dominant color from an image.

**Returns**: `Promise<Color | null>` - A Promise that resolves to a Color object or `null` if extraction fails.

### `getPalette(source, options?)`

**Description**: Extracts a multi-color palette from an image.

**Returns**: `Promise<Color[] | null>` - A Promise that resolves to an array of Color objects sorted by dominance, or `null` if extraction fails.

### `getSwatches(source, options?)`

**Description**: Extracts semantic swatches classified into six roles (Vibrant, Muted, etc.).

**Returns**: `Promise<SwatchMap>` - A Promise that resolves to a SwatchMap object.

## Synchronous Color Extraction

### `getColorSync(source, options?)`

**Description**: Synchronous version of `getColor()`. Browser sources only.

**Returns**: `Color | null` - A Color object or `null` if extraction fails.

### `getPaletteSync(source, options?)`

**Description**: Synchronous version of `getPalette()`. Browser sources only.

**Returns**: `Color[] | null` - An array of Color objects or `null` if extraction fails.

### `getSwatchesSync(source, options?)`

**Description**: Synchronous version of `getSwatches()`. Browser sources only.

**Returns**: `SwatchMap` - A SwatchMap object.

## Reactive Color Extraction

### `observe(source, options)`

**Description**: Reactively watches a video, canvas, or image element and fires a callback with a fresh palette on every frame or change.

**Returns**: `ObserveController` - An ObserveController instance.
```

--------------------------------

### Adjust Quality Settings for Palette Extraction

Source: https://lokeshdhakar.com/projects/color-thief

Controls the sampling quality for palette extraction. Lower `quality` values sample more pixels, resulting in slower but potentially more accurate results. The default is 10.

```javascript
import { getPaletteSync } from 'colorthief';

getPaletteSync(img, { quality: 1 }); // Every pixel
getPaletteSync(img, { quality: 10 }); // Every 10th pixel (default)
getPaletteSync(img, { quality: 50 }); // Every 50th pixel
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.