React useTransition Hook Guide

The useTransition hook lets you mark state updates as non-urgent, keeping your UI responsive during expensive renders. Here's how to use it.

Basic Usage#

import { useState, useTransition } from 'react';

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

  const handleChange = (e) => {
    const value = e.target.value;

    // Urgent: Update input immediately
    setQuery(value);

    // Non-urgent: Update results can wait
    startTransition(() => {
      setResults(filterResults(value));
    });
  };

  return (
    <div>
      <input value={query} onChange={handleChange} />
      {isPending && <div>Loading...</div>}
      <ResultsList results={results} />
    </div>
  );
}

Tab Switching#

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

const SlowTab = memo(function SlowTab() {
  // Simulate slow render
  let items = [];
  for (let i = 0; i < 500; i++) {
    items.push(<SlowItem key={i} index={i} />);
  }
  return <div>{items}</div>;
});

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

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

  return (
    <div>
      <nav>
        <button
          className={tab === 'about' ? 'active' : ''}
          onClick={() => selectTab('about')}
        >
          About
        </button>
        <button
          className={tab === 'posts' ? 'active' : ''}
          onClick={() => selectTab('posts')}
        >
          Posts {isPending && '...'}
        </button>
        <button
          className={tab === 'contact' ? 'active' : ''}
          onClick={() => selectTab('contact')}
        >
          Contact
        </button>
      </nav>

      <div className={isPending ? 'pending' : ''}>
        {tab === 'about' && <AboutTab />}
        {tab === 'posts' && <SlowTab />}
        {tab === 'contact' && <ContactTab />}
      </div>
    </div>
  );
}

List Filtering#

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

function FilterableList({ items }) {
  const [filter, setFilter] = useState('');
  const [displayFilter, setDisplayFilter] = useState('');
  const [isPending, startTransition] = useTransition();

  const filteredItems = useMemo(() => {
    return items.filter((item) =>
      item.name.toLowerCase().includes(displayFilter.toLowerCase())
    );
  }, [items, displayFilter]);

  const handleFilterChange = (e) => {
    const value = e.target.value;

    // Update input immediately
    setFilter(value);

    // Defer the actual filtering
    startTransition(() => {
      setDisplayFilter(value);
    });
  };

  return (
    <div>
      <input
        type="text"
        value={filter}
        onChange={handleFilterChange}
        placeholder="Filter items..."
      />

      <div className={isPending ? 'list pending' : 'list'}>
        {filteredItems.map((item) => (
          <ListItem key={item.id} item={item} />
        ))}
      </div>
    </div>
  );
}

import { useState, useTransition } from 'react';

function Router() {
  const [page, setPage] = useState('home');
  const [isPending, startTransition] = useTransition();

  const navigate = (newPage) => {
    startTransition(() => {
      setPage(newPage);
    });
  };

  return (
    <div>
      <nav>
        <NavLink
          to="home"
          active={page === 'home'}
          pending={isPending}
          onClick={() => navigate('home')}
        />
        <NavLink
          to="dashboard"
          active={page === 'dashboard'}
          pending={isPending}
          onClick={() => navigate('dashboard')}
        />
        <NavLink
          to="settings"
          active={page === 'settings'}
          pending={isPending}
          onClick={() => navigate('settings')}
        />
      </nav>

      {isPending && <LoadingBar />}

      <main style={{ opacity: isPending ? 0.7 : 1 }}>
        <PageContent page={page} />
      </main>
    </div>
  );
}

function NavLink({ to, active, pending, onClick, children }) {
  return (
    <button
      className={`nav-link ${active ? 'active' : ''} ${pending ? 'pending' : ''}`}
      onClick={onClick}
    >
      {children || to}
    </button>
  );
}

Form with Expensive Validation#

import { useState, useTransition } from 'react';

