React useTransition and useDeferredValue

A comprehensive guide to react usetransition and usedeferredvalue with production examples and best practices.

The Concurrency Problem in React 18

React 18 introduced concurrent rendering, a fundamental shift in how React processes state updates. Before concurrency, all state updates were synchronous and blocking: a heavy update would freeze the UI until completion. Concurrent rendering allows React to interrupt a long-running render to process higher-priority updates, keeping the UI responsive. However, this power comes with a cost: developers must now explicitly mark updates as non-urgent to avoid performance cliffs. Two hooks—useTransition and useDeferredValue—are the primary tools for this. They solve the same problem (keeping UI responsive during expensive renders) but in different contexts. useTransition wraps state updates in a transition, giving you a pending flag and the ability to defer the update. useDeferredValue takes a value and returns a deferred copy that lags behind the original. Understanding when to use each is critical for building production-grade React apps that don't jank.

import { useState, useTransition } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  function handleChange(e) {
    startTransition(() => {
      setQuery(e.target.value);
    });
  }

  return (
    <div>
      <input onChange={handleChange} placeholder="Search..." />
      {isPending && <span>Loading...</span>}
      <SlowList query={query} />
    </div>
  );
}

function SlowList({ query }) {
  // Simulate expensive filtering
  const items = Array.from({ length: 20000 }, (_, i) => `Item ${i}`);
  const filtered = items.filter(item => item.includes(query));
  return (
    <ul>
      {filtered.map(item => <li key={item}>{item}</li>)}
    </ul>
  );
}

useTransition: The Pending State Pattern

useTransition returns a tuple: [isPending, startTransition]. isPending is a boolean that becomes true while the transition is in progress. startTransition is a function that accepts a callback; inside that callback, any state updates are marked as transitions. React will prioritize urgent updates (like input changes) over transitions. This pattern is ideal for scenarios where you want to show a loading indicator while a heavy render completes. The key insight: isPending is synchronous—it flips to true immediately when startTransition is called, and flips to false when the deferred render finishes. This allows you to conditionally render spinners or stale UI. However, beware: if you call startTransition outside of an event handler (e.g., in useEffect), React may not treat it as a transition. Always call startTransition in response to a user event.

import { useState, useTransition } from 'react';

function TabSwitcher() {
  const [tab, setTab] = useState('home');
  const [isPending, startTransition] = useTransition();

  function switchTab(nextTab) {
    startTransition(() => {
      setTab(nextTab);
    });
  }

  return (
    <div>
      <button onClick={() => switchTab('home')}>Home</button>
      <button onClick={() => switchTab('settings')}>Settings</button>
      {isPending && <div className="spinner" />}
      <TabContent tab={tab} />
    </div>
  );
}

function TabContent({ tab }) {
  // Simulate heavy component
  const now = performance.now();
  while (performance.now() - now < 200) { /* block */ }
  return <div>{tab} content</div>;
}

useDeferredValue: Deferring a Value, Not an Update

useDeferredValue is the counterpart to useTransition. Instead of wrapping a state update, it takes a value and returns a deferred copy that lags behind the original by one render. This is useful when you cannot control the state update source—for example, when using a third-party hook or a prop. The deferred value is updated after the urgent render completes. React will re-render the component with the original value first (urgent), then re-render with the deferred value (non-urgent). This pattern is ideal for filtering large lists where the input value is the source of truth, but the filtered list can lag. Unlike useTransition, useDeferredValue does not provide a pending flag; you must compare the original and deferred values to detect staleness.

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

function SearchResults({ query }) {
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  const items = useMemo(() => {
    // Simulate expensive filtering
    const all = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
    return all.filter(item => item.includes(deferredQuery));
  }, [deferredQuery]);

  return (
    <div style={{ opacity: isStale ? 0.5 : 1 }}>
      {items.map(item => <div key={item}>{item}</div>)}
    </div>
  );
}

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

useTransition vs useDeferredValue: When to Use Which

Both hooks solve UI jank but differ in control and use cases. useTransition is for when you control the state update—you wrap setState in startTransition. useDeferredValue is for when you receive a value from props or external state and cannot wrap the setter. Rule of thumb: if you can wrap the state update, use useTransition; if you cannot, use useDeferredValue. Additionally, useTransition gives you a pending flag; useDeferredValue requires manual staleness detection. Performance-wise, both achieve the same goal: deferring a render. However, useDeferredValue may cause an extra render (urgent + deferred) while useTransition only renders once (the deferred render). In practice, the difference is negligible. Avoid using both on the same state—it's redundant and can cause confusion.

