Fixing Layout Shift in React and Next.js

Why React apps shift differently

With server rendering, whether through Next.js, Remix, React Router or a custom setup, the browser first paints HTML generated on the server. Then React loads, hydrates that HTML and takes over. If the first client render produces exactly the same markup, nothing moves. Every difference between the two is a chance for a layout shift.

A purely client-rendered app, such as one built with Vite and no server rendering, shows an empty root first. Blank content cannot shift, but the app then renders in stages as data arrives, and each stage that pushes earlier content aside is counted.

There is one more difference. For Core Web Vitals, a single-page app is measured as one long page view. Client-side route changes do not start a new measurement, so a shift on the third screen a visitor opens adds to the same page's CLS. Shifts are grouped into session windows and the worst window is reported, so a bad transition can set the score even if the landing view was perfect.

Hydration mismatches

When the markup React renders in the browser does not match the server HTML, React reports a hydration error. In development you see it in the console. In production, React recovers by discarding the server HTML for the affected part of the tree, up to the nearest Suspense boundary or the whole root, and rendering it again on the client. The visitor sees the page flash and often shift, because the re-rendered version may be a different size.

The usual causes:

• Values that differ by time or place. new Date(), Date.now(), Math.random() and toLocaleString() give different results on the server and in the visitor's browser, which may be in a different time zone or locale.
• Browser-only checks in render. typeof window !== 'undefined' branches, localStorage reads and cookie reads in the render path produce one output on the server and another on the client.
• Invalid HTML nesting. A <div> inside a <p>, or a link inside a link, is corrected by the browser's parser before React sees it, so the DOM no longer matches.
• Browser extensions and injected scripts that add elements before hydration. You cannot control these, but they are worth ruling out when a mismatch only happens on one machine.

Fix the source rather than silencing the warning. suppressHydrationWarning only covers text content of a single element, such as a timestamp, and does nothing for structural differences. For values that must differ, render a stable value on the server (for example a date formatted in a fixed time zone) and update it in an effect, keeping the same element size.

Client-only components

A very common pattern is to wait until the component has mounted before showing anything:

function StockBadge({ sku }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null;              // nothing on the server
  return <p className="stock">{getLocalStock(sku)}</p>;
}

This avoids a hydration error but guarantees a shift: the server HTML has nothing, and after hydration a paragraph appears and pushes the content below. The fix is to render something the same size on the server:

if (!mounted) return <p className="stock stock--pending" aria-hidden="true"></p>;

/* CSS */
.stock { min-height: 1.5em; margin: 0 0 12px; }

The same applies to components loaded with next/dynamic and ssr: false, or with React.lazy. Pass a loading component (or a Suspense fallback) that occupies the final space. A chat launcher or other element in a fixed position can safely appear late, because it does not sit in the page flow.

Layout decided in JavaScript

Hooks that read the window size during render are one of the largest sources of React CLS. The server has no window, so it renders a default, usually the desktop layout. A phone then hydrates, the hook reports a narrow screen, and the component switches to its mobile layout: a different navigation, a stacked grid, a shorter hero. Everything moves.

// Shifts on phones: server always renders the desktop branch
const isMobile = useMediaQuery('(max-width: 768px)');
return isMobile ? <MobileNav /> : <DesktopNav />;

Move the decision to CSS, which the browser applies before first paint:

<MobileNav className="nav-mobile" />
<DesktopNav className="nav-desktop" />

.nav-mobile { display: none; }
@media (max-width: 768px) {
  .nav-mobile { display: block; }
  .nav-desktop { display: none; }
}

Rendering both costs a little extra HTML but removes the swap. Keep JavaScript breakpoints for behaviour that does not change layout, such as whether to attach a swipe handler. The same applies to masonry grids and "fit to container" components that measure elements in an effect: use CSS grid, aspect-ratio and container queries where you can.

Suspense, streaming and loading states

A Suspense boundary shows its fallback while the content inside it is loading, then swaps the content in. The swap is a normal DOM change: if the fallback is 48 pixels tall and the content is 600, the content below moves 552 pixels.

• Make fallbacks skeletons of the right size. A product grid fallback should be a grid of placeholder cards at the real card height, per breakpoint, not a centred spinner.
• Place boundaries around fixed-size regions. A boundary that wraps a sidebar widget with a known height is easy to reserve. One that wraps half the page is not.
• App Router loading files. In Next.js, loading.tsx renders while a route segment streams. Build it to mirror the page's layout, with the heading, image area and text blocks in the same positions.
• Data fetched in effects. Components that fetch in useEffect render an empty or loading state first. Give that state the final dimensions, or fetch on the server so the first HTML already contains the data.

Using the Next.js helpers correctly

next/image

The Image component requires width and height props unless you statically import the file (in which case Next.js reads the dimensions at build time) or use the fill prop. Those numbers set the aspect ratio of the reserved box; the image can still be displayed responsively. With fill, the image takes the size of its parent, so the parent needs position: relative and a size of its own, typically from aspect-ratio. A fill image inside a parent with no height is a zero-height box that jumps open. For images from a CMS, request the width and height from the API and pass them through.

next/font

next/font downloads Google fonts at build time and serves them from your own domain, and supports local font files. By default it uses display: 'swap' and generates a fallback font adjusted with size-adjust and related descriptors (the adjustFontFallback option), so the swap moves text very little. The benefit is lost if the same family is also loaded with a <link> to Google Fonts or an @import in global CSS, so remove those. Font behaviour in general is covered in the web fonts guide.

CSS-in-JS

Libraries that generate styles at runtime must also collect them on the server and include them in the HTML. If they do not, the first paint is unstyled or partly styled, and the page jumps as styles are injected. With the App Router this means setting up the library's style registry; with the Pages Router, a custom document. Zero-runtime options such as CSS Modules or Tailwind avoid the issue.

The fix, step by step

Reporting CLS from the app

import { onCLS } from 'web-vitals/attribution';

onCLS(({ value, attribution }) => {
  navigator.sendBeacon('/analytics/cls', JSON.stringify({
    value,
    target: attribution.largestShiftTarget,
    path: location.pathname,
  }));
});

The CLS value can be reported more than once as the visit continues, and the final report usually happens when the tab is hidden. Keep the latest value per visit rather than adding them up. Group results by route and by the reported target selector: a single component often turns out to be behind most of the poor scores.