react-concurrent

React Concurrent Features

Full Reference: See advanced.md for advanced concurrent patterns including priority-based updates, optimistic updates with transitions, router integration, form actions, and debugging techniques.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: react, topic: concurrent for comprehensive documentation.

When NOT to Use This Skill

Skip this skill when:

Using React 17 or earlier (not available)
Building simple apps with fast renders
All state updates are already fast (< 16ms)
Working with non-React frameworks
Server Components handle the work (Next.js App Router)

Overview

Concurrent React allows interrupting renders to keep the UI responsive:

Traditional Rendering:
[Update starts]────────────────────────[Render complete]
                    UI blocked!

Concurrent Rendering:
[Update starts]──[pause]──[higher priority]──[resume]──[complete]
                    UI remains responsive!

useTransition

Mark state updates as non-urgent (can be interrupted):

import { useState, useTransition } from 'react';

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

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

  return (
    <div>
      <nav>
        {['home', 'about', 'contact'].map((t) => (
          <button key={t} onClick={() => selectTab(t)}>
            {t}
          </button>
        ))}
      </nav>

      <div className={isPending ? 'opacity-50' : ''}>
        {tab === 'home' && <Home />}
        {tab === 'about' && <About />}
        {tab === 'contact' && <Contact />}
      </div>
    </div>
  );
}

useDeferredValue

Defer updating a value to keep UI responsive:

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

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

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />

      <div className={isStale ? 'opacity-50' : ''}>
        <SearchResults query={deferredQuery} />
      </div>
    </div>
  );
}

// Memoize to actually benefit from deferred value
const SearchResults = memo(function SearchResults({ query }: { query: string }) {
  const results = useMemo(() => {
    return items.filter(item =>
      item.name.toLowerCase().includes(query.toLowerCase())
    );
  }, [query]);

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

startTransition (without Hook)

For use outside components or when you don't need isPending:

import { startTransition } from 'react';

function handleClick() {
  startTransition(() => {
    setPage('/heavy-page');
  });
}

Suspense with Transitions

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

  return (
    <div>
      <nav>
        <button onClick={() => startTransition(() => setTab('posts'))}>
          Posts
        </button>
      </nav>

      <Suspense fallback={<TabSkeleton />}>
        <div className={isPending ? 'opacity-50' : ''}>
          {tab === 'posts' && <Posts />}
        </div>
      </Suspense>
    </div>
  );
}

useTransition vs useDeferredValue

Feature	useTransition	useDeferredValue
Purpose	Wrap state updates	Defer a value
Usage	When you control the update	When you receive a value
Returns	`[isPending, startTransition]`	Deferred value
Use case	Button clicks, form submits	Props from parent

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Wrapping every state update	Adds unnecessary complexity	Only for heavy updates
Not memoizing child components	No benefit from deferred value	Use `memo()`
Using for fast operations	Performance overhead	Reserve for slow renders (> 50ms)
Ignoring isPending state	User sees no feedback	Show loading indicator
Multiple transitions unnecessarily	Confusing behavior	Batch related updates

Quick Troubleshooting

Issue	Likely Cause	Solution
No performance improvement	Child not memoized	Add `memo()` to component
Still blocking UI	Synchronous heavy computation	Move to Web Worker
isPending always false	Update completes too fast	No transition needed
Stale UI shown too long	No loading indicator	Check and display isPending
Transition not working	Using in React < 18	Upgrade to React 18+

Best Practices

✅ Use for user-initiated heavy updates
✅ Combine with memo() for list components
✅ Show visual feedback during pending state
✅ Use for route transitions
✅ Prefer useDeferredValue for received props
❌ Don't wrap every state update
❌ Don't use for fast operations
❌ Don't forget to memoize child components

Reference Documentation