CSS image-set() Function

CSS image-set() Function

The CSS image-set() function provides multiple image options and allows the browser to select the most appropriate image for the device.

It is commonly used to supply images at different resolutions or in different formats. The browser can consider display pixel density, supported image formats, and other factors when choosing which image to load.

Syntax

image-set(image-option, image-option, ...)

Each image option contains an image source and may include a resolution descriptor, a type() descriptor, or both.

For example:

.box {
  background-image: image-set(
    url("photo.jpg") 1x,
    url("photo-2x.jpg") 2x
  );
}

The browser selects an image based on the device's resolution and other selection criteria.

Additional examples:

background-image: image-set("photo.jpg" 1x, "photo-2x.jpg" 2x);
background-image: image-set(url("photo.jpg") 1dppx, url("photo-2x.jpg") 2dppx);
background-image: image-set(url("photo.avif") type("image/avif"), url("photo.jpg") type("image/jpeg"));
background-image: image-set(url("photo.jpg") 96dpi, url("photo-2x.jpg") 192dpi);

Image options are separated by commas. At least one image option is required.

Parameters

Each option in image-set() can contain the following components.

For example:

image-set(
  url("photo.avif") 2x type("image/avif"),
  url("photo.jpg") 1x type("image/jpeg")
)

The first option specifies an AVIF image at 2x resolution. The second specifies a JPEG image at 1x resolution.

When a resolution is omitted, it defaults to 1x for image selection.

The type() descriptor is optional and accepts a quoted MIME type.

How It Works

The image-set() function provides a set of image candidates. The browser determines which candidate is most appropriate.

The selection process generally works as follows:

1. The browser examines the available image options.
2. Options declaring unsupported image formats are excluded.
3. Duplicate resolution options are resolved according to their order.
4. The browser selects one remaining option based on resolution and other relevant factors.
5. The selected image is used by the CSS property.

For example:

.banner {
  background-image: image-set(
    url("banner.jpg") 1x,
    url("banner-2x.jpg") 2x
  );
}

A standard-density display may use the 1x image, while a high-density display may use the 2x image.

The browser is not required to select an image based only on pixel density. It may also consider network conditions and other factors.

The function selects an image resource. It does not automatically resize the element receiving the image.

Resolution Descriptors

Resolution descriptors identify the intended pixel density of each image candidate.

The following values are equivalent:

1x = 1dppx = 96dpi
2x = 2dppx = 192dpi

For example:

.logo {
  background-image: image-set(
    url("logo.png") 1x,
    url("logo-2x.png") 2x,
    url("logo-3x.png") 3x
  );
}

The browser can choose from three versions of the same image.

Higher-resolution images generally contain more pixels and can appear sharper on high-density screens when displayed at the same CSS dimensions.

Each candidate should represent the same visual content at a different resolution.

Image Formats

The type() descriptor identifies an image's MIME type and allows the browser to exclude formats it does not support.

For example:

.banner {
  background-image: image-set(
    url("banner.avif") type("image/avif"),
    url("banner.jpg") type("image/jpeg")
  );
}

A browser supporting AVIF can select the AVIF image. A browser that does not support AVIF can select the JPEG alternative.

Common MIME types include:

The type() descriptor does not convert an image into another format. It only describes the format of a candidate.

Ensure the declared MIME type matches the actual image file.

For reliable format fallback, provide a widely supported format such as JPEG or PNG as an alternative.

Combining Descriptors

An image candidate can include both a resolution descriptor and a type() descriptor.

For example:

.hero {
  background-image: image-set(
    url("hero.avif") 1x type("image/avif"),
    url("hero-2x.avif") 2x type("image/avif"),
    url("hero.jpg") 3x type("image/jpeg")
  );
}

Each option has a distinct resolution, allowing the browser to consider the image format and resolution together.

The order of the two descriptors can be reversed:

image-set(
  url("photo.avif") 2x type("image/avif"),
  url("photo.jpg") type("image/jpeg") 1x
)

Both arrangements are valid.

Each candidate should use a unique resolution. If two candidates specify the same resolution, the earlier eligible candidate takes precedence during duplicate resolution filtering.

When combining image formats and resolutions, plan the candidate list carefully so a suitable alternative remains available.

Image Selection

The browser is responsible for choosing one image from the supplied options.

For example:

