awesome-copilot/plugins/react19-upgrade/skills/react19-concurrent-patterns/references/react19-use.md

title

title
React 19 use() Hook Pattern Reference

React 19 use() Hook Pattern Reference

The use() hook is React 19's answer for unwrapping promises and context within React components. It enables cleaner async patterns directly in your component body, avoiding the architectural complexity that previously required separate lazy components or complex state management.

What is use()?

use() is a hook that:

• Accepts a promise or context object
• Returns the resolved value or context value
• Handles Suspense automatically for promises
• Can be called conditionally inside components (not at top level for promises)
• Throws errors, which Suspense + error boundary can catch

use() with Promises

React 18 Pattern

// React 18 approach 1  lazy load a component module:
const UserComponent = React.lazy(() => import('./User'));

function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <UserComponent />
    </Suspense>
  );
}

// React 18 approach 2  fetch data with state + useEffect:
function App({ userId }) {
  const [user, setUser] = useState(null);
  
  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);
  
  if (!user) return <Spinner />;
  return <User user={user} />;
}

React 19 use() Pattern

// React 19  use() directly in component:
function App({ userId }) {
  const user = use(fetchUser(userId)); // Suspends automatically
  return <User user={user} />;
}

// Usage:
function Root() {
  return (
    <Suspense fallback={<Spinner />}>
      <App userId={123} />
    </Suspense>
  );
}

Key differences:

• use() unwraps the promise directly in the component body
• Suspense boundary is still needed, but can be placed at app root (not per-component)
• No state or useEffect needed for simple async data
• Conditional wrapping allowed inside components

use() with Promises -- Conditional Fetching

// React 18  conditional with state
function SearchResults() {
  const [results, setResults] = useState(null);
  const [query, setQuery] = useState('');
  
  useEffect(() => {
    if (query) {
      search(query).then(setResults);
    } else {
      setResults(null);
    }
  }, [query]);
  
  if (!results) return null;
  return <Results items={results} />;
}

// React 19  use() with conditional
function SearchResults() {
  const [query, setQuery] = useState('');
  
  if (!query) return null;
  
  const results = use(search(query)); // Only fetches if query is truthy
  return <Results items={results} />;
}

use() with Context

use() can unwrap context without being at component root. Less common than promise usage, but useful for conditional context reading:

// React 18  always in component body, only works at top level
const theme = useContext(ThemeContext);

// React 19  can be conditional
function Button({ useSystemTheme }) {
  const theme = useSystemTheme ? use(ThemeContext) : defaultTheme;
  return <button style={theme}>Click</button>;
}

---

Migration Strategy

Phase 1 No changes required

React 19 use() is opt-in. All existing Suspense + component splitting patterns continue to work:

// Keep this as-is if it's working:
const Lazy = React.lazy(() => import('./Component'));
<Suspense fallback={<Spinner />}><Lazy /></Suspense>

Phase 2 Post-migration cleanup (optional)

After React 19 migration stabilizes, profile codebases for useEffect + state async patterns. These are good candidates for use() refactoring:

Identify patterns:

grep -rn "useEffect.*\(.*fetch\|async\|promise" src/ --include="*.js" --include="*.jsx"

Target:

• Simple fetch-on-mount patterns
• No complex dependency arrays
• Single promise per component
• Suspense already in use elsewhere in the app

Example refactor:

// Before:
function Post({ postId }) {
  const [post, setPost] = useState(null);
  
  useEffect(() => {
    fetchPost(postId).then(setPost);
  }, [postId]);
  
  if (!post) return <Spinner />;
  return <PostContent post={post} />;
}

​// After:
function Post({ postId }) {
  const post = use(fetchPost(postId));
  return <PostContent post={post} />;
}

// And ensure Suspense at app level:
<Suspense fallback={<AppSpinner />}>
  <Post postId={123} />
</Suspense>

---

Error Handling

use() throws errors, which Suspense error boundaries catch:

function Root() {
  return (
    <ErrorBoundary fallback={<ErrorScreen />}>
      <Suspense fallback={<Spinner />}>
        <DataComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

function DataComponent() {
  const data = use(fetchData()); // If fetch rejects, error boundary catches it
  return <Data data={data} />;
}

---

When NOT to use use()

• Avoid during migration stabilize React 19 first
• Complex dependencies if multiple promises or complex ordering logic, stick with useEffect
• Retry logic use() doesn't handle retry; useEffect with state is clearer
• Debounced updates use() refetches on every prop change; useEffect with cleanup is better