image()

The image() function is used to display an image file via its URL. It works similarly to the url() function, but for images only, and with added features such as using a solid color as a fallback, specifying the image’s directionality, and using media fragments (denoted through the xywh attribute) to crop out a fraction of the image.

Heads up: The image() function hasn’t been implemented by any browser yet! This information is based on the CSS Images Module Level 4 specification, which is in Working Draft status as of August 2025.

.demo {
  background-image: image(rtl "https://example-img.png#xywh=0,15,35,35", #dddddd);
}

Syntax

The image() function syntax is as defined below:

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

While each argument is optional, at least<image-src> or <color> must be defined. You can include either or both, but not neither.

Arguments

The CSS image() function accepts up to three optional arguments:

<image-tags> = [ ltr | rtl ]
<image-src> = [ <url> | <string> ]
<color>

• <image-tags>: An optional argument for specifying the directionality of the image, similar to the HTML dir attribute. It takes either ltr (left-to-right) and rtl (right-to-left). When applied to an image in an opposite direction, the image is inverted along the inline axis, as if viewed in a mirror.
• <image-src>: Another optional argument that we can replace or accompany with a <color> value; otherwise it is no longer optional, but required. Still, 99% of the time, you’ll need it to display the image. It takes the image’s URL, which can be relative, absolute, a data image, or even a url() function. It can be suffixed with media fragment identifiers, xywh, to clip a portion of the entire image and return it as a standalone.

.element {
  background-image: image("image.png#xywh=0,15,35,35");
}

• <color>: This is used with <image-src> to set a fallback background color, if, for any reason, the provided URL is invalid or if the image fails to load. It can be used without <image-src> to set a solid background color.

Basic usage

The option to set a fallback background color is perhaps the most handy image() feature. Images can disappear for a number of reasons and setting a fallback color ensures that there is still background styling on an element if that happens.

.card {
  background-image: image("image.png", #ccc);
}

Cropping images

Did you know we can crop images with this function, too? We can do that with “fragment identifiers” which is a fancy name for parameters you add at the end of the image URL. The parameters act as a set of coordinates that instruct the function to crop the image at specific points.

What are those coordinates? We define them first by adding #xywh= to the end of the image URL. The hash tag tells the function that everything after it is a set of instructions rather than part of the URL. And the letters X, Y, W, H are the points:

• X: The image’s horizontal x-axis
• Y: The image’s vertical y-axis
• W: The image’s width
• Y: The image’s height

So, basically, xywh defines the image area you want to crop:

.cropped {
  background-image: image("https://example-box-img.png#xywh=0,12,30,45");
}

Setting the image direction

A lot of content on the web follows a left-to-right direction, but that’s not true for every part of the world. For example, some regions default to a right-to-left direction (e.g., Arabic, Hebrew).

When you’re building a website that needs to account for multiple writing modes like this, the image() function accepts an <image-tags> argument to set the image’s direction:

.bg-rtl {
  background-image: image(rtl, "https://example-img.png");
}

image() vs. url()

You might be thinking that the image() function looks and sounds a lot like another CSS function, url(). They both take URLs as arguments and they’re both used to fetch a type of media for styling things. But they’re quite different, as you can see in the following table that compares the two:

Specification

The image() function is defined in the Images Module Level 4 which is currently in Editor’s Draft. That means the information about this function can change between now and when it officially becomes a Candidate Recommendation for browser implementation.

Browser support

The image() function is not supported in any browser as of August 2025. You can track its status in the Web Platform Tests dashboard.

Related

Almanac on Sep 4, 2025

image-set()

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

image optimization

Gabriel Shoyombo

Almanac on Sep 4, 2025

url()

.element { background-image: url("https://example.com/image.png"); }

Gabriel Shoyombo

Almanac on Sep 28, 2022

background-image

.element { background-image: url(texture.svg); }

Chris Coyier