CSS Reference Property

background-size

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:

View this demo on the Codrops Playground

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 the background-origin property is set by the author, it has the value of padding-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 to auto, 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 Playground

Browser 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

Mobile / Tablet

* denotes prefix required.

Supported:
Yes
No
Partially
Polyfill

Stats from caniuse.com