background-image
Setting background images on an element.
Overview
| Class | Declarations |
|---|---|
background-image:url(<…>) | background-image: url(<…>);
|
bg:linear-gradient(<…>) | background: linear-gradient(<…>);
|
bg:radial-gradient(<…>) | background: radial-gradient(<…>);
|
bg:repeating-linear-gradient(<…>) | background: repeating-linear-gradient(<…>);
|
bg:repeating-radial-gradient(<…>) | background: repeating-radial-gradient(<…>);
|
bg:conic-gradient(<…>) | background: conic-gradient(<…>);
|
Examples
Add a background image
background-image:url(...) changes only background-image. Supply a real asset, visible box dimensions and the other longhands needed for its composition.
<!-- Local SVG · centered cover --><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 { .background-image\:url\(\/demo\/landscape\.svg\) { background-image: url(/demo/landscape.svg) }}This example uses a local 320 × 200 SVG at /demo/landscape.svg. Backgrounds have no native alternative text; use an <img> when the image itself carries meaning.
Use gradients
Use native gradient functions as background images. Commas inside the function separate color stops; a comma after the function separates background layers.
<!-- One gradient layer --><div id="target" role="img" aria-label="Blue to violet gradient" class="h:160px w-xs max-w:100% background-image:linear-gradient(90deg,var(--color-blue-50),var(--color-violet-50))"></div><!-- Transparent gradient over artwork --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-cover bg-no-repeat background-image:linear-gradient(90deg,transparent,var(--color-blue-50)),url(/demo/landscape.svg)"></div>The first listed image paints on top. The gradient’s transparent edge reveals the artwork beneath it. These background utilities resolve preset palette names inside gradient functions; keep commas and pipe-separated stop positions intact. Pair them with focused position, size and repeat utilities.
Apply conditionally
Widen the preview viewport to sm to add the image. The frame, surface color and image geometry are present at every width; print removes the decorative image.
<!-- Image appears at sm --><div id="target" role="img" aria-label="Geometric landscape" class="h:160px w-xs max-w:100% bg-center bg-cover bg-no-repeat background-image:none bg-surface-muted background-image:none@print background-image:url(/demo/landscape.svg)@screen@sm"></div>Keep important information in HTML so it remains available when backgrounds are absent or disabled in print settings.