Fixing Layout Shift From CSS

How CSS causes layout shift

Cumulative Layout Shift (CLS) is the Core Web Vital that measures unexpected movement. The browser records a layout shift whenever an element that was already visible changes its position in the layout between two frames, and scores it by how much of the viewport moved and how far. Google treats a CLS of 0.1 or less at the 75th percentile of page loads as good. Shifts that happen within half a second of a tap, click or key press are excluded, because the visitor expected something to change.

CSS is involved in almost every shift, but in this guide we mean cases where the stylesheet is the cause rather than just the place you apply the fix:

The CSS Checker flags CSS-driven layout shift, where text and blocks jump as fonts or late styles arrive. For shifts from images without dimensions, adverts, cookie banners, embeds and dynamic content, see CLS Debugger Fixes.

Proving the cause in developer tools

Guessing at layout shift wastes time, because several causes can look the same. Capture the evidence first.

See the shifts as they happen

In Chrome developer tools, open the command menu (Ctrl+Shift+P or Cmd+Shift+P), type "rendering" and open the Rendering tab. Tick Layout Shift Regions. Reload the page and any area that moves flashes with a coloured overlay. Throttle the network to a slow profile in the Network panel first, because many CSS shifts only appear when fonts and stylesheets arrive late.

Find the element and the moment

Record a page load in the Performance panel. Layout shifts appear as markers on their own track; select one to see which nodes moved and their before and after positions. Line the marker up with the network track: if it sits just after a font file or stylesheet finishes downloading, you have found your cause.

Log shifts from the page itself

Paste this into the console before reloading, or add it temporarily to the page, to list every shift and the elements involved:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput) continue;
    console.log('shift', entry.value.toFixed(4), 'at', Math.round(entry.startTime), 'ms');
    for (const s of entry.sources || []) {
      console.log('  moved:', s.node, s.previousRect, '->', s.currentRect);
    }
  }
}).observe({ type: 'layout-shift', buffered: true });

The logged node is the element that moved, which is not always the element that caused the move. If a paragraph moved, look at what is above it: a heading whose font swapped, a box that grew, or a header that changed position.

Late stylesheets and incomplete critical CSS

A stylesheet linked normally in the head blocks rendering, so it cannot cause a shift: the browser waits for it. Shifts start when CSS is made non-blocking to speed up first paint and the first paint is then drawn with incomplete styles. Common versions:

• Critical CSS that misses layout rules. The inlined rules style the header and hero but not the grid below, so the grid appears as a single column and then snaps into place when the full stylesheet arrives.
• Critical CSS generated at one screen size. A tool extracts rules for a desktop viewport, and phones get a first paint with the wrong layout.
• Style blocks injected late. A plugin, widget or CSS-in-JS library adds rules to the page after some content has rendered.
• @import inside a deferred file. The imported file arrives even later and restyles again.

The test is simple: block the main stylesheet in the Network panel (right-click the request and choose Block request URL) and reload. What you see is your first paint. Anything that looks different from the final page above the fold, in size or position rather than just colour, will move when the stylesheet lands.

The fix is to make sure every rule that affects the size or position of above-the-fold elements is in the critical CSS, for each template and at phone and desktop widths. Colours, shadows and hover states can wait; widths, heights, display modes, grid templates, margins, padding, font sizes and line heights cannot. The render-blocking CSS guide covers generating critical CSS; here the point is that it must be complete for layout, not just for looks.

Font swaps and fallback metrics

When a web font has not arrived yet, the browser draws text in a fallback font. When the web font arrives, text is redrawn. If the two fonts have different widths, heights or line spacing, lines rewrap and every block below moves. That is a CSS problem with a CSS answer: make the fallback occupy the same space as the web font.

The @font-face descriptors size-adjust, ascent-override, descent-override and line-gap-override let you define an adjusted version of a local font that closely matches your web font's metrics:

@font-face {
  font-family: "Brand Sans Fallback";
  src: local("Arial");
  size-adjust: 104%;
  ascent-override: 92%;
  descent-override: 24%;
  line-gap-override: 0%;
}

body {
  font-family: "Brand Sans", "Brand Sans Fallback", sans-serif;
}

The numbers above are placeholders; the right values depend on your font. Framework font tools such as the one built into Next.js calculate them automatically, and there are free generators that read a font file and output the descriptors.

The font-display descriptor decides what happens while the font loads. swap shows fallback text immediately and swaps later, which is good for reading but can shift unless the fallback is matched. optional uses the web font only if it is available almost immediately, otherwise it keeps the fallback for that page view, which avoids the swap shift entirely at the cost of sometimes not showing your font on a first visit. Preloading the one or two font files used above the fold makes either option work better.

Font loading itself, including subsetting, hosting and preloading, is covered in depth in Fixing CLS from web fonts.

The fix, step by step

Reserving space with CSS

Several newer CSS properties exist specifically to give boxes a size before their content decides it.

aspect-ratio

.video-wrap { aspect-ratio: 16 / 9; width: 100%; }
.map-embed  { aspect-ratio: 4 / 3; }
img, video  { max-width: 100%; height: auto; }

Browsers turn an image's width and height attributes into an aspect ratio automatically, as long as your CSS does not override the height with a fixed value. A stylesheet rule such as img { height: 100%; } in a container with no height can undo that protection, so check global image rules if images shift despite having dimensions.

contain-intrinsic-size with content-visibility

content-visibility: auto skips rendering off-screen sections, which speeds up long pages. Without a size hint those sections are treated as zero height until they come near the viewport, so the scrollbar and anything anchored below them can jump as they render. The auto keyword tells the browser to remember the real size once it has been rendered:

.article-section {
  content-visibility: auto;
  contain-intrinsic-size: auto 800px;
}

scrollbar-gutter

On desktop systems with classic scrollbars, a page that starts short and becomes scrollable when content loads gains a scrollbar, and centred layouts nudge sideways. Reserving the gutter prevents that:

html { scrollbar-gutter: stable; }

Animations, sticky headers and state classes

An animation that changes top or margin moves the element in the layout, and often pushes its neighbours. If it runs without the visitor doing anything, each frame can count as a layout shift. Transforms move the painted element without changing layout, so they do not produce layout shifts and are also cheaper for the browser.

/* Shifts content below on every frame */
.notice { transition: margin-top 0.3s; }
.notice.is-hidden { margin-top: -60px; }

/* Moves visually, layout stays put */
.notice { transition: transform 0.3s, opacity 0.3s; }
.notice.is-hidden { transform: translateY(-100%); opacity: 0; }

Sticky headers are a common hidden cause. A script that changes a header from normal flow to position: fixed after some scrolling removes it from the layout, so all the content jumps up by the header's height. Because this happens during scrolling, not after an input, it counts. position: sticky keeps the header in the flow and avoids the jump; if you must use fixed, keep a placeholder of the same height.

Also watch for a .js or .loaded class added to the root element after scripts run, with rules that change layout. Anything keyed off such a class should change appearance only, not size or position, or be matched by equivalent rules for the pre-script state.