All articles

Serving Drupal responsive images through media view modes

The cleanest way to get responsive images across a Drupal site is to stop choosing image styles on every field. Create a small set of view modes on the image media type (card, poster, full), give each one the core Responsive Image formatter with a responsive image style that lists several widths and a sizes value, and switch every media reference field to the "Rendered entity" formatter pointing at the right view mode. Image sizing then lives in a handful of media displays instead of dozens of node, paragraph and block displays.

What the site looked like before

A teammate recently did this on one member site in a group of nonprofit membership sites that share a Drupal distribution. The starting point will be familiar to anyone who has inherited a Drupal site that grew over time.

Media reference fields on teasers, paragraphs, contact profiles and a homepage hero block were rendered with the "Thumbnail" formatter (media_thumbnail), each with its own fixed image style. The hero used a single 1440-pixel-wide background style. Teaser cards used one 400-pixel style. The media type's own default display used yet another style through a separate image formatter.

That arrangement has two problems. Every browser downloads the same file whatever the viewport, so a phone gets the 1440-pixel hero. And there's no single place to fix that: the image style choice is scattered across every entity display that references media, so changing how cards are sized means finding and editing every display that shows a card.

Why media view modes are the right place for sizing

The team's change moved the decision onto the media entity. New view modes on the image media type describe the shapes the design actually uses:

  • full: full-width heroes and slides
  • card: 3:2 teaser cards in a grid
  • poster: wide promotional images
  • a portrait mode for people and resource covers

Each of those displays renders the image field with the Responsive Image formatter and a matching responsive image style. The referencing fields switch from "Thumbnail" to "Rendered entity" with the right view mode, and keep no image settings of their own. The change touched more than twenty entity displays, most of which swapped a per-field image style for a one-line view_mode setting.

What I like about this approach is that it matches how designers think. A card is a card wherever it appears, so its srcset should be defined once. When the grid changes from three columns to four, you change one responsive image style, not a search across config.

How the responsive image styles are set up

Each responsive image style uses the "sizes" mapping type rather than one image per breakpoint. You list several image styles at different widths, Drupal turns them into a srcset with width descriptors, and the sizes attribute tells the browser how wide the image will be shown. A minimal style for cards in exported config looks like this:

id: card
label: Card
breakpoint_group: mytheme
fallback_image_style: card_400_fallback
image_style_mappings:
  -
    breakpoint_id: mytheme.small
    multiplier: 1x
    image_mapping_type: sizes
    image_mapping:
      sizes: '(min-width: 768px) 400px, 100vw'
      sizes_image_styles:
        - card_320
        - card_480
        - card_640
        - card_800

A few choices in the team's version are worth copying:

  • Widths go past the display size. A card shown at 400 CSS pixels still gets 640 and 800-pixel candidates, so high-density screens pick a sharp file. A full-width hero gets candidates from 480 to 1440 with sizes: 100vw.
  • Crop only where the shape demands it. Card styles use Focal Point's scale-and-crop effect, so the subject stays in frame at a fixed 3:2 aspect. Hero, poster and portrait styles only scale, because their aspect follows the upload.
  • WebP for the srcset, the original format for the fallback. Every srcset candidate ends with core's Convert effect to WebP. The fallback styles don't convert, so the plain src stays in the uploaded format.
  • An existing style is reused where the width matches. The old 400-pixel card style sits in the new srcset, so derivatives already generated for it keep being served.
  • The fallback is its own style. fallback_image_style is what goes in the img element's src. Giving it a separate, clearly named style makes it obvious which one that is when someone edits the list later.

The breakpoint group comes from the theme's *.breakpoints.yml. With the sizes mapping type the same list usually applies to every breakpoint, because the sizes value already carries the layout's media queries. The admin UI still asks per breakpoint, which is why exported config often repeats the same block several times.

Eager for the hero, lazy for everything else

Moving sizing into view modes also gives loading behaviour a natural home. The Responsive Image formatter has the same image_loading setting as the plain image formatter. In the team's change the full view mode, used for the hero at the top of the page, switched to eager, while card, poster and portrait stayed lazy.

That matters for Largest Contentful Paint. The hero is usually the LCP element, and lazy loading it makes the browser wait for layout before it even requests the image. Cards further down the page are the opposite case: deferring them saves bandwidth for the image that counts. Because the hero uses its own view mode, that decision is made once rather than remembered on every hero-like field.

What to check when you switch formatters

"Rendered entity" isn't a drop-in replacement for "Thumbnail", so a change like this needs a careful pass through the front end:

  • Markup changes. The image now arrives wrapped in the media entity's template, and with a picture element or a srcset. Theme CSS written against a bare img may need adjusting.
  • The thumbnail and the source differ. The Thumbnail formatter renders the media's generated thumbnail field, while a media display renders the source image field. For image media they are usually the same file; for other media types they aren't.
  • Formatters for other file types. If your image media type was set up with a formatter that also handles SVG, check how SVG uploads render once the Responsive Image formatter takes over.
  • Every display that shows media. Field blocks in a Layout Builder default layout keep their formatter settings in the display's third-party settings, not the usual field list, so search exported config for the old image style names to find them all.

Key takeaways

  • Define image sizing on a few view modes of the image media type, not on every field that references media.
  • Render media reference fields with the "Rendered entity" formatter so they inherit the view mode's responsive image style.
  • Use the sizes mapping type with several widths, including ones above the display size, and let the browser choose from the srcset.
  • Set the hero's view mode to eager loading and keep cards lazy, so the likely LCP image is requested first.
  • Search exported config for the old image style names after the switch, because Layout Builder displays hide field settings outside the usual places.