CSS background-size

The CSS background-size property was introduced in CSS3 for the purposes of setting the dimensions of a background image.

The background-size property allows you to specify exactly what size your background image is. Furthermore, you can use the cover and contain keywords to scale the image to the box.

The background-size property is used in conjunction with the background-image property to define a background image on an HTML element.

Syntax

The formal syntax for this property is:

Where

See below for more information.

Possible Values

Here are the possible values:

contain

Specifies that the background image should be scaled, 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.

cover

Specifies that the background image should be scaled, 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.

<length>

Specifies the size explicitly using a lenth value. For example, 300px 100px will result in a background image being scaled to 300 pixels wide and 100 pixels high.

The first value provided defines the width of the background image. The second value provides the height. If only one value is given, the second becomes auto.

For example, background-size:200px 50px provides a width of 200 pixels and a height of 50 pixels. A value of background-size:200px will result in the width being 200 pixels and the height being automatically determined by using the image's intrinsic ratio and the size of the other dimension, or failing that, using the image's intrinsic size, or failing that, treating it as 100%. In other words, the image should keep its proportions as it scales (i.e. not get distorted).

<percentage>

Specifies the size explicitly using a percentage value. A percentage value is relative to the background positioning area - not to the original image size. For example, 70% will result in a background image being scaled to 70 percent of the background positioning area.

As with the <length> values, the first value provides the width and the second provides the height. If the second value is missing, the height is automatically determined.

auto

Specifies that the image size is automatically determined using the intrinsic width and/or height of the image.

In addition, all CSS properties also accept the following CSS-wide keyword values as the sole component of their property value:

initial

Represents the value specified as the property's initial value.

inherit

Represents the computed value of the property on the element's parent.

unset

This value acts as either inherit or initial, depending on whether the property is inherited or not. In other words, it sets all properties to their parent value if they are inheritable or to their initial value if not inheritable.

Basic Property Information

Example Code

Basic CSS

Working Example within an HTML Document

CSS Specifications

• The background-size property is defined in CSS Backgrounds and Borders Module Level 3 (W3C Candidate Recommendation Snapshot)

Browser Support

Browser support for CSS properties can vary, particularly for newer or experimental features. Check current browser compatibility before using a property in production, especially when supporting older browsers.

The following table provided by Caniuse.com shows the level of browser support for this feature.

Initial Value

CSS properties have an initial value that applies when the property has not been explicitly set. The initial value is different from the value inherited from a parent element and may vary between properties.

Inheritance

Some CSS properties inherit their computed value from their parent element by default, while others do not. The inherit, initial, unset, and revert keywords can also be used to control how a property gets its value.

Vendor Prefixes

Most modern CSS properties use the standard, unprefixed syntax. Vendor-prefixed properties such as -webkit- are mainly relevant to older browser versions or specific features and should only be used when required by your browser support targets.