Async Scope

PreviewCode

Installation

CLIManual

pnpmnpmyarnbun

pnpm dlx shadcn@latest add @kaui/async-scope

Usage

import {
  AsyncScope,
  AsyncContent,
  AsyncTrigger,
  useAsyncScope,
} from "@/components/ui/async-scope";

<AsyncScope action={syncData} onSuccess={() => toast.success("Synced")}>
  <AsyncTrigger>Sync</AsyncTrigger>
  <AsyncContent>
    <YourCard />
  </AsyncContent>
</AsyncScope>

Examples

Single area

PreviewCode

Error & Retry

useAsyncScope gives child components direct access to the full async state — including isError, reset, and execute. This example uses all three to build a self-contained retry flow inside the card itself. The trigger is disabled during the retry so the user can’t fire duplicate requests.

PreviewCode

Status indicator

Any component inside AsyncScope can subscribe to state — not just AsyncContent. Here a status badge lives outside the card entirely, reacting to isIdle → isLoading → isSuccess | isError without being part of the loading area.

PreviewCode

Building custom consumers

useAsyncScope is the escape hatch. Use it when AsyncTrigger and AsyncContent aren’t expressive enough.

function RetryButton() {
  const { isError, execute, reset } = useAsyncScope();
  if (!isError) return null;

  return (
    <Button
      variant="destructive"
      onClick={() => {
        reset();
        execute();
      }}
    >
      Retry
    </Button>
  );
}

function SuccessBanner() {
  const { isSuccess, data } = useAsyncScope<{ syncedAt: string }>();
  if (!isSuccess) return null;

  return (
    <p className="text-xs text-emerald-500">
      Last synced {new Date(data.syncedAt).toLocaleTimeString()}
    </p>
  );
}

How it fits in your stack

Most apps have three distinct concerns when handling an async action. AsyncScope owns exactly one of them.

┌──────────────────────────────────────────────────────┐
│  Data layer — TanStack Query, SWR, tRPC, fetch       │
│  Owns: caching, deduplication, background refetch    │
├──────────────────────────────────────────────────────┤
│  State machine — useAsync                            │
│  Owns: loading state, race protection, callbacks     │
├──────────────────────────────────────────────────────┤
│  Coordination layer — AsyncScope           ← this    │
│  Owns: broadcasting state to the component tree      │
├──────────────────────────────────────────────────────┤
│  UI primitives — AsyncTrigger, AsyncContent          │
│  Owns: rendering each state (idle/loading/error)     │
└──────────────────────────────────────────────────────┘

AsyncScope is not a replacement for your data library. It is a UI coordination layer — its only job is to take the result of an action and make the async state available to any component in its subtree. No caching, no deduplication, no background refetch.

That means they compose. If you already use TanStack Query, pass mutation.mutateAsync as the action. TanStack Query owns the data layer; AsyncScope owns the coordination:

const mutation = useMutation({ mutationFn: syncAccount });

<AsyncScope action={mutation.mutateAsync}>
  <AsyncTrigger>Sync</AsyncTrigger>
  <AsyncContent>
    <AccountCard />
  </AsyncContent>
</AsyncScope>;

If you don’t have a data library, useAsync (the built-in state machine) handles the execution. Either way, AsyncScope’s API doesn’t change.

When to use

Component	Use when
AsyncButton	The button itself is the loading indicator — self-contained, no outside coordination needed
AsyncScope	The trigger and the loading area are different elements, or multiple areas update from one action
useAsync	You need the raw state machine with no opinion on rendering

API

AsyncScope

Prop	Type	Default	Description
action	() => Promise<TData> | TData	—	The async function to execute when triggered
onSuccess	(data: TData) => void	—	Called after action resolves
onError	(error: TError) => void	—	Called if action throws
onSettled	(data, error) => void	—	Called after either outcome

AsyncTrigger

All Button props except onClick. Automatically disabled while the scope is loading.

AsyncContent

Prop	Type	Default	Description
loadingFallback	ReactNode	<Loader2 />	Shown in place of children while loading
className	string	—	Applied to the visible content wrapper

useAsyncScope

const {
  // status flags
  isIdle,
  isLoading,
  isSuccess,
  isError,
  // data
  data,
  error,
  // actions
  execute,
  reset,
} = useAsyncScope<TData, TError>();

Returns the full async state from the nearest AsyncScope. Pass generics to type data and error. Throws if called outside an AsyncScope.