Neglected Parking Meter

    postcss-image-set-function
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.7 • Public • Published

    PostCSS image-set() Function PostCSS Logo

    NPM Version CSS Standard Status Build Status Discord

    PostCSS image-set() Function lets you display resolution-dependent images using the image-set() function in CSS, following the CSS Images specification.

    'Can I use' table

    .example {
      background-image: image-set(
        url(img.png) 1x,
        url(img@2x.png) 2x,
        url(img@print.png) 600dpi
      );
    }
    
    /* becomes */
    
    .example {
      background-image: url(img.png);
    }
    
    @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
      .example {
        background-image: url(img@2x.png);
      }
    }
    
    
    @media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
      .example {
        background-image: url(my@print.png);
      }
    }
    
    .example {
      background-image: image-set(
        url(img.png) 1x,
        url(img@2x.png) 2x,
        url(img@print.png) 600dpi
      );
    }

    Usage

    Add PostCSS image-set() Function to your project:

    npm install postcss-image-set-function --save-dev

    Use PostCSS image-set() Function as a PostCSS plugin:

    const postcss = require('postcss');
    const postcssImageSetFunction = require('postcss-image-set-function');
    
    postcss([
      postcssImageSetFunction(/* pluginOptions */)
    ]).process(YOUR_CSS /*, processOptions */);

    PostCSS image-set() Function runs in all Node environments, with special instructions for:

    Node PostCSS CLI Webpack Create React App Gulp Grunt

    Options

    preserve

    The preserve option determines whether the original declaration using image-set() is preserved. By default, it is preserved.

    postcssImageSetFunction({ preserve: false })
    .example {
      background-image: image-set(
        url(img.png) 1x,
        url(img@2x.png) 2x,
        url(img@print.png) 600dpi
      );
    }
    
    /* becomes */
    
    @media (-webkit-min-device-pixel-ratio: 1), (min-resolution: 96dpi) {
      .example {
        background-image: url(img.png);
      }
    }
    
    @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
      .example {
        background-image: url(img@2x.png);
      }
    }
    
    
    @media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
      .example {
        background-image: url(my@print.png);
      }
    }

    onvalid

    The oninvalid option determines how invalid usage of image-set() should be handled. By default, invalid usages of image-set() are ignored. They can be configured to display a warning or throw an error.

    postcssImageSetFunction({ oninvalid: 'warning' }) // warn on invalid usages
    postcssImageSetFunction({ oninvalid: 'throw' }) // throw on invalid usages

    Image Resolution

    The image-set() function allows an author to provide multiple resolutions of an image and let the browser decide which is most appropriate in a given situation. The image-set() also never fails to choose an image; the <resolution> just helps determine which of the images is chosen.

    Since this plugin is not a browser, the image options are sorted by device pixel ratio and the lowest ratio is used as the default, while the remaining images are pushed behind media queries.

    Therefore, this plugin can only approximate native browser behavior. While images should typically match the resolution as the device they’re being viewed in, other factors can affect the chosen image. For example, if the user is on a slow mobile connection, the browser may prefer to select a lower-res image rather than wait for a larger, resolution-matching image to load.

    Install

    npm i postcss-image-set-function

    DownloadsWeekly Downloads

    6,622,470

    Version

    4.0.7

    License

    CC0-1.0

    Unpacked Size

    22.2 kB

    Total Files

    12

    Last publish

    Collaborators

    • alaguna
    • jonathantneal