Build a useLocalStorage Hook in React

A useLocalStorage Hook keeps a piece of React state in sync with the browser's localStorage, so the value survives a page reload. It reads the stored value on first render and writes it back whenever state changes.

Use it for a theme, a saved form draft, or any preference the user expects to persist. When the value changes, the Hook writes it back so state and storage never drift.

The Hook in three parts

The Hook combines a lazy state read, a write Effect, and JSON conversion. localStorage stores only strings, so objects and numbers must be converted on the way in and out.

App.jsx

import { useEffect, useState } from "react";
 
function useLocalStorage(key, initialValue) {
  const [value, setValue] = useState(() => {
    const stored = localStorage.getItem(key);
    return stored !== null ? JSON.parse(stored) : initialValue;
  });
  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);
  return [value, setValue];
}

Passing a function to useState runs it only during the first render, so the Hook reads localStorage once instead of on every render. getItem returns null when the key is missing, and the Hook falls back to the initial value.

The Effect runs after every committed render where value or key changed, writing the latest value back. It needs no cleanup because setItem does not create a subscription.

Use the Hook for a theme toggle

App.jsx

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage("theme", "light");
  function toggleTheme() {
    setTheme(theme === "light" ? "dark" : "light");
  }
  return <button onClick={toggleTheme}>Theme: {theme}</button>;
}

On the first visit the key is missing, so the Hook starts with light. Clicking the button stores dark, and after a reload the Hook reads dark again instead of resetting.

Handle errors and server rendering

JSON.parse throws when the stored value is malformed, and localStorage does not exist during server rendering. The version above crashes in both cases, so add two guards.

App.jsx

const [value, setValue] = useState(() => {
  if (typeof window === "undefined") {
    return initialValue;
  }
  try {
    const stored = localStorage.getItem(key);
    return stored !== null ? JSON.parse(stored) : initialValue;
  } catch {
    return initialValue;
  }
});

The window check keeps the first render safe on the server, before returning the initial value instead of touching localStorage. The try and catch block falls back to the initial value when a stored entry is not valid JSON, so one corrupted key cannot crash the component during render.

The server check matters most in a framework that renders React on the server, such as Next.js. A component using this Hook can render there without throwing, then pick up the real stored value once the Effect runs in the browser after hydration.

What localStorage can and cannot do

• Values persist across page reloads and browser restarts.
• Data is scoped to one origin, and private mode clears it.
• It is synchronous and suits small values, not large files.
• Writes do not notify other tabs unless you listen for the storage event.

For the extraction steps, see how to create a custom Hook, and for the timing rules see when you actually need useEffect.