node-vibrant: Image Color Palette Extraction

4.0.4 · active · verified Sun Apr 19

node-vibrant is a JavaScript library engineered for extracting prominent colors and generating a color palette from images. It effectively analyzes image data to produce a set of 'swatches,' including vibrant, muted, dark vibrant, light vibrant, dark muted, and light muted colors. The library is currently at stable version 4.0.4 and has resumed active development following a substantial four-year hiatus before the significant 4.0.0 release. Key features include comprehensive support for both Node.js and browser environments, a full rewrite in TypeScript since version 3.0.0-alpha.1, and a modern Promise-based API for handling asynchronous operations. This combination makes it a robust solution for applications requiring dynamic, type-safe color palette generation from images, integrating smoothly with contemporary JavaScript development workflows.

Common errors

```
TypeError: (0 , node_vibrant_node__WEBPACK_IMPORTED_MODULE_0__.Vibrant) is not a constructor
```
cause Attempting to use `Vibrant` as a default import or without destructuring when it's a named export.

fix Ensure you are using `import { Vibrant } from 'node-vibrant/node';` (or `/browser`) and then `Vibrant.from(...)`.
```
Error: Cannot find module 'node-vibrant'
```
cause Incorrect import path for v4.0.0+ in a Node.js or browser environment, or attempting to use the root import for environment-specific functionality.

fix For v4.0.0 and later, specify the environment in the import path: `import { Vibrant } from 'node-vibrant/node';` or `import { Vibrant } from 'node-vibrant/browser';`
```
TypeError: Vibrant.from(...).getPalette is not a function (or similar async errors)
```
cause This error often occurs when the `getPalette()` method is called without awaiting the result of `Vibrant.from()`, or if not properly handling the Promise-based API.

fix Ensure you are `await`ing the `getPalette()` call within an `async` function or chaining a `.then()` callback: `await Vibrant.from(imageUrl).getPalette();` or `Vibrant.from(imageUrl).getPalette().then(...)`.

Warnings

breaking Starting with v4.0.0, the `Vibrant` class is no longer a default export but a named export. Code relying on `import Vibrant from 'node-vibrant'` will break.
Fix: Change your import statement to `import { Vibrant } from 'node-vibrant/node;'` or `import { Vibrant } from 'node-vibrant/browser;'` depending on your environment.
breaking Version 4.0.0 introduced mandatory environment-specific imports. You must now import from `node-vibrant/node` for Node.js, `node-vibrant/browser` for browsers, or `node-vibrant/worker` for Web Workers.
Fix: Update your import paths to explicitly target your environment, e.g., `import { Vibrant } from 'node-vibrant/node;'`.
breaking Node.js v18+ is now required for `node-vibrant` versions 4.0.0 and above. Environments running older Node.js versions will encounter compatibility issues.
Fix: Upgrade your Node.js environment to version 18 or higher.
breaking The API was rewritten to be Promise-based in v3.0.0-alpha.1. Code using callbacks will need to be refactored to use `async/await` or `.then().catch()` patterns.
Fix: Refactor your asynchronous operations to use Promises, for example: `Vibrant.from(imageUrl).getPalette().then(palette => ...);` or `const palette = await Vibrant.from(imageUrl).getPalette();`
gotcha The `Builder.getSwatches` alias was removed in v4.0.0; developers should use `Builder.getPalette` instead.
Fix: Replace calls to `getSwatches()` with `getPalette()`.

Install

npm install node-vibrant npm
yarn add node-vibrant yarn
pnpm add node-vibrant pnpm

Imports

Vibrant
wrong:
```
import Vibrant from 'node-vibrant';
```
correct:
```
import { Vibrant } from 'node-vibrant/node';
```
Since v4.0.0, the `Vibrant` class is a named export, and you must import from environment-specific paths like `node-vibrant/node` or `node-vibrant/browser`.
Vibrant (Browser)
wrong:
```
import Vibrant from 'node-vibrant';
```
correct:
```
import { Vibrant } from 'node-vibrant/browser';
```
For browser environments, use the explicit import path `node-vibrant/browser` since v4.0.0.
Vibrant (CommonJS pre-v4)
wrong:
```
import { Vibrant } from 'node-vibrant';
```
correct:
```
const Vibrant = require('node-vibrant');
```
Prior to v4.0.0, `Vibrant` was typically a default export and could be imported via CommonJS `require()` directly from the package root. This pattern is deprecated for v4+.

Quickstart

Demonstrates how to extract a color palette from an image URL using the Promise-based API in a Node.js environment, displaying the dominant color swatches.

import { Vibrant } from 'node-vibrant/node'; // Or 'node-vibrant/browser' for browsers

async function extractColorsFromImage(imageUrl: string) {
  try {
    console.log(`Extracting colors from: ${imageUrl}`);
    const palette = await Vibrant.from(imageUrl).getPalette();

    console.log('Generated Color Palette:');
    console.log('  Vibrant:', palette.Vibrant?.hex || 'N/A');
    console.log('  Muted:', palette.Muted?.hex || 'N/A');
    console.log('  Dark Vibrant:', palette.DarkVibrant?.hex || 'N/A');
    console.log('  Light Vibrant:', palette.LightVibrant?.hex || 'N/A');
    console.log('  Dark Muted:', palette.DarkMuted?.hex || 'N/A');
    console.log('  Light Muted:', palette.LightMuted?.hex || 'N/A');

    if (palette.Vibrant) {
      console.log(`  Vibrant RGB: ${palette.Vibrant.rgb}`);
      console.log(`  Vibrant Population: ${palette.Vibrant.population}`);
    }
  } catch (error) {
    console.error('Failed to extract colors:', error);
  }
}

// Example usage with a public image URL
// For a local file in Node.js, replace 'imageUrl' with a local path like 'file:///path/to/image.jpg'
const exampleImageUrl = 'https://picsum.photos/id/1018/1000/600';
extractColorsFromImage(exampleImageUrl);

view raw JSON →