The background-size
property is used to specify the size of background images.
The background image can be set to cover the element’s entire background area or have definite dimensions defined by the CSS author.
A background image can be set to cover the entire element’s background area using the cover
keyword. It can also be set to be as big as possible while being contained within the background area using the contain
keyword. If any of these two keywords is used, the intrinsic ratio of the image’s height and width are preserved if the image has intrinsic dimensions and proportions.
Some <image>
s have intrinsic dimensions and proportions, such as JPEG images, for example, and other images such as <gradient>
s don’t have intrinsic dimensions and proportions and take up the size of the element’s background area unless specified otherwise (see values below). The final size of the background image is rendered depending on whether an image has intrinsic dimensions and proportions.
The background-size
property takes either a keyword value (cover
or contain
), or a pair of non-keyword values (<length>
| <percentage>
), or a non-keyword value and the value auto
. For example:
background-size: cover; /* keyword value */ background-size: contain; /* keyword value */ background-size: 100% 50%; /* pair of non-keyword values */ background-size: 300px 200px; /* pair of non-keyword values */ background-size: 50% auto; /* non-keyword value + the value 'auto' */
For pair values, the first value specifies the width of the image, and the second value specifies the height of the image.
If only one non-keyword value is specified, the other one is assumed to be auto
.
The background-size
property can also take comma-separated values so that when the element has more than one background image, each value is applied to a corresponding background image (first value for the first image, second value for the second image, and so on).
Click on one of the different background-size
values to see how the background rendering adjusts in the following interactive demo:
Trivia & Notes
The background-size
property can be used to create interesting and creative background patterns when combined with CSS gradients. You can read all about creating those patterns in CSS3 Patterns, Explained by Lea Verou on 24 ways.
Official Syntax
-
Syntax:
background-size: <bg-size> [ , <bg-size> ]* /* where */ <bg-size> = [ <length> | <percentage> | auto ]{1,2} | cover | contain
- Initial: auto
- Applies To: all elements
- Animatable: yes, except keyword values
Values
- <length>
-
A
<length>
value scales the background image to the specified value in the corresponding direction. Negative lengths are not allowed. - <percentage>
-
A percentage value scales the background image to the specified percentage value relative to the background positioning area, which is determined by the value of the
background-origin
property. Unless the value of thebackground-origin
property is set by the author, it has the value ofpadding-box
, which means that the background image is positioned with respect to a background coordinate system whose center is at the top left corner of the padding box. Negative percentage values are not allowed. - contain
- Scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the background positioning area. If the background image has no intrinsic proportion and no intrinsic dimension, then it is rendered at the size of the background positioning area.
- cover
- Scale the image, while preserving its intrinsic aspect ratio (if any), to the smallest size such that both its width and its height can completely cover the background positioning area. If the background image has no intrinsic proportion and no intrinsic dimension, then it is rendered at the size of the background positioning area.
- auto
-
The
auto
keyword that scales the background image in the corresponding direction such that its intrinsic proportion is maintained.- If the image has both intrinsic dimensions (height and width), it’s going to be rendered at its size.
- If the background image has no intrinsic proportion and no intrinsic dimension, then 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.
Notes
If the value of the background-size
property is a pair where one value is auto
and the other value is <length>
or <percentage>
then:
-
If the image has intrinsic proportions: Use the length/percentage value specified to render the image in the corresponding dimension, and then use the image’s proportions to calculate the value of the other dimension. So, if, for example, the first value is a length and second value is
auto
, then the width of the image will be rendered to the specified length, and the height of the image will be calculated based on the image’s proportions. -
If the image does not have an intrinsic proportion: Use the length/percentage value to render the image in the corresponding dimension. For the other direction (which gets the
auto
value), the browser will use the image’s dimension if it has one. For example, a JPEG image has two intrinsic dimensions (height and width), so if a height is set to a length value, and the width is set toauto
, the browser will extract that width from the image and use it, because it has one. But if the image does not have an intrinsic width (e.g. a gradient), the browser will render it to have the same dimension as the background positioning area.
The background-size
property can also inherit the value of the background size specified on its parent element by using the value inherit
. For example: background-size: inherit
.
Examples
The following are all valid syntaxes for the background-size
property.
/* keyword value syntax */ background-size: cover; background-size: contain; /* two-value syntax: first value specifies the width of the image and the second value specifies its height */ background-size: 50% auto; background-size: 50px 30px; background-size: 10em 12em; /* one-value syntax: the second value is always assumed to be 'auto' */ background-size: 32em; background-size: auto; background-size: 100%;
The following are all examples of background image sizes specified with the background-size
property. The image in this example is assumed to be one with intrinsic dimensions and proportions (a JPEG image, for example);
/* stretch the image to fill the background area ignoring image ratio */ background-size: 100% 100%; /* the background image is shown at its intrinsic size */ background-size: auto; /* default */ /* the background is shown with a width of 3em and its height is scaled proportionally to keep the original aspect ratio */ background-size: 3em; /* second value is assumed `auto` */ /* this one forces the background image to be 15px by 15px */ background-size: 15px 15px;
The following example stretches the image so that exactly two copies fit horizontally (notice the values of the background-repeat
property and the background-origin
property). The aspect ratio is preserved.
background-size: 50% auto; background-repeat: repeat; background-origin: border-box;
The following example specifies the background size of two background images. The first value specifies the size of the first image, and the second value specifies the size of the second image.
background-image: url(path/to/first/image.jpg), url(path/to/second/image.png); background-size: 100% 100%, contain;
The following example will force the size of the gradient image to 100px by 100px.
background: linear-gradient(left, white 50%, #8b0 50%); background-size: 100px 100px;
Live Demo
Change the values of the background-size
property in the following demo to see how it changes the rendering of the background image.
As you change the values, try resizing the screen and see how the background image responds to the element’s size.
View this demo on the Codrops PlaygroundBrowser Support
CSS3 Background-image options
New properties to affect background images, including background-clip, background-origin and background-size
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 15
- 4
- 9
- 10
- 7
Mobile / Tablet
- 7.0
- 4.4
- all
- 129
- 130