background-size

  • Revision slug: CSS/background-size
  • Revision title: background-size
  • Revision id: 15093
  • Created:
  • Creator: Waldo
  • Is current revision? No
  • Comment merge multiple definition lists into one; one or more formatting changes

Revision Content

Summary

The background-size CSS property specifies the size of the background images.

  • {{ Xref_cssinitial() }}: auto
  • Applies to: all elements
  • {{ Xref_cssinherited() }}: no
  • Percentages: see below
  • Media: {{ Xref_cssvisual() }}
  • {{ Xref_csscomputed() }}: for <length> the absolute value, otherwise a percentage

Syntax

background-size:  <bg-size>[, <bg-size>]*        /* Gecko 2.0 (Firefox 4.0) and later */

Where <bg-size> is one of:

  • [ {{ Xref_csspercentage() }}| {{ Xref_csslength() }}| auto ]
    [ {{ Xref_csspercentage() }}| {{ Xref_csslength() }}| auto ] ?
  • contain
  • cover

Multiple values apply to individual background layers, from front to back, in the same manner as for all other background properties.

Values

<percentage>
Scales the background image in the desired dimension to the specified percentage of the background positioning area, which is determined by the value of {{ cssxref("background-origin") }}. The background positioning area is, by default, the area containing the content of the box and its padding; the area may also be changed to just the content or to the area containing borders, padding, and content. If the background's {{ cssxref("background-attachment","attachment") }} is fixed, the background positioning area is instead the entire area of the browser window, not including the area covered by scrollbars if they are present.
<length>
Scales the background image to the specified length in the desired dimension.
auto
Scales the background image in the relevant direction such that its intrinsic proportion is maintained.

The first value determines how the image is scaled horizontally, the second how it is scaled vertically. If only one value is specified, the second value is implicitly auto.  Negative sizes are not allowed.

contain
Specifies that the background image should be scaled to be as large as possible while ensuring both its dimensions are less than or equal to the corresponding dimensions of the background positioning area.
cover
Specifies that the background image should be scaled to be as small as possible while ensuring both its dimensions are greater than or equal to the corresponding dimensions of the background positioning area.

Interpretation of possible values depends on the image's intrinsic dimensions (width and height) and intrinsic proportion (ratio of width and height).  A bitmap image always has intrinsic dimensions and an intrinsic proportion.  A vector image may have both intrinsic dimensions (and thus must have an intrinsic proportion).  It also may have one or no intrinsic dimension, and in either case it might or might not have an intrinsic proportion.  Gradients are treated as images with no intrinsic dimensions or intrinsic proportion.  (This behavior changed in Firefox 8: prior to Firefox 8, gradients were treated as images with no intrinsic dimensions, with an intrinsic proportion identical to that of the background positioning area.)  Background images generated from elements using -moz-element (which actually match an element) are currently treated as images with the dimensions of the element, or of the background positioning area if the element is SVG, with the corresponding intrinsic proportion.  (This is not the currently specified behavior, which is that the intrinsic dimensions and proportion should be those of the element in all cases.)

The rendered size of the background image is then computed as follows:

If both components of background-size are specified and are not auto:
The background image renders at the specified size.
If the background-size is contain or cover:
The image is rendered, preserving its intrinsic proportion, at the largest size contained within, or covering, the background positioning area.  If the image has no intrinsic proportion, then it is rendered at the size of the background positioning area.
If the background-size is auto or auto auto:
If the image has both intrinsic dimensions, it is rendered at that size.  If it has no intrinsic dimensions and no intrinsic proportion, it is rendered at the size of the background positioning area.  If it has no dimensions but has a proportion, it's rendered as if contain had been specified instead.  If the image has one intrinsic dimension and a proportion, it's rendered at the size determined by that one dimension and the proportion.  If the image has one intrinsic dimension but no proportion, it's rendered using the intrinsic dimension and the corresponding dimension of the background positioning area.
If the background-size has one auto component and one non-auto component:
If the image has an intrinsic proportion, then render it using the specified dimension, and compute the other dimension from the specified dimension and the intrinsic proportion.  If the image has no intrinsic proportion, use the specified dimension for that dimension.  For the other dimension, use the image's corresponding intrinsic dimension if there is one.  If there is no such intrinsic dimension, use the corresponding dimension of the background positioning area.