// useTransition version
function SearchWithTransition() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();
  return (
    <>
      <input onChange={e => startTransition(() => setQuery(e.target.value))} />
      {isPending && <Spinner />}
      <ExpensiveList query={query} />
    </>
  );
}

// useDeferredValue version
function SearchWithDeferred({ query }) {
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;
  return (
    <div style={{ opacity: isStale ? 0.5 : 1 }}>
      <ExpensiveList query={deferredQuery} />
    </div>
  );
}

Performance Pitfalls: Overusing Transitions

Transitions are not free. Each transition causes React to schedule a lower-priority render, which may be interrupted. If you wrap every state update in a transition, you defeat the purpose—urgent updates become non-urgent, leading to perceived slowness. Only wrap updates that trigger expensive renders. Also, avoid using transitions for updates that are already fast (e.g., toggling a checkbox). The overhead of scheduling a transition (even if the render is fast) can cause a micro-delay. Profile with React DevTools to measure the impact. Another pitfall: transitions do not work with synchronous state updates outside of event handlers (e.g., in useEffect). React will treat them as urgent. Always ensure startTransition is called in an event handler or a callback passed to an event handler.

import { useState, useTransition } from 'react';

function BadExample() {
  const [count, setCount] = useState(0);
  const [isPending, startTransition] = useTransition();

  // BAD: wrapping a fast update in transition
  function increment() {
    startTransition(() => {
      setCount(c => c + 1);
    });
  }

  return (
    <div>
      <button onClick={increment}>Count: {count}</button>
      {isPending && <span>...</span>}
    </div>
  );
}

// GOOD: only wrap expensive updates
function GoodExample() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  function handleSearch(e) {
    startTransition(() => {
      setQuery(e.target.value);
    });
  }

  return (
    <div>
      <input onChange={handleSearch} />
      {isPending && <Spinner />}
      <ExpensiveList query={query} />
    </div>
  );
}

useDeferredValue with Memoization

useDeferredValue works best when combined with useMemo or React.memo. Without memoization, the deferred value still causes the entire component tree to re-render, defeating the purpose. The deferred value should be used as a dependency for expensive computations or as a prop for memoized child components. For example, pass the deferred query to a memoized list component. React will re-render the list only when the deferred query changes, not on every keystroke. Additionally, use the stale detection (query !== deferredQuery) to conditionally apply visual feedback like opacity changes or a loading overlay. This pattern ensures that the UI remains responsive while the expensive part catches up.

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

const ExpensiveList = memo(function ExpensiveList({ query }) {
  const items = useMemo(() => {
    // Simulate heavy computation
    const all = Array.from({ length: 20000 }, (_, i) => `Item ${i}`);
    return all.filter(item => item.includes(query));
  }, [query]);

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

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

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <ExpensiveList query={deferredQuery} />
      </div>
    </div>
  );
}

Testing Transitions and Deferred Values

Testing components that use useTransition or useDeferredValue requires understanding React's concurrent scheduling. In unit tests with React Testing Library, transitions are flushed synchronously by default, so you won't see the pending state. To test the pending state, you need to use act() and wait for the deferred render. Use jest.useFakeTimers() to control time, or use the unstable_batchedUpdates API. For useDeferredValue, test that the deferred value lags behind the original. A common pattern: assert that the component renders with the original value first, then with the deferred value after a tick. Use waitFor or findBy queries to wait for the deferred update. Also, test the stale indicator: check that the opacity changes when query !== deferredQuery.

import { render, screen, fireEvent, act } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import SearchPage from './SearchPage';

jest.useFakeTimers();

test('shows pending state during transition', async () => {
  render(<SearchPage />);
  const input = screen.getByPlaceholderText('Search...');
  
  // Simulate typing
  fireEvent.change(input, { target: { value: 'test' } });
  
  // Pending should be true immediately
  expect(screen.getByText('Loading...')).toBeInTheDocument();
  
  // Flush the transition
  act(() => { jest.runAllTimers(); });
  
  // Pending should be gone
  expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
});

