background-size
Setting the size of the background image.
Overview
| Class | Declarations |
|---|---|
bg-auto | background-size: auto;
|
bg-cover | background-size: cover;
|
bg-contain | background-size: contain;
|
background-size:<size>,<…> | background-size: <size>,<…>;
|
Examples
Cover a frame
bg-cover preserves the image’s aspect ratio and fills the positioning area. Compare the whole 320 × 200 source with a 320 × 160 covered frame, which crops 20px from the top and bottom at full width.
<!-- Whole source · 8:5 aspect ratio --><div id="target" role="img" aria-label="Geometric landscape" class="w-xs max-w:100% aspect-ratio:8/5 bg-center bg-contain bg-no-repeat background-image:url(/demo/landscape.svg)"></div><!-- Cover · fill and crop --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-cover bg-no-repeat bg-surface-muted background-image:url(/demo/landscape.svg)"></div>Generated CSS
@layer utilities { .bg-cover { background-size: cover }}Use position to choose which part of the crop stays visible. The frame can shrink on narrow screens, changing the amount of cropping.
Contain an image
bg-contain preserves the complete image within the positioning area. At full frame size, the artwork becomes 256 × 160 and leaves 32px on each side.
<!-- Contain · whole image with free space --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-contain bg-no-repeat bg-surface-muted background-image:url(/demo/landscape.svg)"></div>Contain does not turn off repetition. This example explicitly uses bg-no-repeat and bg-center, so the unused area exposes the surface color.
Use measured sizes
Use a width with auto to preserve the source ratio, or force both dimensions when distortion is intentional. Use explicit native units such as 3rem for lengths.
<!-- 160px auto · preserved ratio --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-no-repeat background-size:160px|auto bg-surface-muted background-image:url(/demo/landscape.svg)"></div><!-- 12x 12x · forced square --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-no-repeat background-size:3rem|3rem bg-surface-muted background-image:url(/demo/landscape.svg)"></div>At a 16px root font size, the square measures 48 × 48px. For multiple background images, comma-separated sizes match the image list in order.
Apply conditionally
Widen the actual preview viewport to sm to switch from contain to cover. The source, position and repetition stay the same; print restores contain.
<!-- Contain → cover at sm --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-contain bg-no-repeat bg-surface-muted background-image:url(/demo/landscape.svg) bg-contain@print bg-cover@screen@sm"></div>The computed readout reports the keyword. The visible crop shows how it resolves against the image’s intrinsic ratio and the current frame dimensions.