@substrate/local-storage

React hook for enabling synchronization with local-storage.

API Docs can be found here.

Table of Contents

• @substrate/local-storage
  • Table of Contents
  • Install
    • With Yarn
    • With NPM
  • Usage
    • Write to Storage
    • Read From Storage
      • Optionally use a default value
    • Delete From Storage
  • Full Example

Install

With Yarn

yarn add @substrate/local-storage

With NPM

npm i @substrate/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 '@substrate/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 '@substrate/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 '@substrate/local-storage';

function MyComponent() {
  const [counterValue] = useLocalStorage<number>('i'); // specify a type argument for your type
  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 '@substrate/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 '@substrate/local-storage';

writeStorage('name', 'Homer Simpson'); // Add an item first

deleteFromStorage('name'); // Deletes the item

const thisIsNull = localStorage.getItem('name'); // This is indeed null

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 '@substrate/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(getNum !== 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):

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