Theimage()CSSfunction defines an<image> in a similar fashion to theurl() function, but with added functionality including specifying the image's directionality, displaying just a part of that image defined by a media fragment, and specifying a solid color as a fallback in case none of the specified images are able to be rendered.

Syntax

/* Basic usage */image("image1.jpg");image(url("image2.jpg"));/* Bidi-sensitive Images */image(ltr "image1.jpg");image(rtl "image1.jpg");/* Image Fallbacks */image("image1.jpg", black);/* Image Fragments */image("image1.jpg#xywh=40,0,20,20");/* Solid-color Images */image(rgb(0 0 255 / 0.5)), url("bg-image.png");

Values

image-tagsOptional

The directionality of the image, eitherltr for left-to-right orrtl for right-to-left.

image-srcOptional

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

colorOptional

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

Bi-directional awareness

The first, optional parameter of theimage() 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.

Image fragments

One key difference betweenurl() andimage() 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 imagemyImage.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. Thespacial 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 inurl() 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 withurl(). If the browser doesn't understand the media fragments notation, it ignores the fragment, displaying the entire image.

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

Color fallback

If a color is specified inimage() along with your image sources, it acts as a fallback if the images are invalid and do not appear. In such cases, theimage() 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 abackground-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 thebackground-size property. This is different from thebackground-color, which sets a color to cover the entire element. Bothimage(color) andbackground-color placements are impacted by thebackground-clip andbackground-origin properties.

Formal syntax

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

<image-tags> =
ltr|
rtl

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

Accessibility

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 CSSimage() 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.

Examples

Directionally-sensitive images

<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 withdir="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 withdir="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 iftransform: scaleX(-1) had been set. The text will also be displayed left-to-right.

Displaying a section of the background image

<div>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.

Putting color on top of a background image

.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>  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 thebackground-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 usedimage() along with thebackground-size property (and prevented the image from repeating with thebackground-repeat property, the color swatch will only cover a quarter of the container.

Specifications

Browser compatibility

Currently, no browsers support this feature.

See also

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