background-size#

#Introduction

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.

#Examples

css-apisrc/background-size/App.tsx

Code

Preview

#Syntax

background-size: contain;

background-size: 50%;
background-size: 3em;

background-size: auto 1em;
background-size: 50% 25%;

#Values

• cover
  Scales the image as large as possible within its container without cropping or stretching the image. If the container is larger than the image, this will result in image tiling, unless the background-repeat property is set to no-repeat.

• contain
  Scales the image (while preserving its ratio) to the smallest possible size to fill the container (that is: both its height and width completely cover the container), leaving no empty space. If the proportions of the background differ from the element, the image is cropped either vertically or horizontally.

• Default value auto
  Scales the background image in the corresponding direction such that its intrinsic proportions are maintained.

• <length>
  Stretches the image in the corresponding dimension to the specified length. Negative values are not allowed.

• <percentage>
  Stretches the image in the corresponding dimension to the specified percentage of the background positioning area. The background positioning area is determined by the value of background-origin (by default, the padding box).

#Size Calculation

• If both components of background-size are specified and are not auto:
  The background image is rendered at the specified size.

• contain or cover:
  While preserving its intrinsic proportions, the image is rendered at the largest size contained within, or covering, the background positioning area. If the image has no intrinsic proportions, then it's rendered at the size of the background positioning area.

• If the background-size has one auto component and one non-auto component:
  The image stretched to the specified dimension. The unspecified dimension is computed using the specified dimension and the intrinsic proportions.

#Notes

Do not use auto with <gradient>. It may cause some rendering issue in old version SDK.

#Formal definition

#Formal Syntax

<bg-size> = (<length-percentage> | auto){1,2} | cover | contain

#Compatibility