`React.useState` + BrowserStorage API for persistence
npm install react-persistent-state-hookusePersistentState(value, storageKey, options): [value, setValue, purgeValue]





š”š§ A React useState() replacement with built-in persistence with Web Storage API. First-class TypeScript support šŖ
``bash`
yarn add react-persistent-state-hook # or npm, pnpm, bun, etc.
`typescript
// It works just like magic š
const [name, setName] = usePersistentState("John", "user-name")
// For more safety, provide a UNIQUE storageKey (strongly recommended šŖ)
const [name, setName] = usePersistentState("Billy", "ui/userAuth/name")
// For more versatility, use ENUMs as keys
const [name, setName] = usePersistentState("Tim", StorageKeys.USER_NAME)
`
---
Table of contents:
1. Key Features
2. Usage
3. Options API
4. Roadmap
5. Contributing
---
usePersistentState adds persistence to React.useState method:
1. š£ Plug'n'play with Minimal Configuration:
A simple replacement for React.useState hook - provide a unique key and you're good to go!
2. š§ Data Persistence:
Store state values in localStorage or sessionStorage. Until version 2, we only support Web Storage API, but more are coming.
3. ā»ļø Platform-Agnostic:
usePersistentState gracefully handles scenarios where Web Storage is not available, behaving exactly like React.useState.
4. š No Dependencies:
Keep your project light - no dependencies and a single peer dependency (react >= 16.8).
5. š§āš» First-class TypeScript Support:
Fully typed with TypeScript! š
6. š§ Roadmap for Continuous Improvement:
- The roadmap outlines upcoming features and enhancements, ensuring your state management needs are met.
7. š Documentation and Tutorials:
Straight-forward readme with examples and comprehensive JSDoc annotations for the hook and its options.
RPSH is committed to delivering a minimal and flexible solution for state management and persistence in React applications. Join me on this journey by contributing! š
---
Start by importing the hook:
`typescript`
import { usePersistentState } from "react-persistent-state-hook"
#### Basic usage
`typescriptlocalStorage
// Replace React.useState without breaking functionality - uses
const [count, setCount] = usePersistentState(0, "count")
const [count, setCount] = usePersistentState(() => 0, "count")
// Easy switching between local and session storages
const [count, setCount] = usePersistentState(0, "unique-key", "local")
const [count, setCount] = usePersistentState(0, "unique-key", "session")
// Configurable with options API
const [count, setCount] = usePersistentState(0, "unique-key", { verbose: true, persistent: false })
`
> š” Possible state management replacement (like context or Redux) with zero configuration in situations where data loss is acceptable (like UI preferences). āļø
`typescript`
// You can use your own prefixes to group related keys and prevent conflicts
const [count, setCount] = usePersistentState(0, "count", { prefix: "ui/homepage" })
#### Advanced usage
š” You can create a custom usePersistentState hook with default options easily to share or persist configuration values across your application or different contexts:
`typescript
import { createPersistentStateHook } from "react-persistent-state-hook"
// Create your own hook with defaults
export const useMyPersistentState = createPersistentStateHook({
storageType: "session",
prefix: "homepage/pagination",
})
// Usage - you can still override default options
const [page, setPage] = useMyPersistentState(1, "page")
`
---
The Options API in react-persistent-state-hook allows you to tweak the behavior of the hook. More configuration options are coming soon in minor releases.
Breaking changes in the Options API or elsewhere in react-persistent-state-hook are only released in major versions š¤
`typescriptsilent
type Options = {
/** Print all warnings and errors in console. Overrides option.
@default false /
verbose: boolean
/** The type of Web Storage API to use (either "session" or "local").
@default "local" /
storageType: StorageType
/** Allow programatically enabling and disabling persistence in-place.
@default true /
persistent: boolean
/** Allow the use of custom key prefix - group contexts or invalidate state version.
@default "[rpsh]" /
prefix: string
}
`
---
#### Current Plans (v1.0.0 Release):
- Resolution Strategies ?
- Add option to always override with new value, prefer stored value, or use stored if new value is undefined (default)main
- 1.0.0 Release š
- Freeze the branch and move development to dev-v1.x branches, that eventually get merged into main as PRs. We need to act responsible šØāš«
#### Planned Improvements
- More Storage Types
- Add support for IndexedDB, AsyncStorage (React Native), URL params, cookies, etc.JSON.stringify
- Even Smaller Footprint
- Reduce bundle size as much as possible
- Custom Serialization and Deserialization Methods
- Add the ability to configure your own serialization and deserialization functions instead of relying on and JSON.parse - for example to support Date and custom objectsCONTRIBUTING.md
- Open-source Friendliness
- Add a file to make it easier for contributors to get started, link to it from README.md`
- Provide a solid tutorial for contributors, set up PR template, issue template, etc.
- Storage Adapters API
- Say goodbye to Web Storage API as a core feature and say hello to storage adapters API. More flexibility, more possibilities! š
- Implement Web Storage and in-memory storage as exported storage adapter functions / objects
---
Start a new issue whenever you have any questions, problems or suggestions! Or feel free to open a pull request if you want to contribute. To increase the speed of getting your PR merged, please open an issue first to discuss your idea.
More info coming soon.