Have ideas to improve npm?Join in the discussion! »

    @rehooks/local-storage
    TypeScript icon, indicating that this package has built-in type declarations

    2.4.1 • Public • Published

    @rehooks/local-storage

    All Contributors

    React hook for enabling synchronization with local-storage.

    npm version npm downloads

    API Docs can be found here.

    Table of Contents

    Features

    • Automatic JSON serialization
    • Synchronization across multiple tabs
    • Provides functions for updating the localStorage and triggering a state update outside of the component
    • Type hinting via TypeScript

    Install

    With Yarn

    yarn add @rehooks/local-storage

    With NPM

    npm i @rehooks/local-storage --save

    Usage

    Write to Storage

    This can be anywhere from within your application.

    Note: Objects that are passed to writeStorage are automatically stringified. This will not work for circular structures.

    import React from 'react';
    import { writeStorage } from '@rehooks/local-storage';
    
    let counter = 0;
    
    const MyButton = () => (
      <button onClick={_ => writeStorage('i', ++counter)}>
        Click Me
      </button>
    );

    Read From Storage

    This component will receive updates to itself from local storage.

    Javascript:

    import React from 'react';
    import { useLocalStorage } from '@rehooks/local-storage';
    
    function MyComponent() {
      const [counterValue] = useLocalStorage('i'); // send the key to be tracked.
      return (
        <div>
          <h1>{counterValue}</h1>
        </div>
      );
    }

    Typescript:

    import React from 'react';
    import { useLocalStorage } from '@rehooks/local-storage';
    
    function MyComponent() {
      const [counterValue] = useLocalStorage<number>('i'); // specify a type argument for your type
      // Note: Since there was no default value provided, this is potentially null.
      return (
        <div>
          <h1>{counterValue}</h1>
        </div>
      );
    }

    Optionally use a default value

    Note: Objects that are passed to useLocalStorage's default parameter will be automatically stringified. This will not work for circular structures.

    import React from 'react';
    import { useLocalStorage } from '@rehooks/local-storage';
    
    function MyComponent() {
      // Note: The type of user can be inferred from the default value type
      const [user] = useLocalStorage('user', { name: 'Anakin Skywalker' });
      return (
        <div>
          <h1>{user.name}</h1>
        </div>
      );
    }

    Delete From Storage

    You may also delete items from the local storage as well.

    import { writeStorage, deleteFromStorage } from '@rehooks/local-storage';
    
    writeStorage('name', 'Homer Simpson'); // Add an item first
    
    deleteFromStorage('name'); // Deletes the item
    
    const thisIsNull = localStorage.getItem('name'); // This is indeed null

    Using With Context

    It is advisable to use this hook with context if you want to have a properly synchronized default value. Using useLocalStorage in two different components with the same key but different default values can lead to unexpected behaviour.

    Using Context will also prevent components from rendering and setting default values to the localStorage when you just want them to be deleted from localStorage (assuming the context provider also does not re-render).

    import React, { createContext, useContext } from 'react';
    import { useLocalStorage } from '@rehooks/local-storage';
    
    const defaultProfile = { name: 'Spongekebob' };
    const defaultContextValue = [defaultProfile, () => {}, () => {}];
    
    const ProfileContext = createContext(defaultContextValue);
    
    export const ProfileProvider = ({ children }) => {
      const ctxValue = useLocalStorage('profile', defaultProfile);
      return (
        <ProfileContext.Provider value={ctxValue}>
          {children}
        </ProfileContext.Provider>
      );
    };
    
    const useProfile = () => useContext(ProfileContext);
    
    const App = () => {
      const [profile] = useProfile();
      return <h1>{profile && profile.name}</h1>;
    };
    
    export default () => {
      return (
        <ProfileProvider>
          <App />
        </ProfileProvider>
      );
    };

    Full Example

    You may view this example here on StackBlitz.

    Note: The writeStorage and deleteFromStorage functions are provided from useLocalStorage as well, and do not require you to specify the key when using them.

    import React, { Fragment } from 'react';
    import { render } from 'react-dom';
    import { writeStorage, deleteFromStorage, useLocalStorage } from '@rehooks/local-storage';
    
    const startingNum = 0;
    
    const Clicker = () => (
      <Fragment>
        <h4>Clicker</h4>
        <button onClick={_ => {
          writeStorage('num', localStorage.getItem('num')
          ? +(localStorage.getItem('num')) + 1
          : startingNum
          )
        }}>
          Increment From Outside
        </button>
        <button onClick={_ => deleteFromStorage('num')}>
          Delete From Outside
        </button>
      </Fragment>
    );
    
    const IncrememterWithButtons = () => {
      const [number, setNum, deleteNum] = useLocalStorage('num');
    
      return (
        <Fragment>
          <p>{typeof(number) === 'number' ? number : 'Try incrementing the number!'}</p>
          <button onClick={_ => setNum(number !== null ? +(number) + 1 : startingNum)}>Increment</button>
          <button onClick={deleteNum}>Delete</button>
        </Fragment>
      );
    };
    
    const App = () => (
      <Fragment>
        <h1> Demo </h1>
        <IncrememterWithButtons />
        <Clicker />
      </Fragment>
    );
    
    // Assuming there is a div in index.html with an ID of 'root'
    render(<App />, document.getElementById('root'));

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Amit Solanki

    💻 📖 🤔 👀

    Joe

    💻 💡 🤔 🚧 👀 ⚠️

    Fatih Kaya

    💻 ⚠️ 🐛

    Jarl André Hübenthal

    💻 ⚠️ 🐛

    Jamie Kyle

    💻

    Albert Boehmler

    💻 🐛

    Gabriel Dayley

    💻 🐛

    Harley Alexander

    🚧 💻 🐛 ⚠️

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i @rehooks/local-storage

    DownloadsWeekly Downloads

    18,846

    Version

    2.4.1

    License

    MIT

    Unpacked Size

    36.1 kB

    Total Files

    19

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar