use-local-storage

Use localStorage value as react state, sync state across opened tabs

Import

Source

View source code

Docs

Edit this page

Package

@mantine/hooks

Usage

use-local-storage allows you to use value from localStorage as react state. Hook works the same way as useState, but also writes the value to localStorage:

import { useLocalStorage } from '@mantine/hooks';

// hook will read value from localStorage.getItem('color-scheme')
// if localStorage is not available or value at given key does not exist
// 'dark' will be assigned to value variable
const [value, setValue] = useLocalStorage({ key: 'color-scheme', defaultValue: 'dark' });

// Value is set both to state and localStorage at 'color-scheme'
setValue('light');

// You can also use callback like in useState hook to set value
setValue((current) => (current === 'dark' ? 'light' : 'dark'));

Example

Mantine docs website uses this hook to store color scheme information:

import { useLocalStorage } from '@mantine/hooks';
import { ActionIcon, ColorScheme } from '@mantine/core';
import { IconSun, IconMoonStars } from '@tabler/icons';

function ColorSchemeToggle() {
  const [colorScheme, setColorScheme] = useLocalStorage<ColorScheme>({
    key: 'color-scheme',
    defaultValue: 'light',
  });

  const toggleColorScheme = () =>
    setColorScheme((current) => (current === 'dark' ? 'light' : 'dark'));

  return (
    <ActionIcon onClick={toggleColorScheme}>
      {colorScheme === 'dark' ? <IconSun /> : <IconMoonStars />}
    </ActionIcon>
  );
}

Remove value

Use removeValue callback to clean localStorage/sessionStorage. When value is removed it is reset to defaultValue:

import { useLocalStorage } from '@mantine/hooks';

const [value, setValue, removeValue] = useLocalStorage({
  key: 'color-scheme',
  defaultValue: 'light',
});

use-local-storage subscribes to storage event. When state changes in one tab, it automatically updates value in all other opened browser tabs. You can test this feature by opening 2 tabs with Mantine docs side by side and changing color scheme (button on the top right or ⌘ + J on MacOS and Ctrl + J on Windows and Linux).

Serialize/deserialize json

By default, hook will serialize/deserialize data with JSON.stringify/JSON.parse. If you need to store data in local storage that cannot be serialized with JSON.stringify – provide your own serialization handlers:

const [value, setValue] = useLocalStorage({
  key: 'color-scheme',
  serialize: (value) => {
    /* return value serialized to string */
  },
  deserialize: (localStorageValue) => {
    /* parse localStorage string value and return value */
  },
});

Usage with superjson

superjson is compatible with JSON.stringify/JSON.parse but works for Date, Map, Set and BigInt:

import superjson from 'superjson';

const [value, setValue] = useLocalStorage({
  key,
  defaultValue,
  serialize: superjson.stringify,
  deserialize: (str) => (str === undefined ? defaultValue : superjson.parse(str)),
});

use-session-storage

use-session-storage hook works the same way as use-local-storage hook but uses window.sessionStorage instead of window.localStorage:

import { useSessionStorage } from '@mantine/hooks';

const [value, setValue] = useSessionStorage({ key: 'session-key', defaultValue: 'mantine' });

TypeScript

Definition

interface UseLocalStorage<T> {
  /** Local storage key */
  key: string;

  /** Default value that will be set if value is not found in local storage */
  defaultValue?: T;

  /** If set to true, value will be update in useEffect after mount */
  getInitialValueInEffect: boolean;

  /** Function to serialize value into string to be saved in local storage */
  serialize?(value: T): string;

  /** Function to deserialize string value from local storage to value */
  deserialize?(value: string): T;
}

function useLocalStorage<T = string>({
  key,
  defaultValue,
  deserialize,
  serialize,
  getInitialValueInEffect,
}: UseLocalStorage<T>): readonly [
  T, // current value
  (val: T | ((prevState: T) => T)) => void, // callback to set value in storage
  () => void // callback to remove value from storage
];

Set value type

You can specify value type same as in useState hook:

const [value, setValue] = useLocalStorage<'dark' | 'light'>({
  key: 'color-scheme',
  defaultValue: 'light',
});

Go back

use-list-state – @mantine/hooks

Up next

use-pagination – @mantine/hooks

Build fully functional accessible web applications faster than ever

About

Contribute About Mantine Changelog Releases

Community

Chat on Discord Follow on Twitter Follow on Github GitHub discussions

Project

Mantine UI Documentation Github organization npm organization

Built by Vitaly Rtishchev and these awesome people

Join Discord community

Follow Mantine on Twitter