CSS image() Function

CSS image() Function

The CSS image() function defines an image with additional options for fallback colors, image fragments, and direction-aware display.

It extends the capabilities of url() by allowing a color to replace an unavailable image, selecting a portion of an image, or adapting an image to text direction. The function produces a CSS <image> value, but browser support is currently unavailable.

Syntax

image("image.jpg")
image(url("image.jpg"))
image("image.jpg", color)
image(ltr "image.jpg")
image(rtl "image.jpg")
image("image.jpg#xywh=x,y,width,height")
image(color)

The function accepts an optional direction indicator, an optional image source, and an optional fallback color. At least an image source or a color must be supplied.

For example:

.box {
  background-image: image("background.jpg", #333);
}

This specifies a background image and a dark fallback color if the image cannot be rendered.

Additional examples:

background-image: image("photo.jpg");
background-image: image(url("photo.jpg"));
background-image: image("photo.jpg", black);
background-image: image(#0066cc);
background-image: image(rgb(0 0 0 / 40%));
background-image: image("photo.jpg#xywh=20,30,100,80");
list-style-image: image(ltr "arrow.png");

These examples illustrate the specified syntax. Current browsers generally ignore declarations using image().

Parameters

The image() function supports three main components.

For example:

image(ltr "icon.png", #333)

This expression identifies a left-to-right image, specifies its source, and provides a fallback color.

The image source and color are separated by a comma when both are present.

The function does not use resolution descriptors such as 1x or 2x. Those belong to image-set().

How It Works

The image() function defines an image value that can be used by properties accepting CSS images.

Its intended behavior depends on the supplied arguments:

1. If an image source is provided and can be rendered, the browser displays the image.
2. If the source cannot be rendered and a fallback color is provided, the browser displays a solid-color image.
3. If only a color is provided, the browser generates a solid-color image.
4. If an image fragment is provided, the browser uses the specified portion of the source image.
5. If a direction indicator is supplied, the image can be mirrored when used with the opposite text direction.

For example:

.banner {
  background-image: image("banner.jpg", #1f2937);
}

In an implementation supporting image(), the banner image is displayed when available. If it fails, a dark solid-color image replaces it.

Because browsers do not currently implement the function, a separate supported fallback declaration is necessary.

Image Sources

The image() function accepts an image source as a quoted string or through url().

For example:

background-image: image("images/banner.jpg");
background-image: image(url("images/banner.jpg"));

Both forms identify the same image resource.

Relative image paths are resolved against the stylesheet's location, following normal CSS URL rules.

For example:

.header {
  background-image: image("../img/header.jpg");
}

An absolute URL can also be used:

.header {
  background-image: image("https://example.com/images/header.jpg");
}

The function accepts one image source per expression. It does not provide a list of alternative image files for automatic selection.

Use image-set() when the browser should choose among multiple image resources.

Fallback Colors

A fallback color allows image() to display a solid-color image when the specified image cannot be loaded or decoded.

For example:

.hero {
  background-image: image("hero.jpg", #1f2937);
  color: white;
}

If the image is unavailable, the intended result is a dark background that preserves the readability of the white text.

Without image(), a conventional fallback uses background-color:

.hero {
  background-color: #1f2937;
  background-image: url("hero.jpg");
  color: white;
}

The conventional approach works in current browsers.

There is an important difference between these techniques. A background-color remains behind a successfully loaded image, while the fallback color inside image() is intended to replace the image only when the source is unavailable.

This distinction can matter when the original image contains transparent areas.

Solid-Color Images

The image() function can create a solid-color image without loading an external file.

For example:

.box {
  background-image: image(#0066cc);
}

This represents a solid blue image.

Other color formats can also be used:

background-image: image(red);
background-image: image(rgb(0 102 204));
background-image: image(hsl(210 100% 40%));
background-image: image(rgb(0 0 0 / 30%));

A solid-color image can participate in the background image layering system.

For example:

.banner {
  background-image:
    image(rgb(0 0 0 / 30%)),
    url("banner.jpg");
  background-size: cover;
}

The first image layer is intended to provide a semi-transparent dark overlay above the photograph.

In current browsers, use a gradient for the same effect:

.banner {
  background-image:
    linear-gradient(rgb(0 0 0 / 30%), rgb(0 0 0 / 30%)),
    url("banner.jpg");
  background-size: cover;
}

This supported alternative produces a similar visual result without relying on image().

Image Fragments

The image() function can reference a rectangular portion of an image using a spatial media fragment.

The fragment syntax is:

#xywh=x,y,width,height

The four values specify the starting horizontal position, starting vertical position, width, and height of the selected rectangle.

For example:

.icon {
  background-image: image("sprites.png#xywh=32,64,16,16");
}

This selects a 16px by 16px region beginning 32px from the left and 64px from the top of the source image.

Additional examples:

image("photo.jpg#xywh=0,0,100,100")
image("photo.jpg#xywh=pixel:20,30,120,80")
image("photo.jpg#xywh=percent:25,25,50,50")

Spatial media fragments are a separate feature from the image() function and can also appear in url().

Support for cropping images through media fragments varies. For reliable image cropping in current browsers, use background-position, background-size, or object-fit with object-position, depending on the element.

Image Directionality

The image() function can declare whether an image is intended for left-to-right or right-to-left content.

The direction indicators are:

For example:

.navigation-item {
  list-style-image: image(ltr "arrow-right.png");
}

In a supporting implementation, the arrow is displayed normally in left-to-right content and mirrored horizontally when used with right-to-left content in a horizontal writing mode.

Another example uses an image intended for right-to-left content:

.navigation-item {
  list-style-image: image(rtl "arrow-left.png");
}

If directionality is omitted, the function does not request automatic mirroring based on text direction.

For current browsers, direction-specific styles can be written using the :dir() pseudo-class:

.arrow {
  transform: none;
}
.arrow:dir(rtl) {
  transform: scaleX(-1);
}

This alternative can mirror an element without requiring image().

Using Background Images

The image() function is designed for properties that accept CSS image values, including background-image.

For example:

.panel {
  background-image: image("panel.jpg", #eaf3ff);
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
}

In a supporting browser, the image would fill the panel, with the fallback color replacing an unavailable image.

Background image properties continue to control positioning, sizing, and repetition.

A compatible alternative is:

.panel {
  background-color: #eaf3ff;
  background-image: url("panel.jpg");
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
}

This approach is appropriate for production websites that require broad browser compatibility.

Using List Markers

The image() function can also be used with the list-style-image property.

For example:

.custom-list {
  list-style-image: image(ltr "arrow.png");
}

The intended behavior is to display a directional arrow that can be mirrored for right-to-left text.

A supported fallback uses url():

.custom-list {
  list-style-image: url("arrow.png");
  list-style-image: image(ltr "arrow.png");
}

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

For greater control over marker size, spacing, and direction, custom list markers can also be created with the ::before pseudo-element.

image() vs. url()

The image() and url() functions can both reference external image resources, but their capabilities differ.

For example:

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

The first expression references an image directly. The second adds a fallback color within the image value.

Use url() for normal image references on production websites.

image() vs. image-set()

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

For example, image() defines an image with a fallback color:

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

The image-set() function provides alternatives for different display resolutions:

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

Use image-set() when the browser needs to select an appropriate image resolution or supported image format.

Example

This example demonstrates an image with a fallback color. Because image() is unsupported, the Browser Result displays the equivalent supported background declarations.

HTML:

<div class="image-demo">
  <div class="image-demo-card image-demo-loaded">
    <strong>Image Available</strong>
    <span>The image is displayed.</span>
  </div>
  <div class="image-demo-card image-demo-missing">
    <strong>Image Unavailable</strong>
    <span>The fallback color is displayed.</span>
  </div>
</div>

CSS:

.image-demo {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
  gap: 12px;
  max-width: 480px;
  margin: 0 auto;
}
.image-demo-card {
  display: flex;
  flex-direction: column;
  justify-content: center;
  min-height: 140px;
  padding: 12px;
  background-color: #263445;
  background-position: center;
  background-size: cover;
  color: #fff;
  text-align: center;
}
.image-demo-card span {
  margin-top: 8px;
  font-size: 12px;
}
.image-demo-loaded {
  background-image: url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg");
  background-image: image("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg", #263445);
}
.image-demo-missing {
  background-image: url("missing-image.jpg");
  background-image: image("missing-image.jpg", #263445);
}

The first card displays a photograph when the external image is available. The second uses the dark background color because its image source is unavailable.

In current browsers, the demonstration relies on background-color and url(). The image() declarations illustrate the proposed syntax but are ignored.

Color Overlay Example

This example shows how a semi-transparent solid-color image could be layered over a photograph. The Browser Result uses a supported gradient to produce the same effect.

HTML:

<div class="image-overlay-demo">
  <strong>Color Overlay</strong>
  <span>A semi-transparent dark layer improves text readability.</span>
</div>

CSS:

.image-overlay-demo {
  display: flex;
  flex-direction: column;
  justify-content: center;
  min-height: 180px;
  max-width: 440px;
  margin: 0 auto;
  padding: 20px;
  background-image:
    linear-gradient(rgb(0 0 0 / 55%), rgb(0 0 0 / 55%)),
    url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg");
  background-image:
    image(rgb(0 0 0 / 55%)),
    url("https://mdn.github.io/shared-assets/images/examples/balloons-landscape.jpg");
  background-position: center;
  background-size: cover;
  color: #fff;
  text-align: center;
}
.image-overlay-demo strong {
  font-size: 20px;
}
.image-overlay-demo span {
  margin-top: 8px;
  font-size: 13px;
}

The dark overlay makes the white text easier to read against the photograph.

The gradient is the supported implementation. The image() declaration demonstrates the proposed solid-color image syntax.

Browser Fallbacks

Because image() is not currently implemented in major browsers, provide supported declarations before using it.

For example:

.banner {
  background-color: #263445;
  background-image: url("banner.jpg");
  background-image: image("banner.jpg", #263445);
}

Current browsers ignore the unsupported image() declaration and use url().

If the image fails to load, the background color remains visible.

For solid-color image overlays, use a gradient:

.banner {
  background-image:
    linear-gradient(rgb(0 0 0 / 40%), rgb(0 0 0 / 40%)),
    url("banner.jpg");
}

For directional images, use selectors such as :dir() or separate styles for left-to-right and right-to-left layouts.

These approaches provide reliable alternatives without depending on experimental image syntax.

Accessibility

CSS background images are not normally announced by screen readers. Important information should not be conveyed through a background image alone.

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

For example:

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

Fallback colors can help maintain text readability when decorative images fail to load.

Always check text contrast against both the intended image and its fallback color.

Direction-aware images can also help directional icons remain understandable in left-to-right and right-to-left layouts.

Common Uses

The image() function is designed for several image-related tasks, although current browser support prevents general production use.

For production websites, supported CSS alternatives should be used until browser implementations become available.

Limitations

The image() function has several important limitations.

• It is not currently implemented in major browsers.
• It is not interchangeable with image-set().
• It does not automatically choose between different image resolutions.
• Its fallback color replaces an unavailable image rather than providing a permanent background color underneath it.
• Image fragment cropping depends on spatial media fragment support.
• Direction-aware mirroring depends on the element's text direction and writing mode.
• It cannot provide alternative text for meaningful content images.
• Supported fallback declarations are necessary for practical use.

For example, this is valid syntax:

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

The following is invalid because neither an image source nor a color is provided:

background-image: image();

The following is not valid image() syntax because it supplies multiple image candidates:

background-image: image("small.jpg", "large.jpg");

Use image-set() to provide multiple image alternatives.

Browser Support

The CSS image() function has Limited availability and is not Baseline. MDN currently reports no browser support for the function.

Do not confuse support for the general CSS <image> data type with support for the specific image() function. Other image values, including url(), gradients, and image-set(), have separate compatibility information.

For example:

.box {
  background-color: #333;
  background-image: url("photo.jpg");
  background-image: image("photo.jpg", #333);
}

Current browsers use the supported declarations and ignore the unsupported image() value.

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

Until implementations become available, use url(), background-color, gradients, and image-set() as appropriate.

Specifications

The image() function is described in the CSS Images Module Level 4 .

Its syntax and behavior have evolved across CSS Images specifications. Some draft versions describe image sources, directional images, fragments, and fallback colors, while newer draft work also addresses solid-color image generation.

Because the feature remains unimplemented, specification details may change before broad browser adoption.

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