useDeferredValue

useDeferredValue is a React Hook that lets you defer updating a part of the UI.

function useDeferredValue<T>(value: T, initialValue?: T): T

Parameters

required

The value you want to defer. It can be of any type.

Optional value to use during the initial render. If omitted, useDeferredValue will return value on initial render, then schedule a re-render with the deferred value.This parameter is useful to avoid showing a blank screen on the first render.

Returns

During the initial render, the returned deferred value will be the same as the value you provided (or initialValue if provided)
During updates, React will first attempt a re-render with the old value (matching the old value), then try another re-render in background with the new value (matching the updated value)

Usage

Showing stale content while fresh content is loading

Call useDeferredValue at the top level of your component to get a deferred version of that value:

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  
  return (
    <>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <SearchResults query={deferredQuery} />
    </>
  );
}

function SearchResults({ query }) {
  // Expensive rendering
  const results = searchItems(query);
  return (
    <ul>
      {results.map(result => (
        <li key={result.id}>{result.name}</li>
      ))}
    </ul>
  );
}

When the user types, the input updates immediately (using query), but the results update with a slight delay (using deferredQuery). This keeps the input responsive.

Indicating that the content is stale

Show a visual indication while the deferred value is updating:

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;
  
  return (
    <>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <SearchResults query={deferredQuery} />
      </div>
    </>
  );
}

Deferring re-rendering for a part of the UI

You can also use useDeferredValue as a performance optimization:

function ProductList({ products, filter }) {
  const deferredFilter = useDeferredValue(filter);
  
  // Expensive filtering operation
  const filteredProducts = useMemo(() => {
    return products.filter(product => {
      return product.name.toLowerCase().includes(deferredFilter.toLowerCase());
    });
  }, [products, deferredFilter]);
  
  return (
    <ul>
      {filteredProducts.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

This optimization requires the children to be wrapped in memo. Without memo, React will re-render the entire subtree anyway.

Common Patterns

Search with deferred results

Basic Search
With Loading State
With Dimming

function Search() {
  const [input, setInput] = useState('');
  const deferredInput = useDeferredValue(input);
  
  return (
    <>
      <input
        value={input}
        onChange={e => setInput(e.target.value)}
        placeholder="Search..."
      />
      <Results query={deferredInput} />
    </>
  );
}

function Search() {
  const [input, setInput] = useState('');
  const deferredInput = useDeferredValue(input);
  const isSearching = input !== deferredInput;
  
  return (
    <>
      <input
        value={input}
        onChange={e => setInput(e.target.value)}
        placeholder="Search..."
      />
      {isSearching && <div>Searching...</div>}
      <Results query={deferredInput} />
    </>
  );
}

function Search() {
  const [input, setInput] = useState('');
  const deferredInput = useDeferredValue(input);
  const isStale = input !== deferredInput;
  
  return (
    <>
      <input
        value={input}
        onChange={e => setInput(e.target.value)}
        placeholder="Search..."
      />
      <div
        style={{
          opacity: isStale ? 0.5 : 1,
          transition: 'opacity 0.2s'
        }}
      >
        <Results query={deferredInput} />
      </div>
    </>
  );
}

Filter with deferred updates

function ProductFilter({ products }) {
  const [category, setCategory] = useState('all');
  const [priceRange, setPriceRange] = useState([0, 1000]);
  const [searchTerm, setSearchTerm] = useState('');
  
  // Defer the expensive filtering
  const deferredSearchTerm = useDeferredValue(searchTerm);
  
  const filtered = useMemo(() => {
    return products.filter(product => {
      const matchesCategory = category === 'all' || product.category === category;
      const matchesPrice = product.price >= priceRange[0] && product.price <= priceRange[1];
      const matchesSearch = product.name.toLowerCase().includes(deferredSearchTerm.toLowerCase());
      return matchesCategory && matchesPrice && matchesSearch;
    });
  }, [products, category, priceRange, deferredSearchTerm]);
  
  return (
    <>
      <select value={category} onChange={e => setCategory(e.target.value)}>
        <option value="all">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="clothing">Clothing</option>
      </select>
      
      <input
        type="range"
        min={0}
        max={1000}
        value={priceRange[1]}
        onChange={e => setPriceRange([0, Number(e.target.value)])}
      />
      
      <input
        type="text"
        value={searchTerm}
        onChange={e => setSearchTerm(e.target.value)}
        placeholder="Search products..."
      />
      
      <ProductList products={filtered} />
    </>
  );
}

Table with deferred sorting

function DataTable({ data }) {
  const [sortKey, setSortKey] = useState('name');
  const [sortDirection, setSortDirection] = useState('asc');
  
  const deferredSortKey = useDeferredValue(sortKey);
  const deferredSortDirection = useDeferredValue(sortDirection);
  
  const sortedData = useMemo(() => {
    return [...data].sort((a, b) => {
      const aVal = a[deferredSortKey];
      const bVal = b[deferredSortKey];
      const direction = deferredSortDirection === 'asc' ? 1 : -1;
      return aVal > bVal ? direction : -direction;
    });
  }, [data, deferredSortKey, deferredSortDirection]);
  
  return (
    <table>
      <thead>
        <tr>
          <th onClick={() => setSortKey('name')}>Name</th>
          <th onClick={() => setSortKey('price')}>Price</th>
          <th onClick={() => setSortKey('rating')}>Rating</th>
        </tr>
      </thead>
      <tbody>
        {sortedData.map(item => (
          <tr key={item.id}>
            <td>{item.name}</td>
            <td>{item.price}</td>
            <td>{item.rating}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

TypeScript

import { useState, useDeferredValue } from 'react';

function Search() {
  const [query, setQuery] = useState<string>('');
  const deferredQuery = useDeferredValue<string>(query);
  
  return (
    <>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <Results query={deferredQuery} />
    </>
  );
}

// With initial value
function SearchWithInitial() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query, '');
  
  return <Results query={deferredQuery} />;
}

// Complex types
interface Filter {
  category: string;
  priceRange: [number, number];
  searchTerm: string;
}

function FilteredList() {
  const [filter, setFilter] = useState<Filter>({
    category: 'all',
    priceRange: [0, 1000],
    searchTerm: ''
  });
  
  const deferredFilter = useDeferredValue<Filter>(filter);
  
  return <ProductList filter={deferredFilter} />;
}