react-form-drafts

Auto-save and restore unsaved form drafts in React apps.

Never lose form data again.

react-form-drafts saves form values while the user is typing. If the page refreshes or the user comes back later, you can restore the saved draft.

What problem does it solve?

Users can lose form data after a refresh, closed tab, route change, or lost connection. This package keeps a draft in browser storage so the data can be restored.

It does not render UI. It does not replace React Hook Form, Formik, or your form library. It only saves and restores draft data. It works with any form state.

Tiny example

const draft = useFormDraft({
  key: 'profile-form',
  values,
  onRestore: setValues,
})

Installation

npm install react-form-drafts

React 18 and React 19 are supported.

Quick start

import { useState } from 'react'
import { useFormDraft } from 'react-form-drafts'

type FormValues = {
  name: string
  email: string
}

export function ProfileForm() {
  const [values, setValues] = useState<FormValues>({
    name: '',
    email: '',
  })

  const {
    hasDraft,
    restoreDraft,
    clearDraft,
    lastSavedAt,
    isSaving,
  } = useFormDraft<FormValues>({
    key: 'profile-form',
    values,
    onRestore: setValues,
  })

  return (
    <form>
      {hasDraft && (
        <button type="button" onClick={restoreDraft}>
          Restore saved draft
        </button>
      )}

      <input
        value={values.name}
        onChange={(event) =>
          setValues((current) => ({
            ...current,
            name: event.target.value,
          }))
        }
      />

      <button type="button" onClick={clearDraft}>
        Clear draft
      </button>

      {isSaving && <p>Saving...</p>}
      {lastSavedAt && <p>Draft saved</p>}
    </form>
  )
}

API

useFormDraft(options)

Automatically saves values after they change. The default delay is 500ms.

It returns:

• hasDraft: true when a valid draft exists.
• draft: the current draft or null.
• lastSavedAt: the save time as a Date, or null.
• isSaving: true while a save is waiting.
• saveDraft(): saves now.
• restoreDraft(): restores the saved values.
• clearDraft(): removes the saved draft.
• refreshDraft(): reads the draft from storage again.

Storage helpers

import {
  getFormDraft,
  setFormDraft,
  removeFormDraft,
  hasFormDraft,
} from 'react-form-drafts'

These helpers are safe during server rendering. They return safe values when browser storage is not available.

Options

• key: unique draft name. Required.
• values: current form values. Required.
• onRestore: receives restored values. Required.
• enabled: turns saving on or off. Default: true.
• storage: localStorage, sessionStorage, or a custom storage object.
• debounceMs: save delay. Default: 500.
• expiresInMs: removes the draft after this time.
• version: removes old drafts with a different version.
• saveOnMount: saves the first values on mount. Default: false.
• restoreOnMount: restores a valid draft on mount. Default: false.
• clearOnSubmit: clears the draft when a form is submitted.
• shouldSave: decides if the current values should be saved.
• serialize: converts values to a string before storage.
• deserialize: converts the stored string back to values.
• onSave: runs after a successful save.
• onRestoreDraft: runs after a successful restore.
• onClear: runs after clearing.
• onError: receives storage or JSON errors.

Use serialize and deserialize together.

Next.js note

The package is SSR-safe. Browser storage is not used during render.

With the Next.js App Router, use the hook in a Client Component:

'use client'

import { useFormDraft } from 'react-form-drafts'

When should you use it?

Use it for:

• long forms
• admin panels
• checkout forms
• profile forms
• support ticket forms
• CMS editors
• multi-step forms
• forms where losing data would frustrate users

When should you not use it?

Do not use it for:

• tiny forms
• search boxes
• login forms
• sensitive forms where data should not be stored in browser storage
• forms with passwords, tokens, private keys, or credit card numbers
• forms with highly sensitive data

Security

Browser storage is not encrypted. Do not use this package to store passwords, access tokens, credit card numbers, private keys, or highly sensitive personal data.

Development

npm install
npm run typecheck
npm run build

To check the npm package contents:

npm pack --dry-run

License

MIT