Sep 23, 2016 - Abby Milberg

Responsive Image Configuration in Drupal 8

On responsive websites, it's important to optimize images for a variety of screen sizes. While a CSS rule of max-width: 100%; will do the trick visually, it won't prevent that 2000px banner image from trying (and failing) to load over somebody's spotty 3G connection. Luckily, Drupal 8 makes it easier than ever to load the appropriate image size for the user's viewport.

First, ensure that the "Breakpoint" and "Responsive Image" modules are enabled on your site. As of Drupal 8, these are in core! Figure out at which breakpoint(s) you want to swap your images sizes. For this example, I'm using 600px, but you should generally use the same breakpoint(s) that you use in your theme's media queries.

Next, you'll need to create a file named your_theme_slug.breakpoints.yml (or your_module_slug.breakpoints.yml). Back when Breakpoint was a Drupal 7 contrib module, you could set your breakpoints in the admin interface, but now it needs to be done in code. Set your breakpoints like so, making sure to order the weights from smallest to largest:

  label: narrow
  mediaQuery: ''
  weight: 0
  group: Banner Image
  label: wide
  mediaQuery: '(min-width: 600px)'
  weight: 1
  group: Banner Image

In this case, bannerImage is a grouping of breakpoints that I'm going to use in the same responsive image style. You can create multiple groupings as needed for different image styles across your site. For a deeper dive into breakpoint options, including different media queries and resolution multipliers, check out the Breakpoint documentation on

Now it's time to create our image styles - one for each breakpoint. These are standard Drupal image styles as found in both Drupal 7 and 8 at /admin/config/media/image-styles. I've chosen to create "Banner Image Small" for screens under 600px wide, and "Banner Image Large" for screens 600px or over. Once that's done, go to /admin/config/media/responsive-image-style and click "Add responsive image style." 

Give your style a name, and choose your breakpoint group from the available dropdown. (If you're not seeing the breakpoint group you created in your YML file, try clearing caches.) Once selected, this should let you choose an image style for each breakpoint in the group. Select the ones you created in the previous step, and set the smallest one as your fallback image style in case your user is on an extremely old browser and the polyfill fails. Click "Save."

Responsive image style configuration.

Now you're ready to use your responsive image style in the display for an actual image field! For your content type (or other bundle), go to "Manage Display," and for the "Format" of your image field choose "Responsive image." After you've done that, click on the gear icon on the far right, and choose your responsive image style from the available dropdown. Click "Update" and then "Save."

Configuring an image to use your responsive image style.

It's that simple to let Drupal generate appropriately-sized images that improve your site's speed and user experience. 

Related Links

Responsive Images Done Right: A Guide To <picture> And srcset
Working with Breakpoints in Drupal 8