A React Hook Form persistence library with TypeScript support
npm install @liorpo/react-hook-form-persistA lightweight React Hook Form persistence library. Automatically save and restore form data to localStorage.
- ๐ 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
``bash`
npm install @liorpo/react-hook-form-persist
`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 (
$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 (
<>
>
);
}
`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`Thanks to the original react-hook-form-persist package for inspiration.
MIT - Lior Polak