The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Keep meaningful images semantic | <img src="chart.webp" alt="Revenue rose from $2M to $3M" width="800" height="450"> | View examples |
| Hide a decorative image | <img src="divider.svg" alt="" width="320" height="24"> | View examples |
| Crop to cover a box | .avatar {
inline-size: 8rem;
aspect-ratio: 1;
object-fit: cover;
} | View examples |
| Contain the complete object | .product {
inline-size: 100%;
block-size: 18rem;
object-fit: contain;
} | View examples |
| Choose the crop focus | .portrait {
object-fit: cover;
object-position: 50% 25%;
} | View examples |
| Paint a linear gradient | .banner {
background:
linear-gradient(120deg, #172554 0%, #2563eb 55%, #67e8f9 100%);
} | View examples |
| Paint a radial highlight | .spotlight {
background:
radial-gradient(circle at 70% 25%, #fff9 0 8%, transparent 45%), #172554;
} | View examples |
| Paint angular segments | .meter {
background:
conic-gradient(#16a34a 0 72%, #d1d5db 72% 100%);
} | View examples |
| Repeat a stripe pattern | .warning {
background:
repeating-linear-gradient(135deg, #facc15 0 12px, #111827 12px 24px);
} | View examples |
| Offer resolution variants | .logo {
background-image:
image-set(url('/logo.png') 1x, url('/logo@2x.png') 2x);
} | View examples |
| Offer modern image formats | .hero {
background-image:
image-set(url('/hero.avif') type('image/avif'), url('/hero.webp') type('image/webp'));
} | View examples |
| Preserve pixel-art edges | .sprite { image-rendering: pixelated; } | View examples |
| Layer over a color fallback | .hero {
background-color: #172554;
background-image:
linear-gradient(#172554cc, #1d4ed8cc);
} | View examples |
| Gate a newer color space | @supports (background: linear-gradient(in oklab, red, blue)) {
.hero { background-image:
linear-gradient(in oklab, #172554, #22d3ee); };
} | View examples |
CSS can paint generated images and control how replaced content fits its box, but it does not replace semantic image markup. Keep meaningful imagery in HTML with useful alternative text, reserve CSS images for decoration, declare stable dimensions, and layer newer image features over dependable fallbacks.
Step by step
Detailed examples
Choose HTML for content and CSS for decoration
A CSS background has no alternative-text mechanism and is not exposed as document content. Put informative photos, diagrams, and charts in img or picture markup, write alt text for the purpose the image serves, and include width and height so the browser can reserve its aspect ratio before download. Decorative inline images need alt=""; decorative CSS backgrounds should never be the only place a label, warning, or instruction appears. Text over any image also needs sufficient contrast under every crop and loading state.
<figure>
<img src="quarterly-revenue.webp"
alt="Quarterly revenue increased from $2 million to $3 million"
width="800" height="450">
<figcaption>Revenue for the last four quarters</figcaption>
</figure>
<img src="flourish.svg" alt="" width="320" height="24">.callout {
color: #fff;
background-color: #172554;
background-image: url('/decorative-grid.svg');
}
/* The warning text remains real HTML inside .callout. */Control replaced-content sizing and crop focus
object-fit changes how an image or video is drawn inside its established content box; it does not size that box by itself. cover preserves the natural ratio and clips overflow, while contain preserves the whole object and may letterbox it. object-position moves the object within the box, which is useful for a known focal point but cannot guarantee every important detail survives every crop. Declare a box size or aspect-ratio deliberately, and prefer contain when cropping would remove information.
.story-image {
inline-size: 100%;
aspect-ratio: 16 / 9;
object-fit: cover;
object-position: 50% 30%;
}
.product-image {
inline-size: 100%;
block-size: 18rem;
object-fit: contain;
background: #f8fafc;
}Build gradients with explicit geometry and stops
Gradients are generated images, so they scale without downloading an asset. Linear gradients follow a line, radial gradients expand from a center, and conic gradients rotate around one. Double-position stops create hard bands, and repeating gradients repeat the resolved final interval. Treat gradient-only charts as decorative unless the values are also present as text. Check contrast at the lightest and darkest points behind text, and avoid animating large painted gradients when a static result works.
.hero {
background:
radial-gradient(circle at 75% 20%, rgb(255 255 255 / .35) 0 5%, transparent 35%),
linear-gradient(120deg, #172554, #2563eb 60%, #67e8f9);
}
.progress-ring {
background: conic-gradient(#16a34a 0 var(--progress, 72%), #d1d5db 0);
border-radius: 50%;
}
.stripes {
background: repeating-linear-gradient(135deg, #facc15 0 12px, #111827 12px 24px);
}Offer CSS image candidates without confusing density and layout
image-set() supplies candidate images with resolution descriptors and, in Level 4, optional MIME types. A user agent may choose based on supported format, effective resolution, network conditions, and other factors. It does not choose an asset from the rendered element's width, so use HTML picture, srcset, and sizes for meaningful responsive images. Start with an ordinary url() declaration: browsers that reject a later image-set() value retain the earlier declaration. Because CSS backgrounds are fetched only when matching rules apply, narrow media queries can also prevent irrelevant decorative downloads.
.brand-mark {
background-image: url('/brand.png');
background-image: image-set(
url('/brand.avif') type('image/avif') 1x,
url('/brand@2x.avif') type('image/avif') 2x,
url('/brand.webp') type('image/webp') 1x
);
}
@media (min-width: 60rem) {
.masthead { background-image: url('/wide-decoration.webp'); }
}Protect image quality, layout stability, and bandwidth
Do not ship a large raster merely to scale it down in CSS: decode and transfer costs still follow the source. Match source dimensions to likely rendered sizes, compress assets, and reserve space with intrinsic width and height or aspect-ratio. image-rendering: pixelated is a specialized scaling request for pixel art, not a general sharpening switch. Background images have no native loading="lazy" attribute; use them sparingly below the fold or move meaningful imagery to img so the browser can apply responsive selection, lazy loading, decoding, and fetch-priority controls.
.media-frame {
aspect-ratio: 4 / 3;
overflow: clip;
background: #e2e8f0;
}
.media-frame > img {
inline-size: 100%;
block-size: 100%;
object-fit: cover;
}
.pixel-art {
inline-size: 256px;
image-rendering: pixelated;
}Layer fallbacks and isolate evolving image syntax
An invalid image is effectively transparent in many image contexts, so pair decorative imagery with an appropriate background color and keep foreground contrast independent of successful loading. Put a broadly supported declaration first, then override it inside @supports when adopting color-space interpolation or other evolving Level 4 syntax. Forced-colors modes may suppress or alter decorative painting; preserve borders, labels, and state indicators in semantic content rather than encoding them only in a gradient.
.hero {
color: white;
background-color: #172554;
background-image: linear-gradient(120deg, #172554, #0891b2);
}
@supports (background: linear-gradient(in oklab, red, blue)) {
.hero {
background-image: linear-gradient(120deg in oklab, #172554, #22d3ee);
}
}
@media (forced-colors: active) {
.hero { border: 2px solid CanvasText; }
}Local code tester
Explore crop modes and generated images
Change object-fit, object-position, gradient stops, and fallback colors while keeping the image label in semantic HTML.
Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.