test('deferred value lags behind', async () => {
  render(<SearchResults query="initial" />);
  // Initially, deferred equals original
  expect(screen.getByText(/Item 0/)).toBeInTheDocument();
  
  // Update query
  rerender(<SearchResults query="updated" />);
  
  // Still shows old items because deferred hasn't caught up
  expect(screen.getByText(/Item 0/)).toBeInTheDocument();
  
  // After a tick, deferred updates
  act(() => { jest.runAllTimers(); });
  expect(screen.getByText(/Item 0/)).toBeInTheDocument(); // still there, but filtered differently
});

Production Patterns: Combining with Suspense and Error Boundaries

In production, transitions and deferred values often coexist with Suspense for data fetching. When a transition triggers a Suspense fallback, React will keep showing the old UI until the new data is ready. This is the recommended pattern: wrap data-fetching components in Suspense and use useTransition to defer the state update that triggers the fetch. The old UI remains visible, and a pending indicator can be shown via isPending. Similarly, error boundaries should wrap the deferred content to catch errors during the deferred render. A common failure mode: an error in the deferred render is not caught because the error boundary is outside the transition. Always place error boundaries inside the transition-aware component.

import { useState, useTransition, Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';

function ProfilePage() {
  const [userId, setUserId] = useState(1);
  const [isPending, startTransition] = useTransition();

  function switchUser(id) {
    startTransition(() => {
      setUserId(id);
    });
  }

  return (
    <div>
      <button onClick={() => switchUser(2)}>User 2</button>
      {isPending && <span>Switching...</span>}
      <ErrorBoundary fallback={<div>Error loading profile</div>}>
        <Suspense fallback={<div>Loading profile...</div>}>
          <Profile userId={userId} />
        </Suspense>
      </ErrorBoundary>
    </div>
  );
}

function Profile({ userId }) {
  // Simulate data fetch
  const data = fetchData(userId); // throws promise if not ready
  return <div>User {data.name}</div>;
}

Debugging Transition-Related Bugs

Transition bugs are subtle: stale UI, missing pending indicators, or unexpected re-renders. Use React DevTools' Profiler to visualize transitions. Look for 'Transition' labels in the flamegraph. If a transition is missing, check that startTransition is called in an event handler. Another common bug: using useTransition inside a component that re-renders frequently, causing the transition to be re-created. Move the hook to a stable parent. For useDeferredValue, verify that the deferred value is actually different from the original by logging both. If they are always equal, the deferred value is not lagging—likely because the render is too fast or the value is primitive. Also, check that you are not accidentally using the original value in the expensive computation instead of the deferred one.

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

function DebugComponent() {
  const [query, setQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  // Log transition status
  useEffect(() => {
    console.log('isPending:', isPending);
  }, [isPending]);

  function handleChange(e) {
    console.log('Before startTransition');
    startTransition(() => {
      console.log('Inside transition');
      setQuery(e.target.value);
    });
    console.log('After startTransition');
  }

  return <input onChange={handleChange} />;
}

// Check if deferred value lags
function DebugDeferred({ value }) {
  const deferred = useDeferredValue(value);
  console.log('Original:', value, 'Deferred:', deferred);
  return <div>{deferred}</div>;
}

Future of Concurrent Features: What's Next

React 18's concurrent features are the foundation for future improvements. The React team is working on automatic batching for transitions, better integration with Server Components, and possibly a useOptimistic hook for optimistic updates. Currently, useTransition and useDeferredValue are stable but have limitations: they only work with synchronous renders, not with async data fetching (use Suspense for that). In the future, transitions may support async functions directly. Also, the 'use' hook (experimental) may simplify deferred value patterns. For now, master these two hooks—they are the building blocks of responsive UIs in React 18+. Keep an eye on RFCs for 'useOptimistic' and 'useSyncExternalStore' for more advanced patterns.

// Hypothetical future API (not yet released)
// import { useOptimistic } from 'react';

function OptimisticUpdate() {
  const [todos, setTodos] = useState([]);
  const [optimisticTodos, addOptimistic] = useOptimistic(
    todos,
    (state, newTodo) => [...state, { ...newTodo, pending: true }]
  );

  async function addTodo(text) {
    addOptimistic({ text });
    await saveToServer(text);
    setTodos(prev => [...prev, { text, pending: false }]);
  }

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <li key={todo.text} style={{ opacity: todo.pending ? 0.5 : 1 }}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

Common Mistakes and Anti-Patterns

Even experienced developers make mistakes with concurrent hooks. The most common: using useTransition for every state update, including fast ones. This adds unnecessary overhead. Another: forgetting to memoize the expensive child when using useDeferredValue, causing full re-renders. Also, calling startTransition outside an event handler (e.g., in useEffect) renders it ineffective. For useDeferredValue, a frequent error is using the original value instead of the deferred value in the expensive computation. Finally, mixing useTransition and useDeferredValue on the same state leads to double deferral and confusion. Stick to one pattern per state. Always profile before and after to ensure the hooks are actually improving performance.

// ANTI-PATTERN 1: Wrapping fast updates
function BadCounter() {
  const [count, setCount] = useState(0);
  const [isPending, startTransition] = useTransition();
  return <button onClick={() => startTransition(() => setCount(c => c + 1))}>{count}</button>;
}

// ANTI-PATTERN 2: Not memoizing child
function BadDeferred({ query }) {
  const deferredQuery = useDeferredValue(query);
  // ExpensiveList is not memoized, re-renders on every parent render
  return <ExpensiveList query={deferredQuery} />;
}

// ANTI-PATTERN 3: Using original value
function BadComputation({ query }) {
  const deferredQuery = useDeferredValue(query);
  const items = useMemo(() => expensiveFilter(query), [query]); // Should use deferredQuery
  return <List items={items} />;
}

Real-World Case Study: Search-as-You-Type

A common real-world use case is a search-as-you-type input that filters a large list. Without concurrent features, each keystroke causes a full re-render of the list, freezing the UI. Using useTransition, we wrap the setQuery in startTransition, and show a spinner via isPending. The input remains responsive. However, if the list is extremely large (e.g., 100k items), even the deferred render blocks the main thread. In that case, we combine useDeferredValue with virtualization (e.g., react-window) and memoization. The deferred value ensures the virtual list only re-renders when the deferred query changes, not on every keystroke. The result: a smooth search experience even on low-end devices. We also added a stale indicator (opacity change) to inform users that results are being updated.

import { useState, useDeferredValue, useMemo, memo } from 'react';
import { FixedSizeList as List } from 'react-window';

const Row = memo(({ index, style, data }) => (
  <div style={style}>{data[index]}</div>
));

function VirtualSearch({ allItems }) {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  const filtered = useMemo(() => {
    return allItems.filter(item => item.includes(deferredQuery));
  }, [deferredQuery, allItems]);

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.5 : 1 }}>
        <List
          height={400}
          itemCount={filtered.length}
          itemSize={35}
          itemData={filtered}
        >
          {Row}
        </List>
      </div>
    </div>
  );
}

