TypeScript icon, indicating that this package has built-in type declarations

1.1.5Β β€’Β PublicΒ β€’Β Published

πŸ—„οΈ React Storage Complete

React hooks for accessing localStorage and sessionStorage, with syncing and prefix support. The complete package.

npm VersionΒ  View project on GitHubΒ  Deploy StatusΒ  Sponsor


Read the official documentation.

πŸ‘οΈ Live Demo


Hooks for easily accessing localStorage and sessionStorage, with a similar interface to React.useState().

Features include:

  • πŸ”„ Automatic state synchronization
    • Changes are synchronized across hooks, and even different browser tabs, automatically.
  • πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦ Namespacing using prefixes
    • Easily scope your stored data with namespaces. Great for managing data for multiple users.
  • πŸ”’ Support for primitives and objects
    • Store and retrieve strings, booleans, numbers, and objects effortlessly.
  • πŸ‘Ύ Customizable
    • Want to store something unusual? Just provide your own encoder and decoder.
  • πŸ’ Default values
    • Optional support for defaults is baked right in.


I hope this project makes your life a little easier! If it does and you'd like to show your appreciation, consider supporting the project with a coffee or sponsorship.

Your support helps keep the project going and will earn you some serious virtual high fives. Maybe even a virtual fist bump if you're feeling extra cool.

Sponsor via GitHub Buy me a coffee Buy me 3 coffees Buy me 5 coffees

Table of Contents


npm i react-storage-complete

Quick Start

Use this hook... For this Storage API... Storage Description
useLocalStorage localStorage The localStorage object stores data with no expiration date. The data is not deleted when the browser is closed, and is available for future sessions.
useSessionStorage sessionStorage The sessionStorage object stores data for only one session. The data is deleted when the browser is closed.

Basic Usage

import { useLocalStorage } from 'react-storage-complete';
import { useSessionStorage } from 'react-storage-complete';

Both useLocalStorage and useSessionStorage share the same interface and are interchangeable.

In your component or hook:

const [name, setName] = useLocalStorage('name');

This will store and retrieve the value using the name key in localStorage.

Note: If using TypeScript, you can provide a value type like so: useLocalStorage<string>('name').

Providing A Default Value

You can also provide a default value for when the stored value is undefined (not currently set in localStorage):

const [name, setName] = useLocalStorage('name', 'Guest');

In this example, when the stored item with the key name is undefined, the name value will be Guest.

Note: When a value is null in storage, null is returned, not the provided default.

Namespacing Using Prefix

You can namespace stored items using a prefix:

const [name, setName] = useLocalStorage('name', 'Guest', {
  prefix: 'my-namespace',

For example, by using a user ID as the prefix, you can scope the stored data to the user and avoid mixing settings.

Above, the key for the value would be

Namespacing Using User IDs

With react-storage-complete, managing stored data for multiple user accounts in the same browser is easy.

const [name, setName, initialized] = useLocalStorage('name', 'Guest', {
  prefix: user?.id, // Undefined until user ID is available as a namespace
  shouldInitialize: !!user?.id, // Only initialize when user ID is available

As shown above, you can delay initialization of the stored value until your prefix is available and ready to use as the namespace.

For example, a user ID may not be ready until logged in, but you may still be calling the hook in your app before that happens.

In this example:

  • initialized will be false until the is loaded and ready to use as the prefix.
  • When shouldInitialize is true, the prefix is used with the key to retrieve the stored value from localStorage.
  • Then, initialized will return as true, and your value will be ready to use!

Clearing The Value

const [name, setName, initialized, clear] = useLocalStorage('name', 'Guest');

You can clear any stored value and completely remove it from storage using the returned clear function.

In this example, calling clear() will delete the item from storage. You can also call setName(undefined) to achieve the same result.

Accessing The Prefixed Key

const [food, setFood, initialized, clear, prefixedKey] = useLocalStorage('food', 'Hamburger', {
  prefix: 'my-namespace',

The hook also returns the prefixed key, in case you want direct access to it.

In the example above, the prefixed key would be

You can customize the separator by providing the prefixSeparator option.

Additional Options & Uses

See the documentation for additional options and uses:


Type definitions have been included for TypeScript support.

Icon Attribution

Favicon by Twemoji.


Open source software is awesome and so are you. 😎

Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.

For major changes, open an issue first to discuss what you'd like to change.

⭐ Found It Helpful? Star It!

If you found this project helpful, let the community know by giving it a star: πŸ‘‰β­



Package Sidebar


npm i react-storage-complete

Weekly Downloads






Unpacked Size

90.8 kB

Total Files


Last publish


  • justinmahar