React flushSync Usage Guide

The flushSync function forces React to flush pending updates synchronously. Here's when and how to use it.

Basic Usage#

import { flushSync } from 'react-dom';

function SearchInput() {
  const [query, setQuery] = useState('');
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSearch = () => {
    // Force synchronous update
    flushSync(() => {
      setQuery('');
    });

    // DOM is now updated
    inputRef.current?.focus();
  };

  return (
    <div>
      <input
        ref={inputRef}
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <button onClick={handleSearch}>Clear & Focus</button>
    </div>
  );
}

Scroll Position Management#

import { flushSync } from 'react-dom';

function ChatMessages({ messages, onSendMessage }) {
  const listRef = useRef<HTMLDivElement>(null);
  const [newMessage, setNewMessage] = useState('');

  const handleSend = () => {
    // Add message synchronously
    flushSync(() => {
      onSendMessage(newMessage);
      setNewMessage('');
    });

    // Scroll to bottom after DOM update
    listRef.current?.scrollTo({
      top: listRef.current.scrollHeight,
      behavior: 'smooth',
    });
  };

  return (
    <div>
      <div ref={listRef} className="messages">
        {messages.map((msg) => (
          <div key={msg.id}>{msg.text}</div>
        ))}
      </div>
      <input
        value={newMessage}
        onChange={(e) => setNewMessage(e.target.value)}
      />
      <button onClick={handleSend}>Send</button>
    </div>
  );
}

DOM Measurements#

import { flushSync } from 'react-dom';

function ExpandingTextarea() {
  const [value, setValue] = useState('');
  const textareaRef = useRef<HTMLTextAreaElement>(null);

  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
    const newValue = e.target.value;

    // Update value synchronously
    flushSync(() => {
      setValue(newValue);
    });

    // Measure and adjust height
    if (textareaRef.current) {
      textareaRef.current.style.height = 'auto';
      textareaRef.current.style.height =
        textareaRef.current.scrollHeight + 'px';
    }
  };

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

Animation Coordination#

import { flushSync } from 'react-dom';

function AnimatedList({ items, onRemove }) {
  const handleRemove = (id: string) => {
    const element = document.getElementById(`item-${id}`);

    if (element) {
      // Start exit animation
      element.classList.add('fade-out');

      // Wait for animation
      element.addEventListener('animationend', () => {
        // Update state synchronously after animation
        flushSync(() => {
          onRemove(id);
        });
      }, { once: true });
    }
  };

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id} id={`item-${item.id}`}>
          {item.name}
          <button onClick={() => handleRemove(item.id)}>Remove</button>
        </li>
      ))}
    </ul>
  );
}

Focus Management#

import { flushSync } from 'react-dom';

function EditableList({ items, onUpdate }) {
  const [editingId, setEditingId] = useState<string | null>(null);
  const inputRefs = useRef<Map<string, HTMLInputElement>>(new Map());

  const startEditing = (id: string) => {
    flushSync(() => {
      setEditingId(id);
    });

    // Focus the input after it renders
    inputRefs.current.get(id)?.focus();
  };

  const stopEditing = () => {
    setEditingId(null);
  };

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          {editingId === item.id ? (
            <input
              ref={(el) => {
                if (el) inputRefs.current.set(item.id, el);
              }}
              defaultValue={item.name}
              onBlur={stopEditing}
              onKeyDown={(e) => e.key === 'Enter' && stopEditing()}
            />
          ) : (
            <span onClick={() => startEditing(item.id)}>
              {item.name}
            </span>
          )}
        </li>
      ))}
    </ul>
  );
}

Third-Party Library Integration#

import { flushSync } from 'react-dom';
import { useEffect, useRef, useState } from 'react';

function ChartWithControls({ data }) {
  const [selectedRange, setSelectedRange] = useState([0, 100]);
  const chartRef = useRef<Chart | null>(null);
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Initialize chart library
    if (containerRef.current) {
      chartRef.current = new Chart(containerRef.current, {
        data: filterData(data, selectedRange),
      });
    }

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

  const handleRangeChange = (newRange: [number, number]) => {
    // Update state synchronously
    flushSync(() => {
      setSelectedRange(newRange);
    });

    // Update chart library immediately
    chartRef.current?.update({
      data: filterData(data, newRange),
    });
  };

  return (
    <div>
      <RangeSlider value={selectedRange} onChange={handleRangeChange} />
      <div ref={containerRef} />
    </div>
  );
}