React 19 Async Transitions with Server Actions

React 19 introduces async transitions, allowing startTransition to accept async functions. This is particularly powerful when combined with Server Actions, enabling seamless server-side mutations without blocking the UI. The transition remains pending until the async operation completes, and React automatically manages error boundaries and fallback states. This pattern eliminates the need for manual loading states when performing server mutations.

```jsx import { startTransition } from 'react'; import { updateUser } from './actions';

function UserProfile() { const [name, setName] = useState(''); const [isPending, startAsyncTransition] = useTransition();

const handleSubmit = () => { startAsyncTransition(async () => { await updateUser({ name }); // UI updates automatically after server confirms }); };

return ( <form onSubmit={handleSubmit}> <input value={name} onChange={(e) => setName(e.target.value)} /> <button type="submit" disabled={isPending}> {isPending ? 'Saving...' : 'Save'} </button> </form> ); } ```

In this example, startAsyncTransition wraps an async Server Action. The isPending flag remains true until the server responds, providing immediate feedback. React 19 also integrates this with <Suspense>, so if the transition triggers a fallback, it won't flash unnecessarily.

Key benefits: - No manual loading states for server mutations - Automatic error handling via error boundaries - Smooth integration with Suspense and streaming SSR

import { startTransition, useTransition } from 'react';
import { updateUser } from './actions';

