image()

<image()> = 
  image( <image-tags>? [ <image-src>? , <color>? ]! )  

<image-tags> = 
  ltr  |
  rtl  

<image-src> = 
  <url>     |
  <string>  

<url> = 
  <url()>  |
  <src()>  

<url()> = 
  url( <string> <url-modifier>* )  |
  <url-token>                      

<src()> = 
  src( <string> <url-modifier>* )  

where:

image-tags Optional

The directionality of the image, either ltr for left-to-right or rtl for right-to-left.

image-src Optional

Zero or more <url>s or <string>s specifying the image sources, with optional image fragment identifiers.

color Optional

A color, specifying a solid background color to use as a fallback if no image-src is found, supported, or declared.

The first, optional parameter of the image() notation is the directionality of the image. If included, and the image is used on an element with opposite directionality, the image will be flipped horizontally in horizontal writing modes. If the directionality is omitted, the image won't be flipped if the language direction is changed.

One key difference between url() and image() is the ability to add a media fragment identifier — a starting point along the x and y axis, along with a width and height — onto the image source to display only a section of the source image. The section of the image defined in the parameter becomes a standalone image. The syntax looks like so:

background-image: image("my-image.webp#xywh=0,20,40,60");

The background image of the element will be the portion of the image myImage.webp that starts at the coordinate 0px, 20px (the top left-hand corner) and is 40px wide and 60px tall.

The #xywh=#,#,#,# media fragment syntax takes four comma separated numeric values. The first two represent the X and Y coordinates for the starting point of the box that will be created. The third value is the width of the box, and the last value is the height. By default, these are pixel values. The spacial dimension definition in the media specification indicates that percentages will be supported as well:

xywh=160,120,320,240        /* results in a 320x240 image at x=160 and y=120 */
xywh=pixel:160,120,320,240  /* results in a 320x240 image at x=160 and y=120 */
xywh=percent:25,25,50,50    /* results in a 50%x50% image at x=25% and y=25% */

The image fragments can be used in url() notation as well. The #xywh=#,#,#,# media fragment syntax is 'backwards compatible' in that a media fragment will be ignored if not understood, and won't break the source call when used with url(). If the browser doesn't understand the media fragments notation, it ignores the fragment, displaying the entire image.

Browsers that understand image() also understand the fragment notation. Therefore, if the fragment is not understood within image(), the image will be considered invalid.

If a color is specified in image() along with your image sources, it acts as a fallback if the images are invalid and do not appear. In such cases, the image() function renders as if no image were included, generating a solid-color image. As a use case, consider a dark image being used as a background for some white text. A dark background color may be needed for foreground text to be legible, if the image does not render.

Omitting image sources while including a color is valid and creates a color swatch. Unlike declaring a background-color, which is placed under or behind all the background images, this can be used to put (generally semi-transparent) colors over other images.

The size of the color swatch can be set with the background-size property. This is different from the background-color, which sets a color to cover the entire element. Both image(color) and background-color placements are impacted by the background-clip and background-origin properties.

Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document.

• MDN Understanding WCAG, Guideline 1.1 explanations
• Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0

This feature can help improve accessibility by providing a fallback color when an image fails to load. While this can and should be done by including a background-color on every background image, the CSS image() function allows adding allows only including background colors should an image fail to load, which means you can add a fall back color should a transparent PNG/GIF/WebP not load.

<ul>
  <li dir="ltr">Bullet is a right facing arrow on the left</li>
  <li dir="rtl">Bullet is the same arrow, flipped to point left.</li>
</ul>

ul {
  list-style-image: image(ltr "rightarrow.png");
}

In the left-to-right list items — those with dir="ltr" set on the element itself or inheriting the directionality from an ancestor or default value for the page — the image will be used as-is. List items with dir="rtl" set on the <li> or inheriting the right-to-left directionality from an ancestor, such as documents set to Arabic or Hebrew, will have the bullet display on the right, horizontally flipped, as if transform: scaleX(-1) had been set. The text will also be displayed left-to-right.

<div class="box">Hover over me. What cursor do you see?</div>

.box:hover {
  cursor: image("sprite.png#xywh=32,64,16,16");
}

When the user hovers over the box, the cursor will change to display the 16x16 px section of the sprite image, starting at x=32 and y=64.

.quarter-logo {
  height: 200px;
  width: 200px;
  border: 1px solid;
}

.quarter-logo {
  background-image: image(rgb(0 0 0 / 25%)), url("firefox.png");
  background-size: 25%;
  background-repeat: no-repeat;
}

<div class="quarter-logo">
  If supported, a quarter of this div has a darkened logo
</div>

The above will put a semi-transparent black mask over the Firefox logo background image. Had we used the background-color property instead, the color would have appeared behind the logo image instead of on top of it. Additionally, the entire container would have had the same background color. Because we used image() along with the background-size property (and prevented the image from repeating with the background-repeat property, the color swatch will only cover a quarter of the container.

• <image>
• element()
• <url>
• clip-path
• <gradient>
• image-set()
• cross-fade()