Skip to content
This repository has been archived by the owner before Nov 9, 2022. It is now read-only.


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?

Latest commit


Git stats


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

postcss-resemble-image Build Status Build status NPM version Dependency Status

Provide a gradient fallback for an image that loosely resembles the original.


With npm do:

npm install postcss-resemble-image --save

postcss-resemble-image uses Jimp to perform the image analysis. The following image formats are supported:

  • BMP
  • JPEG
  • PNG


This module will add a background gradient fallback for images, should the resource fail to load; the image fallback loosely resembles the original. The idea for this module was inspired by Harry Roberts' article.

Each image will be loaded relative to the CSS file; in these examples, "waves.jpg" is in the same directory as the CSS. Note that this module can also load images from a URL.

There are two ways to use postcss-resemble-image; the first allows you to automatically render these gradients by providing a list of selectors to analyse for images. The second allows you to use a non-standard function, resemble-image, which takes a CSS URL as the first parameter and the fidelity as the second. You may use these interchangeably if you so wish.

Using the automatic render


    selectors: ['header']


header {
    background: url("waves.jpg");


header {
    background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);

Using the resemble-image function


header {
    background: resemble-image(url("waves.jpg"));
header {
    background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);

Passing percentages

fidelity is set globally, but can also be passed as the second parameter to the resemble-image function. This code will generate a colour stop for each tenth of the image.

header {
    background: resemble-image(url("waves.jpg"), 10%);

Passing absolute lengths

fidelity can also be set via a pixel value. Anything other than % will be parsed as a px value, including no unit; these are equivalent:

header {
    background: resemble-image(url("waves.jpg"), 10px);
    background: resemble-image(url("waves.jpg"), 10em);
    background: resemble-image(url("waves.jpg"), 10);


Original image:

After processing (using simpleGradient, with 25% stops):

After processing (using complexGradient, with 5% stops):

Image credit:



Note that postcss-resemble-image is an asynchronous processor. It cannot be used like this:

import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';

const result = postcss([ resembleImage() ]).process(css).css;

Instead make sure your PostCSS runner uses the asynchronous API:

import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';

postcss([ resembleImage() ]).process(css).then((result) => {

postcss-resemble-image is designed to be used with import & export. When using require, make sure that you load the main module by doing:

const resembleImage = require('postcss-resemble-image').default;



Type: number|string
Default: 25%

The fidelity option controls how many colour stops will be generated for the linear gradient fallback. By default, it will be split into quarters. Setting this to anything other than % will be parsed as a px value, including no unit. Zero values are not allowed.


Type: function
Default: simpleGradient

The generator option controls the rendering of the gradient function; by default it is set to simpleGradient which will smoothly transition between the gradient stops. The complexGradient function hard transitions between each colour, for a striped effect. To use this instead you may import the function from the module, like so:

import postcss from 'postcss';
import resembleImage, {complexGradient} from 'postcss-resemble-image';

postcss([ resembleImage({generator: complexGradient}) ]).process(css).then((result) => {

Type: array
Default: []

The selectors array controls which selectors postcss-resemble-image should analyse for URLs to provide gradients for. The module tests using strict equality; if you are checking a selector which contains more than one simple selector only one of these needs to be specified. For example:

import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';

const css = `
header, footer {
    background: url("waves.jpg");

postcss([ resembleImage({selectors: ['footer']}) ]).process(css).then((result) => {
    // => header, footer {
    //        background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);
    //    }

Note that this option isn't required when using the resemble-image function.


See the PostCSS documentation for examples for your environment.


Thanks goes to these wonderful people (emoji key):

Ben Briggs

💻 📖 👀 ⚠️

Manuel Wieser

💻 ⚠️

Steven Sinatra

💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!



MIT © Ben Briggs