.card {
  background-image: image-set(
    url("card-small.jpg") 1x,
    url("card-medium.jpg") 2x,
    url("card-large.jpg") 3x
  );
}

The browser may consider the device's pixel density, network conditions, and other implementation-specific factors.

Selection is not guaranteed to follow a simple rule such as always choosing the 2x image on a 2x screen.

Also, image-set() does not automatically switch images based on the element's width.

For example, a 1x image may be selected for both a small and large element if the browser considers it the best candidate.

To change images based on viewport width, use media queries:

.hero {
  background-image: url("hero-small.jpg");
}
@media (min-width: 768px) {
  .hero {
    background-image: url("hero-large.jpg");
  }
}

Use image-set() for resolution and format selection, and media queries when different layouts require different image compositions or sizes.

Background Images

The image-set() function is commonly used with the background-image property.

For example:

.banner {
  background-image: image-set(
    url("banner.jpg") 1x,
    url("banner-2x.jpg") 2x
  );
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
}

The browser selects an image candidate, and the remaining background properties control how that image is displayed.

The function can also be used with multiple background layers:

.hero {
  background-image:
    linear-gradient(rgb(0 0 0 / 40%), rgb(0 0 0 / 40%)),
    image-set(
      url("hero.jpg") 1x,
      url("hero-2x.jpg") 2x
    );
  background-position: center;
  background-size: cover;
}

The gradient creates a dark overlay while image-set() provides alternative resolutions of the photograph.

The browser selects one image from the set for the background layer.

Generated Images

The image-set() syntax also allows generated CSS images, such as gradients, as candidates.

For example:

