React 19 Patterns skill for Codex

Done well means: mutations run as Actions so React owns pending, error and reset state; no component keeps a manual isSubmitting flag next to a transition; refs flow as plain props; and every pattern used exists in the React version the lockfile actually pins.

Before writing code

1. Read AGENTS.md for the package manager, lint and test commands.
2. Check the real versions: npm ls react react-dom @types/react (or the pnpm/yarn equivalent). useActionState, use, ref-as-prop and form actions need 19.0+; useEffectEvent and <Activity> need 19.2+.
3. Identify the framework. In Next.js App Router, React Router v7 or TanStack Start, a form action can be a server function; in a Vite SPA it is a client async function. The hooks are the same, the transport is not.
4. Find existing mutation code (grep -rn "isLoading\|isSubmitting\|forwardRef" src) so the refactor follows one consistent pattern.

Decision table

Need	Use	Not
Form submit with server result and errors	useActionState + <form action>	useState + onSubmit + e.preventDefault()
Submit button disabled while its form runs	useFormStatus in a child component	prop-drilling pending
Non-form async update with pending UI	useTransition + async function	manual loading boolean
Show the change before the server confirms	useOptimistic inside an Action	copying server state into local state
Read a promise created by a parent or server	use(promise) under <Suspense>	useEffect + useState fetch
Read context conditionally	use(Context)	early-return before useContext
Expose a DOM node to a parent	ref as a normal prop	forwardRef
Event handler that reads latest props in an effect (19.2+)	useEffectEvent	adding the value to deps and re-subscribing
Data fetching with caching, retries, dedupe	a data library (TanStack Query, router loaders)	use() with a promise created during render

Actions and form state

An Action is any async function run inside a transition. React tracks pending state, surfaces thrown errors to the nearest error boundary, and, for <form action>, resets uncontrolled fields after success.

import { useActionState } from "react";
import { useFormStatus } from "react-dom";

type State = { ok: boolean; errors?: Record<string, string>; message?: string };

async function saveProfile(prev: State, formData: FormData): Promise<State> {
  const name = String(formData.get("name") ?? "").trim();
  if (!name) return { ok: false, errors: { name: "Name is required" } };
  const res = await fetch("/api/profile", { method: "POST", body: formData });
  if (!res.ok) return { ok: false, message: "Could not save. Try again." };
  return { ok: true, message: "Saved" };
}

function SubmitButton() {
  const { pending } = useFormStatus(); // reads the parent <form>, so it must be a child
  return <button disabled={pending}>{pending ? "Saving..." : "Save"}</button>;
}

export function ProfileForm({ defaultName }: { defaultName: string }) {
  const [state, formAction, isPending] = useActionState(saveProfile, { ok: false });
  return (
    <form action={formAction} aria-busy={isPending}>
      <input name="name" defaultValue={defaultName} aria-invalid={!!state.errors?.name} />
      {state.errors?.name && <p role="alert">{state.errors.name}</p>}
      <SubmitButton />
      {state.message && <p aria-live="polite">{state.message}</p>}
    </form>
  );
}

Rules:

• Return expected failures (validation, 4xx) as state. Throw only for unexpected failures you want an error boundary to catch.
• The action receives (previousState, formData). Forgetting the first parameter is the most common bug when converting an existing (formData) handler.
• Uncontrolled inputs are reset after a successful form action. If the field must keep its value on validation error, return the submitted values in state and feed them back through defaultValue, or give the form a key that changes only on success.
• useFormStatus returns nothing useful when called in the component that renders the <form>; it must live in a descendant.
• Use requestFormReset(form) from react-dom when you need to reset a form manually inside a transition.

Transitions outside forms

const [isPending, startTransition] = useTransition();

function onArchive(id: string) {
  startTransition(async () => {
    const result = await archive(id);
    if (result.error) {
      setError(result.error);
      return;
    }
    // React does not yet keep state updates that run after an await inside the
    // transition; wrap them again if they should not trigger a Suspense fallback.
    startTransition(() => setSelected(null));
  });
}

