useTransition — React Deep Dive

synchronous → concurrent: split updates by urgency

By default every setState is urgent — React must render it before the browser can paint the next frame. That blocks typing when the render is heavy. useTransition returns a pair [isPending, startTransition]: wrap the expensive setState in startTransition(fn) and React schedules it at transition priority — interruptible, deferred, and shown only when ready. The urgent update (the input) paints immediately; the non-urgent update (the filtered list) catches up in the background.

piece	role	analogy
`startTransition`	runs a callback whose setStates are marked low priority	the "later" tray — React processes it when the urgent queue is empty
`isPending`	`true` while the deferred render is computing	the loading light — on while the background work is in flight
urgent setState	normal `setState` outside `startTransition`	the "now" tray — must paint before the next frame
interruption	a new urgent update cancels the in-progress transition	an interrupting phone call — drop the tray, handle the call, resume after

1 · the transition you write (edit me)

// 200 items — enough rows that filtering is non-trivial work.
var ALL_ITEMS = [];
for (var i = 0; i < 200; i++) {
  ALL_ITEMS.push('Item ' + (i + 1) + ' — ' + Math.random().toString(36).substring(7));
}

function TransitionDemo() {
  // URGENT state — the input value. Typing must always be instant.
  var inputState = React.useState('');
  var input = inputState[0];
  var setInput = inputState[1];

  // The transition hook: [isPending, startTransition].
  var transition = React.useTransition();
  var isPending = transition[0];
  var startTransition = transition[1];

  // NON-URGENT state — the filter the list actually uses.
  var filterState = React.useState('');
  var filter = filterState[0];
  var setFilter = filterState[1];

  // Witness: remember whether isPending was ever true (for the gold-check).
  var sawPendingRef = React.useRef(false);
  React.useEffect(function () {
    if (isPending) sawPendingRef.current = true;
  }, [isPending]);

  function handleChange(e) {
    var val = e.target.value;
    setInput(val);            // urgent — paints now, input stays responsive
    startTransition(function () {
      setFilter(val);         // non-urgent — list re-filtering can wait
    });
  }

  var filtered = ALL_ITEMS.filter(function (item) {
    return item.toLowerCase().indexOf(filter.toLowerCase()) >= 0;
  });

  return (
    <div className="max-w-lg mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-1">
        Search {isPending && <span className="spin" />}
      </h2>
      <p className="text-xs text-[#8b949e] mb-3">
        {filtered.length} of {ALL_ITEMS.length} items
        {isPending ? ' · filtering…' : ' · ready'}
      </p>
      <input
        data-testid="input"
        value={input}
        onChange={handleChange}
        className="w-full px-3 py-2 mb-3 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm outline-none focus:border-[#61dafb]"
        placeholder="Type to filter — input stays responsive, list catches up"
      />
      <ul data-testid="list" className="max-h-64 overflow-auto space-y-1">
        {filtered.map(function (item, idx) {
          return (
            <li
              key={idx}
              data-testid="item"
              className={"px-3 py-1.5 rounded text-sm border " + (isPending ? 'bg-[#0d1117] border-[#30363d] text-[#8b949e] opacity-70' : 'bg-[#0d1117] border-[#30363d] text-[#e6edf3]')}
            >
              {item}
            </li>
          );
        })}
      </ul>
      {/* hidden sentinel — lets the gold-check assert isPending was observed */}
      <div
        data-testid="pending-witness"
        data-seen={sawPendingRef.current ? 'true' : 'false'}
        data-pending={isPending ? 'true' : 'false'}
        style={{ display: 'none' }}
      />
    </div>
  );
}

createRoot(document.getElementById('root')).render(<TransitionDemo/>);

2 · Babel compiles JSX → element tree

<TransitionDemo/> becomes React.createElement(TransitionDemo). setInput runs at urgent priority (input updates now); setFilter inside startTransition runs at transition priority (list updates when React is idle). isPending flips true the moment the transition is scheduled.

// (hit "compile & render" to see Babel's output)

3 · live React (urgent vs non-urgent, proven)

Type fast in the box. The input updates every keystroke (urgent); the list is re-filtered inside a transition, so it dims and catches up — the spinner shows while isPending is true. The gold-check does this automatically: types "Item 1", asserts the input is instant, waits for the list to shrink, and confirms the pending indicator fired.

items: — · pending: — · gold: 200 items → type "Item 1" → list shrinks, pending observed

intent → pattern

intent	pattern	why
keep typing responsive while a heavy list filters	`setInput(v); startTransition(() => setFilter(v))`	input is urgent (paints now); filter is non-urgent (deferred)
show a spinner during the deferred work	`{isPending && <Spinner/>}`	`isPending` is true until the transition commits
switch tabs without blocking the click	`startTransition(() => setTab(next))`	the old tab stays interactive until the new one is ready
you control the value, not the update	use `useDeferredValue` instead	defer at the consumption site (read-side), not the producer
urgent work must never be wrapped	keep typing/clicking/scroll setState OUTSIDE `startTransition`	wrapping urgent updates makes the UI feel frozen