useLayoutEffect — React Deep Dive

useEffect vs useLayoutEffect: same signature, different timing

Both hooks share the signature useXxxEffect(setup, deps). The ONLY difference is when the setup function runs relative to the browser paint. useEffect is asynchronous — the browser paints first, THEN the effect runs, so the user may briefly see a stale DOM. useLayoutEffect is synchronous — it runs after DOM mutation but BEFORE paint, so any setState inside it produces a re-render that the user sees as one flicker-free frame.

phase	what happens	which hook runs
1. render	React calls your component, computes the virtual DOM	—
2. commit	React mutates the real DOM to match the virtual DOM	—
3. layout	`useLayoutEffect` setup runs synchronously — can read layout (`offsetWidth`, `getBoundingClientRect`), can `setState`	`useLayoutEffect`
4. paint	browser paints pixels to the screen — user sees the frame	—
5. passive	`useEffect` setup runs asynchronously — non-blocking, the user already saw the painted DOM	`useEffect`

1 · the measure-before-paint hook (edit me)

function LayoutEffectDemo() {
  var boxRef = React.useRef(null);
  var widthState = React.useState(0);
  var width = widthState[0];
  var setWidth = widthState[1];
  var heightState = React.useState(0);
  var height = heightState[0];
  var setHeight = heightState[1];
  var sizeState = React.useState(100);
  var size = sizeState[0];
  var setSize = sizeState[1];

  // useLayoutEffect: measure BEFORE paint — no flicker
  React.useLayoutEffect(function () {
    if (boxRef.current) {
      setWidth(boxRef.current.offsetWidth);
      setHeight(boxRef.current.offsetHeight);
    }
  }, [size]); // re-measure when size changes

  return (
    <div className="max-w-sm mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-3">
        useLayoutEffect: measure before paint
      </h2>

      {/*
        The box we measure. Its style.width/height come from `size` state,
        so changing `size` triggers a re-render AND a re-measure.
      */}
      <div
        ref={boxRef}
        data-testid="box"
        className="bg-[#61dafb] rounded mb-4 flex items-center justify-center text-[#0d1117] font-bold"
        style={{ width: size + 'px', height: size + 'px' }}
      >
        {size}×{size}
      </div>

      {/* Measured dimensions (set by useLayoutEffect, no flicker) */}
      <div className="p-3 bg-[#0d1117] rounded border border-[#30363d] text-sm">
        <p data-testid="dimensions">Measured: {width}×{height}px</p>
      </div>

      {/* Controls */}
      <div className="flex gap-2 mt-3">
        <button
          data-testid="grow"
          onClick={function () { setSize(function (s) { return s + 50; }); }}
          className="px-3 py-1 bg-[#61dafb] text-[#0d1117] rounded font-bold text-xs"
        >
          Grow +50
        </button>
        <button
          data-testid="shrink"
          onClick={function () { setSize(function (s) { return Math.max(50, s - 50); }); }}
          className="px-3 py-1 bg-[#30363d] text-[#e6edf3] rounded font-bold text-xs"
        >
          Shrink −50
        </button>
      </div>

      <p className="mt-3 text-xs text-[#8b949e]">
        Width/height update synchronously — no flicker because useLayoutEffect runs before paint.
      </p>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<LayoutEffectDemo/>);

2 · Babel compiles JSX → element tree

<LayoutEffectDemo/> becomes React.createElement(LayoutEffectDemo). After commit, React fires useLayoutEffect synchronously — it reads boxRef.current.offsetWidth, calls setWidth, and React re-renders BEFORE the browser paints.

// (hit "compile & render" to see Babel's output)

3 · live React (measure-before-paint, proven)

Click Grow +50 / Shrink −50: the Measured: W×Hpx line updates in the SAME frame as the box resize. The gold-check asserts the sync pipeline: initial 100×100 → Grow 150×150 → Grow 200×200 → Shrink 150×150. If we used useEffect instead, you would see one painted frame with a stale measurement before it corrected.

dimensions: — · gold: 100×100 → Grow → 150×150 → Grow → 200×200 → Shrink → 150×150

intent → hook

intent	hook	why
data fetching, subscriptions, logging	`useEffect`	non-blocking; user shouldn't wait on a network round-trip before paint
measure element size/position before showing it	`useLayoutEffect`	reads `offsetWidth`/`getBoundingClientRect` before paint — no flicker
scroll to a position right after content mounts	`useLayoutEffect`	sets `scrollTop` before the user sees the wrong scroll offset
position a tooltip/popover relative to an anchor	`useLayoutEffect`	measures the anchor box, computes coords, paints once — no jump
animate from `0` to a measured value	`useLayoutEffect` + `useState`	read the target size, then animate; otherwise the first frame is wrong
SSR (no real DOM)	`useEffect` or `useInsertionEffect`	`useLayoutEffect` warns on the server — wrap in `typeof window !== 'undefined'` or use a `useIsomorphicLayoutEffect` shim