Images Causing Layout Shift

Why an unsized image moves the page

A browser lays out a page before most of its files have arrived. When it reaches an <img> tag, it needs a width and a height to know how much room to leave. If the tag says nothing about size and no CSS rule fixes the height, the browser has to guess, and its guess is zero pixels tall. The paragraph after the image is placed directly under the heading above it.

A moment later the image data downloads. The browser now reads the picture's real pixel size from the file header, works out how tall it should be at the current width, and re-lays out the page. The paragraph that was sitting just under the heading is now several hundred pixels lower. That jump is a layout shift, and the CLS Debugger will report the paragraph, and everything after it, as the elements that moved.

How the attributes fix it

Modern browsers use the width and height attributes on an image in a clever way. Their default stylesheet turns the two numbers into an aspect ratio, roughly equivalent to aspect-ratio: auto 1200 / 800. So even when your CSS makes the image fluid with width: 100%, the browser can calculate the right height for whatever width the column happens to be, before a single byte of the file has arrived. The box is reserved, the text is placed underneath it, and nothing moves when the picture fills in.

This is why the attributes do not have to match the displayed size. They describe the shape of the image. A 1600 by 900 photo shown at 400 pixels wide is fine with width="1600" height="900", as long as your CSS lets the height follow the width.

Proving it is an image and not something else

A paragraph moving down does not always mean an image above it was unsized. Fonts, ad slots and banners produce the same symptom. Before editing templates, make sure the mover and the cause line up.

1. Run the CLS Debugger on the page and note the largest shifts and the elements it names. Look at what sits directly above each named element in the page.
2. In Chrome DevTools, open the Network panel, set throttling to a slow profile and tick Disable cache. Reload and watch the page. An image problem looks distinctive: text appears, then a picture pops in and the text drops by roughly the height of the picture.
3. Open the Elements panel, select the image and look at its tag. If there are no width and height attributes, check the Computed tab for aspect-ratio and height. If the computed aspect ratio is auto with no numbers and the height is auto, the browser had nothing to reserve.
4. As a quick proof, block the image in the Network panel (right-click the request and choose block request URL) and reload. If the page no longer jumps at that point, the image was the cause.

You can also list every image on a loaded page that is missing size information by pasting this into the console:

[...document.images].forEach((img) => {
  const cs = getComputedStyle(img);
  const sized = img.getAttribute('width') && img.getAttribute('height');
  if (!sized && cs.aspectRatio === 'auto') {
    console.log(img.currentSrc || img.src, img);
  }
});

Anything it prints is an image the browser could not size before download, unless a fixed CSS height is doing the job instead.

The fix, step by step

Before and after markup

Here is the pattern that causes the problem, followed by the corrected version. The business, file names and sizes are fictional.

<!-- Before: no size information, so the box starts at zero height -->
<img src="/media/greenbank-bakery-shopfront.jpg" alt="Greenbank Bakery shopfront">

<!-- After: intrinsic size in attributes, fluid in CSS -->
<img src="/media/greenbank-bakery-shopfront.jpg"
     width="1600" height="1067"
     alt="Greenbank Bakery shopfront">

/* In the stylesheet */
img {
  max-width: 100%;
  height: auto;
}

/* A cropped card image that must always be square */
.card img {
  width: 100%;
  aspect-ratio: 1 / 1;
  object-fit: cover;
}

Background images in CSS

A hero section that uses background-image has no intrinsic size at all, because the element's height comes from its content, not from the picture. That usually causes no shift on its own. The problem appears when a script measures the image and then sets the section's height, or when the section is empty until the image loads. Set the size up front:

.hero {
  background: #e8e2d8 url("/media/hero-kitchen.jpg") center / cover no-repeat;
  aspect-ratio: 21 / 9;
  min-height: 280px;
}

The background colour gives a calm placeholder while the file downloads, and the box never changes size.

Images inside flex and grid layouts

Inside a flex row, an image with height: auto and attributes behaves well, but a rule like align-items: stretch on the parent, or min-width: 0 missing on a flex child, can make the reserved ratio be ignored until load. If a card grid still jumps after adding attributes, inspect the card and check whether the image wrapper has its own height set by the flex or grid algorithm. Giving the wrapper an explicit aspect-ratio is the most reliable fix.

Awkward cases and how to handle them

If a picture swaps between files with different proportions at different screen sizes, for example a wide banner on desktop and a tall one on phones, that is a different problem with a different fix, covered in fixing CLS from responsive image swap.

Where the tags come from on common platforms

The fix is the same everywhere, but where you apply it depends on how your site generates image tags.

• WordPress. Core adds dimensions to images inserted through the block editor from the media library, but page builders, older themes, custom fields and shortcodes often print bare tags. Check the template or widget that outputs the tag rather than the post content. Plugin-specific patterns are covered in CLS in WordPress.
• Shopify. Liquid's image_tag filter outputs width and height from the image object, while hand-written <img src="{{ image | image_url }}"> tags in older themes do not. See CLS in Shopify for theme and app specifics.
• React and Next.js. The Next.js image component requires a width and height, or a fill mode inside a sized parent, which is designed to prevent this problem. Plain <img> tags in components need attributes like any other HTML.
• Static sites and hand-written HTML. Build tools and static site generators can read file dimensions at build time and write them into the tag. If yours cannot, add them by hand for the images above the fold first.

Keeping new images sized

Image shifts tend to come back quietly, because new content is added every week by people who are not thinking about layout. A few habits keep the problem closed:

• Make the template responsible. The code that renders an image should always add width and height from stored metadata. Editors should never have to type them.
• Add a check to your build or review process. A simple test that fails when an <img> tag in the output lacks both attributes catches regressions before they go live.
• Standardise crops. Where a layout has fixed shapes, such as square product cards or 16:9 article thumbnails, crop images to that shape on upload or in the image service so the ratio is always predictable.
• Re-run the debugger after redesigns. New themes and new components are the most common time for bare image tags to reappear.

For how image dimensions fit with compression, formats and lazy loading more generally, see the image optimisation fixes.