useLocalStorage

state

Installation

npx usehooks-cli@latest add use-local-storage

Description

A React hook for managing localStorage with automatic JSON serialization/deserialization and React state synchronization.

Parameters

Name	Type	Default	Description
key	string	-	The localStorage key to use for storing the value
initialValue	T	-	The initial value to use if no value exists in localStorage

Return Type

[T, (value: SetValue<T>) => void]

Property	Type	Description
storedValue	T	The current value from localStorage or initial value
setValue	(value: SetValue<T>) => void	Function to update the value in both state and localStorage

Examples

Basic Usage

Storing and retrieving a simple value

const [name, setName] = useLocalStorage('user-name', 'Anonymous');

return (
  <div>
    <p>Hello, {name}!</p>
    <input
      value={name}
      onChange={(e) => setName(e.target.value)}
      placeholder="Enter your name"
    />
  </div>
);

Complex Object Storage

Storing and updating complex objects

interface UserSettings {
  theme: 'light' | 'dark';
  notifications: boolean;
}

const [settings, setSettings] = useLocalStorage<UserSettings>('user-settings', {
  theme: 'light',
  notifications: true
});

// Update using function
const toggleTheme = () => {
  setSettings(prev => ({
    ...prev,
    theme: prev.theme === 'light' ? 'dark' : 'light'
  }));
};

Dependencies

react

Notes

•Automatically handles JSON serialization and deserialization
•Gracefully handles localStorage errors (e.g., in private browsing mode)
•Supports functional updates like useState
•Initial value is used as fallback when localStorage is unavailable or parsing fails
•Works with any JSON-serializable data type

Implementation

'use client';

import { useState } from "react";

type SetValue<T> = T | ((val: T) => T);

export function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: SetValue<T>) => void] {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.log(error);
      return initialValue;
    }
  });

  const setValue = (value: SetValue<T>) => {
    try {
      const valueToStore =
        value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      window.localStorage.setItem(key, JSON.stringify(valueToStore));
    } catch (error) {
      console.log(error);
    }
  };

  return [storedValue, setValue];
}

useCounter

CLI Docs All Hooks

useSet