useLayoutEffect

1Same Signature, Different Timing

useLayoutEffect has the exact same signature as useEffect — a callback that can return a cleanup function, plus a dependency array — but React runs it at a different point in the render cycle: synchronously, after DOM mutations are committed, but before the browser paints the screen.

import { useLayoutEffect, useRef, useState } from "react";

function Measured() {
  const boxRef = useRef<HTMLDivElement>(null);
  const [width, setWidth] = useState(0);

  useLayoutEffect(() => {
    const rect = boxRef.current!.getBoundingClientRect();
    setWidth(rect.width); // read the DOM, then update state — BEFORE the user sees anything
  }, []);

  return <div ref={boxRef}>Measured width: {width}px</div>;
}

Because the measurement and the resulting state update both happen before paint, the user never sees an intermediate "0px" frame — the DOM read and the visual correction are invisible to them.

2Timing Comparison

Commit → Paint → useEffect runs        (a flash CAN happen between commit and the fix)
Commit → useLayoutEffect runs → Paint   (no flash possible — fix happens before paint)

3The Canonical Use Case: Measure, Then Adjust

Any pattern that reads a DOM node's actual rendered geometry and then immediately uses that to change what's on screen is the textbook case for useLayoutEffect:

function Tooltip({ anchorRef, children }: { anchorRef: React.RefObject<HTMLElement>; children: React.ReactNode }) {
  const tooltipRef = useRef<HTMLDivElement>(null);
  const [style, setStyle] = useState<React.CSSProperties>({ visibility: "hidden" });

  useLayoutEffect(() => {
    const anchorRect = anchorRef.current!.getBoundingClientRect();
    const tooltipRect = tooltipRef.current!.getBoundingClientRect();

    // flip above the anchor if there isn't room below, so it never renders off-screen
    const top =
      anchorRect.bottom + tooltipRect.height > window.innerHeight
        ? anchorRect.top - tooltipRect.height
        : anchorRect.bottom;

    setStyle({ position: "fixed", top, left: anchorRect.left, visibility: "visible" });
  }, [anchorRef]);

  return <div ref={tooltipRef} style={style}>{children}</div>;
}

Tooltip/popover repositioning, animation start-position setup, and scroll-position restoration all share this shape: read layout → compute → write layout, all before the user's eyes get a chance to see the "wrong" intermediate frame.

4Default to useEffect

Most effects — data fetching, subscriptions, logging, timers — have no visual synchronization requirement at all, and blocking paint for them only hurts perceived performance for no benefit. The rule: start with useEffect; switch to useLayoutEffect only if you can point to an actual visible flicker it fixes. If nothing on screen depends on the effect's DOM read, there's nothing for useLayoutEffect to protect against.

5Server Rendering Note

useLayoutEffect does nothing meaningful without a real browser DOM and a paint cycle — during server rendering there is no paint to run before. React prints a console warning if useLayoutEffect executes during SSR. The common fallback is to keep the effect as useEffect for any code path that might run on the server, or gate the layout-dependent logic so it only runs client-side (a pattern the Next.js ecosystem topics cover in depth — this is just the constraint to be aware of here).

⚠️ Common Pitfalls

1. Reaching for useLayoutEffect "to be safe" by default — it blocks paint for effects (data fetching, subscriptions, logging) that have no visual synchronization need at all, hurting perceived performance for nothing in return.
2. Putting expensive computation inside a layout effect — since it runs synchronously before every paint, a slow layout effect causes direct, visible jank; expensive work belongs in useEffect (or memoized outside the effect entirely) unless it truly must finish before paint.
3. Using it in code that might run during server rendering — there's no paint cycle on the server, so React emits a console warning; guard layout-dependent logic to client-only execution instead.
4. Forgetting the cleanup rules are identical to useEffect — the cleanup function runs before the next execution and on unmount, following the same dependency-diffing rules; useLayoutEffect doesn't change any of that, only the timing of when the effect body itself runs.

📋 Quick Reference

useLayoutEffect(() => { ...; return cleanup; }, [deps])   → same API shape as useEffect

Commit → Paint → useEffect runs           → async, after paint, can flash
Commit → useLayoutEffect runs → Paint      → sync, before paint, no flash, can block

Default: useEffect
Switch to useLayoutEffect only for: DOM measure-then-adjust that would otherwise flicker

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: react_uselayouteffect_theory.md · generated by tools/build_lessons.py