<image>

Summary

The <image> CSS data type represents a 2D image. There are two kinds of images in CSS: plain static images, often referenced using a URL, and dynamically-generated images like gradients or representations of parts of the tree.

CSS can handle different kinds of images:

  • images with intrinsic dimensions, that is a natural size, like a jpeg image which has a fixed dimensions.
  • images with several intrinsic dimensions, that exist in several versions inside a file, like some .ico formats. In that case, the intrinsic dimension will be the one of the bigger image, in surface, and with the closest ratio to the one of the containing box.
  • images with no intrinsic dimensions but with an intrinsic aspect ratio, between its width and height, like some vectorized images, in the SVG format for example.
  • images with neither intrinsic dimensions, nor an intrinsic aspect ratio, like a CSS gradient for example.

CSS determines the concrete object size using these intrinsic dimensions, the specified size defined by CSS properties like width, height or background-size, and the default object size defined by the kind of property the image is used with:

Kind of object Default object size
background-image The size of the element's background positioning area
list-style-image The size of a character of 1em
border-image The size of the element's border image area
cursor A browser-defined size matching the usual size of a cursor on the used system
Replaced content
like with the combination of the CSS content property
in combination with the CSS pseudo-elements ::after and ::before
A 300px × 150px rectangle

The concrete object size is calculated using the following algorithm:

  • If the specified size defines both the width and the height, these values are used as the concrete object size.
  • If the specified size defines one of both the width and the height, the missing value is determined using the intrinsic ratio, if there is any, the intrinsic dimensions if the specified value matches, or using the default object size for that missing value.
  • If the specified size do not define the width and the height, the concrete object size will be calculated so that it matches the intrinsic aspect ratio of the images but do not exceed the default object size in any dimension. If the image has no intrinsic aspect ratio, the intrinsic aspect ratio of the object it applies to is used; if this object has none, the missing width or height are taken from the default object size.

Images can be used with numerous CSS properties like background-image, border-image, content, list-style-image or cursor.

Note: Not all browsers support any type of images on any property. See the browser compatibility section for a comprehensive list.

Syntax

An <image> CSS data type represents may be one of the following:

  • An image denoted by a CSS <uri> data type and the url() function;
  • A CSS <gradient>;
  • A part of the page, defined by the element() function.

Examples

These are valid image values:

url(test.jpg)                          The url() function, as long as test.jpg is an image
linear-gradient(to bottom, blue, red)  A <gradient>
element(#colonne3)                     A part of the page, used with the element() function,
                                       if colonne3 is an existing CSS id on the page.

These are invalid image values:

cervin.jpg                             An image file must be defined using the url() function.
url(report.pdf)                        The file pointed by the url() function must be an image.
element(#fakeid)                       If fakeid is not an existing CSS id on the page

Specifications

Specification Status Comment
CSS Image Values and Replaced Content Module Level 3 Candidate Recommendation Before CSS3, there wasn't an explicitly-defined <image> data type. Images could only be defined using the url() functional notations.

Browser compatibility

Feature Firefox (Gecko) Chrome Internet Explorer Opera Safari
<uri> (Yes) (Yes) (Yes) (Yes) (Yes)
<gradient> (Yes)
limited to background-image & background-moz
(Yes)-webkit IE 10-ms (Yes)-o (Yes)-webkit
element() 4.0 (2.0) limited to background-image & background-moz ? ? ? ?
Feature Firefox Mobile (Gecko) Android IE Phone Opera Mobile Safari Mobile
<uri> (Yes) (Yes) (Yes) (Yes) (Yes)
<gradient> (Yes)
limited to background-image & background-moz
? ? ? ?
element() 4.0 (2.0) limited to background-image & background-moz ? ? ? ?

See also

Document Tags and Contributors

Contributors to this page: Sheppy, Rob W, teoli, kscarfone, FredB, brianloveswords
Last updated by: kscarfone,
Hide Sidebar