Form Autosave

FreeNew

A useAutosave hook and a status indicator: debounced saves with a single request in flight, a queued follow-up for edits made while saving, retry on failure, and a polite Saving, Saved or Failed announcement.

The full demo as documented.

Customize

Derived from this item’s props table, because it declares no controls of its own. Changes drive the preview live.

delay800

enabled

saveOnHide

Guide and examples

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/form-autosave.json

Usage

import { AutosaveIndicator, useAutosave } from "@/components/ui/form-autosave"

const autosave = useAutosave({
  value: draft,                       // any serialisable value
  onSave: (value) => api.saveDraft(value),
  delay: 800,
})
 
<AutosaveIndicator {...autosave} onRetry={autosave.retry} />

Call autosave.flush() before navigating away or before a final submit, so the last edit is not left in the delay window.

Exports

Export	Description
`useAutosave(options)`	Returns `{ status, savedAt, error, flush, retry }`.
`AutosaveIndicator`	The status line: Unsaved changes, Saving..., Saved at 14:32, Could not save. Retry.

Props

Option	Type	Default	Description
`value`	`T`	-	Compared as JSON text.
`onSave`	`(value) => void \| Promise<void>`	-	Reject to enter `error`.
`delay`	`number`	`800`	Milliseconds after the last change.
`enabled`	`boolean`	`true`	Turn it off while the form is invalid.
`saveOnHide`	`boolean`	`true`	Save when the tab goes to the background.

Accessibility

The indicator is a live region: role="status" (polite) for pending, saving and saved, and role="alert" (assertive) for a failure. It stays mounted so a change from empty to text is announced.
Retry is a real button next to the message. Nothing moves focus.
Autosave does not replace an explicit Save for important data: say so in the interface when a person might expect to confirm (for example "Saved as draft").

Testing

The component ships with a Testing Library test (form-autosave.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/form-autosave.json

Usage

import { AutosaveIndicator, useAutosave } from "@/components/ui/form-autosave"

const autosave = useAutosave({
  value: draft,                       // any serialisable value
  onSave: (value) => api.saveDraft(value),
  delay: 800,
})
 
<AutosaveIndicator {...autosave} onRetry={autosave.retry} />

Call autosave.flush() before navigating away or before a final submit, so the last edit is not left in the delay window.

Exports

Export	Description
`useAutosave(options)`	Returns `{ status, savedAt, error, flush, retry }`.
`AutosaveIndicator`	The status line: Unsaved changes, Saving..., Saved at 14:32, Could not save. Retry.

Props

Option	Type	Default	Description
`value`	`T`	-	Compared as JSON text.
`onSave`	`(value) => void \| Promise<void>`	-	Reject to enter `error`.
`delay`	`number`	`800`	Milliseconds after the last change.
`enabled`	`boolean`	`true`	Turn it off while the form is invalid.
`saveOnHide`	`boolean`	`true`	Save when the tab goes to the background.

Accessibility

The indicator is a live region: role="status" (polite) for pending, saving and saved, and role="alert" (assertive) for a failure. It stays mounted so a change from empty to text is announced.
Retry is a real button next to the message. Nothing moves focus.
Autosave does not replace an explicit Save for important data: say so in the interface when a person might expect to confirm (for example "Saved as draft").

Testing

The component ships with a Testing Library test (form-autosave.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.