Image Layout Shift: Fixing It at the Pipeline Level

Why the pipeline should own image dimensions

A browser can only hold space for an image before it downloads if the HTML tells it the image's shape. Current browsers turn the width and height attributes into a default aspect ratio, so an image styled with width: 100%; height: auto gets a correctly shaped empty box straight away. The mechanics of that, and the CSS that goes with it, are covered in the CLS Debugger guide to images causing layout shift. This page deals with a different question: where the numbers should come from.

On a small static site you can type them in. On anything with a CMS, a shop, user uploads or a content team, typed numbers fail in predictable ways:

• Nobody knows them. Editors upload a photo and pick it from a library; they never see its pixel size.
• They go stale. Someone replaces a 4:3 photo with a 16:9 one under the same file name, and the old numbers stay in the template.
• They are guessed. A developer writes width="800" height="600" on a template that shows images of every shape. The box is right for some and wrong for the rest.

Every system that handles images already opens the file at some point: to make thumbnails, to convert formats, to upload it to storage. Reading the pixel dimensions at that moment costs almost nothing, and once they are stored alongside the image, every template can print them. That turns image layout shift from a recurring task into something that stays fixed.

Where to read true dimensions

Almost every image tool and content platform can tell you an image's width and height. The table shows where to get them in common setups.

The common thread is to take the numbers from the file itself, not from a form field or a naming convention. A file called hero-1600x900.jpg is only a promise.

The rotated phone photo trap

Phones and many cameras do not physically rotate the pixels when you hold them upright. They save the image in the sensor's landscape orientation and add an EXIF orientation tag telling software to rotate it for display. Browsers honour that tag, so a portrait photo appears upright. But a tool that reads the raw pixel size reports it as landscape.

The result is a subtle shift. The pipeline records 4032 by 3024, the template prints those numbers, the browser reserves a wide box, and when the image arrives the browser displays it upright, taller than the box. With height: auto the browser then uses the real ratio, and everything below moves down.

EXIF orientation values 5, 6, 7 and 8 mean the width and height are swapped for display. You have two safe options:

1. Rotate the pixels at ingest and remove the orientation tag, so what is stored is already upright. In sharp, calling rotate() with no arguments does this using the EXIF value; in Pillow, ImageOps.exif_transpose; in ImageMagick, -auto-orient.
2. Swap the recorded numbers when the orientation is 5 to 8, and keep the original pixels. This works but every later step has to remember the rule, so option one is usually simpler.

// Node.js with sharp: normalise orientation, then measure
import sharp from 'sharp';

export async function ingest(inputPath, outputPath) {
  const info = await sharp(inputPath)
    .rotate()                 // apply EXIF orientation to the pixels
    .toFile(outputPath);      // strips the orientation tag by default
  return { width: info.width, height: info.height };
}

When the image service changes the shape

Width and height only need to describe the ratio of the image that is actually delivered. If a 2400 by 1600 original is served at 800 by 533, the attributes can stay at 2400 and 1600, because the ratio is the same and CSS sets the display size. Problems start when something between storage and the browser changes the ratio.

Crops in image URLs

Image CDNs and platforms let you ask for a crop in the address, for example ?w=800&h=450&fit=crop for a 16:9 card from a 3:2 original. If the template still prints the original's dimensions, the browser reserves a 3:2 box and then receives a 16:9 image. Print the dimensions of the crop you asked for, which you already know because you wrote them in the URL.

Responsive sets with mixed ratios

Every file in one srcset should share the same ratio. If the pipeline generates a 400 pixel version that is square and a 1200 pixel version that is wide, one set of attributes cannot be right for both. Keep crops consistent within a set.

Art direction with the picture element

When a <picture> element deliberately shows a tall crop on phones and a wide one on desktops, each <source> can carry its own width and height, supported in current versions of the major browsers. Without them, every breakpoint uses the ratio from the fallback <img>.

<picture>
  <source media="(max-width: 600px)"
          srcset="/img/workshop-tall-600.webp"
          width="600" height="800">
  <source srcset="/img/workshop-wide-1600.webp"
          width="1600" height="900">
  <img src="/img/workshop-wide-1600.jpg"
       width="1600" height="900"
       alt="Carpenter planing a table top in the workshop">
</picture>

Your pipeline should output the dimensions for each crop it generates, so the template can fill in each source without anyone measuring.

Checking whether recorded numbers match reality

The Image Optimisation audit flags images that contribute to layout shift. To see whether the cause is missing numbers or wrong numbers, paste this into the browser console on a loaded page. It lists images whose attribute ratio differs from the ratio of the file actually delivered.

[...document.images].forEach(img => {
  const w = img.getAttribute('width'), h = img.getAttribute('height');
  if (!w || !h) { console.log('NO SIZE', img.currentSrc); return; }
  if (!img.naturalWidth) return; // not loaded yet
  const declared = w / h, actual = img.naturalWidth / img.naturalHeight;
  if (Math.abs(declared - actual) > 0.02) {
    console.log('WRONG RATIO', declared.toFixed(3), actual.toFixed(3), img.currentSrc);
  }
});

Scroll to the bottom first so lazy images have loaded. NO SIZE means the template never prints dimensions. WRONG RATIO means the numbers exist but describe a different image: a rotated original, an uncropped original, or a stale value from a replaced file. Group the results by template, because a wrong ratio on one product card usually means the same on all of them.

To confirm the effect, open the Performance panel in developer tools, record a page load with network throttling on, and look at the layout shift entries. Each one names the elements that moved, which lets you tie a shift back to a specific image.

The fix, step by step

Placeholders made at the same time

Reserving space stops the shift, but the reserved box is empty until the image arrives. The same pipeline step that measures an image can make something to show in the meantime, which improves how the page looks without affecting layout:

• A dominant colour. sharp's stats() returns a dominant colour you can store and set as the image's background colour.
• A tiny preview. A very small, blurred version of the image, a few hundred bytes, inlined as the background and replaced by the real image.
• A compact hash. Formats such as BlurHash and ThumbHash store a short string that a small script turns into a blurred preview.

None of these reserve space on their own. They sit inside a box whose size already comes from the width and height attributes. Keep them small: a placeholder that weighs as much as a thumbnail defeats the purpose.

Keeping it fixed

• Reject images without dimensions in the content model or build, rather than rendering them unsized. A build that fails loudly is better than a page that shifts quietly.
• Re-measure on replace. Make file replacement run the same ingest step as a new upload, so a new shape brings new numbers.
• Test with a portrait phone photo whenever the upload code changes, because it is the case most likely to break.
• Add the console check to a test in your end-to-end suite for key templates.
• Watch field CLS after theme and plugin updates, which sometimes replace image markup.

For the responsive sizes themselves, see fixing wrong image dimensions, and for lazy-loaded images, fixing lazy-loading.