<image>

The <image> value type denotes a 2D image. It can be a URL reference, image notation, or gradient notation.

The syntax for an <image> is:

<image> = <url> | <image-list> | <gradient>

In CSS Levels 1 and 2, image values could only be given by a single <url> value. In CSS3, new values were introduced that allow to define an image. The <gradient> value allows defining images as color gradients and patterns. The image() functional notation allows a CSS author to specify fallback images in case the preferred image can’t be decoded or is a type that the browser doesn’t recognize, and it allows using a solid color as an image value. Each <string> or <url> inside image() represents an image, just as if the url() notation had been used.

In Gecko-based browsers, another type of images is supported: one that is defined using the element() notation. The element() CSS function defines an image generated from an arbitrary HTML element. This image is live, meaning that if the HTML element is changed, the CSS properties using the resulting value are automatically updated.
The element() image value is still experimental, and only works in Firefox at this time.

An <image> can be used in many CSS properties, including the background-image, list-style-image, cursor.

Trivia and Notes

In some cases, an image is invalid—for example, when the <url> points to a resource that is not a valid image format. An invalid image is rendered as a solid-color transparent image with no intrinsic dimensions. However, invalid images have special behavior in some contexts, such as the image() notation.

CSS can handle different image types and formats, some of which have intrinsic (inherent) dimension(s) (like JPEG images), others may have height-to-width aspect ratios but no dimensions (like SVG images), and some have neither intrinsic dimensions nor aspect ratios (like CSS gradients). The way the “real” size is determined in CSS depends on an element’s background size, an element’s height and width, and/or the property that an image is used with:

• background-image: When an image is used as a background image, its default size is that of the element’s background positioning area, and its final size is determined based on the default size along with other available sizing information provided by the image type (intrinsic dimensions, ratio, etc.).
• list-style-image: When an image is used as a list marker, its default size is set to the size of a character of 1em, and its final size is determined based on the default size along with other available sizing information provided by the image type (intrinsic dimensions, ratio, etc.).
• border-image: When an image is used as a border image, its default size is the size of the element’s border image area, and its final size is determined based on the default size along with other available sizing information provided by the image type (intrinsic dimensions, ratio, etc.).
• cursor: When an image is used as a cursor image, its default size is a browser-defined size matching the usual size of a cursor on the used system, and its final size is determined based on the default size along with other available sizing information provided by the image type (intrinsic dimensions, ratio, etc.).
• An image can also be used with replaced content, like with the combination of the CSS content property in combination with the CSS pseudo-elements ::after and ::before. In this case, the default image size is 300px by 150px, and its final size is determined based on the default size along with other available sizing information provided by the image type (intrinsic dimensions, ratio, etc.).