Optimistic updates

const [optimisticTodos, addOptimistic] = useOptimistic(
  todos,
  (current, newTodo: Todo) => [...current, { ...newTodo, pending: true }],
);

async function createAction(formData: FormData) {
  const todo = { id: crypto.randomUUID(), title: String(formData.get("title")) };
  addOptimistic(todo);   // must be called inside an Action or transition
  await createTodo(todo); // when the Action settles, React drops the optimistic value
}

• The optimistic value reverts automatically when the Action ends; the real todos must update from the server response (revalidation, refetch, or setState) or the item disappears.
• Calling addOptimistic outside a transition logs a warning and does nothing useful.
• Render pending items differently (opacity, “Sending…”) so users can tell.

use()

// Parent (server component or route loader) starts the request; child suspends on it.
function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
  const comments = use(commentsPromise);
  return comments.map((c) => <p key={c.id}>{c.body}</p>);
}

<Suspense fallback={<Spinner />}>
  <Comments commentsPromise={commentsPromise} />
</Suspense>;

• Never create the promise during render in a client component (use(fetch(url))): each render makes a new promise and the component suspends forever. The promise must be stable: created by a server component, a loader, or cached.
• A rejected promise goes to the nearest error boundary. Use .catch() on the promise to provide a fallback value instead.
• use can be called inside if and loops, unlike other hooks, but not in try/catch.

Refs

function TextField({ ref, label, ...props }: { ref?: React.Ref<HTMLInputElement>; label: string } & React.ComponentProps<"input">) {
  return (
    <label>
      {label}
      <input ref={ref} {...props} />
    </label>
  );
}

• Ref callbacks may return a cleanup function. Because of that, TypeScript rejects an implicit return: write ref={(el) => { instance = el; }}, not ref={(el) => (instance = el)}.
• forwardRef still works but is no longer needed; convert it when touching the file, not in a repo-wide sweep without tests.
• useRef() now requires an argument in the types: useRef<HTMLDivElement>(null).

Other React 19 changes worth using

• <Context value={...}> renders a provider directly; <Context.Provider> still works.
• <title>, <meta> and <link> rendered anywhere are hoisted to <head>. In Next.js prefer its Metadata API; in plain React or React Router this removes the need for helmet-style libraries.
• preload, preinit and preconnect from react-dom hint resources from components.
• useDeferredValue(value, initialValue) accepts an initial value for the first render.

Upgrading from React 18

For the full upgrade procedure, removed APIs and codemods, read references/react-18-upgrade.md only when the task is a version bump rather than writing new 19-style code. Codemods run through npx, which needs network access; in a sandbox without network, ask the user to approve it or apply the mechanical changes by hand.

Gotchas

• Mixing onSubmit with e.preventDefault() and action on one form: the onSubmit wins and the Action never runs. Pick one.
• Returning a new object from the action on every call is fine, but do not store derived UI state (open dialogs, tabs) in action state; it resets on navigation in frameworks that preserve forms.
• isPending from useActionState is per hook instance. Two forms sharing one action need two hooks.
• Strict Mode double-invokes ref callbacks (mount, cleanup, mount) in development. A ref callback that subscribes must return its cleanup.
• Server functions passed to action must be imported from a "use server" module; an inline client function cannot run on the server.

Verification

• tsc --noEmit passes (catches ref callback returns and useRef() without args).
• Lint passes with eslint-plugin-react-hooks on its current recommended config.
• Tests submit the form through the UI (Testing Library user.click on the submit button) and assert pending text, success message and validation errors.
• With network throttled in DevTools, the pending state appears, double submits are blocked, and an optimistic item reverts when the request fails.
• No leftover forwardRef or manual isSubmitting in files you converted.

Output

When reporting the change, list: which mutations became Actions, which components lost forwardRef, any behavior differences users will notice (form reset after success, optimistic rows), and the commands you ran to verify.