Skip to content
Hazine

Async Status Button

Button that runs a promise-returning handler and cycles through idle, pending, success and error by itself, swapping its icon and label. Use it for a save, send or export that settles in a few seconds.

How it differs. The base four-state machine: width is floored at the idle measurement, presses while pending are ignored through aria-disabled so focus stays put, and every transition is announced.

Install

pnpm dlx shadcn@latest add @hazine/async-button-status-cycle

Adds 1 file, 1 shadcn primitive (button), 1 Hazine item (@hazine/use-controllable-state), and 1 package (lucide-react).

First time? Add the registry to components.json
{
  "registries": {
    "@hazine": "https://api.hazine.dev/r/{name}.json"
  }
}

Needed once per project. Items resolve each other through the @hazine namespace.

Props12

onAction
() => Promise<unknown> | void
Runs on press. The button is pending until the returned promise settles, then shows success when it resolved and error when it rejected. Without it the button only reflects `status`.
status
AsyncButtonStatus
Controlled status. The width is held only for runs started by a press at rest, because that is the one moment the idle width can be measured.
defaultStatus
AsyncButtonStatus = "idle"
onStatusChange
(status: AsyncButtonStatus) => void
resetDelay
number = 2000
Milliseconds a result stays visible before the button returns to idle. Pass `Infinity` to hold the result until the next press.
icon
React.ReactNode
Leading icon at rest. The spinner, check and alert take its place. It is hidden from assistive technology, the label carries the name.
pendingLabel
string = "Working"
Visible labels. Keep them no longer than the idle label so the width holds.
successLabel
string = "Done"
errorLabel
string = "Failed"
pendingMessage
string = pendingLabel
Announced when a run starts. Defaults to `pendingLabel`.
successMessage
string = successLabel
Announced when the promise resolves. Defaults to `successLabel`.
errorMessage
string = "Failed. Press the button to try again."
Announced as an alert when the promise rejects. Say what to do next.

Also accepts every prop of Omit<React.ComponentProps<typeof Button>, "asChild">.

Accessibility

Keyboard
Keyboard support for Async Status Button
KeyEffect
Enter or SpaceStarts the action. While it is pending the press is ignored and focus stays on the button
Enter or Space on a resultStarts a new run without waiting for the label to return to rest
Screen reader

A native button that sets aria-disabled and aria-busy while pending, so it stays focusable. Icons are decorative, the label names each state. Pending and success go to a status region, a failure to an alert region.

  • Announces: {pendingMessage}
  • Announces: {successMessage}
  • Announces: {errorMessage}
Reduced motion
The loader icon does not rotate. The icon and label still change, without a transition.
Checked
Not checked yet. Automated results appear here once CI has run.

Dependencies3

  • button
  • @hazine/use-controllable-state
  • lucide-react

Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.

Tokens shipped0

None. The item is styled by the tokens your theme already has.

More in Buttons and Actions