React useLayoutEffect Hook Guide

The useLayoutEffect hook runs synchronously after DOM mutations but before the browser paints. Here's when and how to use it.

Basic Usage#

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

function MeasuredComponent() {
  const ref = useRef<HTMLDivElement>(null);
  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });

  // Runs synchronously after DOM update
  useLayoutEffect(() => {
    if (ref.current) {
      const { width, height } = ref.current.getBoundingClientRect();
      setDimensions({ width, height });
    }
  }, []);

  return (
    <div ref={ref}>
      <p>Width: {dimensions.width}px</p>
      <p>Height: {dimensions.height}px</p>
    </div>
  );
}

vs useEffect#

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

function FlickerExample() {
  const [position, setPosition] = useState(0);

  // ❌ useEffect - may cause visual flicker
  useEffect(() => {
    // DOM is painted before this runs
    // User might see initial position briefly
    setPosition(calculatePosition());
  }, []);

  // ✅ useLayoutEffect - no flicker
  useLayoutEffect(() => {
    // Runs before browser paints
    // User never sees initial position
    setPosition(calculatePosition());
  }, []);

  return <div style={{ transform: `translateX(${position}px)` }} />;
}

// Timeline comparison:
// useEffect:      Render → Paint → Effect → (possible re-paint)
// useLayoutEffect: Render → Layout Effect → Paint

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

  useLayoutEffect(() => {
    if (!target || !tooltipRef.current) return;

    const targetRect = target.getBoundingClientRect();
    const tooltipRect = tooltipRef.current.getBoundingClientRect();

    // Calculate position to avoid cutoff
    let top = targetRect.bottom + 8;
    let left = targetRect.left + (targetRect.width - tooltipRect.width) / 2;

    // Adjust if off-screen
    if (left < 0) left = 8;
    if (left + tooltipRect.width > window.innerWidth) {
      left = window.innerWidth - tooltipRect.width - 8;
    }

    setPosition({ top, left });
  }, [target]);

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

Auto-resize Textarea#

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

  useLayoutEffect(() => {
    const textarea = textareaRef.current;
    if (!textarea) return;

    // Reset height to calculate scroll height
    textarea.style.height = 'auto';
    // Set to scroll height
    textarea.style.height = `${textarea.scrollHeight}px`;
  }, [value]);

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

Scroll Position Restoration#

