Skip to content

React 19 New Features: Complete Guide and Migration Steps

React 19 measured on 19.3.1: how Actions queue, why useOptimistic can show a duplicate, what use() does with a new promise, and which APIs shipped when.

· · 15 min read

Updated: October 16, 2026

React 19 code showing new hooks and Actions in a code editor

Quick Take

I ran React 19.3.1's headline APIs and recorded what they did. Actions run one at a time, useOptimistic shows a duplicate unless you wrap the real update, use() with a promise made in render never settles, and Activity and useEffectEvent arrived in 19.2, not 19.1.

Run this yourself. The script behind every observation in this article: react-19-hooks-measured/ in the Coding Dunia code-examples repo.

React 19 is the major version of React, stable since December 5, 2024, that moved async form handling, optimistic updates and promise reading into the core library. Its headline additions are Actions (useTransition accepts async functions, plus useActionState and <form action>), useOptimistic, ref as a regular prop, and the use() hook. The React Compiler is related but separate: a Babel plugin you install yourself. The migration path is short: npm install react@19 react-dom@19, run npx react-codemod@latest react-19, update @types/react and @types/react-dom to v19, then check your third-party libraries.

Release posts tell you what exists. They don't tell you what happens when you press the button twice, or when the request fails. So I installed React 19.3.1, ran each API in jsdom, checked the exports of the older 19.x releases, and wrote down what came out. No React Compiler anywhere in those runs. Where the article says "measured", it means that script, and it asserts every result, so it fails if a future React changes the answer.

Which React Version Shipped Which API?

I'll start here because it fixed mistakes in my own earlier draft. The question "does this export exist?" has a mechanical answer: install the version and check.

Export18.3.119.0.019.1.019.2.019.3.1
use, useActionState, useOptimisticnoyesyesyesyes
useEffectEvent, Activity, cacheSignalnononoyesyes
react/compiler-runtimenoyesyesyesyes

Release dates from the npm registry: 19.0.0 on December 5, 2024, 19.1.0 on March 28, 2025, 19.2.0 on October 1, 2025, 19.3.0 on September 9, 2026, and 19.3.1 on October 14, 2026. So <Activity> and useEffectEvent are 19.2 features. An earlier version of this guide filed them under 19.1 and called useEffectEvent stable in 19.0. Neither was true, and the table above is the proof.

The bottom row is worth a second look. The compiler isn't in the package, but its runtime is, and has been since 19.0.0.

What Is the React Compiler?

The React Compiler (previously React Forget) memoizes your components and hooks at build time, so you won't need manual useMemo, useCallback or React.memo in most cases. It reached 1.0 in October 2025 and works as a Babel plugin, babel-plugin-react-compiler.

// Before  -  manual memoization
const ExpensiveComponent = memo(({ data }) => {
  const processed = useMemo(() => processData(data), [data]);
  const handleClick = useCallback(() => onClick(processed), [processed, onClick]);
  return <div onClick={handleClick}>{processed.title}</div>;
});

// After  -  compiler handles this automatically
function ExpensiveComponent({ data }) {
  const processed = processData(data);
  const handleClick = () => onClick(processed);
  return <div onClick={handleClick}>{processed.title}</div>;
}

I measured what that buys in a separate test: 1,000 rows under a parent that re-renders for unrelated reasons. With no manual memoization at all, the compiled build re-rendered 0 rows, against 1,000 for the same source uncompiled. The numbers, and the cases where hand-written memo fails, are in React hooks best practices. For installing it and checking that it's actually working, see the React Compiler practical guide.

What Are React 19 Actions?

Actions are React 19's pattern for async mutations: form submissions, pending state and error handling without hand-rolling three useState calls per form. They come in two shapes, useTransition with an async function, and useActionState.

Lines of JavaScript glowing in colorful syntax highlighting on a dark screen
Photo by Gabriel Heinzer on Unsplash

useTransition with async functions

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

  async function handleSubmit(formData: FormData) {
    startTransition(async () => {
      await updateProfile(formData);
    });
  }

  return (
    <form action={handleSubmit}>
      <input name="username" />
      <button disabled={isPending}>
        {isPending ? 'Saving...' : 'Save'}
      </button>
    </form>
  );
}

The render log for a 30 ms async Action was isPending true, then false. Two renders after the click, nothing in between. For a heavy render rather than an Action, the startTransition click-delay measurements show what a transition buys you.

useActionState

useActionState manages an action's state and hands you a wrapped action for <form action>:

