CSS - background-size
The background-size
CSS property specifies the size of the background images. The size of the image can be fully constrained or only partially in order to preserve its intrinsic ratio.
Example
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.
Syntax
/* Keywords syntax */ background-size: cover; background-size: contain; /* One-value syntax */ /* the width of the image (height set to 'auto') */ background-size: 50%; background-size: 3em; background-size: 12px; background-size: auto; /* Two-value syntax */ /* first value: width of the image, second value: height */ background-size: 50% auto; background-size: 3em 25%; background-size: auto 6px; background-size: auto auto; /* Multiple backgrounds values by background-image */ /* Do not confuse this with background-size: auto auto */ background-size: auto, auto; background-size: 50%, 25%, 25%; background-size: 6px, auto, contain; /* Global values */ background-size: inherit; background-size: initial; background-size: unset;
Values
<length>
- A
value that scales the background image to the specified length in the corresponding dimension. Negative lengths are not allowed.<length>
<percentage>
- A
<percentage>
value that scales the background image in the corresponding dimension to the specified percentage of the background positioning area, which is determined by the value ofbackground-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'sattachment
isfixed
, the background positioning area is instead the entire area of the browser window, not including the area covered by scrollbars if they are present. Negative percentages are not allowed. auto
- A keyword that scales the background image in the corresponding direction such that its intrinsic proportion is maintained.
contain
- A keyword that scales the image as large as possible and maintains image aspect ratio (image doesn't get squished). Image is letterboxed within the container. When the image and container have different dimensions, the empty areas (either top/bottom of left/right) are filled with the background-color. The image is automatically centered unless over-ridden by another property such as background-position.
cover
- A keyword that is the inverse of
contain
. Scales the image as large as possible and maintains image aspect ratio (image doesn't get squished). The image "covers" the entire width or height of the container. When the image and container have different dimensions, the image is clipped either left/right or top/bottom.
The 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 dimensions, 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.
Note: This behavior changed in Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5). Before this, 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.
The rendered size of the background image is then computed as follows:
- If both components of
background-size
are specified and are notauto
: - The background image renders at the specified size.
- If the
background-size
iscontain
orcover
: - 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
isauto
orauto 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.Note: SVG images have a preserveAspectRatio attribute which defaults to the equivalent of 'contain'. On Firefox 43, as opposed to Chrome 52, an explicit background-size causes preserveAspectRatio to be ignored. - 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.
Note that background sizing for vector images that lack intrinsic dimensions or proportion is not yet fully implemented in all browsers. Be careful about relying on the behavior described above, and test in multiple browsers (specifically including versions of Firefox 7 or earlier and Firefox 8 or greater) to be sure different renderings are acceptable.
Formal syntax
<a href="css/background-size#bg-size"><bg-size></a><a href="css/value_definition_syntax#hash_mark_(.23)" title="Hash mark">#</a><p>where <br><code><bg-size> = <a href="css/value_definition_syntax#brackets" title="Brackets">[</a> <a href="css/background-size#length-percentage"><length-percentage></a> <a href="css/value_definition_syntax#single_bar" title="Single bar">|</a> auto <a href="css/value_definition_syntax#brackets" title="Brackets">]</a><a href="css/value_definition_syntax#curly_braces_(.7b_.7d)" title="Curly braces">{</a>1,2<a href="css/value_definition_syntax#curly_braces_(.7b_.7d)" title="Curly braces">}</a> <a href="css/value_definition_syntax#single_bar" title="Single bar">|</a> cover <a href="css/value_definition_syntax#single_bar" title="Single bar">|</a> contain</code></p><p>where <br><code><length-percentage> = <a href="css/length" title="Possible values: a number followed by'em', 'ex', 'ch', 'rem', 'px', 'cm', 'mm', 'in', 'vh', 'vw', 'vmin', 'vmax', 'pt', 'pc' or 'px', like 3px, 1.5cm, -0.5em or 0"><length></a> <a href="css/value_definition_syntax#single_bar" title="Single bar">|</a> <a href="css/percentage" title=""><percentage></a></code></p>
Description
The background-size
CSS property specifies the size of the background images. The size of the image can be fully constrained or only partially in order to preserve its intrinsic ratio.
background
shorthand property that is applied to the element after the background-size
CSS property, the value of this property is then reset to its initial value by the shorthand property.Initial value | auto auto |
---|---|
Applies to | all elements. It also applies to ::first-letter and ::first-line . |
Inherited | no |
Percentages | relative to the background positioning area |
Media | visual |
Computed value | as specified, but with relative lengths converted into absolute lengths |
Animation type | a repeatable list of , a simple list of , a length, percentage or calc();, keywords |
Canonical order | the unique non-ambiguous order defined by the formal grammar |
Browser Compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 1.0-webkit[1] 3.0 |
3.6 (1.9.2)-moz[2] 4.0 (2.0)[3] |
9.0[4] | 9.5-o[5] 10.0 |
3.0 (522)-webkit[1] 4.1 (532) |
Support forcontain and cover |
3.0 | 3.6 (1.9.2) | 9.0[4] | 10.0 | 4.1 (532) |
Support for SVG backgrounds | 44.0 | 8.0 (8.0) | 9.0 | 31.0 | ? |
Feature | Android | Firefox Mobile (Gecko) | Windows Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | (Yes)-webkit 2.3 |
1.0-moz 4.0[3] |
? | ? | 5.1 (maybe earlier) |
Support for SVG backgrounds | ? | 8.0 (8.0) | ? | ? | ? |
[1] WebKit-based browsers originally implemented 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.
[2] While this property is new in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0), it is possible to stretch a image fully over the background in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0) by using -moz-border-image
.
.foo { background-image: url(bg-image.png); -webkit-background-size: 100% 100%; /* Safari 3.0 */ -moz-background-size: 100% 100%; /* Gecko 1.9.2 (Firefox 3.6) */ -o-background-size: 100% 100%; /* Opera 9.5 */ 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) */ }
[3] In addition to the unprefixed support, Gecko 44.0 (Firefox 44.0 / Thunderbird 44.0 / SeaMonkey 2.41) added support for a -webkit
prefixed version of the property for web compatibility reasons behind the preference layout.css.prefixes.webkit
, defaulting to false
. Since Gecko 49.0 (Firefox 49.0 / Thunderbird 49.0 / SeaMonkey 2.46) the preference defaults to true
.
[4] Though Internet Explorer 8 doesn't support the background-size
property, it is possible to emulate some of its functionality using the non-standard -ms-filter
property:
-ms-filter: "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='path_relative_to_the_HTML_file', sizingMethod='scale')";
This simulates the value cover
.
[5] 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. This has been fixed in Opera 10.
Notes
If you are specifying a gradient as background and have specified a background-size
to go with it, it's best not to specify a size that uses a single auto component, or is specified using only a width value (for example, background-size: 50%
). Rendering of gradients in such cases changed in Firefox 8, and at present it is generally inconsistent across browsers, which do not all implement rendering in full accordance with the CSS3 background-size
specification and with the CSS3 Image Values gradient specification.
.bar { width: 50px; height: 100px; background-image: gradient(...); /* NOT RECOMMENDED */ background-size: 25px; background-size: 50%; background-size: auto 50px; background-size: auto 50%; /* OKAY */ background-size: 25px 50px; background-size: 50% 50%; }
Note that it's particularly not recommended to use a pixel dimension and an auto
dimension with a gradient, because it's impossible to replicate rendering in versions of Firefox prior to 8, and in browsers not implementing Firefox 8's rendering, without knowing the exact size of the element whose background is being specified.
See Also
Specifications
Specification | Status | Comment |
---|---|---|
CSS Backgrounds and Borders Module Level 3 The definition of 'background-size' in that specification. |
Candidate Recommendation | Initial definition |
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/css/background-size