useActionState: Structured Error Handling for Server Actions

1. What useActionState solves and where the name comes from

useActionState was called useFormState in early React 19 preview versions and got renamed because the hook is no longer only meant for forms, but for any asynchronous action whose result should influence UI state. The hook takes an action function and an initial state, and returns three values: the current state, a wrapper action that can be bound to a form element or a button, and an isPending flag that is automatically true while the action is running.

The decisive difference from a manual approach with useState and a custom async handler is that useActionState consistently ties state to the result of the most recently completed action, including correct behavior with multiple rapid submissions, without you having to guard against race conditions and stale responses yourself. React internally ensures that only the result of the most recently started action actually ends up in state.

2. Basic structure: connecting the action function and the form

The function passed to useActionState receives the previous state as its first parameter and the FormData of the submitted form as its second, and must return the new state, which then becomes available as the current state from the hook. This signature lets you use the previous state for comparisons, for example to detect whether this is the first attempt or a repeated attempt after an error, without having to track that separately.

The wrapper action returned by the hook is bound directly as the action attribute on a form element, so React automatically handles native FormData extraction, prevents the classic page reload, and updates the isPending flag. Important detail: the action function itself must be marked as a server action (with the 'use server' directive at the top of the file or function) if it should actually run on the server, but useActionState works equally well with purely client side async functions.

'use server';

export async function updateProfile(previousState, formData) {
  const email = formData.get('email');

  if (!email || !email.includes('@')) {
    return {
      success: false,
      errors: { email: 'Please provide a valid email address.' },
      values: { email },
    };
  }

  await db.user.update({ where: { id: previousState.userId }, data: { email } });

  return { success: true, errors: {}, values: { email } };
}

3. Returning structured per-field validation errors

The central benefit of useActionState for forms with multiple fields is that the returned state can be an arbitrarily structured object, typically with an errors field that holds a separate error message per form field. Instead of a single global error text, each input field can display its own specific message by having the component read state.errors.email, state.errors.password, and so on, which is far more helpful for users than a single collective message at the end of the form.

In addition to the error messages, it is worth carrying the last entered values along in the same state object, so the form does not appear empty after a failed submission but keeps showing the data already entered. Since server actions go through a full roundtrip on every call, uncontrolled form fields would otherwise fall back to their initial, usually empty state after an error without this value storage, which feels like data loss to the user.

'use client';
import { useActionState } from 'react';
import { updateProfile } from './actions';

function ProfileForm({ userId }) {
  const [state, formAction, isPending] = useActionState(updateProfile, {
    success: false,
    errors: {},
    values: { email: '' },
    userId,
  });

  return (
    <form action={formAction}>
      <input
        name="email"
        defaultValue={state.values.email}
        aria-invalid={Boolean(state.errors.email)}
      />
      {state.errors.email && (
        <p className="text-sm text-red-600">{state.errors.email}</p>
      )}
      <button disabled={isPending}>
        {isPending ? 'Saving ...' : 'Save'}
      </button>
    </form>
  );
}

4. Combining the pending state sensibly

The third return value of useActionState is a boolean isPending value that is automatically true while the action executes and switches back to false as soon as the new state becomes available. This saves a dedicated useState call solely for the loading state and ensures pending and result can never drift apart, which is a common source of bugs with manual state management, for example when the pending flag is incorrectly reset before the request has actually started.

In the UI it is worth using isPending not only for a loading indicator inside the button, but also to prevent double submits by disabling the submit button while the action is running. Additionally, isPending can be used to visually dim existing error messages from a previous attempt while a new attempt is running, instead of letting them disappear abruptly, signaling to the user that a new attempt is in progress without completely losing the previous information.

5. Sensibly complementing with client side pre-validation

useActionState does not replace client side pre-validation, it sensibly complements it: obvious errors such as an empty required field or an incorrect character format can still be caught immediately in the browser using native HTML attributes like required, pattern, or type, without needing a server roundtrip for that. The server action still remains the authoritative instance for the actual validation, because client side checks can be bypassed, for example through direct requests without a browser UI.