Examples

This demonstration of background-size: cover and this demonstration of background-size: contain are meant to be opened in new windows so that you can see how contain and cover behave when the background positioning area's dimensions vary. This series of demos of how background-size works and interacts with other background-* properties should pretty much cover the remaining ground in how to use background-size alone and in conjunction with other properties.

Notes

While this property is new in Gecko 1.9.2 (Firefox 3.6), it is possible to stretch a image fully over the background in Firefox 3.5 by using {{ cssxref("-moz-border-image") }}.

.foo {
        background-image: url(bg-image.png);

       -moz-background-size: 100% 100%;           /* Gecko 1.9.2 (Firefox 3.6) */
         -o-background-size: 100% 100%;           /* Opera 9.5 */
    -webkit-background-size: 100% 100%;           /* Safari 3.0 */
            background-size: 100% 100%;           /* Gecko 2.0 (Firefox 4.0) and other CSS3-compliant browsers */
 
       -moz-border-image: url(bg-image.png) 0;    /* Gecko 1.9.1 (Firefox 3.5) */
}

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 1.0{{ property_prefix("-webkit") }} {{ CompatGeckoDesktop("1.9.2") }}{{ property_prefix("-moz") }} 9.0 9.5{{ property_prefix("-o") }}
with some bugs (see below)
3.0 (522){{ property_prefix("-webkit") }}
but from an older CSS3 draft (see below)
3.0 {{ CompatGeckoDesktop("2.0") }} 10.0
Support for
contain | cover
3.0 {{ CompatGeckoDesktop("1.9.2") }} 9.0 10.0 4.1 (532)
Feature Android Firefox Mobile (Gecko) Windows Phone Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
  • As of July 2009, Opera 9.5's computation of the background positioning area is incorrect for fixed backgrounds.  Opera 9.5 also interprets the two-value form as a horizontal scaling factor and, from appearances, a vertical clipping dimension.
  • WebKit-based browsers as of July 2009 implement an older draft of CSS3 background-size in which an omitted second value is treated as duplicating the first value; this draft does not include the contain or cover keywords.
  • Konqueror 3.5.4 supports -khtml-background-size.
  • -moz-background-size is no longer supported in Gecko 2.0; you must use background-size instead.

Specifications

See also

  • {{ CSS_Reference:Background() }}
  • {{ cssxref("-moz-background-origin") }}, {{ cssxref("-moz-background-clip") }}
  • Multiple backgrounds

{{ languages( { "ja": "ja/CSS/-moz-background-size" } ) }}

Revision Source

