Should I use useTransition here because this render is slow?

Which update is urgent?
Which update may be interrupted?
Which state controls user input and must never be deferred?
Which visual result may lag while the app stays responsive?
Can the user still understand the temporary mismatch?

function ProductPage() {
  const [tab, setTab] = useState<'overview' | 'reviews' | 'pricing'>('overview');

  return (
    <>
      <TabBar value={tab} onChange={setTab} />
      <ExpensiveTabPanel tab={tab} />
    </>
  );
}

urgent feedback     : update immediately
transitioned result : update in background / interruptible render

Transition render must be pure.
Transition state must tolerate being restarted.
Transition UI must tolerate being temporarily stale.

import { useTransition } from 'react';

function Component() {
  const [isPending, startTransition] = useTransition();

  function run() {
    startTransition(() => {
      // state updates here are marked as transition updates
    });
  }
}

isPending        : true while a transition is pending
startTransition  : function used to mark updates as transition work

network request is pending
specific entity is pending
specific mutation is pending
specific route is pending

some transition created by this hook is pending and has not finished showing its final result

If delaying the update breaks direct manipulation, do not transition it.
If delaying the update preserves responsiveness and the temporary mismatch is understandable, transition it.

function SearchPage() {
  const [query, setQuery] = useState('');
  const [mode, setMode] = useState<'grid' | 'table'>('table');

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <ModeSwitch value={mode} onChange={setMode} />
      <VeryExpensiveResults query={query} mode={mode} />
    </>
  );
}

function SearchPage() {
  const [query, setQuery] = useState('');
  const [mode, setMode] = useState<'grid' | 'table'>('table');
  const [resultView, setResultView] = useState({ query: '', mode: 'table' as const });
  const [isPending, startTransition] = useTransition();

  function updateQuery(nextQuery: string) {
    setQuery(nextQuery); // urgent: input must stay responsive

    startTransition(() => {
      setResultView((prev) => ({ ...prev, query: nextQuery }));
    });
  }

  function updateMode(nextMode: 'grid' | 'table') {
    setMode(nextMode); // urgent: control feedback

    startTransition(() => {
      setResultView((prev) => ({ ...prev, mode: nextMode }));
    });
  }

  return (
    <>
      <input value={query} onChange={(e) => updateQuery(e.target.value)} />
      <ModeSwitch value={mode} onChange={updateMode} />

      {isPending && <InlinePendingBadge>Updating results…</InlinePendingBadge>}

      <VeryExpensiveResults query={resultView.query} mode={resultView.mode} />
    </>
  );
}

control state = urgent
result view state = transition

resultView must eventually catch up to query/mode

function SearchResultsPanel({ query }: { query: string }) {
  const deferredQuery = useDeferredValue(query);
  return <Results query={deferredQuery} />;
}

function AnalyticsTabs() {
  const [selectedTab, setSelectedTab] = useState<'summary' | 'funnel' | 'retention'>('summary');
  const [visibleTab, setVisibleTab] = useState(selectedTab);
  const [isPending, startTransition] = useTransition();

  function selectTab(nextTab: typeof selectedTab) {
    setSelectedTab(nextTab);

    startTransition(() => {
      setVisibleTab(nextTab);
    });
  }

  return (
    <section>
      <TabList value={selectedTab} onChange={selectTab} pending={isPending} />
      <TabPanel tab={visibleTab} />
    </section>
  );
}

selectedTab = what user selected now
visibleTab  = content currently rendered or rendering

The tab selection changed; content is catching up.

user changes query
→ new content suspends
→ boundary may replace old content with fallback

user changes query
→ transition update suspends
→ React may keep already revealed content visible while new content loads

function CustomerPage() {
  const [customerId, setCustomerId] = useState('c_001');
  const [shownCustomerId, setShownCustomerId] = useState(customerId);
  const [isPending, startTransition] = useTransition();

  function selectCustomer(nextId: string) {
    setCustomerId(nextId);
    startTransition(() => setShownCustomerId(nextId));
  }

  return (
    <>
      <CustomerPicker value={customerId} onChange={selectCustomer} />
      {isPending && <PendingBar />}

      <Suspense fallback={<CustomerSkeleton />}>
        <CustomerDetail customerId={shownCustomerId} />
      </Suspense>
    </>
  );
}

function QuantityEditor({ initialQuantity }: { initialQuantity: number }) {
  const [quantity, setQuantity] = useState(initialQuantity);
  const [error, setError] = useState<string | null>(null);
  const [isPending, startTransition] = useTransition();

  function saveQuantity(nextQuantity: number) {
    startTransition(async () => {
      setError(null);

      try {
        const saved = await api.updateQuantity(nextQuantity);

        // Current React docs still require wrapping state updates after await
        // in another startTransition to mark them as transition updates.
        startTransition(() => {
          setQuantity(saved.quantity);
        });
      } catch (err) {
        startTransition(() => {
          setError(toUserMessage(err));
        });
      }
    });
  }

  return (
    <QuantityControl
      value={quantity}
      disabled={isPending}
      error={error}
      onChange={saveQuantity}
    />
  );
}

