WordPress Image Dimensions And The Layout Shift Problem

Cumulative Layout Shift (CLS) is one of the Core Web Vitals. It measures how much the visible page layout shifts unexpectedly during loading. The largest contributor to CLS on most WordPress sites is images that load without explicit width and height dimensions.

The fix is mechanical: add width and height attributes to image elements. The browser uses the attributes to reserve space before the image loads, preventing the layout shift when the image arrives. The fix is documented but commonly missed in theme code, custom blocks, and content with embedded media.

How the layout shift happens

Without explicit dimensions: the browser parses the HTML, sees an <img> tag with no dimensions, doesn't know how big the image will be, renders the surrounding content collapsed (no space reserved for the image), then when the image loads, pushes the content down to make room.

The user sees: the page renders with text first, then content suddenly jumps as images load. The jumping is disorienting and is the CLS.

With explicit dimensions: the browser reserves space matching the dimensions before the image loads. The image arrives and fills the reserved space. No layout shift.

The fix in HTML

Image elements should include width and height attributes:

<img src="image.jpg" width="800" height="450" alt="Description">

The dimensions can be any unit; pixels are standard. The browser uses the ratio to reserve space proportionally to the available width.

Responsive images: CSS can override the dimensions for actual display, but the HTML attributes are still needed for the aspect ratio reservation.

img { max-width: 100%; height: auto; }

This CSS makes the image responsive (scales to container width) while the HTML attributes (width/height) provide the aspect ratio.

What WordPress does correctly

WordPress added automatic width and height to images in the_content() output starting in version 5.5. Images inserted through the standard editor get dimensions automatically.

For most blog posts using the standard editor and uploading images normally, the dimensions are correct without any manual intervention.

The check: look at the rendered HTML of a typical post. The img tags should have width and height attributes. If they do, WordPress is handling it correctly for that content.

Where the fix gets missed

Theme template code that outputs images directly. Custom theme templates that use functions like get_post_thumbnail() might output images without dimensions if the template author didn't include them.

The fix in theme code:

<?php
$thumb_id = get_post_thumbnail_id();
$thumb = wp_get_attachment_image_src($thumb_id, 'large');
?>
<img src="<?php echo $thumb[0]; ?>" width="<?php echo $thumb[1]; ?>" height="<?php echo $thumb[2]; ?>" alt="...">

The wp_get_attachment_image_src function returns the URL, width, and height. Use all three.

Custom blocks that render images. Block developers sometimes output img tags without dimensions. The fix is the same: include the dimensions in the block's rendered output.

Content from third parties: embedded videos, social media embeds, ad networks. The third-party HTML may not include dimensions. The fix depends on the source; sometimes wrapping in a sized container helps.

SVG images used as decorative elements. SVGs need either explicit dimensions in the SVG markup or in the <svg> element attributes.

The aspect-ratio CSS property

Modern CSS has an aspect-ratio property that can specify the ratio without specific dimensions:

.responsive-image-container { aspect-ratio: 16 / 9; }

The container reserves space matching the ratio. Useful for cases where the exact dimensions aren't known but the aspect ratio is.

The pattern: wrap dynamic content in a container with aspect-ratio set. The container provides the layout reservation; the dynamic content fills it.

The font loading contribution to CLS

Beyond images, custom fonts contribute to CLS. The pattern: text renders with a fallback font initially, then switches to the custom font when it loads. The font swap causes the text size to change slightly, which shifts layout.

The fix: use font-display: swap and configure the fallback font to closely match the dimensions of the custom font. CSS size-adjust property can fine-tune the fallback dimensions to minimize the swap shift.

For most sites, the font CLS contribution is smaller than the image CLS contribution. Address images first; address fonts as a secondary optimization.

The ad and embed contribution

Ads and embedded content (Twitter, Instagram, YouTube) can cause CLS when they load and push content around. The fix is to reserve space for them.

For ads: define minimum dimensions for the ad slot in CSS. The ad loads into the reserved space rather than expanding it dynamically.

For embeds: wrap in a container with explicit aspect ratio. YouTube embeds typically use 16:9; Instagram embeds vary; Twitter embeds vary.

The CLS contribution from ads is often the hardest to control because ad networks change ad dimensions dynamically. The defensive approach: set the largest expected dimensions, accept some empty space when smaller ads load.

The verification approach

Measure CLS using PageSpeed Insights (lab data) and Search Console (field data).

For specific pages with CLS issues, use Chrome DevTools Performance panel. Record a page load and identify which elements cause layout shift in the trace.

The targeted approach reveals which specific elements need fixing. The fixes are then specific to those elements rather than blanket changes.

The maintenance discipline

The CLS fix isn't one-time. New content can introduce new CLS sources:

Theme updates might change how images are rendered.

New plugins might add content without proper dimensions.

New embedded content might not have aspect-ratio handling.

The discipline: check Search Console's Core Web Vitals report periodically. New CLS issues appear there over time. Address them as they emerge.

For sites with significant CLS issues that aren't obvious, automated monitoring (DebugBear, SpeedCurve) can catch regressions before users do.

The honest framing

CLS issues are usually mechanical to fix once identified. The harder part is knowing they exist.

The pattern that works: build CLS awareness into theme development and content creation. Theme templates always include image dimensions. New plugin choices are evaluated for CLS impact. New embedded content gets containerized.

The discipline pays off in passing Core Web Vitals consistently. The CLS metric is often the easiest of the three to fix because the issues are usually obvious once identified. Many sites pass LCP and INP but fail CLS for fixable reasons.

For sites that haven't audited CLS, this is worth a few hours of investigation. The Search Console report identifies problem URLs; the Chrome DevTools trace identifies specific elements; the fix is usually adding width and height attributes.