In practice a two tier strategy works well: fast, optimistic feedback via native HTML validation for the most common typos, combined with the authoritative server side check via useActionState for anything that actually needs to be verified against the database or external rules, such as whether an email address is already taken. Both layers write into the same errors object in state, so the UI components do not need to distinguish between the two error sources.

6. Difference from manual try/catch in the handler

A classic approach without useActionState would write a custom async onSubmit handler that calls e.preventDefault(), manually sets an isSubmitting state to true, calls the server function inside a try/catch, sets an error state in the catch block, and resets isSubmitting to false in the finally block. This works but produces noticeably more boilerplate, spreads state across several useState calls, and makes it easy to forget the finally block or a race condition guard for rapid multiple clicks.

A further structural difference: try/catch only catches actually thrown exceptions, while useActionState also works with functions that model errors as a regular return value, which is the semantically better fit for validation errors, since an invalid email address is not an exceptional case in the sense of an exception, but an expected, regular form state. Genuine exceptional cases, such as a database connection error, can still be handled with try/catch inside the action function itself and then mapped into a structured error within the returned state, instead of letting the exception propagate uncaught.

// Manual approach without useActionState
function ProfileFormManual({ userId }) {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState(null);
  const [email, setEmail] = useState('');

  const handleSubmit = async (e) => {
    e.preventDefault();
    setIsSubmitting(true);
    setError(null);
    try {
      await updateProfileClient(userId, email);
    } catch (err) {
      setError(err.message);
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      {error && <p>{error}</p>}
      <button disabled={isSubmitting}>Save</button>
    </form>
  );
}

7. Modeling nested and global errors at the same time

Real world forms often need both field specific errors and global messages, for example when a server side error cannot be attributed to a single field, such as an expired session token. The state object from useActionState can easily carry both levels at once, by having an additional formError field exist next to the per-field errors object for such cross-cutting messages, which the component displays separately above the actual form.

For more complex forms with nested fields, for example an address inside an order form, it pays off to build the errors object with the same structure as the form data itself, meaning state.errors.address.zipCode instead of a flat key like state.errors.addressZipCode. This makes it easier to pass error handling generically through nested components, without every level needing to know how the other level names its error keys.

8. Working together with useFormStatus in child components

While useActionState is called in the parent that owns the action and manages the state, deeply nested child components, such as a reusable submit button, have the separate useFormStatus hook, which provides the pending state of the nearest enclosing form element without isPending having to be explicitly passed down as a prop. This is especially useful for generic UI components meant to be reused across multiple forms with different useActionState calls.

useFormStatus must always be called inside the form element whose status it is meant to read, since internally it refers to the nearest form context rather than an explicitly passed reference. A submit button using useFormStatus can therefore be exported as a standalone, form-independent component and used in any number of different useActionState forms, without those forms needing any knowledge of the button's internal implementation.

import { useFormStatus } from 'react-dom';

function SubmitButton({ children }) {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Saving ...' : children}
    </button>
  );
}

// Usage in any form:
function ProfileForm({ userId }) {
  const [state, formAction] = useActionState(updateProfile, initialState);
  return (
    <form action={formAction}>
      <input name="email" defaultValue={state.values.email} />
      <SubmitButton>Save</SubmitButton>
    </form>
  );
}

9. When useActionState really pays off

useActionState shows its value mainly for forms with genuine server side processing, especially in combination with server actions in frameworks like Next.js, where the hook respects the browser's native form semantics and forms keep working even without active JavaScript, an advantage a purely client side fetch approach does not offer. For purely client side, very simple forms without a server roundtrip, a plain useState approach can still be sufficient and even clearer.

For multiple forms existing simultaneously on a page, for example in a table with inline editing per row, each row should get its own useActionState call with its own initial state, instead of sharing one state across all rows, since otherwise the pending state and error messages of one row would incorrectly appear in other rows as well. This isolation is one of the reasons useActionState was designed as a hook rather than a global store.

10. Summary

11. FAQ: useActionState Error Handling: The Essentials at a Glance