# use-storage-backed-state

> Custom React hook for storage backed persisted state.

Latest version **2.0.5** (published 2026-02-12) · ISC license · 0 weekly downloads

## Install

```sh
npm install use-storage-backed-state
pnpm add use-storage-backed-state
yarn add use-storage-backed-state
bun add use-storage-backed-state
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.5 |
| Published | 2026-02-12 |
| First published | 2021-01-26 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 56.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Filip Chalupa |
| Maintainers | onset |
| Keywords | react, hook, localstorage, typescript |

## Links

- npm: https://www.npmjs.com/package/use-storage-backed-state
- Repository: https://github.com/FilipChalupa/use-storage-backed-state
- Homepage: https://github.com/FilipChalupa/use-storage-backed-state#readme
- Issues: https://github.com/FilipChalupa/use-storage-backed-state/issues
- npm.io page: https://npm.io/package/use-storage-backed-state

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 2.0.5 (latest) — 2026-02-12
- 2.0.4 — 2026-02-09
- 2.0.3 — 2025-08-07
- 2.0.2 — 2025-08-07
- 2.0.1 — 2025-08-07
- 2.0.0 — 2025-08-07
- 1.4.1 — 2025-08-06
- 1.4.0 — 2025-03-24
- 1.3.1 — 2025-02-12
- 1.3.0 — 2024-12-18
- 1.2.1 — 2024-10-14
- 1.2.0 — 2024-05-16
- 1.1.3 — 2024-01-03
- 1.1.2 — 2024-01-03
- 1.1.1 — 2024-01-03
- … 15 more at https://npm.io/package/use-storage-backed-state/versions

## README

# useStorageBackedState [![npm](https://img.shields.io/npm/v/use-storage-backed-state.svg)](https://www.npmjs.com/package/use-storage-backed-state) ![npm type definitions](https://img.shields.io/npm/types/use-storage-backed-state.svg)

Custom React hook for state management like `useState` but persisted to `localStorage`. Check interactive [demo](http://filipchalupa.cz/use-storage-backed-state/).

![example](https://raw.githubusercontent.com/FilipChalupa/use-storage-backed-state/HEAD/screencast.gif)

## Installation

```bash
npm install use-storage-backed-state
```

## How to use

```jsx
import React from 'react'
import { useStorageBackedState } from 'use-storage-backed-state'

export const MyComponent = () => {
	const [count, setCount] = useStorageBackedState({
		key: 'count',
		defaultValue: 0,
	})

	return (
		<section>
			<h1>
				Value: <output>{count}</output>
			</h1>
			<button
				onClick={() => {
					setCount(count + 1)
				}}
			>
				increment
			</button>
			<button
				onClick={() => {
					setCount(count - 1)
				}}
			>
				decrement
			</button>
		</section>
	)
}
```

## Notes

- Stores data in `localStorage`.

- Works with `sessionStorage` too.

  ```jsx
  useStorageBackedState({
  	// …
  	storage: sessionStorage,
  })
  ```

- Realtime synchronization between multiple uses with the same `key`. Even across tabs.

- You can opt out from storage and synchronization by passing `null` to `storage` option.

  ```jsx
  const [count, setCount] = useStorageBackedState({
  	key: 'local-count',
  	initialValue: 1,
  	storage: null,
  })
  ```

## Advanced Usage

### Custom parser and serializer

By default, `use-storage-backed-state` uses `JSON.stringify` and `JSON.parse` to handle values. You can provide your own functions to handle custom data types, like `Date` objects.

```jsx
const [date, setDate] = useStorageBackedState({
	key: 'my-date',
	defaultValue: new Date(),
	parse: (value) => new Date(value),
	stringify: (value) => value.toISOString(),
})
```

### Usage outside of React component

You can also get, set, and remove values from outside of a React component.

```jsx
import {
	getStorageBackedValue,
	setStorageBackedValue,
	removeStorageBackedValue,
} from 'use-storage-backed-state'

// Set a value
setStorageBackedValue({ key: 'my-key', value: 'my-value' })

// Get a value
const value = getStorageBackedValue({ key: 'my-key', defaultValue: 'default' })

// Remove a value
removeStorageBackedValue({ key: 'my-key' })
```

### Subscribing to changes

You can subscribe to changes of a value. This is useful for integrating with other libraries like `rxjs`.

```jsx
import { subscribeStorageBackedValue } from 'use-storage-backed-state'
import { Observable } from 'rxjs'

const myValue$ = new Observable((subscriber) => {
	const { unsubscribe } = subscribeStorageBackedValue({
		key: 'my-key',
		defaultValue: 'default',
		onChange: (value) => {
			subscriber.next(value)
		},
	})

	return unsubscribe
})

myValue$.subscribe((value) => {
	console.log('Value changed:', value)
})
```

---
_Source: https://npm.io/package/use-storage-backed-state · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._