useLayoutEffect — Synchronous DOM Reads

Why this matters

useLayoutEffect fires synchronously after React mutates the DOM but before the browser paints. This makes it the correct tool when you need to read a DOM measurement (getBoundingClientRect, scrollHeight) and immediately apply a visual adjustment — doing the same read in useEffect would show a frame where the adjustment hasn't been applied yet, causing a visible flash or layout jump. The cost is real: synchronous work in useLayoutEffect is on the critical rendering path. Reserve it strictly for DOM measurement-then-adjustment flows; useEffect handles everything else.

Demo

useLayoutEffect runs synchronously after DOM mutations, before paint. Use it when you need to read layout and apply a style change without the user seeing an intermediate state.

import { useRef, useState, useLayoutEffect, useEffect } from 'react';

// useLayoutEffect: tooltip positions itself BEFORE paint — no flash
export function Tooltip({ text }: { text: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [style, setStyle] = useState<React.CSSProperties>({});

  useLayoutEffect(() => {
    const el = ref.current;
    if (!el) return;
    const { right } = el.getBoundingClientRect();
    if (right > window.innerWidth) {
      // nudge left before the browser has a chance to paint
      setStyle({ transform: 'translateX(-100%)' });
    }
  }, [text]);

  return (
    <div ref={ref} style={{ position: 'absolute', ...style }}>
      {text}
    </div>
  );
}

// useEffect: same code but causes a visible flicker
export function FlickyTooltip({ text }: { text: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [style, setStyle] = useState<React.CSSProperties>({});

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const { right } = el.getBoundingClientRect();
    if (right > window.innerWidth) {
      setStyle({ transform: 'translateX(-100%)' });
      // setState triggers a second render AFTER the first painted frame — flash!
    }
  }, [text]);

  return <div ref={ref} style={{ position: 'absolute', ...style }}>{text}</div>;
}

Try it yourself

1. Render both Tooltip and FlickyTooltip with a long text string near the right edge of the screen. Slowly resize the window until the tooltip would overflow. With Tooltip you should see no flash; with FlickyTooltip you should see a brief flicker as it repositions.
2. In useLayoutEffect, add console.time('layout') at the start and console.timeEnd('layout') at the end. Do the same in a useEffect version. Compare the times — both should be similar, but the layout version blocks the paint thread.
3. Add an artificial while (Date.now() < Date.now() + 50) {} (50ms busy loop) inside useLayoutEffect. Notice the entire frame is delayed — the browser won't paint until useLayoutEffect completes. Do the same in useEffect and observe the component renders first, then the effect fires.
4. Open React DevTools Profiler and record a render. In the flame chart, find the 'Layout Effects' phase. Confirm it appears before the commit phase ends, unlike 'Passive Effects' which appear after.

Prompt your AI

Use these three in order. Each builds on the one before.

1. Basics & terminology

In one paragraph, explain when to use useLayoutEffect instead of useEffect. What would go wrong with useEffect in the tooltip repositioning example?

2. Why it works (the mechanism)

Walk me through the React commit phase. In what order do useLayoutEffect, DOM mutations, browser paint, and useEffect fire? Why does useLayoutEffect's synchronous execution prevent the flash that useEffect causes?

3. Advanced — application & what's next

useLayoutEffect on the server throws a warning because there is no DOM to read. How do libraries like Radix UI and Floating UI handle this — and what's the pattern for writing a hook that uses useLayoutEffect on the client without crashing on the server?

References

• React docs — useLayoutEffect
• Kent C. Dodds — useEffect vs useLayoutEffect
• React source — commit phase ordering