function ChatMessages({ messages }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [shouldScrollToBottom, setShouldScrollToBottom] = useState(true);

  // Check if user is near bottom before update
  const handleScroll = () => {
    const container = containerRef.current;
    if (!container) return;

    const { scrollTop, scrollHeight, clientHeight } = container;
    setShouldScrollToBottom(scrollHeight - scrollTop - clientHeight < 100);
  };

  // Scroll to bottom after new messages
  useLayoutEffect(() => {
    if (shouldScrollToBottom && containerRef.current) {
      containerRef.current.scrollTop = containerRef.current.scrollHeight;
    }
  }, [messages, shouldScrollToBottom]);

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

Focus Management#

function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousFocus = useRef<HTMLElement | null>(null);

  useLayoutEffect(() => {
    if (isOpen) {
      // Store current focus
      previousFocus.current = document.activeElement as HTMLElement;

      // Focus modal immediately
      modalRef.current?.focus();
    }

    return () => {
      // Restore focus when closing
      previousFocus.current?.focus();
    };
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      ref={modalRef}
      tabIndex={-1}
      role="dialog"
      aria-modal="true"
    >
      {children}
      <button onClick={onClose}>Close</button>
    </div>
  );
}

Animation Setup#

function AnimatedList({ items }) {
  const itemRefs = useRef<Map<string, HTMLLIElement>>(new Map());

  useLayoutEffect(() => {
    // Measure all items before animation
    const positions = new Map();

    itemRefs.current.forEach((el, id) => {
      positions.set(id, el.getBoundingClientRect());
    });

    // Apply FLIP animation
    itemRefs.current.forEach((el, id) => {
      const oldPos = positions.get(id);
      const newPos = el.getBoundingClientRect();

      const deltaY = oldPos.top - newPos.top;

      if (deltaY !== 0) {
        el.animate(
          [
            { transform: `translateY(${deltaY}px)` },
            { transform: 'translateY(0)' },
          ],
          { duration: 300, easing: 'ease-out' }
        );
      }
    });
  }, [items]);

  return (
    <ul>
      {items.map((item) => (
        <li
          key={item.id}
          ref={(el) => {
            if (el) itemRefs.current.set(item.id, el);
          }}
        >
          {item.name}
        </li>
      ))}
    </ul>
  );
}

Dynamic Width Measurement#

function TruncatedText({ text, maxWidth }) {
  const ref = useRef<HTMLSpanElement>(null);
  const [truncatedText, setTruncatedText] = useState(text);

  useLayoutEffect(() => {
    const element = ref.current;
    if (!element) return;

    let current = text;
    element.textContent = current;

    while (element.scrollWidth > maxWidth && current.length > 0) {
      current = current.slice(0, -1);
      element.textContent = current + '...';
    }

    setTruncatedText(element.textContent || '');
  }, [text, maxWidth]);

  return (
    <span ref={ref} style={{ display: 'inline-block', maxWidth }}>
      {truncatedText}
    </span>
  );
}

Third-Party Library Integration#

function ChartComponent({ data }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const chartRef = useRef<Chart | null>(null);

  useLayoutEffect(() => {
    if (!containerRef.current) return;

    // Initialize chart synchronously
    chartRef.current = new Chart(containerRef.current, {
      type: 'line',
      data: data,
    });

    return () => {
      chartRef.current?.destroy();
    };
  }, []);

  // Update data synchronously
  useLayoutEffect(() => {
    if (chartRef.current) {
      chartRef.current.data = data;
      chartRef.current.update('none'); // No animation
    }
  }, [data]);

  return <div ref={containerRef} />;
}

Window Resize Handler#

function ResponsiveGrid({ children }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [columns, setColumns] = useState(3);

  useLayoutEffect(() => {
    const calculateColumns = () => {
      if (!containerRef.current) return;

      const width = containerRef.current.offsetWidth;

      if (width < 480) setColumns(1);
      else if (width < 768) setColumns(2);
      else if (width < 1024) setColumns(3);
      else setColumns(4);
    };

    calculateColumns();

    window.addEventListener('resize', calculateColumns);
    return () => window.removeEventListener('resize', calculateColumns);
  }, []);

  return (
    <div
      ref={containerRef}
      style={{
        display: 'grid',
        gridTemplateColumns: `repeat(${columns}, 1fr)`,
        gap: '1rem',
      }}
    >
      {children}
    </div>
  );
}

SSR Considerations#

import { useLayoutEffect, useEffect } from 'react';

// Create isomorphic effect
const useIsomorphicLayoutEffect =
  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

function Component() {
  // Safe for SSR
  useIsomorphicLayoutEffect(() => {
    // DOM operations
  }, []);

  return <div />;
}

// Or suppress SSR warning
function ClientOnlyComponent() {
  useLayoutEffect(() => {
    // Only runs on client
  }, []);

  return <div suppressHydrationWarning />;
}

Best Practices#

When to Use:
✓ DOM measurements
✓ Preventing visual flicker
✓ Synchronous DOM mutations
✓ Focus management

vs useEffect:
✓ useLayoutEffect: visual updates
✓ useEffect: data fetching, subscriptions
✓ useLayoutEffect: blocks paint
✓ useEffect: non-blocking

Performance:
✓ Keep effects fast
✓ Avoid heavy computation
✓ Consider throttling resize
✓ Use useEffect when possible

Avoid:
✗ Data fetching
✗ Subscriptions (use useEffect)
✗ Long-running operations
✗ SSR without isomorphic check

The useLayoutEffect hook runs synchronously after DOM mutations but before paint, making it ideal for measurements and visual updates that must happen before the user sees the result. Use it sparingly for cases where useEffect would cause visual flicker. For most side effects, prefer useEffect to avoid blocking the browser.