--- name: using-react-actions description: Use when working with React forms, async actions, or needing optimistic UI updates --- ## Overview React Actions are async functions used in transitions that automatically handle pending states, errors, forms, and optimistic updates. They unify form handling through three key hooks: `useActionState` for managing submission state, `useFormStatus` for reading parent form status, and `useOptimistic` for immediate UI feedback. ## When to Use - Handling form submissions with built-in pending\/error states - Creating reusable submit buttons that reflect form status - Showing optimistic UI updates before server response - Managing complex form workflows with validation and errors - Coordinating multiple async operations with user feedback **When NOT to use:** - Simple onClick handlers without forms (use regular async functions) - Read-only data fetching (use server components or queries) - Non-form transitions (use `useTransition` directly) ## Core Patterns ### Form with useActionState Manages form submission state, errors, and pending status in one hook. ```tsx import { useActionState } from "react"; async function addToCart(prevState: { message: string } | null, formData: FormData) { const itemId = formData.get("itemId") as string; const result = await api.addToCart(itemId); if (!result.success) return { message: result.error }; return null; } function AddToCartForm({ itemId }: { itemId: string }) { const [state, formAction, isPending] = useActionState(addToCart, null); return (