CSS image-set() Function

The image-set() function allows the browser to pick the most appropriate image from a given set of options.

It's mainly used for delivering responsive background images. Instead of forcing all users to download a massive high-resolution image, you can provide multiple versions (like standard and high-res) and let the browser decide which one to download based on the user's device screen density.

In addition to resolution switching, modern implementations of image-set() also allow you to provide different image formats. This means you can offer next-generation formats like AVIF or WebP, with a fallback to standard JPEG or PNG for older browsers.

It can be used anywhere an image data type is accepted, such as the background-image property. Here is an example of providing standard (1x) and high-resolution (2x) versions of an image:

Providing Different Image Formats

The CSS Images Module Level 4 specification expanded the image-set() function to support format switching using the type() function.

This allows you to list multiple formats of the same image. The browser will parse the list and download the first format it supports, ignoring the rest. This is highly useful for serving modern, highly-compressed formats like AVIF or WebP while ensuring older browsers still get a JPEG.

Here is an example of format switching:

Official Syntax

The official syntax of the image-set() function is as follows:

Where <image-set-option> is defined as:

Possible Values

As indicated in the official syntax, the image-set() function accepts a comma-separated list of options, which can include:

image or string

The image to be used. This can be a standard url(), a CSS gradient, or simply a string representing the URL (e.g., "image.jpg").

resolution

An optional resolution identifier. Common units include x or dppx (dots per pixel unit), dpi (dots per inch), and dpcm (dots per centimeter). For example, 1x represents a standard display, and 2x represents a high-density (Retina) display.

type(<string>)

An optional MIME type string specifying the file format of the image, wrapped in the type() function. For example, type("image/webp").

CSS Specifications

• The image-set() function is defined in CSS Image Values and Replaced Content Module Level 4 (Editor’s Draft)

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.