Responsive Picture Block

Core Essentials – Responsive Picture Block turns several standard Image blocks into one semantic, front-end <picture> HTML element. It’s built for art direction: choose different crops, compositions, or formats for different breakpoints (e.g., a tight mobile crop, a wider desktop crop, or an AVIF/WebP source).

Why this matters:

• <picture> vs <img srcset>
  srcset is great for picking the right resolution of the same image. But when you need different content (crop/ratio/composition) at different viewport widths, you need art direction — that’s exactly what <picture> does by letting you swap entire sources via <source media="…">.

• Editor-first UX
  Authors see a single “Responsive Picture (Block)” wrapper, then insert one Image per breakpoint. The plugin mirrors the link /caption from the Desktop image. Per-image design controls (aspect ratio, object-fit, width/height) are respected. The block’s preview shows the native Desktop / Tablet / Mobile toolbar:

  • Desktop preview ⇒ show all child images
  • Tablet preview ⇒ show Tablet, else Desktop, else Mobile
  • Mobile preview ⇒ show Mobile, else Tablet, else Desktop

• Perfect source ordering
  Custom media queries are auto-sorted so the correct <source> wins (most specific first). Works with max-width, min-width, and range queries.

Key Features

• Wraps multiple core Image blocks into a single semantic <picture>
• Pick Desktop / Tablet / Mobile / Custom images (true art direction)
• Override media per Tablet/Mobile/Custom (e.g., (max-width: 1200px))
• Optional sizes override per source (advanced bandwidth tuning)
• Allows width, height, aspect-ratio, object-fit per breakpoint
• Uses link + caption from the Desktop (fallback) image
• Editor preview follows WordPress’ device switcher (Desktop/Tablet/Mobile)
• Prevents layout overflow; picture wrapper is fully responsive
• Works with standard WP image sizes and responsive srcset
• Lightweight, no front-end JS — pure HTML/CSS on the front end

Why <picture> (Art Direction 101)

When your layout needs different imagery across breakpoints (e.g., a vertical crop on phones and a wide landscape on desktops), you’re doing art direction. The <picture> element enables this by letting the browser choose an entire source based on media conditions (and even file type, like AVIF/WebP), not just a different width of the same file. The result is better design control and faster pages because each device downloads only the most appropriate asset for its layout saving you bandwidth as well as having compositions control.

Use Cases

• Hero banners with different crops for mobile vs desktop
• Product images where the subject framing changes on small screens
• Editorial layouts that require portrait vs landscape compositions
• File format switching (e.g., AVIF/WebP with PNG/JPEG fallback)

Usage

1. Insert the Responsive Picture (Block) block.
2. Add Image blocks inside it for: Desktop (fallback), Tablet, Mobile, and/or Custom.
3. Select each Image and open the Responsive: Breakpoint panel:
   • Viewport: Desktop / Tablet / Mobile / Custom
   • Override media query (Tablet/Mobile): optional (e.g., (max-width: 1200px))
   • Custom media query: required when using the “Custom” viewport
4. (Optional) Open Advanced: Sizes override to set a custom sizes="" for that source.
5. Use the editor’s Desktop / Tablet / Mobile preview to check the effective image per breakpoint.
6. Publish. The front end renders a single <picture> with perfectly ordered <source> tags and a fallback <img>.

Block Details

• Block name: ce/responsive-picture
• Children: one or more core/image blocks

• Front-end HTML output:

  <picture>
    <source media="(max-width: 767px)" srcset="…" sizes="…">
    <source media="(max-width: 1024px)" srcset="…" sizes="…">
    <!-- custom sources (auto-sorted) -->
    <img src="…" srcset="…" sizes="…" alt="">
  </picture>