Read the official documentation.

👁️ Live Demo

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

• 🔄 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.

If this project helped you, please consider buying me a coffee or sponsoring me. Your support is much appreciated!

• Documentation
• Overview
  • Features include:
• Donate
• Table of Contents
• Installation
• Quick Start
  • Basic Usage
  • Providing A Default Value
  • Namespacing Using Prefix
    • Namespacing Using User IDs
  • Clearing The Value
  • Accessing The Prefixed Key
  • Additional Options & Uses
• TypeScript
• Icon Attribution
• Contributing
• ⭐ Found It Helpful? Star It!
• License

npm i react-storage-complete

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').

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.

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 my-namespace.name.

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 user.id 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!

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.

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 my-namespace.food.

You can customize the separator by providing the prefixSeparator option.

See the documentation for additional options and uses:

• useLocalStorage documentation
• useSessionStorage documentation

Type definitions have been included for TypeScript support.

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.

If you found this project helpful, let the community know by giving it a star: 👉⭐

See LICENSE.md.