usePendingAction
Runs inline actions, such as row buttons, under one lock. Tracks which key is pending, which ran last, and which last failed.
Use for
- an async action from a button or row
- pending state and an error for a list of row actions
- one lock so a second click is ignored while an action runs
Practices
| Guidance | Practice |
|---|---|
| Do | Derive disabled state from isPending instead of mirroring it in useState. |
| Do | Pass a stable key per row, such as the resource id, and compare it to pendingKey and errorKey. |
| Don’t | Wrap run in try/catch. It resolves false on failure and owns the error copy. |
| Don’t | Use it for a form submit or a confirm dialog. Use useForm or useConfirmController instead. |
Options
| Prop | Type | Description |
|---|---|---|
errorFallback | string | Copy shown when the action fails without an error Clerk can describe, such as a network fault.Default: the generic error |
Returns
| Prop | Type | Description |
|---|---|---|
run | (key: string, action: () => void | Promise<unknown>, options?: PendingActionOptions) => Promise<boolean> | Runs action under key. Resolves true on success and false on failure. Ignored while any run is in flight. Clears the last error when it starts. A cancelled reverification is not an error. |
pendingKey | string | The key that is running, if any. |
lastKey | string | The key that ran last, pending or not. |
isPending | boolean | Whether any run is in flight. |
error | string | Localized copy for the last failure. |
errorKey | string | The key that last failed. |
reset | () => void | Clears the last error. |
Examples
Row actions in a controller
const actions = usePendingAction();
onSetPrimary: id => void actions.run(id, () => onSetPrimaryEmail(id)),
isDisabled: actions.isPending,Related
useConfirmController- useForm
- useListRemovalFocus