Documentation

Read the official documentation.

👁️ Live Demo

Overview

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.

Donate

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

Table of Contents

• 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

Installation

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

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 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!

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

You can customize the separator by providing the prefixSeparator option.

Additional Options & Uses

See the documentation for additional options and uses:

• useLocalStorage documentation
• useSessionStorage documentation

TypeScript

Type definitions have been included for TypeScript support.

Icon Attribution

Favicon by Twemoji.

Contributing

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: 👉⭐

License

See LICENSE.md.