Action status

Transient feedback for async work — the same feel as a copy button’s green check, but for pending → success / error → idle.

One-shot buttons (labeled or icon-only): prefer composed ActionButton.
Disclosures / metric strips / custom chrome: use useActionStatus + ActionStatusIcon here.

useActionStatus owns the state machine and timers. ActionStatusIcon (returned as save.icon) swaps the trailing indicator with a short pop-in animation. Defaults: disclosure chevron while idle, spinner while pending, green check on success, red X on error.

Instant work still spends at least 350ms in pending (minPendingMs) so the spinner → check transition doesn’t feel like a flash. Success color is set on the status wrapper so parent disclosure styles can’t wash out the green.

import { useActionStatus, Button } from "@vesyl/ui-next";

const save = useActionStatus();

await save.run(async () => {
  await mutate(); // throw or reject → error status, then rewind
});

Save button

Pass a custom idle icon (here a save glyph). The returned save.icon cycles through pending / success / idle. Disable the control while save.isBusy to prevent double-submit.

import { Button, useActionStatus } from "@vesyl/ui-next";
import { SaveIcon } from "lucide-react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function ActionStatusButton() {
  const save = useActionStatus({
    icon: <SaveIcon className="size-3.5" />,
  });

  return (
    <Button
      variant="outline"
      size="sm"
      disabled={save.isBusy}
      onClick={() =>
        void save.run(async () => {
          await delay(900);
        })
      }
    >
      Save changes
      {save.icon}
    </Button>
  );
}

Disclosure chevron

Default idle icon is a chevron — drop save.icon into DisclosureButton (or RegionDisclosure.Value) and set rotateOnOpen={save.status === "idle"} so the spinner and check don’t flip when the popover is open.

Simulate a packaging save: open the popover, hit Save, watch the trailing icon.

import {
  Button,
  DisclosureButton,
  Popover,
  PopoverContent,
  PopoverTrigger,
  useActionStatus,
} from "@vesyl/ui-next";
import { useState } from "react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function ActionStatusDisclosure() {
  const [open, setOpen] = useState(false);
  const [weight, setWeight] = useState("1 lb 4 oz");
  const save = useActionStatus();

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger
        render={(props) => (
          <DisclosureButton
            {...props}
            icon={save.icon}
            rotateOnOpen={save.status === "idle"}
          >
            Ship weight · {weight}
          </DisclosureButton>
        )}
      />
      <PopoverContent align="start" className="w-72 gap-3">
        <p className="text-sm font-medium">Ship weight</p>
        <p className="text-muted-foreground text-xs">
          Simulated save — spinner, then green check on the chevron.
        </p>
        <div className="flex justify-end gap-2">
          <Button variant="ghost" size="sm" onClick={() => setOpen(false)}>
            Cancel
          </Button>
          <Button
            size="sm"
            disabled={save.isBusy}
            onClick={() => {
              void save.run(async () => {
                await delay(800);
                setWeight("1 lb 6 oz");
                setOpen(false);
              });
            }}
          >
            Save
          </Button>
        </div>
      </PopoverContent>
    </Popover>
  );
}

Region disclosure (metric strip)

Same pattern on a parcel-style metric row. Each cell owns its own useActionStatus so box and weight feedback stay independent.

Parcel metrics

import {
  Button,
  Popover,
  PopoverContent,
  PopoverTrigger,
  RegionDisclosure,
  useActionStatus,
} from "@vesyl/ui-next";
import { useState } from "react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function Metric({
  label,
  value,
  onSave,
}: {
  label: string
  value: string
  onSave: () => Promise<void>
}) {
  const [open, setOpen] = useState(false);
  const [face, setFace] = useState(value);
  const save = useActionStatus();

  return (
    <RegionDisclosure.Cell>
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger
          render={(props) => (
            <RegionDisclosure {...props}>
              <RegionDisclosure.Label>{label}</RegionDisclosure.Label>
              <RegionDisclosure.Value
                icon={save.icon}
                rotateOnOpen={save.status === "idle"}
              >
                {face}
              </RegionDisclosure.Value>
            </RegionDisclosure>
          )}
        />
        <PopoverContent align="end" className="w-64 gap-3 p-3">
          <p className="text-sm font-medium">Edit {label.toLowerCase()}</p>
          <div className="flex justify-end gap-2">
            <Button variant="ghost" size="sm" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button
              size="sm"
              disabled={save.isBusy}
              onClick={() => {
                void save.run(async () => {
                  await onSave();
                  setFace(`${value} ✓`);
                  setOpen(false);
                });
              }}
            >
              Save
            </Button>
          </div>
        </PopoverContent>
      </Popover>
    </RegionDisclosure.Cell>
  );
}

export default function ActionStatusRegion() {
  return (
    <div className="border-border bg-card w-full max-w-md overflow-hidden rounded-lg border">
      <div className="text-muted-foreground px-4 py-2 text-xs">Parcel metrics</div>
      <RegionDisclosure.Group>
        <Metric
          label="Box"
          value="Small Box"
          onSave={async () => {
            await delay(750);
          }}
        />
        <Metric
          label="Ship weight"
          value="1 lb 4 oz"
          onSave={async () => {
            await delay(750);
          }}
        />
      </RegionDisclosure.Group>
    </div>
  );
}

Error path

If run’s promise rejects (or you call fail() / settle(false)), the icon shows the error state for errorMs, then returns to idle. Pair with a toast for the message — the icon is only the ambient signal.

status: idle

