Socket
Socket
Sign inDemoInstall

postcss-image-set-function

Package Overview
Dependencies
6
Maintainers
3
Versions
19
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

    postcss-image-set-function

Display resolution-dependent images using the image-set() function in CSS


Version published
Weekly downloads
5.7M
decreased by-1.87%
Maintainers
3
Install size
46.0 kB
Created
Weekly downloads
 

Package description

What is postcss-image-set-function?

The postcss-image-set-function package is a PostCSS plugin that allows you to polyfill the CSS image-set function. This function is used to specify different images to use in different situations, such as high-resolution displays or different types of devices. The plugin transforms image-set notation into a background-image declaration that is compatible with all browsers.

What are postcss-image-set-function's main functionalities?

Transform image-set function

This feature allows you to write CSS using the image-set function, which the plugin will then transform into a background-image property with corresponding -webkit-image-set for compatibility with browsers that support it.

background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x, 'img/test-print.png' 600dpi);

Fallback for browsers without image-set support

The plugin provides a fallback for browsers that do not support the image-set function by outputting a standard background-image property with the 1x image as the default.

background-image: url('img/test.png');
background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x);

Other packages similar to postcss-image-set-function

Readme

Source

PostCSS image-set() Function PostCSS Logo

NPM Version Build Status Discord

Baseline Status CSS Standard Status

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:

NodePostCSS CLIWebpackGulpGrunt

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

onInvalid

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 emit a warning with warn or throw an exception with throw.

postcssImageSetFunction({ onInvalid: 'warn' }) // 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.

Keywords

FAQs

Last updated on 19 Feb 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc