background-size property CSS Reference

---

Definition and Usage

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.

Note: If the value of this property is not set in a 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 auto auto
• Applies to all elements
• Inherited no
• Percentages relative to the background positioning area
• Media visual
• Computed Value as specified, with lengths made absolute
• Animatable yes, as a repeatable list of a simple list of a length, percentage or calc(); when both values are lengths, they are interpolated as lengths; when both values are percentages, they are interpolated as percentages; otherwise, both values are converted into a calc() function that is the sum of a length and a percentage (each possibly zero), and these calc() functions have each half interpolated as real numbers. . This means keyword values are not animatable.
• Canonical order the unique non-ambiguous order defined by the formal grammar

---

Syntax

Formal syntax: <bg-size>#

/* Keywords syntax */
background-size: cover
background-size: contain
/* One-value syntax: the value defines the width of the image, the height is implicitly set to 'auto' */
background-size: 50%
background-size: 3em
background-size: 12px
background-size: auto
/* Two-value syntax: the first value defines the width of the image, the second its height */
background-size: 50% auto
background-size: 3em 25%
background-size: auto 6px
background-size: auto auto
/* Values for the multiple backgrounds, defined by background-image, may be listed separated by commas */
background-size: auto, auto     /* Do not confuse this with background-size: auto auto */
background-size: 50%, 25%, 25%
background-size: 6px, auto, contain
background-size: inherit

---

Values

<length>

A <length> value that scales the background image to the specified length in the corresponding dimension. Negative lengths are not allowed.

<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 of 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 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. Negative percentages are not allowed.

auto

The auto keyword that scales the background image in the corresponding direction such that its intrinsic proportion is maintained.

cover

This keyword 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.

contain

This keyword 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.

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.

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.

Note: 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.

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.

---

Examples

.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%;
}

---

Compatibility

Desktop browsers

Mobile browsers