Async State Slot

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<AsyncStateSlot />

Installation

npx shadcn@latest add https://webberui.com/r/async-state-slot.json

Usage

A single state prop drives the whole slot; when the state changes, the frame height tweens smoothly while the exiting element folds away and the entering element slides in to take its place. The content state shows children, and the other four states render a built-in placeholder unless you provide an override.

import { AsyncStateSlot } from "@/components/ui/async-state-slot";

function Inbox() {
  const [state, setState] = React.useState<AsyncState>("loading");

  React.useEffect(() => {
    fetch("/api/items")
      .then((r) => r.json())
      .then((items) => setState(items.length ? "content" : "empty"))
      .catch(() => setState("error"));
  }, []);

  return (
    <AsyncStateSlot state={state} onRetry={() => setState("loading")}>
      <ItemList />
    </AsyncStateSlot>
  );
}

Every state's built-in view can be replaced entirely through its matching prop:

<AsyncStateSlot
  state={state}
  loading={<MySkeleton />}
  empty={<MyEmptyState />}
>
  <ItemList />
</AsyncStateSlot>

Props

How it works

• Height morphing: the frame tweens smoothly to the entering element's actual height using Motion's layout, while the inner layer uses layout="position" to cancel out the scaling so text is never stretched.
• Shared-element transitions: AnimatePresence runs in mode="popLayout", so the exiting element leaves the layout flow and the incoming element decides the new height on its own, with the two transitions overlapping — producing the "empty state folds away as the first row slides in to take its place" effect.
• Controlled state: state is driven by a single external source and the component holds no internal state machine, which makes it easy to hook up to any async data flow.
• Without overrides, idle / empty / error share one centered illustration layout, and loading is a skeleton of an avatar plus body rows.

Accessibility

• The container carries aria-busy (true while loading) and data-state, which makes it easy for styling and assistive technology to identify.
• It includes a hidden role="status" region with aria-live="polite" that announces the current state when it changes; the text can be overridden with srLabels.
• The retry button has keyboard focus styling (focus-visible).
• When the user has "reduce motion" enabled at the system level, the height and displacement animations are disabled and the state switches instantly.