background-position
Positioning background images within their positioning area.
Overview
| Class | Declarations |
|---|---|
bg-top | background-position: top;
|
bg-bottom | background-position: bottom;
|
bg-right | background-position: right;
|
bg-left | background-position: left;
|
bg-center | background-position: center;
|
background-position:<value> | background-position: <value>;
|
Examples
Position a background image
Use position shortcuts to align an image within its positioning area. This 160 × 100 image is smaller than its 320 × 160 frame, leaving visible free space.
<!-- Left · vertical center --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-left bg-no-repeat background-size:160px|100px bg-surface-muted background-image:url(/demo/landscape.svg)"></div><!-- Center · both axes --><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|100px bg-surface-muted background-image:url(/demo/landscape.svg)"></div><!-- Right · vertical center --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-no-repeat bg-right background-size:160px|100px bg-surface-muted background-image:url(/demo/landscape.svg)"></div>Generated CSS
@layer utilities { .bg-center { background-position: center } .bg-left { background-position: left } .bg-right { background-position: right }}A single horizontal keyword keeps the vertical axis centered. bg-top and bg-bottom center the horizontal axis.
Use explicit positions
A two-value position supplies horizontal then vertical offsets. Percentages align matching points on the image and positioning area; lengths offset the image from the top-left.
<!-- 50% 25% · shares the free space --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-no-repeat background-position:50%|25% background-size:160px|100px bg-surface-muted background-image:url(/demo/landscape.svg)"></div><!-- 24px 12px · measured offset --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-no-repeat background-position:var(--spacing-lg)|var(--spacing-sm) background-size:160px|100px bg-surface-muted background-image:url(/demo/landscape.svg)"></div>At the full 320 × 160 frame size, 50% 25% gives x = (320 − 160) × 50% = 80px and y = (160 − 100) × 25% = 15px. On narrow screens the frame shrinks, so the horizontal result changes. If the image fills an axis exactly, percentages on that axis produce no movement.
Apply conditionally
The image covers a deliberately shallow frame. Widen to sm to move its crop from center to top; print restores the center crop.
<!-- Centered crop → top crop at sm --><div id="target" role="img" aria-label="Geometric landscape" class="h:120px w-xs max-w:100% bg-center bg-cover bg-no-repeat background-image:url(/demo/landscape.svg) bg-center@print bg-top@screen@sm"></div>Cover crops vertically here because the frame is wider than the source’s 8:5 ratio. Position moves the cropped image without changing its rendered size.