import { Button, useActionStatus } from "@vesyl/ui-next";
import { CloudUploadIcon } from "lucide-react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function ActionStatusError() {
  const upload = useActionStatus({
    icon: <CloudUploadIcon className="size-3.5" />,
    errorMs: 2000,
  });

  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button
        variant="outline"
        size="sm"
        disabled={upload.isBusy}
        onClick={() =>
          void upload.run(async () => {
            await delay(700);
            // Reject so the status icon shows error, then rewinds to idle.
            throw new Error("Network failed");
          })
        }
      >
        Upload (will fail)
        {upload.icon}
      </Button>
      <Button
        variant="outline"
        size="sm"
        disabled={upload.isBusy}
        onClick={() =>
          void upload.run(async () => {
            await delay(700);
          })
        }
      >
        Upload (succeeds)
        {upload.icon}
      </Button>
      <span className="text-muted-foreground text-xs tabular-nums">
        status: {upload.status}
      </span>
    </div>
  );
}

Halo

Set variant="halo" to keep one Halo mounted while the status changes. Pending uses a neutral gray spinner; success and error transition the Halo color while swapping to circular status icons. Provide a circular idle icon to keep the Halo visible between actions, or null to show it only while an action is active.

import { Button, ButtonGroup, HStack, useActionStatus } from "@vesyl/ui-next";
import { CircleDotIcon } from "lucide-react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function ActionStatusHalo() {
  const action = useActionStatus({
    variant: "halo",
    icon: <CircleDotIcon />,
  });

  return (
    <HStack gap={5} align="center">
      {action.icon}
      <ButtonGroup>
        <Button
          variant="outline"
          disabled={action.isBusy}
          onClick={() =>
            void action.run(async () => {
              await delay(900);
            })
          }
        >
          Succeed
        </Button>
        <Button
          variant="outline"
          disabled={action.isBusy}
          onClick={() =>
            void action.run(async () => {
              await delay(900);
              throw new Error("Action failed");
            })
          }
        >
          Fail
        </Button>
      </ButtonGroup>
    </HStack>
  );
}

Custom status icons

Override any of pending / success / error (and the idle icon) when the control isn’t a disclosure — e.g. a delete mini-button.

import { MiniButton, useActionStatus } from "@vesyl/ui-next";
import { CheckCircle2Icon, LoaderCircleIcon, Trash2Icon, XCircleIcon } from "lucide-react";

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function ActionStatusCustomIcons() {
  const del = useActionStatus({
    icon: <Trash2Icon className="size-3.5" />,
    icons: {
      pending: <LoaderCircleIcon className="size-3.5 animate-spin text-muted-foreground" />,
      success: <CheckCircle2Icon className="size-3.5 text-status-success-foreground" />,
      error: <XCircleIcon className="size-3.5 text-destructive" />,
    },
  });

  return (
    <MiniButton
      disabled={del.isBusy}
      aria-label="Delete"
      onClick={() =>
        void del.run(async () => {
          await delay(900);
        })
      }
    >
      {del.icon}
    </MiniButton>
  );
}

Reference

`useActionStatus(options?)`

Option	Type	Default	Description
`successMs`	`number`	`1400`	How long to hold the success icon before idle
`errorMs`	`number`	`1800`	How long to hold the error icon before idle
`minPendingMs`	`number`	`350`	Minimum time in pending so instant work still reads as “working”
`icon`	`ReactNode \| null`	chevron	Idle icon. `undefined` → disclosure chevron; `null` → empty idle slot
`icons`	`{ pending?, success?, error? }`	—	Override status icons
`variant`	`"inline" \| "halo"`	`"inline"`	Compact indicator or transitioning Halo presentation
`size`	`"sm" \| "md" \| "lg"`	`"sm"` for Halo	Halo size; ignored by the inline variant
`colors`	`Partial<Record<ActionStatus, CSS color>>`	—	Override the color used for any state

Return	Type	Description
`status`	`'idle' \| 'pending' \| 'success' \| 'error'`	Current state
`isBusy`	`boolean`	`true` while `pending`
`icon`	`ReactNode`	Ready-to-render trailing indicator
`run(fn)`	`<T>(fn: () => Promise<T>) => Promise<T \| undefined>`	Wraps async work; rejects → error status, returns `undefined` (no rethrow)
`settle(ok)`	`(ok: boolean) => void`	`true` → success, `false` → error (for `toastMutationResult`-style booleans)
`start` / `succeed` / `fail` / `reset`	`() => void`	Manual control if you already own the async flow

`ActionStatusIcon`

Presentational only — useful if you drive status yourself.

Prop	Type	Default	Description
`status`	`ActionStatus`	—	Which icon to show
`icon`	`ReactNode \| null`	chevron	Idle icon (`null` = empty)
`icons`	`ActionStatusIcons`	—	Overrides for pending / success / error
`variant`	`"inline" \| "halo"`	`"inline"`	Compact indicator or transitioning Halo presentation
`size`	`"sm" \| "md" \| "lg"`	`"sm"` for Halo	Halo size; ignored by the inline variant
`colors`	`ActionStatusColors`	—	Overrides state colors
`className`	`string`	—	Merged onto the wrapper

With disclosures

const save = useActionStatus();

<DisclosureButton
  icon={save.icon}
  rotateOnOpen={save.status === "idle"}
>
  Ship weight
</DisclosureButton>

// Full-bleed metric cells:
<RegionDisclosure.Value
  icon={save.icon}
  rotateOnOpen={save.status === "idle"}
>
  Small Box
</RegionDisclosure.Value>

RegionDisclosure.Value and DisclosureButton both accept icon and rotateOnOpen so status feedback drops in without a custom layout.