postcss-resemble-image

    2.1.1 • Public • Published

    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

    💻 ⚠️

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

    Resources

    License

    MIT © Ben Briggs

    Install

    npm i postcss-resemble-image

    DownloadsWeekly Downloads

    13

    Version

    2.1.1

    License

    MIT

    Last publish

    Collaborators

    • beneb