useAction
useAction
const action = useAction(typedReference, options)
Import references from #safe-action/actions; input, output, business-error, and server-error types are inferred. Reference metadata supplies route and method.
Options
| Option | Type | Default | Behavior |
|---|---|---|---|
headers | HeadersInit or () => HeadersInit | — | Evaluated for every execution |
credentials | RequestCredentials | Transport default | Fetch credential policy |
signal | AbortSignal | — | External cancellation signal |
timeout | number | — | Abort after positive milliseconds |
cancelPrevious | boolean | false | Abort older owned requests at the next start |
abortOnDispose | boolean | false | Abort on the current Vue scope's disposal |
detached | boolean | false | Select native browser fetch instead of $fetch |
invalidate | { keys?: readonly string[], tags?: readonly string[] } | — | Refresh matching Nuxt data keys after the latest successful mutation |
onExecute | ({ input }) => void | — | Runs for every execution start |
onSuccess | ({ data, input }) => void | — | Latest successful completion |
onError | ({ error, input }) => void | — | Latest business/server/validation/transport failure |
onSettled | ({ result, input }) => void | — | Latest completed execution; follows its onSuccess/onError even if they reset |
Callbacks are not awaited. Their exceptions/rejections are logged without changing the action result. error contains businessError?, serverError?, and validationErrors?; result is the full action envelope. A successful void action calls onSuccess with data: undefined.
Return value
| Member | Type / behavior |
|---|---|
execute(input) | void; fire and forget |
executeAsync(input) | Promise<ActionResult<TOutput, TServerError>>; envelope, not unwrapped data |
data | Readonly ref containing last successful output or undefined |
businessError | Readonly ref of the action's declared business envelope or undefined |
isRefreshing | Readonly ref; mutation succeeded and matching query refresh is pending |
refreshError | Readonly ref; separate refresh failure, preserving mutation success |
serverError | Readonly ref containing latest server/transport error or undefined |
validationErrors | Readonly ref of Record<string, string[]> or undefined |
status | Readonly ref: idle, executing, hasSucceeded, hasErrored |
isIdle, isExecuting, hasSucceeded, hasErrored | Computed status shortcuts |
cancel() | Abort owned requests, invalidate pending updates, set idle; preserves existing values |
reset() | Cancel and clear data/errors |
Only the latest execution owns state and completion callbacks. Older promises still return their own result. External abort/timeout resolve an error result; explicit cancel/reset before the response arrives leave state idle and suppress completion callbacks. A reset() or new execution started from onSuccess/onError does not cancel that run's refresh or onSettled. Abort cannot undo a mutation that already reached the server.
Automatic retries are disabled. Both transports can continue across SPA navigation unless explicitly cancelled. Native fetch provides no completion guarantee across unload and is intended for browser execution. See lifecycle details.
Mutation refresh
invalidate uses Nuxt's refreshNuxtData() for explicit keys and registered tags. It does not create a second cache. Only the latest successful execution refreshes; business/validation/server/transport failures and stale or cancelled executions do not. Resetting from onSuccess does not cancel the refresh. Successful void mutations also refresh. executeAsync() resolves after requested refresh settles; refresh failure is reported separately in refreshError and does not change the successful result. Query registration and lifecycle.
Nuxt refresh is client-side; refreshNuxtData() is a no-op during SSR. Normal useAsyncData fetch failures are stored on the query's own error ref and may not reject the refresh promise. Render that ref as well as refreshError, which reports rejected refresh triggers/hooks. Cancellation suppresses owned updates and refresh not yet dispatched; it does not abort Nuxt fetches already started.