Auto Save Input

InstallCopy Anchor Link

pnpm exec vegastack-design verify auto-save-input

pnpm dlx shadcn@4.21.0 add @vegastack/auto-save-input

UsageCopy Anchor Link

import { AutoSaveInput } from "@/components/ui/auto-save-input";

<AutoSaveInput
  aria-label="Workspace name"
  defaultValue={workspace.name}
  onSave={async (name) => {
    await updateWorkspace({ name });
  }}
  validate={(v) => v.trim().length > 0}
/>;

AutoSaveInput composes InputGroup around an InputGroupInput — upstream's Input flattened into the box — so the trailing status indicator sits in a real addon slot rather than on top of a padded field. It owns its value as local state from defaultValue (or follows value + onValueChange when controlled), debounces keystrokes, and calls onSave(value) once the field settles. A trailing indicator reflects the outcome: a spinner while saving, a success check once saved, and an error cross on failure.

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

A failing onSave (rejected promise) flags the error state and sets aria-invalid; a failing validate skips the save entirely and flags error without ever calling onSave. Edit the field below and pause — it saves after 800ms; clear it and the validator blocks the save.

StatesCopy Anchor Link

Status is owned by the component and only advances when the field is edited, so this is a live example — type into each field and pause for the debounce to watch the trailing indicator move. Each field is wired to a different outcome:

• Saving — a deliberately slow onSave holds the spinning Loader in flight.
• Saved — a fast onSave resolves to the text-success-text Check.
• Error (rejecting onSave) — a rejected promise flags the text-destructive-text X and sets aria-invalid.
• Error (failed validate) — clearing the field fails validate, which flags error without ever calling onSave.

Controlled valueCopy Anchor Link

Pass value + onValueChange to let the parent own the draft. External value changes — like switching records — are treated as a new saved baseline, so moving between records never auto-saves stale data and never re-flags a status. Edit the field to save after the debounce, or switch records to reset the baseline.

Status indicatorCopy Anchor Link

AutoSaveIndicator is the same lifecycle as a line of text for an action row: a spinner and "Saving…", a check and "Saved", and the -text ink with its own icon for "Couldn't save" and a conflict ("Not saved"). It is a polite live region, empty while idle.

Icon onlyCopy Anchor Link

variant="icon" is the same status as one 16px icon for a field's trailing slot — an InputGroupAddon align="inline-end" on an input or textarea, or beside a select: a muted spinner while saving, a text-success-text check once saved, a text-destructive-text warning triangle when the save failed (text-warning-text on a conflict). Each state pops in (a fade and a 0.9 → 1 scale on the motion tokens), the check fades out over duration-slow when the status returns to idle, and the box is always reserved, so nothing shifts. The wording ("Saving", "Saved", "Couldn't save") stays as screen-reader text in the live region; reduced motion swaps instantly.

An invalid valueCopy Anchor Link

A value the field rejects (an empty required name) is not a save state: nothing was sent. Pass invalid and the indicator — either variant — drops the tick and says Not saved in the warning ink, so a field never shows "saved" beside its own error. useInvalidRevert finishes the job: leave the field while it is invalid and, a second later, onRevert puts the last saved value back and shows why ("Name can't be empty"); coming back to the field, or fixing the value, cancels it. AutoSaveInput does both itself — a value validate rejects reads "Not saved", and onInvalidRevert turns on the revert.

In a top barCopy Anchor Link

compact="narrow" keeps a text indicator to one line and, below sm or in a narrow AppShellHeader (under 40rem), shows the icon alone — the words are still read out. Use it for a document's connection state ("Reconnecting…") among a top bar's actions.

<AutoSaveIndicator
  status="connecting"
  compact="narrow"
  labels={{ connecting: "Reconnecting…" }}
/>

A whole form (useAutoSave)Copy Anchor Link

useAutoSave saves a form object rather than one field: debounced (600ms), only the changed fields, one save in flight at a time with the latest values sent next, a version carried for optimistic concurrency (isConflict turns a stale-version error into the conflict status), and a flush() to call before a step change or navigation. Pending changes are also saved on unmount and when the tab closes.

API ReferenceCopy Anchor Link

AutoSaveIndicatorCopy Anchor Link

useAutoSaveCopy Anchor Link

useInvalidRevertCopy Anchor Link

AutoSaveStatus is the union of states the trailing indicator can reflect; pass onStatusChange to react to transitions (e.g. disable a submit button while saving).

AccessibilityCopy Anchor Link

• Renders a native <input> — always associate a visible <label> (wrap it or use htmlFor/id); use aria-label only when a visible label is impossible.
• Status is conveyed by a distinct icon per state (spinner / check / cross) paired with a semantic color token, so it never depends on color alone.
• A single role="status" aria-live="polite" aria-atomic="true" slot announces "Saving", "Saved", "Save failed", or "Not saved" (a value validate rejects) as hidden text while the visible icon remains decorative.
• AutoSaveIndicator invalid shows "Not saved" as visible text, in the same live region, never a check beside an error.
• The error status sets aria-invalid on the field, matching Input's invalid styling and announcing the failure to screen readers.
• The spinner respects prefers-reduced-motion (motion-reduce:animate-none).
• On focus the underlying InputGroup darkens its border subtly (border-ring/50, easing in over 150ms) and paints no fill — text entry's exception to FOC-14 (MK 2026-09-27) — instead of removing the affordance; never outline: none with nothing in its place. The error status keeps its destructive border while focused.

Do / Don'tCopy Anchor Link