use-local-storage
Use localStorage value as react state, sync state across opened tabs
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 "@bigcomponents/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"));Remove value
Use removeValue callback to clean localStorage/sessionStorage. When value is removed it is reset to defaultValue:
import { useLocalStorage } from "@bigcomponents/hooks";
const [value, setValue, removeValue] = useLocalStorage({
key: "color-scheme",
defaultValue: "light",
});Browser tabs synchronization
use-local-storage subscribes to storage event. When state changes in one tab, it automatically updates value in all other opened browser tabs.
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 "@bigcomponents/hooks";
const [value, setValue] = useSessionStorage({
key: "session-key",
defaultValue: "hello-world",
});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 updated in useEffect after mount */
getInitialValueInEffect: boolean;
/** Function to serialize value into a 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",
});