@liorpo/react-hook-form-persist

A lightweight React Hook Form persistence library. Automatically save and restore form data to localStorage.

Features

- 🔄 Automatic Persistence: Automatically saves form data as users type
- 🗂️ Flexible Storage: Default localStorage with support for sessionStorage or custom storage
- ⏰ Timeout Support: Optional data expiration with cleanup
- 🚫 Field Exclusion: Exclude sensitive fields from persistence
- 📱 SSR Compatible: Works with server-side rendering
- 🎯 TypeScript: Full TypeScript support with proper types
- 🧪 Well Tested: Comprehensive test coverage

Installation

``bash
npm install @liorpo/react-hook-form-persist
`

Quick Start

$3

`tsx
import { useForm } from "react-hook-form";
import { useFormPersist } from "@liorpo/react-hook-form-persist";

function MyForm() {
const form = useForm({
defaultValues: {
name: "",
email: "",
},
});

const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
});

return (





Submit

Clear Saved Data


);
}


`

$3

`tsx
import { useForm } from "react-hook-form";
import { FormPersist } from "@liorpo/react-hook-form-persist";

function MyForm() {
const form = useForm({
defaultValues: {
name: "",
email: "",
},
});

return (
<>






Submit


);
}


`

API Reference

$3

A hook that handles form persistence.

`tsx
const { clear, isRestoringRef, isSavingRef } = useFormPersist(name, config);
`

#### Parameters

- name (string): Unique identifier for the form data in storage
- config (FormPersistConfig): Configuration object

#### Returns (UseFormPersistResult)

- clear(): Function to manually clear the persisted data
- isRestoringRef: RefObject indicating if data is being restored
- isSavingRef: RefObject indicating if data is being saved

#### Configuration Options (FormPersistConfig)

| Option | Type | Default | Description |
| ---------------- | ------------------ | ---------------- | ------------------------------------------- |
| storage | Storage | localStorage | Storage implementation to use |
| control | Control | required | React Hook Form control for watching values |
| setValue | UseFormSetValue | required | React Hook Form setValue for restoring data |
| exclude | string[] | [] | Field names to exclude from persistence |
| onDataRestored | (data: T) => void | - | Callback when data is restored |
| validate | boolean | false | Trigger validation when restoring data |
| dirty | boolean | false | Mark fields as dirty when restored |
| touch | boolean | false | Mark fields as touched when restored |
| timeout | number | - | Data expiration time in milliseconds |
| onTimeout | () => void | - | Callback when data expires |
| debounceDelay | number | 0 | Debounce delay in ms before persisting |

$3

A component that automatically handles form persistence.

`tsx

`

#### Props (FormPersistProps)

All props from FormPersistConfig except control and setValue, plus:

| Prop | Type | Required | Description |
| ---------- | ---------------- | -------- | ----------------------------------------------- |
| form | UseFormReturn | Yes | React Hook Form instance from useForm() |
| formKey | string | Yes | Unique identifier for storage (e.g., "form-v1") |
| children | ReactNode | No | Optional child elements to render |

Advanced Usage

$3

`tsx
import { useFormPersist } from "@liorpo/react-hook-form-persist";

function MyForm() {
const form = useForm();

const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
storage: sessionStorage, // Use sessionStorage instead of localStorage
});

return

...;
}


`

$3

`tsx
const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
exclude: ["password", "confirmPassword"], // Don't persist passwords
});
`

$3

`tsx
const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
timeout: 24 60 60 * 1000, // 24 hours
onTimeout: () => {
console.log("Form data expired");
},
});
`

$3

`tsx
const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
debounceDelay: 500, // Save after 500ms of inactivity
});
`

$3

`tsx
const customStorage = {
getItem: (key: string) => {
// Custom get logic
return localStorage.getItem(key);
},
setItem: (key: string, value: string) => {
// Custom set logic
localStorage.setItem(key, value);
},
removeItem: (key: string) => {
// Custom remove logic
localStorage.removeItem(key);
},
};

const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
storage: customStorage,
});
`

$3

`tsx
const { clear } = useFormPersist("my-form", {
control: form.control,
setValue: form.setValue,
validate: true, // Trigger validation when data is restored
dirty: true, // Mark form as dirty
touch: true, // Mark fields as touched
});
`

Development

$3

`bash
npm install
`

$3

`bash
npm run build
`

$3

`bash
npm test
npm run test:watch
npm run test:coverage
`

$3

`bash
npm run lint
npm run lint:fix
`

GitHub Actions

This repository uses a single CI/CD workflow (.github/workflows/ci.yml) that handles:

- Testing: Runs on push to main and pull requests

- Tests against Node.js 22 and 24
- Type checking, linting, formatting, and tests
- Coverage reports uploaded to Codecov

- Publishing: Automatically publishes to npm when a release is created
- Requires NPM_TOKEN secret in repository settings

$3

1. Update version in package.json`
2. Create a new GitHub release
3. The workflow will automatically test and publish to npm

Acknowledgments

Thanks to the original react-hook-form-persist package for inspiration.

License

MIT - Lior Polak