async function updateName(prevState: State, formData: FormData) {
  const name = formData.get('name') as string;
  const error = await saveToServer(name);
  return error ? { error } : { success: true };
}

function NameForm() {
  const [state, formAction, isPending] = useActionState(updateName, null);

  return (
    <form action={formAction}>
      <input name="name" />
      {state?.error && <p>{state.error}</p>}
      {state?.success && <p>Saved!</p>}
      <button disabled={isPending}>Update</button>
    </form>
  );
}

I submitted a real form with requestSubmit() and logged every render. One submit produced two: pending, then settled. Returning an error object is ordinary state, the same two renders. Throwing is different. The component never reached a settled state, and the nearest error boundary rendered instead.

Then the case the docs undersell. I called requestSubmit() twice back to back, while the first action was still waiting. The actions did not overlap. The log read start, end, start, end, and the second call received the state the first one returned (prevState was 0, then 1). The user-visible result was still just two renders.

useActionState runs submissions one after the other: the second action starts only after the first ends, and it receives the state the first one returned.

Share this Post on X Bluesky

That's a feature if you want ordered writes and a trap if you expected two parallel requests. Debounce or block double submits yourself if latency matters. For how to type the state and payload of these actions, with ten compile errors run on two TypeScript versions, see typing useActionState in React 19.

The compiler is stricter about this signature than most people expect, and useActionState type errors explained lists the seven messages you'll meet first.

How Does useOptimistic Work?

useOptimistic shows a speculative state while an async Action runs, then drops it when the Action ends. Here's the shape I measured, a list that appends an item:

