postcss-resemble-image

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

Install

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

Example

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

Options

{
    selectors: ['header']
}

Input

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

Output

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

Using the resemble-image function

Defaults

Input

header {
    background: resemble-image(url("waves.jpg"));
}

Output

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);
}

Screenshots

Original image:

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

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

Image credit: https://unsplash.com/?photo=9EM7s13H2I0

API

resembleImage([options])

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;
console.log(result);

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) => {
    console.log(result.css);
});

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;

options

fidelity

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.

generator

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) => {
    console.log(result.css);
});

selectors

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) => {
    console.log(result.css);
    // => 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.

Usage

See the PostCSS documentation for examples for your environment.

Contributors

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!

Resources

• Harry Roberts' original article.
• Manuel Wieser's resemble image blog post.

License

MIT © Ben Briggs