Api

useAction

Client action options, results, status, callbacks, and request ownership reference.

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

OptionTypeDefaultBehavior
headersHeadersInit or () => HeadersInit—Evaluated for every execution
credentialsRequestCredentialsTransport defaultFetch credential policy
signalAbortSignal—External cancellation signal
timeoutnumber—Abort after positive milliseconds
cancelPreviousbooleanfalseAbort older owned requests at the next start
abortOnDisposebooleanfalseAbort on the current Vue scope's disposal
detachedbooleanfalseSelect 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

MemberType / behavior
execute(input)void; fire and forget
executeAsync(input)Promise<ActionResult<TOutput, TServerError>>; envelope, not unwrapped data
dataReadonly ref containing last successful output or undefined
businessErrorReadonly ref of the action's declared business envelope or undefined
isRefreshingReadonly ref; mutation succeeded and matching query refresh is pending
refreshErrorReadonly ref; separate refresh failure, preserving mutation success
serverErrorReadonly ref containing latest server/transport error or undefined
validationErrorsReadonly ref of Record<string, string[]> or undefined
statusReadonly ref: idle, executing, hasSucceeded, hasErrored
isIdle, isExecuting, hasSucceeded, hasErroredComputed 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.

Copyright © 2026