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

Live Examples

Art direction, format switching, and image variants applied through the <picture> element.

Art Direction

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

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 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.

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.

Applying Variants

Apply variant classes to the inner <img> element, not the <picture>. All <img> variant classes (.rounded, .circle, .thumbnail, etc.) work inside <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

Related

  • <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
  • <compare-surface> - Before/after image comparison slider for showcasing image differences

CSS Reference

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

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