Form Validation#

import { flushSync } from 'react-dom';

function ValidatedForm() {
  const [values, setValues] = useState({ name: '', email: '' });
  const [errors, setErrors] = useState<Record<string, string>>({});
  const errorRefs = useRef<Map<string, HTMLDivElement>>(new Map());

  const validate = () => {
    const newErrors: Record<string, string> = {};

    if (!values.name) newErrors.name = 'Name is required';
    if (!values.email.includes('@')) newErrors.email = 'Invalid email';

    return newErrors;
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    const validationErrors = validate();

    if (Object.keys(validationErrors).length > 0) {
      // Update errors synchronously
      flushSync(() => {
        setErrors(validationErrors);
      });

      // Scroll to first error
      const firstErrorKey = Object.keys(validationErrors)[0];
      errorRefs.current.get(firstErrorKey)?.scrollIntoView({
        behavior: 'smooth',
        block: 'center',
      });

      return;
    }

    // Submit form
    submitForm(values);
  };

  return (
    <form onSubmit={handleSubmit}>
      <div ref={(el) => el && errorRefs.current.set('name', el)}>
        <input
          value={values.name}
          onChange={(e) => setValues({ ...values, name: e.target.value })}
        />
        {errors.name && <span className="error">{errors.name}</span>}
      </div>

      <div ref={(el) => el && errorRefs.current.set('email', el)}>
        <input
          value={values.email}
          onChange={(e) => setValues({ ...values, email: e.target.value })}
        />
        {errors.email && <span className="error">{errors.email}</span>}
      </div>

      <button type="submit">Submit</button>
    </form>
  );
}

import { flushSync } from 'react-dom';

function ModalWithAnimation({ isOpen, onClose, children }) {
  const [isAnimating, setIsAnimating] = useState(false);
  const modalRef = useRef<HTMLDivElement>(null);

  const handleClose = () => {
    setIsAnimating(true);

    // Wait for exit animation
    setTimeout(() => {
      // Synchronously update before callback
      flushSync(() => {
        setIsAnimating(false);
      });

      // Parent's onClose runs after DOM update
      onClose();
    }, 300);
  };

  if (!isOpen && !isAnimating) return null;

  return (
    <div
      ref={modalRef}
      className={`modal ${isAnimating ? 'fade-out' : 'fade-in'}`}
    >
      <div className="modal-content">
        {children}
        <button onClick={handleClose}>Close</button>
      </div>
    </div>
  );
}

Batching Override#

import { flushSync } from 'react-dom';

function Counter() {
  const [count, setCount] = useState(0);
  const [log, setLog] = useState<string[]>([]);

  const handleClick = () => {
    // Normally these would batch
    setCount((c) => c + 1);
    setCount((c) => c + 1);
    setCount((c) => c + 1);
    // One render with count = 3

    // With flushSync, each triggers a render
    flushSync(() => setCount((c) => c + 1));
    // Render 1: count = 1
    flushSync(() => setCount((c) => c + 1));
    // Render 2: count = 2
    flushSync(() => setCount((c) => c + 1));
    // Render 3: count = 3
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={handleClick}>Increment 3x</button>
    </div>
  );
}

Best Practices#

When to Use:
✓ DOM measurements after update
✓ Scroll position management
✓ Focus after render
✓ Third-party library sync

Performance:
✗ Avoid in hot paths
✗ Don't use for every update
✗ Prefer React's batching
✗ Consider alternatives first

Alternatives:
✓ useLayoutEffect for measurements
✓ useEffect for most side effects
✓ ref callbacks for elements
✓ State lifting for coordination

Avoid:
✗ Inside render functions
✗ For animation frames
✗ In tight loops
✗ When batching works

The flushSync function forces synchronous DOM updates when you need immediate access to updated DOM. Use it sparingly for focus management, scroll positioning, and third-party library integration. In most cases, React's automatic batching and useLayoutEffect provide better alternatives with less performance impact.