useDeferredValue Hook

Defer updating a part of the UI to keep the rest responsive during expensive renders.

Recipe

Quick-reference recipe card — copy-paste ready.

const deferredQuery = useDeferredValue(query);
 
// The component using deferredQuery re-renders at lower priority
<SearchResults query={deferredQuery} />
 
// Detect stale content
const isStale = deferredQuery !== query;

When to reach for this: You have a fast-changing value (like search input) driving an expensive child render, and you want the input to stay responsive while the child catches up.

Working Example

"use client";
 
import { memo, useDeferredValue, useState } from "react";
 
const HeavyList = memo(function HeavyList({ query }: { query: string }) {
  const items = Array.from({ length: 5000 }, (_, i) => `Result ${i}: ${query}`);
  return (
    <ul className="max-h-64 overflow-y-auto text-sm">
      {items
        .filter((item) => item.toLowerCase().includes(query.toLowerCase()))
        .slice(0, 100)
        .map((item, i) => (
          <li key={i} className="py-0.5">{item}</li>
        ))}
    </ul>
  );
});
 
export function DeferredSearch() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
  const isStale = deferredQuery !== query;
 
  return (
    <div className="space-y-3">
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Type to search..."
        className="border rounded px-3 py-2 w-full"
      />
      <div className={isStale ? "opacity-50 transition-opacity" : "transition-opacity"}>
        <HeavyList query={deferredQuery} />
      </div>
    </div>
  );
}

What this demonstrates:

• query updates instantly on every keystroke, keeping the input responsive
• deferredQuery lags behind, so HeavyList re-renders at a lower priority
• React.memo on HeavyList is essential — without it, the component re-renders with query anyway
• Visual staleness feedback via opacity when deferredQuery !== query

Deep Dive

How It Works

• useDeferredValue accepts a value and returns a deferred copy of it
• On the initial render, the deferred value equals the original value
• When the original value changes, React first re-renders with the old deferred value, then schedules a background re-render with the new value
• The background re-render is interruptible — if the original value changes again, React abandons the in-progress render and starts a new one
• This works with Suspense: if the deferred value causes a component to suspend, the user sees the old content while the new content loads

Parameters & Return Values

Variations

Deferring Suspense content:

function App() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
 
  return (
    <>
      <SearchInput value={query} onChange={setQuery} />
      <Suspense fallback={<Skeleton />}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </>
  );
}

React 19 initial value (avoid showing stale content on mount):

// Show empty results initially, then fill in at low priority
const deferredItems = useDeferredValue(items, []);

Combining with transition for loading state:

const deferredQuery = useDeferredValue(query);
const isStale = deferredQuery !== query;
 
return (
  <div>
    {isStale && <p className="text-sm text-gray-400">Loading...</p>}
    <Results query={deferredQuery} />
  </div>
);

TypeScript Notes

// Type is inferred from the input value
const deferredQuery = useDeferredValue(query); // string
 
// React 19 with initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Gotchas

• Forgetting React.memo — useDeferredValue only helps if the child component is memoized. Otherwise, the child re-renders with the current value on the first pass anyway. Fix: Wrap the expensive child in React.memo.

• Not suitable for throttling API calls — useDeferredValue defers rendering, not the value change itself. It does not reduce the number of fetch calls. Fix: Use debounce for API calls; use useDeferredValue for render performance.

• Stale content flash — The deferred value lags behind the real value, so users see stale content briefly. Fix: Show a visual indicator (opacity, spinner) when deferredValue !== value.

• Primitive values only — Passing a new object or array every render defeats the purpose, because Object.is comparison finds a new value each time. Fix: Memoize objects or arrays with useMemo before passing to useDeferredValue.

Alternatives

useDeferredValue vs. useTransition: useTransition wraps the state update; useDeferredValue wraps the value consumption. Use useDeferredValue when you don't control the state update (e.g., it comes from a prop or parent).

FAQs

const deferredQuery = useDeferredValue(query);
const isStale = deferredQuery !== query;
 
return (
  <div className={isStale ? "opacity-50" : ""}>
    <Results query={deferredQuery} />
  </div>
);

// First render uses [] instead of the full items array
const deferredItems = useDeferredValue(items, []);

// Type is inferred from the input value
const deferredQuery = useDeferredValue(query); // string
 
// React 19 with initialValue
const deferredItems = useDeferredValue<Item[]>(items, []);

Related

• useTransition — wrap state updates instead of deferring values
• useMemo — memoize expensive computations
• useCallback — stabilize references for memoized children
• useState — the state source driving deferred values