function TodoList({ todos, setTodos, createTodo }) {
  const [, startTransition] = useTransition();
  const [optimisticTodos, addOptimistic] = useOptimistic(
    todos,
    (state, newTodo) => [...state, { ...newTodo, pending: true }]
  );

  function addTodo(text: string) {
    startTransition(async () => {
      addOptimistic({ id: crypto.randomUUID(), text });
      const saved = await createTodo(text);
      // State updates after an await are not part of the transition,
      // so wrap this one or you get a duplicate render (see below).
      startTransition(() => {
        setTodos(prev => [...prev, saved]);
      });
    });
  }

  return (
    <ul>
      {optimisticTodos.map(todo => (
        <li key={todo.id} style={{ opacity: todo.pending ? 0.5 : 1 }}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

I tracked what each render displayed, starting from a and adding b:

CaseRenders, in order
Success, real update after await not wrappeda,b* then a,b,b* then a,b
Success, real update wrapped in startTransitiona,b* then a,b* then a,b
Failure, nothing written to real statea,b* then a
addOptimistic called outside any actiona,b* then a
Hand-written pending state, successa,b* then a,b

The second row is the gotcha. With the real update unwrapped, one render shows the new item twice, once as real data and once as the optimistic copy still sitting on top. Wrap the update and the duplicate goes. Failure reverts on its own, which is the part that earns the hook its place. Calling it outside an action also reverts after one render, and React prints "An optimistic state update occurred outside a transition or action."

Is it worth it over hand-written pending state? The manual version needed two renders for a success, and the hook needed three. So what you save is the rollback code on failure, not renders. An earlier draft of this guide claimed it removes a fixed number of lines per component. I never counted, and the real figure depends on how much bookkeeping you were writing.

How Does ref Work as a Prop in React 19?

forwardRef isn't needed anymore. In React 19, ref is just a regular prop:

// React 19  -  no forwardRef needed
function Input({ ref, ...props }) {
  return <input ref={ref} {...props} />;
}

// Usage
function Form() {
  const inputRef = useRef<HTMLInputElement>(null);
  return <Input ref={inputRef} type="text" />;
}

I rendered both versions side by side. The plain function received the DOM node, and so did a component still wrapped in forwardRef. Neither logged a single warning in a development build of 19.3.1. The migration codemod handles forwardRef wrappers, and the React team has said the old API will be deprecated, but today it's quiet. An earlier draft of this article promised a deprecation warning. It doesn't exist yet.

One more thing I checked: a ref callback can return a cleanup function. Mine logged attach on mount and cleanup on unmount, in that order.

What Is the use() Hook in React 19?

use() reads a value from a Promise or Context inside render:

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

function UserProfile({ userPromise }) {
  const user = use(userPromise); // suspends until resolved
  return <h1>{user.name}</h1>;
}

function App() {
  const [userPromise] = useState(() => fetchUser());
  return (
    <Suspense fallback={<Spinner />}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}

Notice where the promise comes from. It's created once, outside the component that reads it. That detail is the whole story, and I have numbers. With the promise made outside, one fetch started and the component function ran three times before the text appeared. Create the promise inside the component instead, use(fetchUser()), and the page never finished loading. In a 1.5 second window with a promise that resolves in 20 ms, the fetch started about 70 times, the fallback never went away, and React printed no warning at all. Each retry made a fresh promise, and each fresh promise suspended again.

Where use() differs from every other hook is conditional calls. After an early return, it worked fine when the condition flipped. A second useState in the same position threw "Rendered more hooks than during the previous render" and the error boundary caught it. A rejected promise went to the boundary too.

Unlike every other hook, use() can sit after an early return, but a promise created inside the component suspends forever: in a 1.5 second test it started about 70 fetches and never left the fallback.

Share this Post on X Bluesky

What Is the React Activity API?

<Activity> shipped stable in React 19.2 (October 1, 2025), not 19.1. It keeps a subtree mounted while hiding it, and it's the stable form of the old experimental Offscreen API.

import { Activity } from 'react';

function Tabs({ activeTab }) {
  return (
    <>
      <Activity mode={activeTab === 'profile' ? 'visible' : 'hidden'}>
        <ProfileTab />
      </Activity>
      <Activity mode={activeTab === 'settings' ? 'visible' : 'hidden'}>
        <SettingsTab />
      </Activity>
    </>
  );
}

The usual claim is that hidden subtrees stop rendering. I compared it with display: none on the same child, logging renders, commits and effects:

Step<Activity mode="hidden">display: none
Hideeffect cleanup runs, child renders after the host commitchild renders, then host commits, effect keeps running
Parent changes a prop while hiddenhost commits first, then the child renderschild renders, then host commits
Show againchild renders, host commits, effect sets up againchild renders, host commits
Text typed into an input before hidingstill therestill there

So Activity doesn't skip the work. It moves the work behind the visible commit, and it tears down effects while hidden, which is the useful part for a hidden tab holding a subscription or a timer. State survives in both approaches. The "defers updates" claim holds, "skips rendering" doesn't. A longer run covers leaked listeners, hidden prefetching and the lint rules in Activity and useEffectEvent in practice.

A widescreen monitor on a wooden desk in a dimly lit room
Photo by Amr Taha on Unsplash

How Does useEffectEvent Work?

useEffectEvent (React 19.2) solves a common useEffect footgun: you need to read the latest props or state inside an effect, but those values shouldn't trigger a re-run.

import { useEffect, useEffectEvent } from 'react';

function Chat({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification('Connected to ' + roomId, theme);
  });

  useEffect(() => {
    const connection = createConnection(roomId);
    connection.on('connected', onConnected);
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]); // theme is NOT in deps, onConnected always reads the latest value
}

I counted effect runs after mounting and then changing only theme. With theme in the dependency array: 2 runs. With useEffectEvent and [roomId] alone: 1. That's one reconnect avoided per theme toggle, and the code says why.

What Landed in React 19.2 and 19.3?

React 19.2 (October 1, 2025) brought <Activity>, useEffectEvent, cacheSignal for Server Components, Performance Tracks in Chrome DevTools, resume APIs for partial pre-rendering, and batched Suspense reveals during server rendering. It also added Web Streams to Node.js server rendering.

React 19.3.0 (September 9, 2026) added <ViewTransition />, Fragment refs, a browser() API, Trusted Types integration, and independent rendering for transitions. Its changelog also lists a new dev-only warning for components unblocked by a conditional use(). I saw none in my conditional test, which does not mean you won't. The latest release is 19.3.1 (October 14, 2026), and the 19.2 line is at 19.2.9.

What About the Security Fixes?

An earlier version of this guide described a cross-site scripting fix in React 19.1, involving Unicode sequences in serialized props. I went looking for it in the official changelog and the 19.1.0 entry (March 28, 2025) doesn't contain it. I can't stand behind that claim, so it's gone.

What the changelog does show is a run of security-relevant patches to Server Components and Server Actions: 19.0.1, 19.1.2 and 19.2.1 on December 3, 2025, then 19.0.3, 19.1.4 and 19.2.3 on December 11, 2025, and more hardening in 19.2.4 (January 26, 2026) and later. If you run Server Components or Server Actions, the advice is simple. Be on the newest patch of your minor line, and don't stay on a plain 19.0.0 or 19.1.0.

npm install react@latest react-dom@latest

Client-only apps with no server rendering aren't running that code, but updating is still the right call.

React 18 vs React 19: What Changed?

Here's every headline API change at a glance, with the version corrections applied.

FeatureReact 18React 19 and later
MemoizationManual useMemo, useCallback, React.memoReact Compiler (separate Babel plugin) handles it
Async mutationsuseEffect + useState patternsuseTransition accepts async functions directly
Form state managementCustom state + handlersuseActionState built in (19.0)
Optimistic UIThird-party libs (SWR optimisticData, etc.)useOptimistic built in (19.0)
Ref forwardingforwardRef() wrapper requiredref is a regular prop (19.0)
Reading Promises in renderNot possibleuse() hook, can sit after an early return (19.0)
Context readinguseContext onlyuse(MyContext) as an alternative
<form action> supportNot supportedAccepts async functions directly
Hidden subtreesCSS display: none<Activity mode="hidden"> defers renders and cleans up effects (19.2)
Non-reactive effect valuesuseRef workaround or lint-disableuseEffectEvent (19.2)

Migration effort varies by codebase. The codemod handles string refs, legacy context, and forwardRef wrappers automatically. Manual memoization you can leave in place.

How Do You Migrate to React 19?

  1. Update packages: npm install react@19 react-dom@19
  2. Run the codemod: npx react-codemod@latest react-19
  3. Fix TypeScript types: Update @types/react and @types/react-dom to v19
  4. Test third-party libraries: Some older libraries might not support React 19 yet - so you'll want to check first

The React team's published a detailed upgrade guide with all breaking changes and how to handle them.

A home workspace with a large monitor and keyboard on a white wooden desk
Photo by Roberto Nickson on Unsplash

Which Libraries Work Well With React 19?

  • TanStack Query - pairs perfectly with Actions for server/client state separation; useQuery and useMutation complement useActionState cleanly; if its data comes back empty, seven causes of undefined data cover it
  • React Hook Form - native form management that integrates directly with React 19's useActionState and <form action={...}> pattern
  • Zustand - lightweight client state that complements React 19's server-first model; manages UI state while Actions handle mutations
  • Framer Motion - animation library fully compatible with React 19 and the new Compiler; works alongside useOptimistic for animated state transitions
  • Lucide React - tree-shakeable icon set, each icon is its own import so it adds near-zero weight to a React 19 bundle
  • cmdk - the command menu primitive behind Linear and Vercel's palettes, drops into a React 19 app with useActionState for the trigger action

Where Can You Read More?

Frequently Asked Questions

Is React 19 backwards compatible?
React 19 includes codemods for most breaking changes. The majority of apps can upgrade without major rewrites, though some patterns like string refs are fully removed.
When should I start using React 19 in production?
React 19 has been stable since December 5, 2024, and the latest release is 19.3.1 (October 14, 2026). If your dependencies support it, you can migrate now. Stay on the newest patch of whichever minor you pick, because the 2025 and 2026 patches fixed Server Components and Server Actions issues.
What replaces forwardRef in React 19?
In React 19, ref is a regular prop, so a function component can read it from its props with no forwardRef wrapper. forwardRef still works. In a development build of 19.3.1 it produced no warning, although the React team plans to deprecate it.
What is the React Compiler and do I need to install it separately?
The React Compiler is a build-time Babel plugin that inserts memoization, replacing most manual useMemo and useCallback calls. It does not ship in the react package. You install babel-plugin-react-compiler yourself. What react does ship, since 19.0.0, is react/compiler-runtime, the small runtime that compiled code imports. React 18.3.1 has no such entry.
What is the useOptimistic hook in React 19?
useOptimistic shows a speculative state while an async Action is in flight. When the Action finishes, the optimistic value is dropped and the real state shows, so a failed request reverts with no rollback code. One catch: if you update the real state after an await without wrapping that update in startTransition, one render shows the new item twice.
What is the React Activity component?
Activity (stable in React 19.2, October 1, 2025) hides a subtree while keeping its state. Measured on 19.3.1: hidden children still render when props change, but after the visible part commits, and their effects are cleaned up while hidden and set up again on show. Typed input survives.
What is useEffectEvent in React 19?
useEffectEvent, stable since React 19.2, extracts non-reactive logic from an effect. The effect reads the latest props or state through it without listing them as dependencies. In a test where only a theme prop changed, the effect that listed the theme ran twice in total, and the useEffectEvent version ran once.