useActionState and useFormStatus

useActionState(action, initialState) is a React 19 hook that wraps a Server Action to track its state across submissions. It takes the action function and an initial state value, and returns a tuple you can use to drive the entire form experience.

The hook returns [state, formAction, isPending]. The state holds the most recent return value of the action (starting as null or your initial value). formAction is the wrapped action to pass to the form. isPending is true while the action is executing on the server.

Each time the form is submitted, the Server Action runs and its return value becomes the new state. On the first render, state equals initialState. This makes it straightforward to show different UI depending on whether there have been previous submissions and what they returned.

If the Server Action returns { errors: { email: 'Invalid email' } }, you can display the error inline: {state.errors?.email && <p>{state.errors.email}</p>}. Because the state persists across re-renders, the error message stays visible until the next successful submission replaces the state.

When the action returns { success: true }, the component can render a success message: {state?.success && <p>Form submitted!</p>}. The form can be conditionally hidden or replaced by the success message based on the state value.

useFormStatus() is a hook that reads the pending state of the nearest ancestor <form> element. It returns an object including { pending: boolean }. This hook must be used inside a component that is a child of the form — not in the component that renders the form itself.

The restriction that useFormStatus must be used inside the form exists because the hook reads the form's context from the React tree above it. If called in the same component that renders the form, it would be a sibling of the form, not a descendant, and would not have access to the form's state.

The standard pattern is to extract the submit button into its own component: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. This component is then placed inside the form, giving it access to the form's pending state.

Setting disabled={pending} on the submit button prevents double submissions. When the user clicks submit and the Server Action is executing, pending is true, the button becomes disabled and unclickable. When the action completes, pending returns to false and the button re-enables.

The complete form UX pattern combines both hooks: useActionState in the form component tracks the action result and provides formAction, while useFormStatus inside a child SubmitButton component tracks pending state. Together they provide validated error display and a responsive submit button.

For an even more responsive feel, useOptimistic pairs with useActionState. You immediately update the UI with the expected result before the server responds, then reconcile when the actual response arrives. This pattern is common in like buttons, todo lists, and other fast-feedback interactions.

Where must useFormStatus be called for it to work correctly?

useActionState(action, initialState) returns [state, formAction, isPending] to track Server Action results. The state holds the action's return value, enabling inline error and success display. useFormStatus() provides { pending } inside child components of the form, enabling responsive submit buttons. Both hooks together create a complete, accessible form experience.