safe-action-hooks

Import useAction from next-safe-action/hooks, pass your server action and optional callbacks like onSuccess and onError, then call execute(input) from an event handler. The hook returns result, status, and isPending for rendering UI states.

execute is fire-and-forget and reports outcomes through callbacks and the result state. executeAsync returns a Promise of the SafeActionResult for inline awaiting, but it throws on navigation errors, so wrap it in try/catch and rethrow navigation errors.

Default to useAction unless you need the <form action={formAction}> pattern or prevResult access on the server. useStateAction requires the action to be defined with .stateAction() and React 19, while useAction works with .action().

The server action was defined with .action() instead of .stateAction(). useStateAction only accepts stateful actions that receive prevResult as a second argument, so redefine the action using .stateAction().

Pass currentState from the server and a pure updateFn that computes the optimistic state from the input. The UI updates synchronously on execute, then reverts to the real server state after revalidation or on error.

When throwOnNavigation is true, navigation errors are thrown during React's render phase, so effects and callbacks cannot run. TypeScript enforces this via a discriminated union; use server-side action callbacks for side effects instead.