picture

The picture element enables art direction and format switching by providing multiple image sources for different screen sizes and browser capabilities.

Description

The <picture> element is a container for zero or more <source> elements and one <img> element. It allows the browser to choose the most appropriate image source based on media queries, image format support, or pixel density.

Vanilla Breeze styles <picture> as a block-level element, with the contained <img> expanding to fill its width. This ensures responsive behavior while allowing the browser to select the optimal source.

When to Use

  • Art direction - Different image crops for different viewport sizes (e.g., landscape hero on desktop, portrait on mobile)
  • Format switching - Serve modern formats (WebP, AVIF) with fallbacks for older browsers
  • Resolution switching - Serve different resolutions based on device pixel ratio
  • Dark mode images - Different images for light and dark color schemes

When to Use img Instead

  • Single image that works well at all sizes - use <img> with srcset and sizes
  • Simple responsive images where only resolution changes - <img srcset> is sufficient
  • Decorative images - CSS background images may be more appropriate

Art Direction

Serve different image crops based on viewport width using media queries on <source> elements.

Responsive art directed image
<picture> <!-- Wide viewport: landscape crop --> <source media="(min-width: 800px)" srcset="hero-wide.jpg" /> <!-- Medium viewport: square crop --> <source media="(min-width: 500px)" srcset="hero-medium.jpg" /> <!-- Small viewport: portrait crop (fallback) --> <img src="hero-mobile.jpg" alt="Hero image" /> </picture>

The browser evaluates <source> elements from top to bottom and uses the first one with a matching media condition. The <img> serves as the fallback.

Format Switching

Serve modern image formats to browsers that support them while providing fallbacks for others.

Format switching example
<picture> <!-- AVIF: best compression, growing support --> <source type="image/avif" srcset="photo.avif" /> <!-- WebP: good compression, wide support --> <source type="image/webp" srcset="photo.webp" /> <!-- JPEG: universal fallback --> <img src="photo.jpg" alt="A beautiful photograph" /> </picture>
Format MIME Type Best For
AVIF image/avif Best compression, photos and illustrations
WebP image/webp Good compression, wide browser support
JPEG image/jpeg Photos, universal compatibility
PNG image/png Transparency, sharp edges, screenshots

Dark Mode Images

Serve different images based on the user's color scheme preference.

<picture> <!-- Dark mode version --> <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png" /> <!-- Light mode version (fallback) --> <img src="logo-light.png" alt="Company logo" /> </picture>

This technique is especially useful for logos, diagrams, and illustrations that need different color treatments for light and dark themes.

Combined Techniques

Combine art direction, format switching, and resolution switching for optimal delivery.

<picture> <!-- Wide viewport, modern format --> <source media="(min-width: 800px)" type="image/avif" srcset="hero-wide.avif 1x, hero-wide@2x.avif 2x" /> <source media="(min-width: 800px)" type="image/webp" srcset="hero-wide.webp 1x, hero-wide@2x.webp 2x" /> <source media="(min-width: 800px)" srcset="hero-wide.jpg 1x, hero-wide@2x.jpg 2x" /> <!-- Narrow viewport: different crop --> <source type="image/avif" srcset="hero-mobile.avif 1x, hero-mobile@2x.avif 2x" /> <source type="image/webp" srcset="hero-mobile.webp 1x, hero-mobile@2x.webp 2x" /> <!-- Ultimate fallback --> <img src="hero-mobile.jpg" srcset="hero-mobile.jpg 1x, hero-mobile@2x.jpg 2x" alt="Hero banner" /> </picture>

Live Examples

Basic Picture

Basic picture element example

With Variants

Apply variant classes to the inner <img> element, not the <picture>.

Rounded picture
<picture> <source srcset="photo.webp" type="image/webp" /> <img src="photo.jpg" alt="..." class="rounded" /> </picture>

Accessibility

  • The alt attribute goes on the <img> element, not <picture>
  • All source variations should convey the same information (art direction changes framing, not content)
  • Screen readers announce the <img> - the <picture> wrapper is transparent
  • Don't use <picture> to hide content from some users
<!-- Correct: alt on img --> <picture> <source srcset="hero-wide.jpg" media="(min-width: 800px)" /> <img src="hero-mobile.jpg" alt="Team members collaborating around a table" /> </picture>

Related Elements

  • <img> - Required child element that receives the final image
  • <source> - Define alternative image sources with media/type conditions
  • <figure> - Wrap picture elements that need captions

CSS Reference

Styles defined in /src/native-elements/image/styles.css

Selector Properties
picture display: block;
picture > img inline-size: 100%;