Persistence · Formedible

Configuration

Persistence is a useFormedible option with five properties. In the browser, Formedible uses the configured storage and falls back to sessionStorage unless you choose localStorage.

key is required and is passed to storage.setItem, getItem, and removeItem.
storage accepts localStorage or sessionStorage; blank means sessionStorage.
exclude removes top-level field names before Formedible writes the payload.

Property	Type	Default	Description
`key`	`string`	`Required`	Storage key for the saved draft. Include product area, form name, and a version, such as onboarding:v2.
`storage`	`'localStorage' \| 'sessionStorage'`	`'sessionStorage'`	Browser storage target. Use localStorage for drafts that should survive closed tabs.
`debounceMs`	`number`	`500`	Delay after value changes before Formedible writes a draft.
`exclude`	`readonly (Extract<keyof TFormValues, string> \| string)[]`	`[]`	Field names removed from saved values before each write.
`restoreOnMount`	`boolean`	`false`	Loads the saved payload on mount and applies its values and page when present.

Persistence config from the live example

tsx

const { Form, saveToStorage, loadFromStorage, clearStorage } = useFormedible({
  fields,
  pages,
  persistence: {
    key: 'demo-project-inquiry-form',
    storage: 'localStorage',
    debounceMs: 1500,
    exclude: ['agreeToTerms'],
    restoreOnMount: true,
  },
  formOptions: { defaultValues, onSubmit },
});

Auto-save behavior

The persistence hook watches form.state.values. In the browser, it schedules saveToStorage after debounceMs, or 500 ms by default, and cancels that write if values change first.

createPersistedFormPayload always writes values and timestamp.
currentPage is included only when Formedible passes a page number.
After onSubmit resolves, Formedible clears the configured storage key.

What the hook writes

ts

const payload = createPersistedFormPayload(
  { name: 'Ada', email: 'ada@example.com', agreeToTerms: true },
  3,
  ['agreeToTerms'],
);

// With Date.now() mocked to 1234, tests assert:
// {
//   values: { name: 'Ada', email: 'ada@example.com' },
//   timestamp: 1234,
//   currentPage: 3,
// }

Manual controls

useFormedible returns the persistence helpers from useFormPersistence. Manual buttons and debounce writes use the same key, storage target, and payload format.

saveToStorage writes current form values with the current page from useFormedible.
loadFromStorage sets saved fields, restores a valid currentPage, and returns the parsed payload.
clearStorage removes the configured key when storage is available.

Manual draft buttons

tsx

const { Form, saveToStorage, loadFromStorage, clearStorage } = useFormedible(config);

return (
  <>
    <Form />
    <button type="button" onClick={saveToStorage}>Save draft</button>
    <button type="button" onClick={() => void loadFromStorage()}>Restore draft</button>
    <button type="button" onClick={clearStorage}>Clear draft</button>
  </>
);

Payload structure

The stored value is JSON.stringify(payload). The parser returns undefined for bad JSON, missing values, or a missing timestamp.

values must parse as an object; timestamp must parse as a number.
currentPage is kept only when it parses as a number.
loadFromStorage calls form.setFieldValue for each saved field before returning the payload.

Property	Type	Default	Description
`values`	`Partial<TFormValues>`	`Required`	Saved field values after exclude runs.
`timestamp`	`number`	`Required`	Save time in milliseconds since the Unix epoch.
`currentPage`	`number`	`undefined`	Saved page number for multi-page forms. It restores when the saved number fits within the current page count.

PersistedFormPayload interface

ts

export interface PersistedFormPayload<TFormValues extends FormedibleFormValues> {
  readonly values: Partial<TFormValues>;
  readonly timestamp: number;
  readonly currentPage?: number;
}

UX patterns

Formedible gives you storage mechanics, not a status banner. Build visible draft controls around the returned helpers and the timestamp from loadFromStorage.

Use restoreOnMount for automatic restore.
Call loadFromStorage from a button when users should choose whether to restore.
Change the key when field names change; the parser validates shape but does not migrate old drafts.

Timestamp-driven restore copy

tsx

const restored = await loadFromStorage();

if (restored) {
  setDraftMessage('Draft restored from ' + new Date(restored.timestamp).toLocaleString());
}

Restore drafts with a clear storage contract.