React useDeferredValue Hook Guide

The useDeferredValue hook defers updating part of the UI to keep the interface responsive. Here's how to use it.

Basic Usage#

import { useState, useDeferredValue } from 'react';

function SearchResults() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  // Input responds immediately
  // Results update with deferred value
  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      <Results query={deferredQuery} />
    </div>
  );
}

function Results({ query }) {
  // Expensive computation or filtering
  const results = searchItems(query);

  return (
    <ul>
      {results.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

Showing Stale Content#

import { useState, useDeferredValue, memo } from 'react';

function App() {
  const [text, setText] = useState('');
  const deferredText = useDeferredValue(text);

  // Check if showing stale content
  const isStale = text !== deferredText;

  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
      />

      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <SlowList text={deferredText} />
      </div>
    </div>
  );
}

// Memoize to prevent re-renders with same deferred value
const SlowList = memo(function SlowList({ text }) {
  const items = [];
  for (let i = 0; i < 500; i++) {
    items.push(<SlowItem key={i} text={text} />);
  }
  return <ul>{items}</ul>;
});

function SlowItem({ text }) {
  // Simulate slow render
  const startTime = performance.now();
  while (performance.now() - startTime < 1) {
    // Artificial delay
  }

  return <li>{text}</li>;
}

With Suspense#

import { Suspense, useState, useDeferredValue } from 'react';

function SearchApp() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  const isStale = query !== deferredQuery;

  return (
    <div>
      <SearchInput value={query} onChange={setQuery} />

      <Suspense fallback={<Loading />}>
        <div style={{ opacity: isStale ? 0.7 : 1 }}>
          <SearchResults query={deferredQuery} />
        </div>
      </Suspense>
    </div>
  );
}

// SearchResults can suspend while fetching
function SearchResults({ query }) {
  const results = use(fetchResults(query));

  return (
    <ul>
      {results.map((result) => (
        <li key={result.id}>{result.title}</li>
      ))}
    </ul>
  );
}

Filter Performance#

import { useState, useDeferredValue, useMemo, memo } from 'react';

function ProductList({ products }) {
  const [filter, setFilter] = useState('');
  const [category, setCategory] = useState('all');

  const deferredFilter = useDeferredValue(filter);
  const deferredCategory = useDeferredValue(category);

  const isStale =
    filter !== deferredFilter || category !== deferredCategory;

  return (
    <div>
      <div className="filters">
        <input
          value={filter}
          onChange={(e) => setFilter(e.target.value)}
          placeholder="Filter products..."
        />

        <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>
      </div>

      <div className={isStale ? 'stale' : ''}>
        <FilteredProducts
          products={products}
          filter={deferredFilter}
          category={deferredCategory}
        />
      </div>
    </div>
  );
}

const FilteredProducts = memo(function FilteredProducts({
  products,
  filter,
  category,
}) {
  const filtered = useMemo(() => {
    return products.filter((product) => {
      const matchesFilter = product.name
        .toLowerCase()
        .includes(filter.toLowerCase());
      const matchesCategory =
        category === 'all' || product.category === category;
      return matchesFilter && matchesCategory;
    });
  }, [products, filter, category]);

  return (
    <div className="product-grid">
      {filtered.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
});

Chart Updates#

import { useState, useDeferredValue, memo } from 'react';

function Dashboard() {
  const [data, setData] = useState(initialData);
  const [range, setRange] = useState({ start: 0, end: 100 });

  const deferredRange = useDeferredValue(range);
  const isStale = range !== deferredRange;

  return (
    <div>
      <RangeSlider
        value={range}
        onChange={setRange}
      />

      <div style={{ opacity: isStale ? 0.6 : 1 }}>
        <ExpensiveChart
          data={data}
          range={deferredRange}
        />
      </div>
    </div>
  );
}

const ExpensiveChart = memo(function ExpensiveChart({ data, range }) {
  // Expensive rendering with many data points
  const filteredData = data.slice(range.start, range.end);

  return (
    <svg width="800" height="400">
      {filteredData.map((point, i) => (
        <circle
          key={i}
          cx={point.x}
          cy={point.y}
          r="2"
          fill="blue"
        />
      ))}
    </svg>
  );
});

Table Filtering#

import { useState, useDeferredValue, useMemo, memo } from 'react';

function DataTable({ rows }) {
  const [sortColumn, setSortColumn] = useState('name');
  const [sortDirection, setSortDirection] = useState('asc');
  const [search, setSearch] = useState('');

  const deferredSearch = useDeferredValue(search);
  const isSearching = search !== deferredSearch;

  return (
    <div>
      <input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search table..."
      />

      {isSearching && <span className="searching">Searching...</span>}

      <TableBody
        rows={rows}
        search={deferredSearch}
        sortColumn={sortColumn}
        sortDirection={sortDirection}
      />
    </div>
  );
}

const TableBody = memo(function TableBody({
  rows,
  search,
  sortColumn,
  sortDirection,
}) {
  const processedRows = useMemo(() => {
    let result = rows;

    // Filter
    if (search) {
      result = result.filter((row) =>
        Object.values(row).some((value) =>
          String(value).toLowerCase().includes(search.toLowerCase())
        )
      );
    }

    // Sort
    result = [...result].sort((a, b) => {
      const aVal = a[sortColumn];
      const bVal = b[sortColumn];
      const direction = sortDirection === 'asc' ? 1 : -1;
      return aVal > bVal ? direction : -direction;
    });

    return result;
  }, [rows, search, sortColumn, sortDirection]);

  return (
    <tbody>
      {processedRows.map((row) => (
        <tr key={row.id}>
          {Object.values(row).map((cell, i) => (
            <td key={i}>{cell}</td>
          ))}
        </tr>
      ))}
    </tbody>
  );
});

vs useTransition#

import { useState, useTransition, useDeferredValue } from 'react';

// useTransition - you control when to defer
function WithTransition() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  const handleChange = (e) => {
    // Input updates immediately
    setQuery(e.target.value);

    // Results update in transition
    startTransition(() => {
      setQuery(e.target.value);
    });
  };

  return (
    <div>
      <input onChange={handleChange} />
      <Results query={query} />
    </div>
  );
}

// useDeferredValue - React controls deferral
function WithDeferredValue() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  // React automatically defers based on value
  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <Results query={deferredQuery} />
    </div>
  );
}

