use-local-storage-value

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

Usage

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

import { useLocalStorageValue } 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] = useLocalStorageValue({ 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 { useLocalStorageValue } from '@mantine/hooks';
import { ActionIcon } from '@mantine/core';
import { SunIcon, MoonIcon } from '@modulz/radix-icons';
function ColorSchemeToggle() {
const [colorScheme, setColorScheme] = useLocalStorageValue({
key: 'color-scheme',
defaultValue: 'light',
});
const toggleColorScheme = () =>
setColorScheme((current) => (current === 'dark' ? 'light' : 'dark'));
return (
<ActionIcon onClick={toggleColorScheme}>
{colorScheme === 'dark' ? <SunIcon /> : <MoonIcon />}
</ActionIcon>
);
}

Browser tabs synchronization

use-local-storage-value 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 mac and Ctrl + J on Windows and Linux).

TypeScript

Definition

function useLocalStorageValue<T extends string>(options: {
key: string;
defaultValue?: T;
}): [T, (val: T | ((prevState: T) => T)) => void];

Set value type

You can specify value type same as in useState hook, type must extend string:

type ColorScheme = 'dark' | 'light';
const [value, setValue] = useLocalStorageValue<ColorScheme>({
key: 'color-scheme',
defaultValue: 'light',
});
Build fully functional accessible web applications faster than ever
Feedback
Your feedback is most valuable contribution to the project, please share how you use Mantine, what features are missing and what is done good
Leave feedback