function UserProfile() {
  const [name, setName] = useState('');
  const [isPending, startAsyncTransition] = useTransition();

  const handleSubmit = () => {
    startAsyncTransition(async () => {
      await updateUser({ name });
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving...' : 'Save'}
      </button>
    </form>
  );
}

useOptimistic for Immediate UI Feedback

The useOptimistic hook provides a way to show immediate UI updates before a server confirms the change. It works hand-in-hand with transitions: you start a transition that performs the server mutation, and while it's pending, useOptimistic returns an optimistic state. This pattern is ideal for likes, comments, or any action where you want instant feedback.

```jsx import { useOptimistic, useTransition } from 'react'; import { addComment } from './actions';

function CommentSection({ comments: initialComments }) { const [optimisticComments, addOptimisticComment] = useOptimistic( initialComments, (state, newComment) => [...state, { ...newComment, pending: true }] ); const [, startTransition] = useTransition();

const handleSubmit = (formData) => { const newComment = { text: formData.get('comment'), id: Date.now() }; addOptimisticComment(newComment); startTransition(async () => { await addComment(newComment); }); };

return ( <div> <form action={handleSubmit}> <input name="comment" /> <button type="submit">Add</button> </form> {optimisticComments.map((comment) => ( <div key={comment.id} className={comment.pending ? 'pending' : ''}> {comment.text} </div> ))} </div> ); } ```

Here, addOptimisticComment immediately adds the comment with a pending flag. The transition runs the server action; if it fails, you can revert the optimistic state using error boundaries or manual rollback.

Best practices: - Always provide a unique key for optimistic items - Handle errors gracefully (e.g., revert or show error state) - Combine with useTransition's isPending for loading indicators

import { useOptimistic, useTransition } from 'react';
import { addComment } from './actions';

function CommentSection({ comments: initialComments }) {
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    initialComments,
    (state, newComment) => [...state, { ...newComment, pending: true }]
  );
  const [, startTransition] = useTransition();

  const handleSubmit = (formData) => {
    const newComment = { text: formData.get('comment'), id: Date.now() };
    addOptimisticComment(newComment);
    startTransition(async () => {
      await addComment(newComment);
    });
  };

  return (
    <div>
      <form action={handleSubmit}>
        <input name="comment" />
        <button type="submit">Add</button>
      </form>
      {optimisticComments.map((comment) => (
        <div key={comment.id} className={comment.pending ? 'pending' : ''}>
          {comment.text}
        </div>
      ))}
    </div>
  );
}

Suspense + useTransition Data Fetching Architecture

Combining Suspense with useTransition prevents the common problem of fallback flashing when navigating between pages or fetching new data. Normally, wrapping a component in <Suspense> shows a fallback (e.g., spinner) every time new data is fetched. With useTransition, you can defer showing the fallback and instead keep the old UI visible until the new data is ready, then smoothly swap.

```jsx import { Suspense, useTransition } from 'react'; import { fetchUser } from './api';

function UserProfile({ userId }) { const [isPending, startTransition] = useTransition(); const [currentUserId, setCurrentUserId] = useState(userId);

const handleUserChange = (newId) => { startTransition(() => { setCurrentUserId(newId); }); };

return ( <div> <button onClick={() => handleUserChange(1)}>User 1</button> <button onClick={() => handleUserChange(2)}>User 2</button> <div style={{ opacity: isPending ? 0.5 : 1 }}> <Suspense fallback={<Spinner />}> <UserData userId={currentUserId} /> </Suspense> </div> </div> ); }

function UserData({ userId }) { const user = use(fetchUser(userId)); // Requires React 19's use hook return <div>{user.name}</div>; } ```

In this pattern, when the user clicks a new user button, startTransition wraps the state update. React then keeps the old UserData visible (with a slight opacity change) while the new data loads. The <Suspense> fallback only shows if the transition is not used, but here it's suppressed because the transition tells React to keep the previous content.

Key points: - Use useTransition to wrap state updates that trigger Suspense - The isPending flag allows visual feedback (e.g., dimming) without replacing content - This architecture eliminates flash of loading states during navigation

Caveat: This pattern works best with React 19's use hook or libraries that integrate with Suspense (e.g., Relay, SWR with Suspense mode).

import { Suspense, useTransition, use } from 'react';
import { fetchUser } from './api';

function UserProfile({ userId }) {
  const [isPending, startTransition] = useTransition();
  const [currentUserId, setCurrentUserId] = useState(userId);

  const handleUserChange = (newId) => {
    startTransition(() => {
      setCurrentUserId(newId);
    });
  };

  return (
    <div>
      <button onClick={() => handleUserChange(1)}>User 1</button>
      <button onClick={() => handleUserChange(2)}>User 2</button>
      <div style={{ opacity: isPending ? 0.5 : 1 }}>
        <Suspense fallback={<Spinner />}>
          <UserData userId={currentUserId} />
        </Suspense>
      </div>
    </div>
  );
}

function UserData({ userId }) {
  const user = use(fetchUser(userId));
  return <div>{user.name}</div>;
}