Color Thief

Examples

Try it yourself

Drag an image here

Drop it!

Getting started

The Color Thief package includes multiple distribution files to support different environments and build processes. Here is the list of all the files in the /dist folder and what formats they support:

color-thief.js - CommonJS module for use in Node.
color-thief.mjs - ES6 module. For modern browsers as well as Webpack and Rollup.
color-thief.umd.js - UMD module. For simple script tag loading that exposes a global variable or for RequireJS AMD support.
color-thief.min.js - Duplicate of color-thief.umd.js. Kept around to maintain backwards compatibility.

Using in Node

Install and import. The name of the package is colorthief, not color-thief.
```
$ npm i --save colorthief
```
Get colors. Both the getColor() and getPalette() methods return a Promise when used in Node.

Using in the browser

1. Install

There are multiples ways to install Color Thief when using it in the browser:

Install as dependency with npm. The name of the package is colorthief, not color-thief.
```
$ npm i --save colorthief
```
Load from a CDN. The distribution files are hosted on cdnjs for quick access.
Download from Github. You can download a zip of the latest release (or any previous one) from the project's Github Releases page.

2. Import and use

As a global variable.
As an ES6 module.
index.html
app.js
With RequireJS. The /dist/color-thief.umd.js file uses the UMD (Universal Module Definition) format. This includes RequireJS AMD support.

API

Note: Both `getColor` and `getPalette` return a `Promise` when used in Node.

getColor(image [, quality])

Returns: [Number, Number, Number]

Gets the dominant color from the image. Color is returned as an array of three integers representing red, green, and blue values.

image - When called in the browser, this argument expects an HTML image element, not a URL. When run in Node, this argument expects a path to the image.

quality is an optional argument that must be an Integer of value 1 or greater, and defaults to 10. The number determines how many pixels are skipped before the next one is sampled. We rarely need to sample every single pixel in the image to get good results. The bigger the number, the faster a value will be returned.

getPalette(image [, colorCount, quality]

Returns: [[Number, Number, Number], ...]

Gets a palette from the image by clustering similar colors. The palette is returned as an array containing colors, each color itself an array of three integers.

FAQ

All questions are about the usage of Color Thief in the browser, not Node.

Do I have to wait for the image to load?

Yes. If you see an error that reads: Cannot read property '0' of null, it is likely that the image had not finished loading when you passed it to getColor() or getPalette().

How do I test the script locally?

If you are testing the script locally in a web browser, you might see the following error: Access to script at 'file://...' from origin 'null' has been blocked by CORS policy. This is because the browser restricts direct access to the filesystem.

To get around this, you can set up a minimal server to host the files. One option is http-server. To run this on demand without installing it as a proejct dependency, you can use the npx command:

Now you can visit http://localhost:8080 to view your server.

Does it work if the image is hosted on another domain?

A) If you manage the server hosting the image...

Yes. If you are seeing an error that reads: The canvas has been tainted by cross-origin data., then you are running into a cross-origin resouce sharing (CORS) issue. Check the following two items:

CORS policy on the server. Is the server hosting the image properly configured? Make sure the requesting domain is whitelisted in the access-control-allow-origin header, or the server hosting the image has an open policy: access-control-allow-origin: *.
crossorigin attr. The HTML image element must be given a crossorigin attribute.
If you're dynamically adding the image element, you can do the following:

B) If you don't have access to the server hosting the image...

You can use a proxy server that pulls down the image and returns it with a more liberal CORS policy. Below you can see an example of this with an image that is proxied through a public Google server. If you don't own the proxy server, just know, that you are at their mercy. But this is handy in a pinch for testing.

How do I get hex values?

The ColorThief methods return colors as an array of three integers representing red, green, and blue values. If you are looking to use the output in CSS, you can do that using the rgb format: color: rgb(102, 51, 153). If you do need to convert to hex, you can use the following function:

Help

Trouble using Color Thief?

Follow the steps below to get help. Make sure you have read the documentation on this page first.

Search Stackoverflow to see if other people have run into the same issue you are having.
If your issue is unique, then post a new question on Stackoverflow. Use the color-thief tag to make it easier to find.

Have a feature request?

Search through existing Github Issues and PRs to see if the feature has been discussed or already created.
If your feature request is unique, then post a new issue in Github detailing your request.

Found a bug?

Search through existing Github Issues that have been reported to avoid creating a duplicate issue.
If your bug has not been reported, create a new issue. In your bug report, please includes the version of the library you are using, your browser and operating system, and steps to recreate.

License

Color Thief is licensed under the MIT License.

Github provides a nice summary of the license:
"A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code."