<h3>Summary</h3>
<p>The<code> background-size </code>CSS property specifies the size of the background images.</p>
<ul> <li>{{ Xref_cssinitial() }}:<code> auto</code></li> <li>Applies to: all elements</li> <li>{{ Xref_cssinherited() }}: no</li> <li>Percentages: see below</li> <li>Media: {{ Xref_cssvisual() }}</li> <li>{{ Xref_csscomputed() }}: for &lt;length&gt; the absolute value, otherwise a percentage</li>
</ul>
<h3>Syntax</h3>
<pre>background-size:  &lt;bg-size&gt;[, &lt;bg-size&gt;]*        /* Gecko 2.0 (Firefox 4.0) and later */</pre>
<p>Where <strong>&lt;bg-size&gt;</strong> is one of:</p>
<ul> <li><code>[ {{ Xref_csspercentage() }}| {{ Xref_csslength() }}| auto ]<br> [ {{ Xref_csspercentage() }}| {{ Xref_csslength() }}| auto ] ?</code></li> <li><code>contain<br> </code></li> <li><code>cover</code></li>
</ul>
<p>Multiple values apply to individual background layers, from front to back, in the same manner as for all other background properties.</p>
<h3>Values</h3>
<dl> <dt>&lt;percentage&gt;</dt> <dd>Scales the background image in the desired dimension to the specified percentage of the background positioning area, which is determined by the value of {{ cssxref("background-origin") }}. The background positioning area is, by default, the area containing the content of the box and its padding; the area may also be changed to just the content or to the area containing borders, padding, and content. If the background's {{ cssxref("background-attachment","attachment") }} is<code> fixed</code>, the background positioning area is instead the entire area of the browser window, not including the area covered by scrollbars if they are present.</dd> <dt>&lt;length&gt;</dt> <dd>Scales the background image to the specified length in the desired dimension.</dd> <dt>auto</dt> <dd>Scales the background image in the relevant direction such that its intrinsic proportion is maintained.</dd>
</dl>
<p>The first value determines how the image is scaled horizontally, the second how it is scaled vertically. If only one value is specified, the second value is implicitly<code> auto</code>.  Negative sizes are not allowed.</p>
<dl> <dt>contain</dt> <dd>Specifies that the background image should be scaled to be as large as possible while ensuring both its dimensions are less than or equal to the corresponding dimensions of the background positioning area.</dd> <dt>cover</dt> <dd>Specifies that the background image should be scaled to be as small as possible while ensuring both its dimensions are greater than or equal to the corresponding dimensions of the background positioning area.</dd>
</dl>
<p>Interpretation of possible values depends on the image's intrinsic dimensions (width and height) and intrinsic proportion (ratio of width and height).  A bitmap image always has intrinsic dimensions and an intrinsic proportion.  A vector image may have both intrinsic dimensions (and thus must have an intrinsic proportion).  It also may have one or no intrinsic dimension, and in either case it might or might not have an intrinsic proportion.  Gradients are treated as images with no intrinsic dimensions or intrinsic proportion.  (This behavior changed in Firefox 8: prior to Firefox 8, gradients were treated as images with no intrinsic dimensions, with an intrinsic proportion identical to that of the background positioning area.)  Background images generated from elements using -moz-element (which actually match an element) are currently treated as images with the dimensions of the element, or of the background positioning area if the element is SVG, with the corresponding intrinsic proportion.  (This is not the currently specified behavior, which is that the intrinsic dimensions and proportion should be those of the element in all cases.)</p>
<p>The rendered size of the background image is then computed as follows:</p>
<dl> <dt>If both components of <code>background-size</code> are specified and are not <code>auto</code>:</dt> <dd>The background image renders at the specified size.</dd> <dt>If the <code>background-size</code> is <code>contain</code> or <code>cover</code>:</dt> <dd>The image is rendered, preserving its intrinsic proportion, at the largest size contained within, or covering, the background positioning area.  If the image has no intrinsic proportion, then it is rendered at the size of the background positioning area.</dd> <dt>If the <code>background-size</code> is <code>auto</code> or <code>auto auto</code>:</dt> <dd>If the image has both intrinsic dimensions, it is rendered at that size.  If it has no intrinsic dimensions and no intrinsic proportion, it is rendered at the size of the background positioning area.  If it has no dimensions but has a proportion, it's rendered as if <code>contain</code> had been specified instead.  If the image has one intrinsic dimension and a proportion, it's rendered at the size determined by that one dimension and the proportion.  If the image has one intrinsic dimension but no proportion, it's rendered using the intrinsic dimension and the corresponding dimension of the background positioning area.</dd> <dt>If the background-size has one <code>auto</code> component and one non-<code>auto</code> component:</dt> <dd>If the image has an intrinsic proportion, then render it using the specified dimension, and compute the other dimension from the specified dimension and the intrinsic proportion.  If the image has no intrinsic proportion, use the specified dimension for that dimension.  For the other dimension, use the image's corresponding intrinsic dimension if there is one.  If there is no such intrinsic dimension, use the corresponding dimension of the background positioning area.</dd>
</dl><h3>Examples</h3>
<p><a class=" external" href="http://whereswalden.com/files/mozilla/background-size/page-cover.html" target="_blank">This demonstration of <code>background-size: cover</code></a> and <a class=" external" href="http://whereswalden.com/files/mozilla/background-size/page-contain.html" target="_blank">this demonstration of <code>background-size: contain</code></a> are meant to be opened in new windows so that you can see how <code>contain</code> and <code>cover</code> behave when the background positioning area's dimensions vary. <a class=" external" href="http://whereswalden.com/files/mozilla/background-size/more-examples.html">This series of demos of how <code>background-size</code> works and interacts with other <code>background-*</code> properties</a> should pretty much cover the remaining ground in how to use <code>background-size</code> alone and in conjunction with other properties.</p>
<h3>Notes</h3>
<p>While this property is new in Gecko 1.9.2 (Firefox 3.6), it is possible to stretch a image fully over the background in Firefox 3.5 by using {{ cssxref("-moz-border-image") }}.</p>
<pre class="brush: css">.foo {
        background-image: url(bg-image.png);

       -moz-background-size: 100% 100%;           /* Gecko 1.9.2 (Firefox 3.6) */
         -o-background-size: 100% 100%;           /* Opera 9.5 */
    -webkit-background-size: 100% 100%;           /* Safari 3.0 */
            background-size: 100% 100%;           /* Gecko 2.0 (Firefox 4.0) and other CSS3-compliant browsers */
 
       -moz-border-image: url(bg-image.png) 0;    /* Gecko 1.9.1 (Firefox 3.5) */
}
</pre>
<h3 name="Browser_Compatibility">Browser compatibility</h3>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
<table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari (WebKit)</th> </tr> <tr> <td rowspan="2">Basic support</td> <td>1.0{{ property_prefix("-webkit") }}</td> <td>{{ CompatGeckoDesktop("1.9.2") }}{{ property_prefix("-moz") }}</td> <td rowspan="2">9.0</td> <td>9.5{{ property_prefix("-o") }}<br> with some bugs (see below)</td> <td rowspan="2">3.0 (522){{ property_prefix("-webkit") }}<br> but from an older CSS3 draft (see below)</td> </tr> <tr> <td>3.0</td> <td>{{ CompatGeckoDesktop("2.0") }}</td> <td>10.0</td> </tr> <tr> <td>Support for<br> <code>contain | cover</code></td> <td>3.0</td> <td>{{ CompatGeckoDesktop("1.9.2") }}</td> <td>9.0</td> <td>10.0</td> <td>4.1 (532)</td> </tr> </tbody>
</table>
</div>
<div id="compat-mobile">
<table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>Windows Phone</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody>
</table>
</div>
<ul> <li>As of July 2009, Opera 9.5's computation of the background positioning area is incorrect for fixed backgrounds.  Opera 9.5 also interprets the two-value form as a horizontal scaling factor and, from appearances, a vertical <em>clipping</em> dimension.</li> <li>WebKit-based browsers as of July 2009 implement an older draft of CSS3<code> background-size </code>in which an omitted second value is treated as <em>duplicating</em> the first value; this draft does not include the<code> contain </code>or<code> cover </code>keywords.</li> <li>Konqueror 3.5.4 supports<code> -khtml-background-size</code>.</li> <li><code>-moz-background-size</code> is no longer supported in Gecko 2.0; you must use <code>background-size</code> instead.</li>
</ul><h3>Specifications</h3>
<ul> <li><a class="external" href="http://www.w3.org/TR/css3-background/#the-background-size" title="http://www.w3.org/TR/css3-background/#the-background-size">CSS 3 Backgrounds and borders #background-size</a></li>
</ul>
<h3>See also</h3>
<ul> <li>{{ CSS_Reference:Background() }}</li> <li>{{ cssxref("-moz-background-origin") }}, {{ cssxref("-moz-background-clip") }}</li> <li><a href="/en/CSS/Multiple_backgrounds" title="en/CSS/Multiple backgrounds">Multiple backgrounds</a></li>
</ul>
<p>{{ languages( { "ja": "ja/CSS/-moz-background-size" } ) }}</p>
Revert to this revision