# Status capsule

> A pill for something that takes a moment: a ring turns while it runs, and when it’s done a ribbon of light scans the pill and the words change under it.

Locking a door, syncing a library, connecting a bank: most apps swap a spinner for a green tick and the moment it worked goes by unseen. Status capsule is one pill that carries the whole job. Idle, it offers your action. Working, a fine ring turns at its end. Done, a ribbon of azure light scans it from left to right, catching the top and bottom edges as it passes, with starlight dust trailing behind; under it the badge turns into a check and the words change, and the pill keeps its light in the rim (colour bleeding in from the corners and a fine prismatic bezel) for as long as it stays done. View grows the same pill into the history below it, with your follow-up action at the foot. If it fails, the badge turns red, the pill gives one shake and your action is offered again.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/status-capsule.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/status-capsule
- Registry item (source): https://hairlineui.com/r/status-capsule.json

## Usage

```tsx
import { StatusCapsule } from "@/components/status-capsule";

<StatusCapsule
  status={status}
  title={status === "done" ? "Front door locked" : "Locking front door"}
  subtitle="Deadbolt"
  action={{ label: "Lock", onClick: lock }}
/>
```

## A lock that reports back

Your request decides the status; the capsule only shows it. Pass the device’s history as the log.

```tsx
"use client";
import { useState } from "react";
import { StatusCapsule, type CapsuleStatus } from "@/components/status-capsule";

export function FrontDoor({ history }: { history: { id: string; label: string; time: string }[] }) {
  const [status, setStatus] = useState<CapsuleStatus>("idle");

  async function lock() {
    setStatus("working");
    const res = await fetch("/api/locks/front/lock", { method: "POST" });
    setStatus(res.ok ? "done" : "failed");
  }

  return (
    <StatusCapsule
      status={status}
      title={status === "done" ? "Front door locked" : status === "working" ? "Locking front door" : status === "failed" ? "Couldn’t lock" : "Front door"}
      subtitle={status === "done" ? "Deadbolt · just now" : "Deadbolt"}
      action={{ label: status === "failed" ? "Try again" : "Lock", onClick: lock }}
      log={history}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"idle" \| "working" \| "done" \| "failed"` | – | What the task is doing. Done plays the ribbon and lights the rim. |
| `title` | `string` | – | The main line. |
| `subtitle` | `string` | – | The second line: a detail, a count, a time. |
| `icon` | `ReactNode` | – | The badge while idle or working; done and failed have their own. |
| `action` | `{ label: string; icon?: ReactNode; onClick: () => void }` | – | Idle: the button at the end. Failed: offered again. Done: at the foot of the log, or at the end when there’s no log. |
| `log` | `{ id: string; label: string; detail?: string; time: string }[]` | – | History, newest first, shown under View once done. |
| `logLabel` | `string` | `"History"` | Names the log for screen readers. |
| `palette` | `"azure" \| "solar" \| "prism" \| "dusk" \| LightPalette` | `"azure"` | The light’s colours. |

## States

- **idle**: Your icon on a primary badge and your action at the end.
- **working**: A ring turns at the end every 900ms. Changes to the words show straight away, so a count can tick in the subtitle.
- **done**: A ribbon scans left to right over 1.18s; at 36% the content is most out of focus (7.8px) and the badge, title and subtitle change there. The rim blooms, then settles to its resting glow over 1.4s.
- **log**: View grows the pill downward over 420ms (rows 0fr to 1fr) while its corners ease from 36 to 26px; Hide folds it back.
- **failed**: The badge crossfades to a red cross and the pill shakes once, ±5px over 380ms.
- **reduced motion**: No ribbon, no shake: states change in place.

## What it handles

A spinner that swaps for a tick doesn’t mark the moment something finished, and its history usually lives on another screen.

- **Four states**: Idle, working, done and failed, from one status prop.
- **The finish**: A ribbon of light scans the pill and the words change under it.
- **Stays lit**: The rim keeps its light while the status is done.
- **History in place**: View grows the pill into its log, with your action at the foot.
- **Failure**: A red cross, one shake, and your action offered again to retry.
- **Screen readers**: Done and failed are announced once, with the new words.

## Replaces

status pill, progress toast, loading badge, success toast, activity log popover

## Where it fits

- **Smart home**: A lock turning, a garage closing, a scene running on a device.
- **Sync and upload**: A photo library, a backup or an import that takes a while.
- **Connections**: Linking a bank, a calendar or an integration, with the history under View.
- **Deploys and jobs**: A release or a long job in a header, finishing in place.

## Notes

- The light is a 2D canvas over the pill, drawn only while a ribbon crosses; the content under it is blurred on its own layer, so the pill’s edge stays crisp. Nothing runs while it’s still.
- Words that change while it’s working show at once; only the change into done waits for the ribbon.
- The badge’s icons crossfade with scale and blur; View’s label morphs; the log folds by height, never by fading in a separate panel.
- On light surfaces the white of the light gives way to its colours, since white on white shows nothing.
- A polite live region announces the title and subtitle when it’s done or failed; the ring and the light are hidden from screen readers.
- Reduced motion drops the ribbon and the shake.

License: MIT (https://hairlineui.com/license#components)
