useDeferredValue Patterns

The Value That Lags Behind

Think of useDeferredValue as the sibling of useTransition that you use when you don't own the state update. It takes a value and returns a "deferred" version that deliberately lags behind. During urgent renders, the deferred value keeps its old value. Once the urgent render completes, React schedules a background render with the new value.

function SearchResults({ query }) {
  // deferredQuery lags behind query during heavy renders
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  // Expensive filtering uses the deferred value
  const results = filterProducts(deferredQuery);

  return (
    <div style={{ opacity: isStale ? 0.7 : 1 }}>
      {results.map(r => <ProductCard key={r.id} product={r} />)}
    </div>
  );
}

When the user types "abc", each keystroke updates query immediately. But deferredQuery stays at the old value until React has time to process the expensive filter. The input is responsive. The list updates when the browser is free.

The Mental Model

useDeferredValue vs useTransition

People always ask "which one should I use?" Both achieve similar results. The difference comes down to who owns the state update:

// useTransition: YOU control the state update
function SearchPage() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  function handleChange(e) {
    const value = e.target.value;
    setQuery(value);  // Can split: sync for input, transition for results
    startTransition(() => {
      setFilteredQuery(value); // You decide what's deferred
    });
  }
}

// useDeferredValue: SOMEONE ELSE controls the state update
function SearchResults({ query }) {
  // You receive query as a prop — can't control how it was set
  const deferredQuery = useDeferredValue(query);
  // The deferral happens at the consumption point
}

Use useTransition when you own the state update (event handlers, actions). Use useDeferredValue when you receive the value as a prop and can't control how it was set.

Practical Patterns

Pattern 1: Deferred List Rendering

function FilterableList({ items, filter }) {
  const deferredFilter = useDeferredValue(filter);
  const isStale = filter !== deferredFilter;

  // Memoize the expensive rendering with the deferred value
  const filteredItems = useMemo(
    () => items.filter(item => item.name.includes(deferredFilter)),
    [items, deferredFilter]
  );

  return (
    <div style={{ opacity: isStale ? 0.6 : 1 }}>
      {filteredItems.map(item => (
        <ListItem key={item.id} item={item} />
      ))}
    </div>
  );
}

The useMemo combined with deferredFilter means the expensive filtering only runs when the deferred value catches up — not on every keystroke.

Pattern 2: Deferred Chart Updates

function RealTimeChart({ dataPoints }) {
  // Data arrives at 60fps from a WebSocket
  // Chart can't render 60 times per second
  const deferredData = useDeferredValue(dataPoints);

  return <Chart data={deferredData} />;
}

The chart renders when the browser is idle, not on every data tick.

Pattern 3: Deferred Suspense

function ProfilePage({ userId }) {
  const deferredId = useDeferredValue(userId);

  return (
    <Suspense fallback={<ProfileSkeleton />}>
      <ProfileContent userId={deferredId} />
    </Suspense>
  );
}

When userId changes, deferredId keeps the old value momentarily. React shows the old user's profile (stale but complete) instead of the Suspense fallback. Once the new user's data is ready, the deferred value catches up and the profile updates.

// WASTEFUL: Badge is trivially cheap
function NotificationBadge({ count }) {
  const deferredCount = useDeferredValue(count);  // Pointless
  return <span>{deferredCount}</span>;  // Renders in microseconds anyway
}

How useDeferredValue Works Internally

If you're curious what's happening under the hood, it's surprisingly straightforward. React treats useDeferredValue similarly to a self-triggered transition:

// Conceptual implementation (simplified)
function useDeferredValue(value) {
  const [deferredValue, setDeferredValue] = useState(value);

  useEffect(() => {
    // Schedule an update at transition priority
    startTransition(() => {
      setDeferredValue(value);
    });
  }, [value]);

  return deferredValue;
}

When value changes, React immediately returns the old deferredValue (fast render). Then it schedules a transition to update deferredValue to the new value (background render). If another value change arrives before the transition completes, the transition is interrupted and restarted.

// Initial render: deferredQuery === query (both are '')
// First keystroke: deferredQuery = '', query = 'a' (deferred lags)
const deferredQuery = useDeferredValue(query);

Production Scenario: The Collaborative Spreadsheet

A spreadsheet app receives cell updates via WebSocket from other collaborators. Each update triggers re-rendering affected cells:

function Spreadsheet({ cells }) {
  // cells change frequently from WebSocket updates
  const deferredCells = useDeferredValue(cells);
  const isStale = cells !== deferredCells;

  return (
    <div className={isStale ? 'updating' : ''}>
      <table>
        {deferredCells.map((row, i) => (
          <tr key={i}>
            {row.map((cell, j) => (
              <Cell key={`${i}-${j}`} value={cell} />
            ))}
          </tr>
        ))}
      </table>
    </div>
  );
}

Without deferral: every WebSocket update triggers a full table re-render. 10 updates per second means the UI freezes.

With deferral: the table uses the deferred cells, rendering at whatever rate the browser can handle. The user's own edits (local state) are immediate. Remote updates render when idle.

Common Mistakes

Challenge

Challenge: Choose the right tool

// For each scenario, decide: useTransition, useDeferredValue,
// or neither? Explain why.

// Scenario 1: A search input in your own component
function MySearch() {
  const [query, setQuery] = useState('');
  const results = expensiveFilter(data, query);
  return (
    <>
      <input onChange={e => setQuery(e.target.value)} />
      <ResultList items={results} />
    </>
  );
}

// Scenario 2: A chart component that receives data as props
function Chart({ data }) {
  // data changes frequently from parent
  return <SVGChart points=`{data}` />;
}

// Scenario 3: A button that toggles a boolean
function Toggle() {
  const [on, setOn] = useState(false);
  return <button onClick={() => setOn(!on)}>`{on ? 'ON' : 'OFF'}`</button>;
}

const [query, setQuery] = useState('');
const [filterQuery, setFilterQuery] = useState('');
const [isPending, startTransition] = useTransition();

function handleChange(e) {
  setQuery(e.target.value); // Sync: input responsive
  startTransition(() => setFilterQuery(e.target.value)); // Deferred: filter
}
const results = expensiveFilter(data, filterQuery);

function Chart({ data }) {
  const deferredData = useDeferredValue(data);
  return <SVGChart points={deferredData} />;
}

Quiz

Key Rules