useLocalStorage()
Persist the state with local storage so that it remains after a page refresh. This can be useful for a dark theme.
This hook is used in the same way as useState except that you must pass the storage key in the 1st parameter.
If the window object is not present (as in SSR), useLocalStorage()
will return the default value.
Side notes:
- If you really want to create a dark theme switch, see useDarkMode().
- If you just want read value from local storage, see useReadLocalStorage().
Related hooks:
The Hook
1import {2 Dispatch,3 SetStateAction,4 useCallback,5 useEffect,6 useState,7} from 'react'89import { useEventCallback } from '../useEventCallback'10// See: https://usehooks-ts.com/react-hook/use-event-listener11import { useEventListener } from '../useEventListener'1213declare global {14 interface WindowEventMap {15 'local-storage': CustomEvent16 }17}1819type SetValue<T> = Dispatch<SetStateAction<T>>2021function useLocalStorage<T>(key: string, initialValue: T): [T, SetValue<T>] {22 // Get from local storage then23 // parse stored json or return initialValue24 const readValue = useCallback((): T => {25 // Prevent build error "window is undefined" but keep keep working26 if (typeof window === 'undefined') {27 return initialValue28 }2930 try {31 const item = window.localStorage.getItem(key)32 return item ? (parseJSON(item) as T) : initialValue33 } catch (error) {34 console.warn(`Error reading localStorage key “${key}”:`, error)35 return initialValue36 }37 }, [initialValue, key])3839 // State to store our value40 // Pass initial state function to useState so logic is only executed once41 const [storedValue, setStoredValue] = useState<T>(readValue)4243 // Return a wrapped version of useState's setter function that ...44 // ... persists the new value to localStorage.45 const setValue: SetValue<T> = useEventCallback(value => {46 // Prevent build error "window is undefined" but keeps working47 if (typeof window == 'undefined') {48 console.warn(49 `Tried setting localStorage key “${key}” even though environment is not a client`,50 )51 }5253 try {54 // Allow value to be a function so we have the same API as useState55 const newValue = value instanceof Function ? value(storedValue) : value5657 // Save to local storage58 window.localStorage.setItem(key, JSON.stringify(newValue))5960 // Save state61 setStoredValue(newValue)6263 // We dispatch a custom event so every useLocalStorage hook are notified64 window.dispatchEvent(new Event('local-storage'))65 } catch (error) {66 console.warn(`Error setting localStorage key “${key}”:`, error)67 }68 })6970 useEffect(() => {71 setStoredValue(readValue())72 // eslint-disable-next-line react-hooks/exhaustive-deps73 }, [])7475 const handleStorageChange = useCallback(76 (event: StorageEvent | CustomEvent) => {77 if ((event as StorageEvent)?.key && (event as StorageEvent).key !== key) {78 return79 }80 setStoredValue(readValue())81 },82 [key, readValue],83 )8485 // this only works for other documents, not the current one86 useEventListener('storage', handleStorageChange)8788 // this is a custom event, triggered in writeValueToLocalStorage89 // See: useLocalStorage()90 useEventListener('local-storage', handleStorageChange)9192 return [storedValue, setValue]93}9495export default useLocalStorage9697// A wrapper for "JSON.parse()"" to support "undefined" value98function parseJSON<T>(value: string | null): T | undefined {99 try {100 return value === 'undefined' ? undefined : JSON.parse(value ?? '')101 } catch {102 console.log('parsing error on', { value })103 return undefined104 }105}
Usage
1import React from 'react'23import { useLocalStorage } from 'usehooks-ts'45// Usage6export default function Component() {7 const [isDarkTheme, setDarkTheme] = useLocalStorage('darkTheme', true)89 const toggleTheme = () => {10 setDarkTheme(prevValue => !prevValue)11 }1213 return (14 <button onClick={toggleTheme}>15 {`The current theme is ${isDarkTheme ? `dark` : `light`}`}16 </button>17 )18}
See a way to make this page better?
Edit there »