PostCSS image-set() Function lets you display resolution-dependent images
using the image-set()
function in CSS, following the CSS Images
specification.
.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
);
}
Add PostCSS image-set() Function to your build tool:
npm install postcss-image-set-function --save-dev
Use PostCSS image-set() Function to process your CSS:
import postcssImageSetFunction from 'postcss-image-set-function';
postcssImageSetFunction.process(YOUR_CSS, /* processOptions */, /* pluginOptions */);
Add PostCSS to your build tool:
npm install postcss --save-dev
Use PostCSS image-set() Function as a plugin:
import postcss from 'gulp-postcss';
import postcssImageSetFunction from 'postcss-image-set-function';
postcss([
postcssImageSetFunction(/* pluginOptions */)
]).process(YOUR_CSS);
Add PostCSS Loader to your build tool:
npm install postcss-loader --save-dev
Use PostCSS image-set() Function in your Webpack configuration:
import postcssImageSetFunction from 'postcss-image-set-function';
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
{ loader: 'postcss-loader', options: {
ident: 'postcss',
plugins: () => [
postcssImageSetFunction(/* pluginOptions */)
]
} }
]
}
]
}
}
Add Gulp PostCSS to your build tool:
npm install gulp-postcss --save-dev
Use PostCSS image-set() Function in your Gulpfile:
import postcss from 'gulp-postcss';
import postcssImageSetFunction from 'postcss-image-set-function';
gulp.task('css', () => gulp.src('./src/*.css').pipe(
postcss([
postcssImageSetFunction(/* pluginOptions */)
])
).pipe(
gulp.dest('.')
));
Add Grunt PostCSS to your build tool:
npm install grunt-postcss --save-dev
Use PostCSS image-set() Function in your Gruntfile:
import postcssImageSetFunction from 'postcss-image-set-function';
grunt.loadNpmTasks('grunt-postcss');
grunt.initConfig({
postcss: {
options: {
use: [
postcssImageSetFunction(/* pluginOptions */)
]
},
dist: {
src: '*.css'
}
}
});
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 */
.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);
}
}
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
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.