CSS Reference ยท Functions
The image-set() function
Reference for the CSS image-set() function: offering several images for different pixel densities, type() hints, where it works and live examples.
The image-set() function lets a CSS image value offer several candidates with different resolutions, and the browser picks the best one for the screen. It is the CSS counterpart of srcset on <img>: ship a standard image and a sharper one for high-density displays, and each device downloads only the one it needs.
It can be used wherever a CSS <image> is accepted, such as background-image, list-style-image, border-image-source and content.
.logo { background-image: image-set( url("logo.png") 1x, url("[email protected]") 2x ); }
Try it
Syntax
image-set( <option># ) /* <option> = [ <image> | <string> ] [ <resolution> || type(<string>) ]? */ image-set( url("a.avif") 1x type("image/avif"), url("a.webp") 1x type("image/webp"), url("a.jpg") 1x )
- Resolution units:
x(ordppx),dpi,dpcm.2xis the same as192dpi. Without a resolution the candidate counts as1x. - Inherited: not applicable. Animatable: no, although the properties that use it may have their own rules.
Values
| Part | Description |
|---|---|
| Image | Normally url("..."). Plain quoted strings are also allowed in current specs, but url() is the safe form. |
| Resolution | The pixel density the file is designed for. The browser chooses the candidate closest to the display density, preferring one that is not smaller. |
type("mime") |
Optional format hint (for example image/avif). Candidates with an unsupported type are skipped, letting you offer modern formats first. |
Usage notes
- Pick by density, not by size.
image-set()does not look at the element's size or the viewport width. For art direction or size-based choices use media queries, or<picture>andsrcsetin HTML. - Only one is downloaded. The browser requests the chosen candidate only. Changing the zoom level may trigger a different choice.
- Size the box yourself. A 2x image is twice as many pixels, but its natural size is still treated as half. When used with
background-size: containorcoverthis takes care of itself. - Fallback first. Put a plain
url()declaration before theimage-set()declaration so older browsers still show an image. - Content images belong in HTML. If the image carries meaning, use
<img>withalt; backgrounds are for decoration. - Gradients and other images are allowed as candidates, but the main use remains raster files with different densities.
Browser support
The unprefixed image-set() is supported in current browsers; older ones needed the -webkit-image-set() prefix. Support for type() and plain string candidates is newer, so check a compatibility table before relying on them.