Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 5 commits ahead of awgreenblatt:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Javascript library that allows you to easily apply gradient maps to any HTML element on the page.

Check out the blog post at:

Browser Support

This functionality is currently supported on desktop Chrome and Firefox, and on iOS7 mobile Safari.

What is a Gradient Map you ask?

Traditionally, gradient maps are used in Photoshop. Think about taking an image and converting it to grayscale. Then, take a linear gradient and map that linear gradient to your image, where the left end of your gradient are the darkest values in your image, and the right end of your gradient maps to the brightest parts of your image. If you have a simple linear gradient from red to blue, the darkest parts of your image will get mapped to red, the brightest parts will get mapped to blue, and everything else will be some combination of red and blue, depending on how light or dark it is.


First, include the script in your page, most likely just before your closing <body> tag.

<script src='gradientmaps.min.js'></script>

Now, you can apply a gradient to any element on the page using the following Javascript:

GradientMaps.applyGradientMap(targetElement, linearGradient);

linearGradient uses the same format as CSS linear gradients without the initial angle, sides or corners. Instead you provide simply a list of comma-separated color-stops.

Each color-stop consists of a color followed by an optional position.

The color can be in any of the standard CSS color formats (rgb, rgba, hsl, hsla, named color or #hex-color).

The position is either a percentage (e.g. 50%) or a fraction from 0.0 to 1.0.

If the initial color-stop has no position, it is assumed to be 0% If the final color-stop has no position, it is assumed to be 100% If a color stop has no position, and it is not the first or last color-stop, it is positioned half way between the previous and next color-stop. If a color stop's position is less than the previous color-stop, it is repositioned to that of the previously positioned color-stop.


<img src="myimage.png" id="myimage">

Convert to Black & White:

<script src="gradientmaps.min.js"></script>
var target = document.getElementById('myimage');
var gradientMap = "black, white";

GradientMaps.applyGradientMap(target, gradientMap);

Convert to Black & white, and darken the mid-tones a bit:

GradientMaps.applyGradientMap(target, "black, gray 60%, white");

Map to a range of colors:

GradientMaps.applyGradientMap(target, "red, #00FF00, rgb(0, 0, 255), yellow");


DO NOT directly modify the gradientmaps.js or gradientmaps.min.js files in the project root. These files are automatically built from components located under the src/ directory.

The project uses Grunt to automate the build process.

Grunt depends on Node.js and npm.

Install Grunt

npm install -g grunt

Tell Grunt to watch for changes and automatically build gradientmaps.js and gradientmaps.min.js:

grunt watch

While grunt watch is running, every time you make changes to components under src/ the main files, cssregions.js and cssregions.min.js, are built and written to the project root.

To do a one-time build run:

grunt build


** Currently there are no tests **

I know, lame.


License information

The code in this repository implies and respects different licenses. This is a quick overview. For details check each folder's corresponding file.

  • Adobe Apache 2 for Gradientmaps
  • MIT for csscolorparser
  • Public Domain for tests, demos and docs
  • Third party assets under their own licenses

See for details.









No releases published


No packages published


  • JavaScript 100.0%