The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Embed an image | <img
src="team.jpg"
alt="The product team in the studio"> | View examples |
| Hide a decorative image | <img src="divider.svg" alt=""> | View examples |
| Reserve image space | <img
src="portrait.jpg"
alt="Ada Lovelace"
width="800"
height="1000"> | View examples |
| Lazy-load an image | <img
src="gallery-4.jpg"
alt="Mountain lake at sunrise"
loading="lazy"
width="1200"
height="800"> | View examples |
| Request async decoding | <img
src="chart.png"
alt="Quarterly revenue increased each month"
decoding="async"
width="960"
height="540"> | View examples |
| Prioritize a key image | <img
src="hero.jpg"
alt="Developer workspace"
fetchpriority="high"
width="1600"
height="900"> | View examples |
| Offer density variants | <img
src="logo.png"
srcset="logo.png 1x, logo@2x.png 2x"
alt="Northwind"
width="240"
height="80"> | View examples |
| Offer width variants | <img
src="trail-800.jpg"
srcset="trail-480.jpg 480w, trail-800.jpg 800w, trail-1280.jpg 1280w"
alt="Forest trail"> | View examples |
| Describe the image slot | <img
src="trail-800.jpg"
srcset="trail-480.jpg 480w, trail-800.jpg 800w, trail-1280.jpg 1280w"
sizes="(max-width: 600px) 100vw, 50vw"
alt="Forest trail"> | View examples |
| Offer a modern format | <picture>
<source srcset="portrait.avif" type="image/avif">
<img src="portrait.jpg" alt="Ada at her desk">
</picture> | View examples |
| Offer several formats | <picture>
<source srcset="hero.avif" type="image/avif">
<source srcset="hero.webp" type="image/webp">
<img src="hero.jpg" alt="City skyline">
</picture> | View examples |
| Change the crop | <picture>
<source
media="(max-width: 600px)"
srcset="speaker-close.jpg">
<img
src="speaker-wide.jpg"
alt="Speaker presenting on stage">
</picture> | View examples |
| Combine media and widths | <picture>
<source
media="(min-width: 900px)"
srcset="banner-1200.jpg 1200w, banner-1800.jpg 1800w"
sizes="80vw">
<img src="banner-720.jpg" alt="Conference attendees">
</picture> | View examples |
| Caption an image | <figure>
<img
src="diagram.svg"
alt="Request flow from browser to server">
<figcaption>Figure 1: Request lifecycle</figcaption>
</figure> | View examples |
| Label an image link | <a href="/reports/">
<img
src="report-cover.jpg"
alt="Open the annual report">
</a> | View examples |
Start with an img element that has a useful text alternative and intrinsic dimensions. Add srcset and sizes when the same image must adapt to its layout, and use picture when the content, crop, or file format should change under specific conditions.
Step by step
Detailed examples
Give every image an appropriate text alternative
Use concise alt text when an image conveys meaning, describing its purpose in context rather than its appearance alone. Use an empty alt attribute for a purely decorative image; omitting alt entirely can cause assistive technology to announce the filename instead.
<article>
<h2>Meet the product team</h2>
<img src="team.jpg" alt="The product team in the studio">
<img src="divider.svg" alt="">
<p>We design and maintain the application together.</p>
</article>Note: Do not begin alt text with phrases such as 'image of'; screen readers already expose the element as an image.
Control layout, loading, and decoding deliberately
Set width and height to the source image's intrinsic pixel dimensions so the browser can calculate its aspect ratio. Lazy-load images below the initial viewport, but keep the primary above-the-fold image eager and use high fetch priority only for a genuinely important resource. Loading and decoding values are hints, so the browser retains final scheduling control.
<main>
<img src="hero.jpg" alt="Developer workspace" fetchpriority="high" width="1600" height="900">
<img src="portrait.jpg" alt="Ada Lovelace" width="800" height="1000">
<img src="chart.png" alt="Quarterly revenue increased each month" decoding="async" width="960" height="540">
<img src="gallery-4.jpg" alt="Mountain lake at sunrise" loading="lazy" width="1200" height="800">
</main>Note: Do not lazy-load the likely largest contentful paint image; delaying it can make the page appear slower.
Supply density variants for a fixed-size slot
Use x descriptors when an image renders at one stable CSS size but higher-density displays benefit from more source pixels. Keep the candidate dimensions proportional, and do not mix density descriptors with width descriptors in the same srcset.
<img
src="logo.png"
srcset="logo.png 1x, logo@2x.png 2x"
alt="Northwind"
width="240"
height="80">Match source width to the rendered slot
Use w descriptors when an image changes size with the layout. Each descriptor must state the candidate file's real intrinsic width, while sizes describes the slot width, not the source file width. The browser combines this information with display density and may choose any suitable candidate.
<img
src="trail-800.jpg"
srcset="trail-480.jpg 480w, trail-800.jpg 800w, trail-1280.jpg 1280w"
sizes="(max-width: 600px) 100vw, 50vw"
alt="Forest trail"
width="1280"
height="853">Note: Keep sizes synchronized with the CSS layout; an inaccurate slot size can make the browser download an unnecessarily large or visibly soft resource.
Offer image formats with a dependable fallback
Place source elements before the required img fallback inside picture. The browser considers sources in document order and uses the type value to skip unsupported formats without downloading them. The img element still owns the alternative text, dimensions, and fallback URL.
<picture>
<source srcset="hero.avif" type="image/avif">
<source srcset="hero.webp" type="image/webp">
<img src="hero.jpg" alt="City skyline" width="1600" height="900">
</picture><picture>
<source srcset="portrait.avif" type="image/avif">
<img src="portrait.jpg" alt="Ada at her desk" width="800" height="1000">
</picture>Use picture for art direction
Use media conditions when different viewport ranges need a genuinely different crop or composition. A source can also provide its own srcset and sizes. Keep the img alternative accurate for every selected source because all variants share that single accessible description.
<picture>
<source media="(max-width: 600px)" srcset="speaker-close.jpg">
<img src="speaker-wide.jpg" alt="Speaker presenting on stage" width="1400" height="800">
</picture><picture>
<source media="(min-width: 900px)" srcset="banner-1200.jpg 1200w, banner-1800.jpg 1800w" sizes="80vw">
<img src="banner-720.jpg" alt="Conference attendees" width="720" height="720">
</picture>Provide captions and meaningful image links
Use figure and figcaption when a visible caption belongs with the image. When an image is the only content of a link, its alt text must communicate the link destination or action rather than merely describe the artwork. Avoid repeating the same wording in adjacent alt text and captions unless both are necessary in context.
<figure>
<img src="diagram.svg" alt="Request flow from browser to server" width="900" height="500">
<figcaption>Figure 1: Request lifecycle</figcaption>
</figure><a href="/reports/">
<img src="report-cover.jpg" alt="Open the annual report" width="320" height="420">
</a>Local code tester
Try accessible image markup
Edit the figure, alternative text, dimensions, and loading hints, then render the markup locally.
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.