useLayoutEffect vs useEffect

The Timing Difference

This is one of those things that seems like a tiny detail until you're staring at a flickering tooltip. Both hooks run after React commits DOM changes. The difference is when they run relative to the browser paint:

Render → Commit (DOM update) → useLayoutEffect → Browser Paint → useEffect

function Component() {
  useLayoutEffect(() => {
    // Runs BEFORE the browser paints.
    // You can read DOM and synchronously modify it.
    // The user never sees the intermediate state.
  });

  useEffect(() => {
    // Runs AFTER the browser paints.
    // The user has already seen the DOM.
    // If you modify DOM here, they see a flicker.
  });
}

When useLayoutEffect Is Required

So when do you actually need this? Three main scenarios.

1. Measuring DOM Before Paint

function Tooltip({ targetRef, children }) {
  const tooltipRef = useRef(null);
  const [position, setPosition] = useState({ top: 0, left: 0 });

  useLayoutEffect(() => {
    const targetRect = targetRef.current.getBoundingClientRect();
    const tooltipRect = tooltipRef.current.getBoundingClientRect();

    setPosition({
      top: targetRect.top - tooltipRect.height - 8,
      left: targetRect.left + (targetRect.width - tooltipRect.width) / 2,
    });
  }, [targetRef]);

  return (
    <div
      ref={tooltipRef}
      style={{
        position: 'fixed',
        top: position.top,
        left: position.left,
      }}
    >
      {children}
    </div>
  );
}

If this used useEffect, the tooltip would briefly appear at (0, 0) before jumping to the correct position — a visible flicker. useLayoutEffect measures and repositions before the user sees anything.

2. Preventing Visual Flicker

function AnimatedHeight({ isOpen, children }) {
  const contentRef = useRef(null);
  const [height, setHeight] = useState(0);

  useLayoutEffect(() => {
    if (isOpen) {
      setHeight(contentRef.current.scrollHeight);
    } else {
      setHeight(0);
    }
  }, [isOpen]);

  return (
    <div style={{ height, overflow: 'hidden', transition: 'height 300ms' }}>
      <div ref={contentRef}>{children}</div>
    </div>
  );
}

3. Scroll Restoration

function ChatMessages({ messages }) {
  const containerRef = useRef(null);

  useLayoutEffect(() => {
    // Scroll to bottom before user sees the new message
    containerRef.current.scrollTop = containerRef.current.scrollHeight;
  }, [messages.length]);

  return (
    <div ref={containerRef} style={{ height: 400, overflow: 'auto' }}>
      {messages.map(msg => <Message key={msg.id} message={msg} />)}
    </div>
  );
}

The SSR Warning

One more gotcha: useLayoutEffect does not run on the server because there is no DOM. React logs a warning in SSR:

Warning: useLayoutEffect does nothing on the server

Solutions:

// Option 1: Suppress by using useEffect with initial state
function Tooltip({ children }) {
  const [position, setPosition] = useState(null);

  useLayoutEffect(() => {
    // Measure and position
    setPosition(calculatePosition());
  }, []);

  if (!position) return null; // Render nothing until measured
  return <div style={position}>{children}</div>;
}

// Option 2: Use dynamic import for client-only components
// Option 3: Custom hook that falls back to useEffect on server
const useIsomorphicLayoutEffect =
  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

Side-by-Side Comparison

Production Scenario: Auto-Resizing Textarea

function AutoResizeTextarea({ value, onChange }) {
  const textareaRef = useRef(null);

  useLayoutEffect(() => {
    const textarea = textareaRef.current;
    textarea.style.height = '0px'; // Reset to measure scrollHeight
    textarea.style.height = `${textarea.scrollHeight}px`;
  }, [value]);

  return (
    <textarea
      ref={textareaRef}
      value={value}
      onChange={onChange}
      style={{ overflow: 'hidden', resize: 'none' }}
    />
  );
}

With useEffect, the textarea would flash at 0px height before growing — visible as a flicker. useLayoutEffect adjusts height before the browser paints, making the resize invisible.

Challenge: Fix the Tooltip Flicker

Challenge: Tooltip Positioning

// This tooltip flickers — it appears at (0,0) briefly before
// jumping to the correct position. Fix it.

function Tooltip({ anchorRef, children }) {
  const tooltipRef = useRef(null);
  const [coords, setCoords] = useState({ top: 0, left: 0 });

  useEffect(() => {
    if (!anchorRef.current || !tooltipRef.current) return;
    const anchorRect = anchorRef.current.getBoundingClientRect();
    setCoords({
      top: anchorRect.bottom + 8,
      left: anchorRect.left,
    });
  }, [anchorRef]);

  return (
    <div
      ref={tooltipRef}
      style={{
        position: 'fixed',
        top: coords.top,
        left: coords.left,
      }}
    >
      {children}
    </div>
  );
}

function Tooltip({ anchorRef, children }) {
  const tooltipRef = useRef(null);
  const [coords, setCoords] = useState({ top: 0, left: 0 });

  useLayoutEffect(() => {
    if (!anchorRef.current || !tooltipRef.current) return;
    const anchorRect = anchorRef.current.getBoundingClientRect();
    setCoords({
      top: anchorRect.bottom + 8,
      left: anchorRect.left,
    });
  }, [anchorRef]);

  return (
    <div
      ref={tooltipRef}
      style={{
        position: 'fixed',
        top: coords.top,
        left: coords.left,
      }}
    >
      {children}
    </div>
  );
}