Async work can be part of an Action.
State updates after await currently need another startTransition wrapper to be marked as transition updates.

function useTransitionAction<TArgs extends unknown[]>(
  action: (...args: TArgs) => Promise<void>,
) {
  const [isPending, startTransition] = useTransition();

  const run = useCallback((...args: TArgs) => {
    startTransition(async () => {
      await action(...args);
    });
  }, [action, startTransition]);

  return { isPending, run };
}

startTransition(async () => {
  const result = await fetchCustomers(query);
  startTransition(() => setCustomers(result));
});

cache identity
request deduplication
stale data
retry
abort
pagination
background refresh
invalidation after mutation
SSR hydration

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

  const customersQuery = useCustomersQuery(submittedQuery);

  function submitSearch(nextQuery: string) {
    setQuery(nextQuery);

    startTransition(() => {
      setSubmittedQuery(nextQuery);
    });
  }

  return (
    <>
      <SearchBox value={query} onChange={setQuery} onSubmit={submitSearch} />
      <CustomerResults
        customers={customersQuery.data ?? []}
        loading={customersQuery.isLoading}
        refreshing={isPending || customersQuery.isFetching}
      />
    </>
  );
}

React transition = render scheduling
Query library     = server-state lifecycle

function SearchBox() {
  const [text, setText] = useState('');
  const [isPending, startTransition] = useTransition();

  return (
    <input
      value={text}
      onChange={(event) => {
        startTransition(() => {
          setText(event.target.value);
        });
      }}
    />
  );
}

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

  function onChange(nextText: string) {
    setText(nextText);

    startTransition(() => {
      setQuery(nextText);
    });
  }

  return (
    <>
      <input value={text} onChange={(event) => onChange(event.target.value)} />
      {isPending && <span>Updating results…</span>}
      <SearchResults query={query} />
    </>
  );
}

function ExpensiveGrid({ filters }: Props) {
  const [isPending, startTransition] = useTransition();
  // too late: grid does not own the filter transition
}

function SearchPage() {
  const [filters, setFilters] = useState(defaultFilters);
  const [appliedFilters, setAppliedFilters] = useState(defaultFilters);
  const [isPending, startTransition] = useTransition();

  function applyFilters(next: Filters) {
    setFilters(next);
    startTransition(() => setAppliedFilters(next));
  }

  return (
    <SearchLayout
      controls={<FilterPanel value={filters} onChange={applyFilters} />}
      result={<ResultGrid filters={appliedFilters} pending={isPending} />}
    />
  );
}

controls urgent, results transition

urgent feedback       : clicked link active/pressed state
transition work       : route tree render, data boundary, Suspense boundary
history mutation      : route framework responsibility
scroll/focus policy   : router/app shell responsibility

function AppRouter() {
  const [route, setRoute] = useState(() => parseLocation(window.location));
  const [isPending, startTransition] = useTransition();

  const navigate = useCallback((href: string) => {
    window.history.pushState(null, '', href);

    startTransition(() => {
      setRoute(parseLocation(window.location));
    });
  }, [startTransition]);

  return (
    <RouterContext value={{ route, navigate, isNavigating: isPending }}>
      <AppShell pending={isPending}>
        <Suspense fallback={<RouteSkeleton />}>
          <RouteRenderer route={route} />
        </Suspense>
      </AppShell>
    </RouterContext>
  );
}

Navigation state is a classic transition use case.

What is urgent feedback?
What is transition-rendered result?
What tracks network pending?
What tracks transition pending?
What handles error?
What handles rollback or retry?
What prevents duplicate submit?

<button aria-busy={isPending} data-pending={isPending || undefined}>
  Reviews
</button>

<div aria-live="polite">
  {isPending ? 'Updating view…' : null}
</div>

<ResultPanel dimmed={isPending} />

{isPending ? <FullPageSpinner /> : <ExistingContent />}

local
non-destructive
understandable
not layout-jumping
not hiding useful old content unless correctness requires it

input feels broken
button state lags
modal close feels delayed
screen reader announces stale selection

direct manipulation state was marked as transition work

split urgent control state from transition content state

user selected Customer B, but detail panel still shows Customer A with no indication

transition kept old content visible, but UI did not communicate staleness

const stale = selectedCustomerId !== shownCustomerId;

<CustomerDetailFrame aria-busy={stale || isPending} data-stale={stale || undefined}>
  <CustomerDetail customerId={shownCustomerId} />
</CustomerDetailFrame>

memoization
virtualization
splitting components
moving computation out of render
precomputing read models
web worker for CPU-heavy pure computation
server-side aggregation
canvas/WebGL for huge visualizations

function ExpensivePanel({ tab }: { tab: string }) {
  analytics.track('tab_rendered', { tab }); // side effect during render
  return <Panel tab={tab} />;
}

function ExpensivePanel({ tab }: { tab: string }) {
  useEffect(() => {
    analytics.track('tab_committed', { tab });
  }, [tab]);

  return <Panel tab={tab} />;
}

transition A has pending flag A
transition B has pending flag B
React guarantees separate scheduling and completion semantics

