Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 | 86x 106x 106x 106x 106x 106x 106x 106x 106x 106x 106x 106x 106x 62x 62x 62x 61x 6x 5x 61x 62x 62x 62x 61x 106x 370x 370x 370x 370x 284x 86x 36x 50x 76x 76x 10x 10x 10x 10x 106x 106x 106x 34x 34x 34x 34x 34x 11x 23x 34x 34x 34x 34x 34x 34x 1x 106x 3x 3x 3x 3x 3x 3x 106x | import { useCallback, useRef, useSyncExternalStore } from "react";
import { subscribe, notifyListeners } from "./store";
/**
* Type for initial value that can be a value or a function returning a value (lazy initialization)
*/
export type InitialValue<T> = T | (() => T);
/**
* Options for useLocalStorage hook
*/
export interface UseLocalStorageOptions<T> {
/**
* Custom serializer function for converting value to string
* @default JSON.stringify
*/
serializer?: (value: T) => string;
/**
* Custom deserializer function for parsing stored string to value
* @default JSON.parse
*/
deserializer?: (value: string) => T;
/**
* Whether to sync value across browser tabs via storage event
* @default true
*/
syncTabs?: boolean;
/**
* Callback function called when an error occurs
*/
onError?: (error: Error) => void;
}
/**
* Return type for useLocalStorage hook - tuple similar to useState
*/
export type UseLocalStorageReturn<T> = readonly [
/** Current stored value */
T,
/** Function to update the value (same signature as useState setter) */
React.Dispatch<React.SetStateAction<T>>,
/** Function to remove the value from localStorage */
() => void
];
/**
* Helper function to resolve initial value (supports lazy initialization)
*/
function resolveInitialValue<T>(initialValue: InitialValue<T>): T {
return typeof initialValue === "function"
? (initialValue as () => T)()
: initialValue;
}
/**
* A hook for persisting state in localStorage with automatic synchronization.
* Works like useState but persists the value in localStorage.
*
* Features:
* - Same-tab synchronization: Multiple components using the same key will stay in sync
* - Cross-tab synchronization: Changes in other tabs are automatically reflected
* - SSR compatible: Works with Next.js, Remix, and other SSR frameworks
*
* @template T - The type of the stored value
* @param key - The localStorage key to store the value under
* @param initialValue - Initial value or function returning initial value (lazy initialization)
* @param options - Configuration options for serialization, sync, and error handling
* @returns A tuple of [storedValue, setValue, removeValue]
*
* @example
* ```tsx
* // Basic usage with string
* function ThemeToggle() {
* const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');
*
* return (
* <div>
* <p>Current theme: {theme}</p>
* <button onClick={() => setTheme('dark')}>Dark</button>
* <button onClick={() => setTheme('light')}>Light</button>
* <button onClick={removeTheme}>Reset</button>
* </div>
* );
* }
* ```
*
* @example
* ```tsx
* // Same-tab synchronization - both components stay in sync
* function ComponentA() {
* const [user, setUser] = useLocalStorage('user', null);
* return <button onClick={() => setUser({ name: 'John' })}>Set User</button>;
* }
*
* function ComponentB() {
* const [user] = useLocalStorage('user', null);
* // Automatically updates when ComponentA calls setUser!
* return <p>User: {user?.name}</p>;
* }
* ```
*
* @example
* ```tsx
* // With object type
* interface UserSettings {
* notifications: boolean;
* language: string;
* }
*
* const [settings, setSettings] = useLocalStorage<UserSettings>('settings', {
* notifications: true,
* language: 'en',
* });
*
* // Functional update
* setSettings(prev => ({ ...prev, notifications: false }));
* ```
*
* @example
* ```tsx
* // With lazy initialization
* const [config, setConfig] = useLocalStorage('config', () => computeExpensiveDefault());
* ```
*
* @example
* ```tsx
* // With custom serializer/deserializer
* const [date, setDate] = useLocalStorage<Date>('lastVisit', new Date(), {
* serializer: (d) => d.toISOString(),
* deserializer: (s) => new Date(s),
* });
* ```
*
* @example
* ```tsx
* // With error handling
* const [value, setValue] = useLocalStorage('key', 'default', {
* onError: (error) => console.error('Storage error:', error),
* });
* ```
*/
export function useLocalStorage<T>(
key: string,
initialValue: InitialValue<T>,
options: UseLocalStorageOptions<T> = {}
): UseLocalStorageReturn<T> {
const {
serializer = JSON.stringify,
deserializer = JSON.parse,
syncTabs = true,
onError,
} = options;
// Store options in refs for stable references and access to latest values
const serializerRef = useRef(serializer);
const deserializerRef = useRef(deserializer);
const onErrorRef = useRef(onError);
const initialValueRef = useRef(initialValue);
serializerRef.current = serializer;
deserializerRef.current = deserializer;
onErrorRef.current = onError;
initialValueRef.current = initialValue;
// Cache for getSnapshot to ensure stable returns and prevent infinite loops
// useSyncExternalStore requires getSnapshot to return the same reference
// if the data hasn't changed
const cacheRef = useRef<{ rawValue: string | null; parsedValue: T } | null>(
null
);
// SSR check
const isClient = typeof window !== "undefined";
// Subscribe function for useSyncExternalStore
// Handles both same-tab and cross-tab synchronization
const subscribeToStore = useCallback(
(onStoreChange: () => void) => {
// Subscribe to same-tab changes via internal store
const unsubscribeStore = subscribe(key, onStoreChange);
// Subscribe to cross-tab changes via storage event
let handleStorageEvent: ((event: StorageEvent) => void) | null = null;
if (isClient && syncTabs) {
handleStorageEvent = (event: StorageEvent) => {
if (event.key === key) {
onStoreChange();
}
};
window.addEventListener("storage", handleStorageEvent);
}
// Cleanup function
return () => {
unsubscribeStore();
if (handleStorageEvent) {
window.removeEventListener("storage", handleStorageEvent);
}
};
},
[key, syncTabs, isClient]
);
// getSnapshot: Read current value from localStorage with caching
const getSnapshot = useCallback((): T => {
Iif (!isClient) {
return resolveInitialValue(initialValueRef.current);
}
try {
const rawValue = window.localStorage.getItem(key);
// Check cache: if rawValue is the same, return cached parsed value
if (cacheRef.current && cacheRef.current.rawValue === rawValue) {
return cacheRef.current.parsedValue;
}
// Parse new value
let parsedValue: T;
if (rawValue !== null) {
parsedValue = deserializerRef.current(rawValue);
} else {
parsedValue = resolveInitialValue(initialValueRef.current);
}
// Update cache
cacheRef.current = { rawValue, parsedValue };
return parsedValue;
} catch (error) {
onErrorRef.current?.(error as Error);
const fallbackValue = resolveInitialValue(initialValueRef.current);
cacheRef.current = { rawValue: null, parsedValue: fallbackValue };
return fallbackValue;
}
}, [key, isClient]);
// getServerSnapshot: Return initial value for SSR
const getServerSnapshot = useCallback((): T => {
return resolveInitialValue(initialValueRef.current);
}, []);
// Use useSyncExternalStore for synchronized state
const storedValue = useSyncExternalStore(
subscribeToStore,
getSnapshot,
getServerSnapshot
);
// setValue - stable reference that updates localStorage and notifies listeners
const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(
(value) => {
try {
// Get current value for functional updates
const currentValue = (() => {
try {
const item = window.localStorage.getItem(key);
if (item !== null) {
return deserializerRef.current(item);
}
return resolveInitialValue(initialValueRef.current);
} catch {
return resolveInitialValue(initialValueRef.current);
}
})();
const valueToStore =
value instanceof Function ? value(currentValue) : value;
Eif (typeof window !== "undefined") {
const serialized = serializerRef.current(valueToStore);
window.localStorage.setItem(key, serialized);
// Invalidate cache so next getSnapshot reads fresh value
cacheRef.current = {
rawValue: serialized,
parsedValue: valueToStore,
};
// Notify all same-tab listeners
notifyListeners(key);
}
} catch (error) {
onErrorRef.current?.(error as Error);
}
},
[key]
);
// removeValue - stable reference
const removeValue = useCallback(() => {
try {
Eif (typeof window !== "undefined") {
window.localStorage.removeItem(key);
// Invalidate cache
const initialVal = resolveInitialValue(initialValueRef.current);
cacheRef.current = { rawValue: null, parsedValue: initialVal };
// Notify all same-tab listeners
notifyListeners(key);
}
} catch (error) {
onErrorRef.current?.(error as Error);
}
}, [key]);
return [storedValue, setValue, removeValue] as const;
}
|