Images & Media

<img src="url" alt="description" width="w" height="h">

<img src="/images/team-photo.jpg" alt="Our engineering team at the 2025 offsite" width="800" height="450">

Note Always provide meaningful alt text for accessibility. Set explicit width and height to prevent layout shift while the image loads.

<figure>
  <img src="url" alt="description">
  <figcaption>Caption text</figcaption>
</figure>

<figure>
  <img src="/charts/revenue.png" alt="Bar chart showing 40% revenue growth year over year">
  <figcaption>Revenue growth from 2023 to 2025</figcaption>
</figure>

Note figure is for self-contained content that could be moved to an appendix without losing meaning. The figcaption provides a visible caption, while alt describes the image content itself.

<picture>
  <source media="(condition)" srcset="image-url">
  <img src="fallback.jpg" alt="description">
</picture>

<picture>
  <source media="(min-width: 1024px)" srcset="/images/hero-wide.webp" type="image/webp">
  <source media="(min-width: 600px)" srcset="/images/hero-medium.webp" type="image/webp">
  <img src="/images/hero-small.jpg" alt="Mountain landscape at sunrise">
</picture>

Note The browser picks the first matching source. Always include the img fallback as the last child. Use picture for art direction (different crops at different sizes) or serving modern formats with fallbacks.

<img srcset="small.jpg 480w, medium.jpg 800w, large.jpg 1200w"
     sizes="(max-width: 600px) 100vw, 50vw"
     src="medium.jpg" alt="description">

<img
  srcset="/photos/product-480.jpg 480w,
         /photos/product-800.jpg 800w,
         /photos/product-1200.jpg 1200w"
  sizes="(max-width: 640px) 100vw,
         (max-width: 1024px) 50vw,
         33vw"
  src="/photos/product-800.jpg"
  alt="Wireless headphones in midnight blue"
>

Note The w descriptor tells the browser the intrinsic pixel width of each image. sizes tells it how wide the image will display at each breakpoint, so it can pick the best file. This is for resolution switching, not art direction.

<img src="url" alt="description" loading="lazy">

<img src="/gallery/photo-42.jpg" alt="Sunset over the canyon" loading="lazy" width="600" height="400">

Note loading="lazy" defers loading until the image nears the viewport. Do not lazy-load images that are visible on initial load (above the fold) since it slows their appearance. Use loading="eager" (the default) for hero images.

<video src="url" controls width="w" height="h"></video>

<video controls width="720" height="405" poster="/thumbs/demo.jpg">
  <source src="/videos/demo.webm" type="video/webm">
  <source src="/videos/demo.mp4" type="video/mp4">
  Your browser does not support video playback.
</video>

Note Provide multiple source formats for compatibility. The poster attribute shows a thumbnail before playback. Avoid autoplay with sound since browsers block it and users dislike it.

<audio src="url" controls></audio>

<audio controls>
  <source src="/audio/podcast-ep12.ogg" type="audio/ogg">
  <source src="/audio/podcast-ep12.mp3" type="audio/mpeg">
  Audio playback is not supported in your browser.
</audio>

Note Like video, provide multiple source formats. The controls attribute gives users play, pause, and volume UI. Without controls, the element is invisible.

<img src="url" alt="" role="presentation">

<img src="/images/decorative-divider.svg" alt="">

Note For purely decorative images that add no information, use an empty alt attribute. Screen readers will skip them entirely. Never omit the alt attribute since that causes readers to announce the file name.