Skip to content
Tutorials Center
My learning

Topics

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.

CSS
.logo {
  background-image: image-set(
    url("logo.png") 1x,
    url("[email protected]") 2x
  );
}

Try it

Which candidate did your screen pick?
Using a real file with a fallback

Syntax

CSS
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 (or dppx), dpi, dpcm. 2x is the same as 192dpi. Without a resolution the candidate counts as 1x.
  • 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> and srcset in 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: contain or cover this takes care of itself.
  • Fallback first. Put a plain url() declaration before the image-set() declaration so older browsers still show an image.
  • Content images belong in HTML. If the image carries meaning, use <img> with alt; 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.