use-local-storage (use-local-storage)

Manages local storage with declarative methods.

v0.1.0

Usage

import { use-local-storage } from "@/hooks"

"use client";

import React from "react";

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

import { useLocalStorage } from "@/components/hooks/use-local-storage";

export function UseLocalStorageDemo() {
  // Example with a string
  const [name, setName] = useLocalStorage<string>("demo-name", "");

  return (
    <Card className="relative max-w-sm w-full">
      <CardHeader>
        <CardTitle>useLocalStorage</CardTitle>
        <CardDescription>
          This component uses the <code>useLocalStorage</code> hook to manage a
          local storage item.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-6">
        <div className="flex flex-col gap-2">
          <Label htmlFor="name">Name</Label>
          <Input
            id="name"
            value={name}
            onChange={(e) => setName(e.target.value)}
            placeholder="Enter your name"
          />
        </div>
        <div className="flex items-end gap-2">
          <p>Name:</p>
          <pre className="text-sm text-muted-foreground bg-accent w-fit px-1 py-0.5 rounded-xs">
            {name}
          </pre>
        </div>
      </CardContent>
      <CardFooter>
        <p className="text-muted-foreground text-sm">
          Looks in the local storage for the key <code>demo-name</code>.
        </p>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-local-storage

Options

Name	Type	Default	Description
key	string	-	The key to store the value in local storage
initialValue	string	-	The initial value to store in local storage
options?	UseLocalStorageOptions	-	The options for the hook

Cross-Tab Synchronization

The hook listens for storage events and updates the state if the value changes in another tab or window.

Serialization & Deserialization

By default, values are serialized with JSON.stringify and deserialized with JSON.parse .
You can provide custom serialize and deserialize functions for non-JSON data or advanced use cases.

Error Handling

If reading or writing to localStorage fails (e.g., quota exceeded, invalid JSON), the hook logs a warning and falls back to the initial value.

SSR & Initial Value

On the server, the hook always returns the initial value.
The initial value is only used if there is no value in localStorage for the given key.

Best Practices & Caveats

The hook is client-side only; on the server, it does not interact with localStorage.
Avoid storing sensitive data in localStorage.
Changing the key will re-read and update the value from localStorage.
For best performance, avoid creating new serialize / deserialize functions on every render (use useCallback or useMemo if needed).

Files in this hook

Source	Destination
files/use-local-storage.ts	src/hooks/use-local-storage.ts