Async Feedback

Installation & usage

npm i @youj/motion

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use it when a control starts work that takes a moment and ends in an outcome people need to know: sending, saving, publishing, syncing. The control itself shows the state, so nobody has to look elsewhere for the result. Don't use it for work that finishes instantly, and don't use it for long jobs with progress to report. Show a Progress bar for those. For a finished button, use the UI Button's onAction, which is built on this.

Three pieces make an async control. useAsyncAction runs the work and reports its state, AsyncFeedback is what the control shows, and AsyncAnnouncer says it out loud. Put the feedback inside a useMorphRoot box so the control's width morphs with its label.

import { motion } from 'motion/react'
import { AsyncAnnouncer, AsyncFeedback, useAsyncAction, useMorphRoot } from '@youj/motion'

const labels = { pendingLabel: 'Sending…', successLabel: 'Invited', errorLabel: 'Couldn’t send' }

export function InviteButton({ onInvite }: { onInvite: () => Promise<unknown> }) {
  const { state, run } = useAsyncAction(onInvite)
  const morph = useMorphRoot(8) // the button's corner radius, in px

  return (
    <>
      <motion.button
        type="button"
        {...morph}
        onClick={run}
        aria-busy={state === 'pending' || undefined}
        className="relative inline-flex h-8 items-center overflow-hidden bg-fg px-3 text-canvas"
      >
        <AsyncFeedback state={state} {...labels}>
          Send invite
        </AsyncFeedback>
      </motion.button>
      <AsyncAnnouncer state={state} {...labels} />
    </>
  )
}

With a Base UI button, pass the motion element through render: <ButtonPrimitive render={<motion.button {...morph} />} …>.

Description

An invite form with a fail switch, whose action button shows the outcome.

useAsyncAction(onAction) returns the current state and a run function.

Resolve for success, and reject or throw for an error. A synchronous throw counts as an error, and a plain return value counts as success.
run is ignored while an action is in flight and while a success is showing. The guard is set synchronously, so a double click within one frame can't start two actions. After an error, run retries at once.
It never updates after the component unmounts, and it clears its reset timer.
onStateChange fires on every change, so the rest of the UI can follow: a status dot, a toast, a refetch.

A quiet sync control with its own marks and no tint.

Replace any of the three marks with icons, and turn the colored wash off with tint={false} for quieter, secondary controls. The tint needs a relative overflow-hidden parent, so it stays inside the control's shape.

import { CheckCircleIcon, LoaderDotsIcon, RefreshIcon } from '@youj/icons'

<AsyncFeedback
  state={state}
  tint={false}
  icons={{ pending: <LoaderDotsIcon size={16} />, success: <CheckCircleIcon trigger="mount" size={15} /> }}
>
  <RefreshIcon size={14} />
  Sync
</AsyncFeedback>

The default pending mark is a quarter arc on a faint track, turning at a constant rate. For a spinner of your own, use Spinner.

Reference

Propsstate, children, pendingLabel… (11)

Props

AsyncFeedback

AsyncFeedback props
Prop	Type	Default
`state`Required	`AsyncState` `'idle''pending''success''error'`	–
`children`Required	`ReactNode` What the control shows at rest.	–
`pendingLabel`	`string` Shown instead of the spinner when motion is reduced. Default: the `working` label, "Working…".	–
`successLabel`	`string` Shown next to the check. Default: the `done` label, "Done".	–
`errorLabel`	`string` Shown next to the cross. Default: the `failed` label, "Failed".	–
`icons`	`Partial<Record<'pending' \| 'success' \| 'error', ReactNode>>` Replace the spinner, check or cross.	–
`tint`	`boolean` Wash the surface in success / danger while settled. Needs a `relative overflow-hidden` parent. default true	`true`

AsyncAnnouncer

AsyncAnnouncer props
Prop	Type	Default
`state`Required	`AsyncState` `'idle''pending''success''error'`	–
`pendingLabel`	`string` Default: the `working` label, "Working…".	–
`successLabel`	`string` Default: the `done` label, "Done".	–
`errorLabel`	`string` Default: the `failed` label, "Failed".	–

useAsyncAction

function useAsyncAction(onAction: () => unknown, options?: AsyncActionOptions): { state: AsyncState; run: () => void }

type AsyncState = 'idle' | 'pending' | 'success' | 'error'

Option	Type	Default	Description
`resetAfter`	`number`		How long success and error hold before returning to idle, in ms. Defaults to three `deliberate` durations.
`onStateChange`	`(state: AsyncState) => void`		Fires on every state change.

MotionLabel swap, width morph, spinner… · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Label swapcrossfade with a touch of blur and scale	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)
Width morphthe `useMorphRoot` box	`spring.snappy` 0.2s, bounce 0	0.2s, bounce 0
Spinnerone turn	`ease.linear` cubic-bezier(0, 0, 1, 1) · deliberate × 1.25	cubic-bezier(0, 0, 1, 1)deliberate × 1.25
Checkthe stroke draws, then settles	`duration.slowease.emphasized` 340ms · cubic-bezier(0.6, 0, 0.1, 1)	340mscubic-bezier(0.6, 0, 0.1, 1)
Check settlescale, after a `base` delay	`spring.settle` 0.45s, bounce 0.3	0.45s, bounce 0.3
Crosstwo strokes, the second two `base` steps later	`duration.fastease.enter` 140ms · cubic-bezier(0.16, 1, 0.3, 1)	140mscubic-bezier(0.16, 1, 0.3, 1)
Error shake4, 3, 2 px and home	`duration.slowease.standard` 340ms · cubic-bezier(0.2, 0, 0, 1)	340mscubic-bezier(0.2, 0, 0, 1)
Tintsuccess or danger wash, `opacity`	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)
Holdsuccess and error, before idle, unless `resetAfter` is set	no token 3 × deliberate	3 × deliberate

Reduced motion

A text label (pendingLabel) replaces the spinner. Swaps and tints are instant, the marks appear already drawn, and errors don't shake.

Success earns the one overshoot in the system: the check settles on the settle spring. Errors stay level. The shake is a short, decaying nudge, never a bounce.

Reduced motion

The control still walks through all four states, and every state still has its words. pendingLabel replaces the spinner, so the pending state is readable without motion, and success and error appear with their marks already drawn. Swaps and tints change instantly and nothing shakes.

AccessibilityKeyboard, ARIA, focus