Need help with postcss-resemble-image?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

ben-eb
435 Stars 10 Forks MIT License 26 Commits 2 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

No Data

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

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

💻 ⚠️ | | :---: | :---: | :---: | <!-- ALL-CONTRIBUTORS-LIST:END -->

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

Resources

License

MIT © Ben Briggs

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.