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.
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. | ||
| 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:89