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 |
|---|---|---|---|
| formContext | FormContext | yes | The form context providing validation state. |
| props | object | yes | Reactive action form configuration. |
props Properties
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| actionErrorSummary | string | Toast text on failure. | ||
| actionState | object | Action execution status. | ||
| actionSuccessSummary | string | Toast text on success. | ||
| dryRunTarget | 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. | ||
| fetchState | object | Data-fetch status. | ||
| hasInput | boolean | Whether the form has input fields that must be validated before submission. | ||
| onSubmissionErrorHandler | (args: object) => Promise | Replaces the default error toast. | ||
| onSubmissionSuccessHandler | (response: any) => void | Replaces the default success toast and redirect. | ||
| onSubmissionWarningsRequireConfirmation | (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. | ||
| readyToDryRun | 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. | ||
| redirectTo | (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. | ||
| requireModified | 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. | ||
| runAction | (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
Source
client/lib/use/useActionForm.js:103