.box {
  background-image: image-set(
    linear-gradient(#0066cc, #66b3ff) 1x,
    linear-gradient(#003366, #0066cc) 2x
  );
}

This provides two generated image options with different resolution descriptors.

Because gradients are vector-like CSS images, they normally render sharply at different display resolutions without requiring separate versions.

For most gradient backgrounds, a regular gradient is simpler:

.box {
  background-image: linear-gradient(#0066cc, #66b3ff);
}

Use image-set() primarily when multiple image resources offer a practical benefit.

The function cannot be nested inside another image-set() function.

image-set() vs. url()

The url() function references one image resource, while image-set() provides multiple image candidates.

For example:

background-image: url("photo.jpg");

This always references the same image file.

background-image: image-set(
  url("photo.jpg") 1x,
  url("photo-2x.jpg") 2x
);

This allows the browser to select between two image resolutions.

Use url() for a single image source and image-set() when multiple alternatives are useful.

image-set() vs. image()

The image-set() and image() functions have different purposes.

For example:

background-image: image-set(
  url("photo.jpg") 1x,
  url("photo-2x.jpg") 2x
);

This provides two alternative image resources.

background-image: image("photo.jpg", #333);

This specifies one image and a fallback color using the experimental image() syntax.

For production websites, image-set() is the supported choice when providing multiple image resolutions or formats.

Example

This example uses image-set() to provide two resolutions of the same background photograph.

HTML:

<div class="image-set-demo">
  <strong>Responsive Image Resolution</strong>
  <span>The browser selects an appropriate image.</span>
</div>

CSS:

.image-set-demo {
  display: flex;
  flex-direction: column;
  justify-content: center;
  min-height: 180px;
  max-width: 440px;
  margin: 0 auto;
  padding: 20px;
  background-color: #263445;
  background-image: url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg");
  background-image: image-set(
    url("https://mdn.github.io/shared-assets/images/examples/balloons-small.jpg") 1x,
    url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg") 2x
  );
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
  color: #fff;
  text-align: center;
  text-shadow: 0 1px 4px #000;
}
.image-set-demo strong {
  font-size: 19px;
}
.image-set-demo span {
  margin-top: 8px;
  font-size: 13px;
}

The browser chooses between the 1x and 2x image candidates according to its image selection criteria.

The background-size: cover declaration controls how the selected image fills the box.

The earlier url() declaration provides a fallback for browsers that do not recognize image-set().

Image Format Example

This example provides AVIF and JPEG versions of the same image.

HTML:

<div class="image-set-format-demo">
  <strong>Image Format Selection</strong>
  <span>AVIF or JPEG, depending on browser support.</span>
</div>

CSS:

.image-set-format-demo {
  display: flex;
  flex-direction: column;
  justify-content: center;
  min-height: 180px;
  max-width: 440px;
  margin: 0 auto;
  padding: 20px;
  background-color: #263445;
  background-image: url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg");
  background-image: image-set(
    url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.avif") type("image/avif"),
    url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg") type("image/jpeg")
  );
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
  color: #fff;
  text-align: center;
  text-shadow: 0 1px 4px #000;
}
.image-set-format-demo strong {
  font-size: 19px;
}
.image-set-format-demo span {
  margin-top: 8px;
  font-size: 13px;
}

A browser supporting AVIF can select the AVIF image. A browser without AVIF support can use the JPEG candidate.

The selected file is not visually identified in the Browser Result because both images contain the same photograph.

Browser developer tools can be used to inspect which image resource was loaded.

Browser Fallbacks

Although image-set() is widely supported, a conventional image declaration can provide compatibility with older browsers.

For example:

.banner {
  background-image: url("banner.jpg");
  background-image: image-set(
    url("banner.jpg") 1x,
    url("banner-2x.jpg") 2x
  );
}

Browsers that do not recognize image-set() retain the first declaration.

Browsers supporting the function can choose from the supplied candidates.

For image format alternatives:

.banner {
  background-image: url("banner.jpg");
  background-image: image-set(
    url("banner.avif") type("image/avif"),
    url("banner.jpg") type("image/jpeg")
  );
}

The JPEG declaration provides an older-browser fallback, while the image set allows supported browsers to select an appropriate format.

Include valid image candidates rather than relying on the browser to recover from missing files.

Accessibility

Images used through CSS backgrounds are generally decorative and are not announced by screen readers.

Important information should not depend entirely on a background image.

For meaningful content images, use an HTML <img> element with appropriate alternative text.

For example:

<img src="diagram.png" alt="Diagram showing the layout structure">

The HTML srcset and sizes attributes can provide responsive image selection for content images.

For example:

<img src="photo.jpg" srcset="photo.jpg 1x, photo-2x.jpg 2x" alt="Mountain landscape">

Use image-set() primarily for CSS image values and HTML responsive image features for meaningful content images.

Common Uses

The image-set() function is useful whenever the browser should choose among alternative images.

For example:

.icon {
  width: 32px;
  height: 32px;
  background-image: image-set(
    url("icon.png") 1x,
    url("icon-2x.png") 2x
  );
  background-size: 32px 32px;
  background-repeat: no-repeat;
}

The icon retains the same CSS dimensions while the browser can select a higher-resolution image.

Limitations

The image-set() function has several important rules and limitations.

• It selects one image candidate rather than combining all candidates.
• It does not automatically select images based on an element's rendered width.
• It does not replace HTML srcset and sizes for responsive content images.
• Each image option must contain a valid image source or generated image.
• Resolution descriptors must be valid positive resolutions.
• Duplicate resolutions are filtered, with earlier eligible candidates taking precedence.
• The type() descriptor identifies a format but does not convert image files.
• It cannot be nested inside another image-set() function.
• The browser controls which eligible image is selected.
• Image loading can still fail if the selected resource is missing or unavailable.

For example, this is valid:

background-image: image-set(
  url("photo.jpg") 1x,
  url("photo-2x.jpg") 2x
);

The following is invalid because no image options are provided:

background-image: image-set();

The following is invalid because an image set cannot be nested inside another image set:

background-image: image-set(
  image-set(url("photo.jpg") 1x) 1x
);

Use separate image candidates within one image-set() expression.

Browser Support

The CSS image-set() function is Baseline Widely available. It has been supported across major browser engines since September 2023.

Modern versions of Chrome, Edge, Firefox, Safari, and other major browsers support the unprefixed function.

Older browser versions may require the prefixed -webkit-image-set() form or may support only a subset of the syntax.

For example:

.box {
  background-image: url("photo.jpg");
  background-image: image-set(
    url("photo.jpg") 1x,
    url("photo-2x.jpg") 2x
  );
}

The first declaration provides a fallback for browsers without image-set() support.

For current compatibility information, visit Can I Use? and search for CSS image-set().

Specifications

The image-set() function is defined in the CSS Images Module Level 4 .

The specification defines image candidates, resolution and type descriptors, duplicate resolution handling, and browser image selection.

Related CSS functions include url(), image(), linear-gradient(), and cross-fade().