<image>

  • Revision slug: Web/CSS/image
  • Revision title: image
  • Revision id: 462035
  • Created:
  • Creator: FredB
  • Is current revision? No
  • Comment

Revision Content

{{ CSSRef() }}

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 {{ cssxref("width") }}, {{ cssxref("height") }} or {{ cssxref("background-size") }}, and the default object size defined by the kind of property the image is used with:

Kind of object Default object size
{{ cssxref("background-image") }} The size of the element's background positioning area
{{ cssxref("list-style-image") }} The size of a character of 1em
{{ cssxref("border-image") }} The size of the element's border image area
{{ cssxref("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 {{ cssxref("content") }} property
in combination with the CSS pseudo-elements {{ cssxref("::after") }} and {{ cssxref("::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 {{ cssxref("background-image") }}, {{ cssxref("border-image") }}, {{ cssxref("content") }}, {{ cssxref("list-style-image") }} or {{ cssxref("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 {{ xref_cssuri() }} data type and the url() function;
  • A CSS {{ xref_cssgradient() }};
  • A part of the page, defined by the {{ cssxref("element", "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
{{ SpecName('CSS3 Images', '#image-notation', 'image()') }} {{ Spec2('CSS3 Images') }} Before CSS3, there wasn't an explicitly-defined <image> data type. Images could only be defined using the url() functional notations.

Browser compatibility

{{ CompatibilityTable() }}

Feature Firefox (Gecko) Chrome Internet Explorer Opera Safari
<uri> {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }}
<gradient> {{ compatVersionUnknown() }}
limited to {{ cssxref("background-image") }} & {{ cssxref("background") }}{{ property_prefix("-moz") }}
{{ compatVersionUnknown() }}{{ property_prefix("-webkit") }} IE 10{{ property_prefix("-ms") }} {{ compatVersionUnknown() }}{{ property_prefix("-o") }} {{ compatVersionUnknown() }}{{ property_prefix("-webkit") }}
element() 4.0 (2.0) limited to {{ cssxref("background-image") }} & {{ cssxref("background") }}{{ property_prefix("-moz") }} {{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }}
Feature Firefox Mobile (Gecko) Android IE Phone Opera Mobile Safari Mobile
<uri> {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }} {{ compatVersionUnknown() }}
<gradient> {{ compatVersionUnknown() }}
limited to {{ cssxref("background-image") }} & {{ cssxref("background") }}{{ property_prefix("-moz") }}
{{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }}
element() 4.0 (2.0) limited to {{ cssxref("background-image") }} & {{ cssxref("background") }}{{ property_prefix("-moz") }} {{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }} {{ compatUnknown() }}

See also

Revision Source

<p>{{ CSSRef() }}</p>
<h2 id="Summary">Summary</h2>
<p>The <code>&lt;image&gt;</code> <a href="/en/CSS" title="CSS">CSS</a> 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.</p>
<p>CSS can handle different kinds of images:</p>
<ul>
  <li>images with <em>intrinsic dimensions</em>, that is a natural size, like a jpeg image which has a fixed dimensions.</li>
  <li>images with <em>several intrinsic dimensions</em>, 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.</li>
  <li>images with no intrinsic dimensions but with <em>an intrinsic aspect ratio</em>, between its width and height, like some vectorized images, in the SVG format for example.</li>
  <li>images with <em><a name="no_intrinsic">neither intrinsic dimensions</a>, nor an intrinsic aspect ratio</em>, like a CSS gradient for example.</li>
</ul>
<p>CSS determines the <em>concrete object size</em> using these <em>intrinsic dimensions</em>, the <em>specified size </em>defined by CSS properties like {{ cssxref("width") }}, {{ cssxref("height") }} or {{ cssxref("background-size") }}, and the <em>default object size</em> defined by the kind of property the image is used with:</p>
<table class="standard-table">
  <thead>
    <tr>
      <th>Kind of object</th>
      <th>Default object size</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{ cssxref("background-image") }}</td>
      <td>The size of the element's background positioning area</td>
    </tr>
    <tr>
      <td>{{ cssxref("list-style-image") }}</td>
      <td>The size of a character of <code>1em</code></td>
    </tr>
    <tr>
      <td>{{ cssxref("border-image") }}</td>
      <td>The size of the element's border image area</td>
    </tr>
    <tr>
      <td>{{ cssxref("cursor") }}</td>
      <td>A browser-defined size matching the usual size of a cursor on the used system</td>
    </tr>
    <tr>
      <td>Replaced content<br />
        like with the combination of the CSS {{ cssxref("content") }} property<br />
        in combination with the CSS pseudo-elements {{ cssxref("::after") }} and {{ cssxref("::before") }}</td>
      <td>A <code>300px</code><code> × 150px</code> rectangle</td>
    </tr>
  </tbody>
</table>
<p>The concrete object size is calculated using the following algorithm:</p>
<ul>
  <li>If the specified size defines both the width and the height, these values are used as the concrete object size.</li>
  <li>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.</li>
  <li>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.</li>
</ul>
<p>Images can be used with numerous CSS properties like {{ cssxref("background-image") }}, {{ cssxref("border-image") }}, {{ cssxref("content") }}, {{ cssxref("list-style-image") }} or {{ cssxref("cursor") }}.</p>
<div class="note">
  <strong>Note:</strong>&nbsp;Not all browsers support any type of images on any property. See the <a href="/en/CSS/image#Browser_compatibility" title="https://developer.mozilla.org/en/CSS/image#Browser_compatibility">browser compatibility section</a> for a comprehensive list.</div>
<h2 class="note" id="Syntax">Syntax</h2>
<p>An <code>&lt;image&gt;</code> CSS data type represents may be one of the following:</p>
<ul>
  <li>An image denoted by a CSS {{ xref_cssuri() }} data type and the <code>url()</code> function;</li>
  <li>A CSS {{ xref_cssgradient() }};</li>
  <li>A part of the page, defined by the {{ cssxref("element", "element()") }} function.</li>
</ul>
<h2 id="Examples">Examples</h2>
<p>These are valid image values:</p>
<pre>
url(test.jpg)&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The url() function, as long as test.jpg is an image
linear-gradient(to bottom, blue, red)&nbsp; A &lt;gradient&gt;
element(#colonne3)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; A part of the page, used with the element() function,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if colonne3 is an existing CSS id on the page.
</pre>
<p>These are invalid image values:</p>
<pre>
cervin.jpg&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; An image file must be defined using the url() function.
url(report.pdf)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;  The file pointed by the url() function must be an image.
element(#fakeid)                       If fakeid is not an existing CSS id on the page
</pre>
<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{ SpecName('CSS3 Images', '#image-notation', 'image()') }}</td>
      <td>{{ Spec2('CSS3 Images') }}</td>
      <td>Before <a href="/en-US/docs/Web/CSS/CSS3" title="CSS3">CSS3</a>, there wasn't an explicitly-defined <code>&lt;image&gt;</code> data type. Images could only be defined using the <code>url()</code> functional notations.</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Firefox (Gecko)</th>
        <th>Chrome</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td><code>&lt;uri&gt;</code></td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
      </tr>
      <tr>
        <td><code>&lt;gradient&gt;</code></td>
        <td>{{ compatVersionUnknown() }}<br />
          limited to {{ cssxref("background-image") }} &amp; {{ cssxref("background") }}{{ property_prefix("-moz") }}</td>
        <td>{{ compatVersionUnknown() }}{{ property_prefix("-webkit") }}</td>
        <td>IE 10{{ property_prefix("-ms") }}</td>
        <td>{{ compatVersionUnknown() }}{{ property_prefix("-o") }}</td>
        <td>{{ compatVersionUnknown() }}{{ property_prefix("-webkit") }}</td>
      </tr>
      <tr>
        <td><code>element()</code></td>
        <td>4.0 (2.0) limited to {{ cssxref("background-image") }} &amp; {{ cssxref("background") }}{{ property_prefix("-moz") }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>Android</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td><code>&lt;uri&gt;</code></td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
        <td>{{ compatVersionUnknown() }}</td>
      </tr>
      <tr>
        <td><code>&lt;gradient&gt;</code></td>
        <td>{{ compatVersionUnknown() }}<br />
          limited to {{ cssxref("background-image") }} &amp; {{ cssxref("background") }}{{ property_prefix("-moz") }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
      </tr>
      <tr>
        <td><code>element()</code></td>
        <td>4.0 (2.0) limited to {{ cssxref("background-image") }} &amp; {{ cssxref("background") }}{{ property_prefix("-moz") }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
        <td>{{ compatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en/CSS/CSS_Reference" title="CSS Reference">CSS Reference</a></li>
  <li><a href="/en/CSS/Using_CSS_gradients" title="Using gradients">Using CSS gradients</a>, {{ xref_cssgradient() }}, <a href="/en/CSS/linear-gradient" title="linear-gradient"><code>linear-gradient()</code></a>, <a href="/en/CSS/radial-gradient" title="radial-gradient"><code>radial-gradient()</code></a>, <a href="/en/CSS/repeating-linear-gradient" title="repeating-linear-gradient"><code>repeating-linear-gradient()</code></a>, <a href="/en/CSS/repeating-radial-gradient" title="repeating-radial-gradient"><code>repeating-radial-gradient()</code></a>;</li>
  <li><a href="/en/CSS/element" title="en/CSS/element"><code>element()</code></a>;</li>
  <li>CSS Data Types: {{ CSSDataTypes() }}.</li>
</ul>
Revert to this revision