# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `errorFallback` | `string` | `the generic error` | Copy shown when the action fails without an error Clerk can describe, such as a network fault. |

## Returns

| Prop | Type | Default | 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

```tsx
const actions = usePendingAction();

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

## Related

- `useConfirmController`
- [useForm](/docs/hooks/use-form.md)
- [useListRemovalFocus](/docs/hooks/use-list-removal-focus.md)
