Images in the WebCMS: Nuts and Bolts

Read the Adding and Deleting Images page to learn how to add images first.

All images on this page are centered, and use the different image styles available: Large, Medium, Original, Small. The original image is here: /system/files/images/2021-06/cc-cookies.jpg

This original image is 1,920px wide x 1,272px tall. That's a 3:2 aspect ratio. Uploading this image to Drupal 9 creates six variants (plus a banner), along with the original:

Hero (2048px X 820px), default ratio is 5:2 but height will change based on the text overlay box.
Colossal (1,920px x 1,272px), the 16:9 ratio is preserved
Huge (1,280px x 848px), 3;2
Large (960px x 636px), 3:2
Medium (640px x 424px), 3:2
Small (320px x 212px), 3:2
Thumbnail (160px x 106px), 3:2
Original (1,920px x 1,272px), 3:2

The image is scaled proportionally for every variant, with no cropping. Each variant that we use (large, medium, small, thumbnail) was chosen to fit 100%, 66%, 33%, and 16%, of the width of a standard (not wide) www.epa.gov page.

However, and this is the tricky bit, we're also using new markup to serve people a smaller/larger version of the image based on their device size and pixel density of the screen. Think about it: a 1920px wide screen and a 360px screen with the same density usually get the same image, which means you make significant compromises, either on blurriness or on slowness. We're changing that with the new markup.

It is now possible to define images that allows browsers to pick the right one for the current pixel density and viewport size. We do automatically that by defining the set of available image resources along with their physical dimensions (i.e. their width in pixels), and have the browser download one based on the image’s display dimensions.

Large Image

This image is the original image set to use the Large variant.

The code to output this image looks something like this:

What does this mean??

SRCSET and Sizes

The srcset attribute contains a list of images that the browser can pick from, and the w descriptors tell the browser each resource’s physical dimensions. The sizes attribute is comprised of value pairs, where the first (optional) value is a media condition (a media query) and the second value is a CSS length. The src attribute is the fallback, if the browser can't understand the rest of the code.

The browser goes over the media conditions (the sizes) and looks for the first one that matches the current viewport. The second value of the pair (or the first one if the media condition is missing), is set as the "effective size," and it describes the estimated dimensions of the image. This is a hint the developer gives the browser in order for it to know which image to pick. In our case, we set the image size to 960px, if the viewport is larger than 960px. If the viewport is less than or equal to 960px, we set the image size to 100% of the viewport width minus some padding on the left and right (generally between 16px to 32px). This way, the image doesn't butt against the window edges.

This effective size is used by the browser, along with the screen’s DPR (and possibly other factors) to figure out which resource would be the best to download and display.

Going back to our code, assuming we’re running with a browser viewport of 960px, the browser will go over the sizes pairs and pick the first one: (max-width: 960px). That would indicate it that the image is likely to be displayed at nearly the full width of the viewport (960px - 32px = 928px), so assuming a DPR of 1, the browser is likely try to download the first resource that is larger than 928px wide and end up downloading cc-cookie-large.jpg. If the pixel density of the device is 2, in order to match the screen’s density the required resource needs to be twice as large, so the browser will probably download the first resource larger than 1920px, which would be cc-cookie-huge.jpg... but we deliberately capped the largest image to be 960px, so the image is still cc-cookie-large.jpg.

Now, if our viewport is 640px, the (max-width: 960px) still applies, and the image is likely to take up nearly the full width of the viewport (as before). That means the image picked it probably the first one larger than 320px for 1x screens and 640px for 2x screens, and the downloaded resources are likely to be identical in both cases.

Why did I use all of those "likely"s and "probably"s above? Because for the resources inside srcset, the browser is free to pick whatever resource its algorithms see fit. That means that you, as a content editor, can't rely on the browser downloading and displaying the exact resource you want it to. That's a Good Thing™, since it leaves the browser room to innovate in this space, by adding user preferences, network considerations, and other future optimizations to the decision-making process. And since all of the different resources should only differ in quality, differing resource choices shouldn’t have any impact on your page's layout.

My Head Hurts

You asked. Mine does too. Thankfully, you don't have to do all of these calculations: the application (Drupal) and the browser will do it for you. The above code is slightly different depending on which variant you choose.

All this to say, however, that you don't have much control over what your images will be sized at. Your best bet is to upload images of at least 960px, and let the browser and the application handle the rest.

We haven't talked about Hero images yet!

Hero Images

Started with this image (download from EPA's account at Flickr) (2048x1640). When we originally uploaded it to Drupal 7, it got cropped to 731x350.

This original image migrated to Drupal 9. When we upload the same original image to D9, it gets cropped to 2048x820 Note that we focal pointed the image to crop it more sensibly On my laptop screen, the image was 1280px wide. The height varies based on the callout box text. The original image is here (2048x1640)

Medium Image

This image is the original image set to use the Medium variant.

Small Image

This image is the original image set to use the Small variant.

Thumbnail Image

This image is the original image set to use the Thumbnail variant.

Original Image

This image is the original image.

Administrator Regan at the podium at EPA HQ

It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness, it was the epoch of belief, it was the epoch of incredulity, it was the season of Light, it was the season of Darkness, it was the spring of hope, it was the winter of despair, we had everything before us, we had nothing before us, we were all going direct to Heaven, we were all going direct the other way - in short, the period was so far like the present period, that some of its noisiest authorities insisted on its being received, for good or for evil, in the superlative degree of comparison only. It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness, it was the epoch of belief, it was the epoch of incredulity, it was the season of Light, it was the season of Darkness, it was the spring of hope, it was the winter of despair, we had everything before us, we had nothing before us, we were all going direct to Heaven, we were all going direct the other way - in short, the period was so far like the present period, that some of its noisiest authorities insisted on its being received, for good or for evil, in the superlative degree of comparison only. It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness, it was the epoch of belief, it was the epoch of incredulity, it was the season of Light, it was the season of Darkness, it was the spring of hope, it was the winter of despair, we had everything before us, we had nothing before us, we were all going direct to Heaven, we were all going direct the other way - in short, the period was so far like the present period, that some of its noisiest authorities insisted on its being received, for good or for evil, in the superlative degree of comparison only.