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.

Defaults

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

Input

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

Output

header {
    background: url("alchemy.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("alchemy.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("alchemy.jpg"), 10px);
    background: resemble-image(url("alchemy.jpg"), 10em);
    background: resemble-image(url("alchemy.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);
});

Usage

See the PostCSS documentation for examples for your environment.

Contributors

Thanks goes to these wonderful people (emoji key):

Ben Briggs 💻 📖 👀 ⚠️	Manuel Wieser 💻 ⚠️

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

License

MIT © Ben Briggs