function ComplexForm() {
  const [formData, setFormData] = useState({
    username: '',
    email: '',
    bio: '',
  });
  const [validationResult, setValidationResult] = useState(null);
  const [isPending, startTransition] = useTransition();

  const handleChange = (field) => (e) => {
    const value = e.target.value;

    // Update form immediately
    setFormData((prev) => ({ ...prev, [field]: value }));

    // Defer expensive validation
    startTransition(() => {
      const result = validateForm({ ...formData, [field]: value });
      setValidationResult(result);
    });
  };

  return (
    <form>
      <div>
        <input
          value={formData.username}
          onChange={handleChange('username')}
          placeholder="Username"
        />
      </div>

      <div>
        <input
          value={formData.email}
          onChange={handleChange('email')}
          placeholder="Email"
        />
      </div>

      <div>
        <textarea
          value={formData.bio}
          onChange={handleChange('bio')}
          placeholder="Bio"
        />
      </div>

      {isPending ? (
        <span>Validating...</span>
      ) : validationResult?.errors ? (
        <ul className="errors">
          {validationResult.errors.map((err, i) => (
            <li key={i}>{err}</li>
          ))}
        </ul>
      ) : null}
    </form>
  );
}

Search with Debounce Alternative#

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

// Using useTransition
function SearchWithTransition() {
  const [query, setQuery] = useState('');
  const [searchResults, setSearchResults] = useState([]);
  const [isPending, startTransition] = useTransition();

  const handleSearch = (e) => {
    const value = e.target.value;
    setQuery(value);

    startTransition(() => {
      // Expensive search operation
      const results = performSearch(value);
      setSearchResults(results);
    });
  };

  return (
    <div>
      <input value={query} onChange={handleSearch} />
      {isPending && <Spinner />}
      <SearchResults results={searchResults} />
    </div>
  );
}

// Alternative: useDeferredValue
function SearchWithDeferredValue() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  const searchResults = useMemo(
    () => performSearch(deferredQuery),
    [deferredQuery]
  );

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

Multiple Transitions#

import { useState, useTransition } from 'react';

function Dashboard() {
  const [data, setData] = useState(null);
  const [filter, setFilter] = useState('all');
  const [sort, setSort] = useState('date');

  const [isFilterPending, startFilterTransition] = useTransition();
  const [isSortPending, startSortTransition] = useTransition();

  const handleFilterChange = (newFilter) => {
    startFilterTransition(() => {
      setFilter(newFilter);
    });
  };

  const handleSortChange = (newSort) => {
    startSortTransition(() => {
      setSort(newSort);
    });
  };

  const processedData = useMemo(() => {
    if (!data) return [];
    let result = [...data];

    if (filter !== 'all') {
      result = result.filter((item) => item.category === filter);
    }

    result.sort((a, b) => {
      if (sort === 'date') return b.date - a.date;
      if (sort === 'name') return a.name.localeCompare(b.name);
      return 0;
    });

    return result;
  }, [data, filter, sort]);

  return (
    <div>
      <FilterBar
        filter={filter}
        onChange={handleFilterChange}
        isPending={isFilterPending}
      />
      <SortBar
        sort={sort}
        onChange={handleSortChange}
        isPending={isSortPending}
      />
      <DataTable data={processedData} />
    </div>
  );
}

With Suspense#

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

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

  return (
    <div>
      <TabButtons
        activeTab={tab}
        isPending={isPending}
        onSelect={(nextTab) => {
          startTransition(() => {
            setTab(nextTab);
          });
        }}
      />

      <Suspense fallback={<Spinner />}>
        <TabPanel tab={tab} />
      </Suspense>
    </div>
  );
}

// Lazy loaded components work seamlessly
const TabPanel = ({ tab }) => {
  switch (tab) {
    case 'home':
      return <HomePage />;
    case 'profile':
      return <ProfilePage />; // May suspend while loading
    case 'settings':
      return <SettingsPage />;
    default:
      return null;
  }
};

Best Practices#

When to Use:
✓ Tab switching with heavy content
✓ Search/filter with large lists
✓ Form validation feedback
✓ Navigation between views
✓ Any non-urgent state update

Patterns:
✓ Pair urgent and non-urgent updates
✓ Show isPending feedback
✓ Use with Suspense for data fetching
✓ Consider useDeferredValue alternative

Performance:
✓ Wrap only the slow update
✓ Keep transitions granular
✓ Don't nest startTransition calls
✓ Use memo for expensive children

Avoid:
✗ Wrapping all state updates
✗ Using for urgent UI feedback
✗ Controlled input value in transition
✗ Ignoring isPending state

The useTransition hook keeps your UI responsive by marking state updates as non-urgent. Use it for tab switching, list filtering, and navigation where the update can be deferred. The isPending flag lets you show loading states while transitions process. Pair it with useMemo for expensive computations and Suspense for data fetching. Remember: urgent updates like text input should stay outside startTransition.