PostCSS image-set() Function 
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([email protected]) 2x,
url([email protected]) 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([email protected]);
}
}
@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
.example {
background-image: url([email protected]);
}
}
.example {
background-image: image-set(
url(img.png) 1x,
url([email protected]) 2x,
url([email protected]) 600dpi
);
}
Usage
Add PostCSS image-set() Function to your build tool:
npm install postcss-image-set-function --save-dev
Node
Use PostCSS image-set() Function to process your CSS:
import postcssImageSetFunction from 'postcss-image-set-function';
postcssImageSetFunction.process(YOUR_CSS, /* processOptions */, /* pluginOptions */);
PostCSS
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);
Webpack
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 */)
]
} }
]
}
]
}
}
Gulp
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('.')
));
Grunt
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'
}
}
});
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([email protected]) 2x,
url([email protected]) 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([email protected]);
}
}
@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
.example {
background-image: url([email protected]);
}
}
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