The background-size
CSS property sets the size of the element's background image. The image can be left to its natural size, stretched, or constrained to fit the available space.
Spaces not covered by a background image are filled with the background-color
property, and the background color will be visible behind background images that have transparency/translucency.
/* Keyword values */ background-size: cover; background-size: contain; /* One-value syntax */ /* the width of the image (height becomes 'auto') */ background-size: 50%; background-size: 3.2em; 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 */ background-size: auto, auto; /* Not to be confused with `auto auto` */ background-size: 50%, 25%, 25%; background-size: 6px, auto, contain; /* Global values */ background-size: inherit; background-size: initial; background-size: unset;
The background-size
property is specified in one of the following ways:
contain
or cover
.auto
.
<length>
, a <percentage>
, or auto
.To specify the size of multiple background images, separate the value for each one with a comma.
contain
cover
auto
<length>
<percentage>
background-origin
(by default, the padding box). However, if the background's background-attachment
value is fixed
, the positioning area is instead the entire viewport. Negative values are not allowed.The computation of values depends on the image's intrinsic dimensions (width and height) and intrinsic proportions (width-to-height ratio). These attributes are as follows:
<gradient>
s have no intrinsic dimensions or intrinsic proportions.element()
function use the intrinsic dimensions and proportions of the generating element.Note: The behavior of <gradient>
s changed in Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5). Before this, they were treated as images with no intrinsic dimensions, but with intrinsic proportions identical to that of the background positioning area.
Note: In Gecko, background images created using the element()
function 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 non-standard behavior.
Based on the intrinsic dimensions and proportions, the rendered size of the background image is computed as follows:
background-size
are specified and are not auto
:background-size
is contain
or cover
:background-size
is auto
or auto auto
:contain
had been specified instead.preserveAspectRatio
attribute that defaults to the equivalent of contain
. In Firefox 43, as opposed to Chrome 52, an explicit background-size
causes preserveAspectRatio
to be ignored.background-size
has one auto
component and one non-auto
component:Note: Background sizing for vector images that lack intrinsic dimensions or proportions is not yet fully implemented in all browsers. Be careful about relying on the behavior described above, and test in multiple browsers to be sure the results are acceptable.
<bg-size>#where
<bg-size> = [ <length-percentage> | auto ]{1,2} | cover | containwhere
<length-percentage> = <length> | <percentage>
Please see Scaling background images for examples.
If you use a <gradient>
as the background and specify 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 <gradient>
s in such cases changed in Firefox 8, and at present 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.
.gradient-example { width: 50px; height: 100px; background-image: linear-gradient(blue, red); /* Not safe to use */ background-size: 25px; background-size: 50%; background-size: auto 50px; background-size: auto 50%; /* Safe to use */ 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.
Specification | Status | Comment |
---|---|---|
CSS Backgrounds and Borders Module Level 3 The definition of 'background-size' in that specification. | Candidate Recommendation | Initial definition. |
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 | repeatable list of simple list of length, percentage, or calc |
Canonical order | the unique non-ambiguous order defined by the formal grammar |
Desktop | ||||||
---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | |
Basic support | 3
|
12 | 4
|
9 | 10
|
4.1
|
contain and cover
|
3 | 12 | 3.6 | 9 | 10 | 4.1 |
SVG image as background | 44 | 12 | 8 | 9 | 31 | ? |
Mobile | |||||||
---|---|---|---|---|---|---|---|
Android webview | Chrome for Android | Edge Mobile | Firefox for Android | Opera for Android | iOS Safari | Samsung Internet | |
Basic support | 2.3
|
Yes
|
Yes | 4
|
Yes | Yes | Yes |
contain and cover
|
? | ? | Yes | Yes | ? | Yes | ? |
SVG image as background | ? | ? | Yes | 8 | Yes | ? | ? |
© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/CSS/background-size