---
url: "https://vueda.dev/v3/reference/api/js/use/useActionForm/functions/useActionForm.md"
title: "useActionForm"
---

# useActionForm

## Overview

Provides submit, cancel, and dry-run behaviour for action forms. Pass the injected
form context and a reactive props-compatible object. `ActionForm` calls this internally;
use it directly when you want the logic without the `ActionForm` shell.

When the server gates the action behind warning acknowledgement (HTTP 409, surfaced as a
`ConfirmationRequiredError` with a digest), the returned `confirmation` controller prompts the
user and a confirmed action is retried once with the digest acknowledged. `ActionForm` mounts
the `FormConfirmDialog` bound to the controller; standalone callers must render one (or register
a custom consumer), otherwise warned submissions fail closed as cancelled.

When the server refuses the action with a rate limit (HTTP 429, surfaced as a `RateLimitedError`), the
failure toast shows the error's message, and the form shows no error. The submit control stays enabled,
because the same action succeeds once the limit resets.

## Signature

`useActionForm(formContext, props)`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| <span id="param-formContext">formContext</span> | [FormContext](/v3/reference/api/js/use/useForm/types/FormContext.md) | yes | The form context providing validation state. |
| <span id="param-props">props</span> | `object` | yes | Reactive action form configuration. |

#### props Properties

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="param-props-actionErrorSummary">actionErrorSummary</span> | `string` |  |  | Toast text on failure. |
| <span id="param-props-actionState">actionState</span> | `object` |  |  | Action execution status. |
| <span id="param-props-actionSuccessSummary">actionSuccessSummary</span> | `string` |  |  | Toast text on success. |
| <span id="param-props-dryRunTarget">dryRunTarget</span> | `string` |  |  | Identity of the current dry-run target. A value different from the last run's  target permits another automatic validation pass once `readyToDryRun` is `true`, including when returning to a  previously validated target. Omit it for a caller with no target concept; automatic validation then runs at most  once per `useActionForm` instance, even if readiness toggles. |
| <span id="param-props-fetchState">fetchState</span> | `object` |  |  | Data-fetch status. |
| <span id="param-props-hasInput">hasInput</span> | `boolean` |  |  | Whether the form has input fields that must be validated before submission. |
| <span id="param-props-onSubmissionErrorHandler">onSubmissionErrorHandler</span> | `(args: object) => Promise` |  |  | Replaces the default error toast. |
| <span id="param-props-onSubmissionSuccessHandler">onSubmissionSuccessHandler</span> | `(response: any) => void` |  |  | Replaces the default success toast and redirect. |
| <span id="param-props-onSubmissionWarningsRequireConfirmation">onSubmissionWarningsRequireConfirmation</span> | `(options: object) => Promise` |  |  | Replaces the default handling of a  confirmation-required response (HTTP 409): render the warnings and ask the user via the confirmation  controller. Resolving `true` retries the action once with the warnings acknowledged. |
| <span id="param-props-readyToDryRun">readyToDryRun</span> | `boolean` |  |  | When `true`, permits the first automatic dry-run validation pass and another  pass when `dryRunTarget` differs from the last run's target. Toggling readiness off and on does not repeat  validation for the same target. |
| <span id="param-props-redirectTo">redirectTo</span> | `(reason: "cancel" \| "success") => Promise` |  |  | Called after success or cancel. After  success, the form stays locked until it unmounts, so the view it leaves cannot submit again while the destination  loads. Resolve `false` when the call did not navigate away, such as when there was no destination or the router  rejected the navigation, to unlock the form instead. |
| <span id="param-props-requireModified">requireModified</span> | `boolean` |  |  | When `false`, skips the "no changes detected" guard. Defaults to `true`. Set to `false` for forms that start empty (sign-in, forgot-password) where modification is not a meaningful concept. |
| <span id="param-props-runAction">runAction</span> | `(options: object) => Promise` |  |  | Executes  the action. `acknowledgeWarnings` carries the warnings digest of a confirmed retry; implementations should forward  it as the `Acknowledge-Warnings` header (see `useModelAction`). |

### Returns

[ActionFormContext](/v3/reference/api/js/use/useActionForm/types/ActionFormContext.md)

## Source

`client/lib/use/useActionForm.js:103`