Skip to content
Mosaic
On this page

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

GuidancePractice
DoDerive disabled state from isPending instead of mirroring it in useState.
DoPass a stable key per row, such as the resource id, and compare it to pendingKey and errorKey.
Don’tWrap run in try/catch. It resolves false on failure and owns the error copy.
Don’tUse it for a form submit or a confirm dialog. Use useForm or useConfirmController instead.

Options

PropTypeDescription
errorFallbackstringCopy shown when the action fails without an error Clerk can describe, such as a network fault.Default: the generic error

Returns

PropTypeDescription
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.
pendingKeystringThe key that is running, if any.
lastKeystringThe key that ran last, pending or not.
isPendingbooleanWhether any run is in flight.
errorstringLocalized copy for the last failure.
errorKeystringThe key that last failed.
reset() => voidClears the last error.

Examples

Row actions in a controller

TSX
const actions = usePendingAction();

onSetPrimary: id => void actions.run(id, () => onSetPrimaryEmail(id)),
isDisabled: actions.isPending,