transition pending is a coarse UI scheduling signal
for domain-specific pending state, track domain-specific identity

type PendingCommand =
  | { type: 'none' }
  | { type: 'saving-customer'; customerId: string }
  | { type: 'recalculating-report'; reportId: string };

function TransactionsExplorer({ transactions }: Props) {
  const [draftFilters, setDraftFilters] = useState(defaultFilters);
  const [appliedFilters, setAppliedFilters] = useState(defaultFilters);
  const [isPending, startTransition] = useTransition();

  const rows = useMemo(() => {
    return buildTransactionRows(transactions, appliedFilters);
  }, [transactions, appliedFilters]);

  function updateFilters(next: Filters) {
    setDraftFilters(next);
    startTransition(() => {
      setAppliedFilters(next);
    });
  }

  return (
    <ExplorerLayout
      filters={<TransactionFilters value={draftFilters} onChange={updateFilters} />}
      table={<TransactionTable rows={rows} busy={isPending} />}
    />
  );
}

TransactionFilters renders cheaply
TransactionTable is expensive
buildTransactionRows is tied to table render path
stale table while filters update is acceptable

function CaseTree({ root }: { root: CaseNode }) {
  const [expandedDraft, setExpandedDraft] = useState<Set<string>>(() => new Set());
  const [expandedRendered, setExpandedRendered] = useState<Set<string>>(() => new Set());
  const [isPending, startTransition] = useTransition();

  function toggle(nodeId: string) {
    setExpandedDraft((current) => toggleSet(current, nodeId));

    startTransition(() => {
      setExpandedRendered((current) => toggleSet(current, nodeId));
    });
  }

  return (
    <TreeFrame pending={isPending}>
      <TreeView root={root} expanded={expandedRendered} onToggle={toggle} />
    </TreeFrame>
  );
}

type SavePanelProps = {
  saveAction: (input: SaveInput) => void;
  pending: boolean;
};

function SavePanel({ saveAction, pending }: SavePanelProps) {
  return (
    <button disabled={pending} onClick={() => saveAction(readInput())}>
      {pending ? 'Saving…' : 'Save'}
    </button>
  );
}

function CasePage() {
  const [isPending, startTransition] = useTransition();

  function saveAction(input: SaveInput) {
    startTransition(async () => {
      await saveCase(input);
      startTransition(() => {
        // update visible state or invalidate cache
      });
    });
  }

  return <SavePanel saveAction={saveAction} pending={isPending} />;
}

1. Reproduce the jank.
2. Identify the urgent interaction that feels blocked.
3. Profile render cost.
4. Find which subtree is expensive.
5. Check whether the expensive update can be stale/interrupted.
6. Add transition boundary at the owner of the UX policy.
7. Add pending/stale indication.
8. Re-profile.
9. If still slow, reduce actual work.

[ ] Direct input/control state is not transitioned.
[ ] There is a clear urgent vs non-urgent split.
[ ] Stale UI is either acceptable or visibly marked.
[ ] `isPending` is not misused as network/domain pending state.
[ ] State updates after await are correctly marked if needed.
[ ] Render path is pure and restart-safe.
[ ] Expensive subtree is actually the render bottleneck.
[ ] The transition boundary lives at the owner of the UX policy.
[ ] Error handling is explicit.
[ ] Server-state lifecycle is not reinvented with transition state.

type SearchModel = {
  keyword: string;
  status: 'all' | 'open' | 'closed';
  page: number;
};

function CaseSearchPage() {
  const [draft, setDraft] = useState<SearchModel>({
    keyword: '',
    status: 'all',
    page: 1,
  });

  const [applied, setApplied] = useState(draft);
  const [isPending, startTransition] = useTransition();

  const query = useCasesQuery(applied);

  function updateDraft(patch: Partial<SearchModel>) {
    setDraft((current) => ({ ...current, ...patch, page: 1 }));
  }

  function apply() {
    startTransition(() => {
      setApplied(draft);
    });
  }

  function goToPage(page: number) {
    setDraft((current) => ({ ...current, page }));

    startTransition(() => {
      setApplied((current) => ({ ...current, page }));
    });
  }

  const refreshing = isPending || query.isFetching;

  return (
    <CaseSearchLayout
      filters={
        <CaseFilters
          value={draft}
          onChange={updateDraft}
          onApply={apply}
          disabled={false}
        />
      }
      results={
        <CaseResults
          cases={query.data?.items ?? []}
          page={applied.page}
          refreshing={refreshing}
          onPageChange={goToPage}
        />
      }
    />
  );
}

Draft filter editing is urgent and local.
Applied query state changes in a transition.
Server-state lifecycle belongs to useCasesQuery.
Refresh indicator combines transition scheduling and query fetching.
Pagination is explicit command state.

Draft and applied are intentionally separate. The invariant must be visible in names and tests.

a debounce
an async request manager
a cache
a data fetching strategy
a replacement for virtualization
a way to make expensive code cheap
a safe place to hide stale correctness problems

Urgent state represents direct user manipulation.
Transition state represents visual work that may lag.
Pending UI explains the lag.
Pure rendering makes interruption safe.
Domain pending state remains domain-owned.