// Key difference:
// - useTransition: wrap the state update
// - useDeferredValue: wrap the value usage

Debouncing Alternative#

// Traditional debouncing
function DebounceSearch() {
  const [query, setQuery] = useState('');
  const [debouncedQuery, setDebouncedQuery] = useState('');

  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedQuery(query);
    }, 300);

    return () => clearTimeout(timer);
  }, [query]);

  return <Results query={debouncedQuery} />;
}

// useDeferredValue - no fixed delay
function DeferredSearch() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  // Defers based on device capability
  // Fast devices: minimal delay
  // Slow devices: longer delay to keep responsive

  return <Results query={deferredQuery} />;
}

// Combine both for best results
function OptimalSearch() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  // Debounce network requests
  // Defer expensive renders
  useEffect(() => {
    if (!deferredQuery) return;

    const timer = setTimeout(() => {
      fetchResults(deferredQuery);
    }, 300);

    return () => clearTimeout(timer);
  }, [deferredQuery]);

  return <Results query={deferredQuery} />;
}

Best Practices#

Usage:
✓ Defer expensive renders
✓ Keep input responsive
✓ Show stale indicators
✓ Memoize child components

When to Use:
✓ Filtering large lists
✓ Complex visualizations
✓ Real-time search
✓ Expensive computations

Patterns:
✓ Combine with memo()
✓ Track stale state
✓ Use with Suspense
✓ Apply visual feedback

Avoid:
✗ Deferring fast operations
✗ Without memoization
✗ For network requests alone
✗ Nested deferred values

The useDeferredValue hook improves UI responsiveness by deferring non-urgent updates. Use it for expensive renders like filtering large lists or rendering complex charts. Always memoize child components and provide visual feedback when showing stale content. It adapts to device capabilities automatically, unlike fixed debounce delays.