Button

A settings list where each AsyncButton resolves, rejects or syncs through its own pending, success and error states.

When the attempt ends in an outcome people need to know, such as saving, sending, publishing or syncing, use AsyncButton. It is a Button (same variant, size and look) that morphs its label through the whole attempt: pending, then success or error. To show the same states on a control that isn't a button, use Async Feedback.

import { AsyncButton } from '@youj/react'

export function SaveBar() {
  return (
    <AsyncButton
      onAction={() => saveProfile(values)}
      pendingLabel="Saving…"
      successLabel={(profile) => `Saved ${profile.name}`}
      errorLabel={(error) => error instanceof Error ? error.message : 'Couldn’t save'}
    >
      Save
    </AsyncButton>
  )
}

// Work started elsewhere, such as a TanStack Query mutation: show its status.
<AsyncButton status={mutation.status} onClick={() => mutation.mutate(values)} successLabel="Saved" errorLabel={mutation.error?.message}>
  Save
</AsyncButton>

One driver per button: onAction runs the work itself, status shows work started elsewhere. The types allow only one.

Run an action

Pass onAction to show the action’s progress inside the button. The label changes to a spinner, then a check and successLabel, or a cross and errorLabel. It returns to idle after a hold. Resolve the promise for success; reject it or throw for an error. Presses are ignored while pending and during the success hold. After an error, the next press retries immediately.

The box morphs to each label's width on the same spring as the label, and success and error tint the button. Icon-only buttons stay square: their labels are announced, not shown. onActionStateChange reports every step (idle, pending, success or error, then idle again), and resetAfter sets the hold in milliseconds.

onAction is a function, so in the Next.js App Router the button goes in a Client Component, a file that starts with 'use client':

'use client'

<AsyncButton
  onAction={() => saveProfile(values)}
  pendingLabel="Saving…"
  successLabel="Saved"
  errorLabel="Couldn’t save"
>
  Save
</AsyncButton>

Labels from the outcome

successLabel and errorLabel also take a function. successLabel gets what onAction resolved with, errorLabel what it rejected or threw with (typed unknown, even when your mutation knows its error type, so check it with error instanceof Error). Strings keep working.

'use client'

// A fetch only rejects on a network failure: throw on !res.ok.
async function save(values: Profile) {
  const res = await fetch('/api/profile', { method: 'POST', body: JSON.stringify(values) })
  if (!res.ok) throw new Error((await res.json()).message)
  return res.json() as Promise<{ name: string }>
}

<AsyncButton
  onAction={() => save(values)}
  successLabel={(profile) => `Saved ${profile.name}`}
  errorLabel={(error) => (error instanceof Error ? error.message : 'Couldn’t save')}
>
  Save
</AsyncButton>

With TanStack Query, mutateAsync returns the promise and rejects on error, so it fits onAction as is:

'use client'

const mutation = useMutation({ mutationFn: save })

<AsyncButton onAction={() => mutation.mutateAsync(values)} successLabel={(p) => `Saved ${p.name}`} errorLabel={(e) => (e instanceof Error ? e.message : 'Couldn’t save')}>
  Save
</AsyncButton>

Status from elsewhere

status drives the same pending, check or shake, hold, idle lifecycle for work started elsewhere. It takes 'idle' | 'pending' | 'success' | 'error', TanStack Query's mutation status names, so status={mutation.status} works as it is. Start the work in onClick.

'use client'

const mutation = useMutation({ mutationFn: save })

<AsyncButton status={mutation.status} onClick={() => mutation.mutate(values)} successLabel="Saved" errorLabel={mutation.error?.message}>
  Save
</AsyncButton>

• A mutation keeps success until it is reset, so after the hold the button returns to rest even though status stays success. The next change of status plays again. A button that mounts already settled is at rest.
• status and onAction drive one lifecycle: pass one (the types allow only one, and with both, status wins and development builds log an error).
• Function labels need an outcome the button ran itself, so with status pass strings (errorLabel={mutation.error?.message}).
• Announcements, sounds and reduced motion behave as with onAction.

A publish card whose Publish button runs its own async action, beside Discard and Export.

The six variants, each with a note on when to use it.

One default button per view carries the accent. secondary and outline sit beside it, ghost handles quiet actions and dismissals, and danger marks the action that deletes or revokes. link is an action styled as text. It's still a button.

Youj icons inside a button play when the button is hovered or keyboard-focused, with no wiring. An icon at either end sits 2px closer to its edge than text would, which reads as even padding.

Text sizes from extra small to large, and the four matching icon sizes.

Four text sizes and four square icon sizes sit on the control-height scale: 24, 28, 32 and 40px. On touch screens (pointer: coarse), every size is 8px taller and a default button is never under 44px, so it is a 44px target without a prop. The extra-small and small sizes stay compact and reach 44px with an invisible hit area around them.

An icon-only button has no visible text, so it needs an aria-label.

Export CSV and Run checks buttons that stay busy while their onClick promise is pending.

Return a promise from onClick and the button looks after the wait: it shows its loading state (a spinner in place of the label, aria-busy, presses blocked, focus kept) until the promise settles, then returns to normal. There is no prop and no state to keep. A rejected promise ends the wait too, and the error surfaces as it would for any unawaited handler, so catch it in the handler if you need to show it. An explicit loading prop always wins.

<Button onClick={() => exportReport()}>Export CSV</Button>

A danger zone whose Delete project button runs only after the press is held, then confirms as Deleted.

Hold to confirm lives on AsyncButton, not on the plain Button: pass hold and the action runs only once a press is held, by a pointer or with Space or Enter held down. While held, a fill sweeps across from the inline start, so the press shows how long is left. Letting go early springs the fill back and nothing runs. When the fill is full the action starts and the button goes through its usual lifecycle: the spinner, then the success tint with the drawn check and successLabel, held, then back to rest (or the error, if it fails). The press sound plays as the hold completes, not on the press. hold (or hold={true}) takes twice the deliberate motion token, scaled by the provider's speed; a number is milliseconds.

<AsyncButton variant="danger" hold onAction={() => deleteProject(id)} pendingLabel="Deleting…" successLabel="Deleted">
  Delete project
</AsyncButton>

<AsyncButton hold onAction={() => sendPayment(invoice)} pendingLabel="Sending…" successLabel="Sent">
  Send payment
</AsyncButton>

Use a hold for actions that are easy to trigger by mistake and costly to undo, where a dialog would be too much. For a slower, more deliberate gesture, use Slide to Confirm.

Two buttons whose loading state is set from state you own.

loading is the controlled alternative, for work that starts somewhere else or outlives the press. The label hands over to a spinner without changing the button's width, presses are blocked, and focus stays on the button.

Pass loading (even as false) from the first render on any button that can load. Its live region then exists before it has anything to say, which some screen readers need before they'll announce a change.