React useSessionStorage Hook

Ever tried to manage sessionStorage in React and ended up with JSON.stringify chaos, serialization error nightmares, or broken state synchronization? You know the drill—manually calling sessionStorage.setItem(), forgetting to handle JSON parsing errors, dealing with cross-component state sync, missing cleanup on component unmount. This free open source React useSessionStorage custom hook handles all that session storage complexity so you can focus on building stateful features instead of debugging storage edge cases in your React applications.

useSessionStorage showcase

Smart session storage with automatic serialization and state synchronization:

"use client";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useSessionStorage } from '@/components/ui/shadcn-io/use-session-storage';interface UserPrefs {  theme: 'light' | 'dark';  count: number;}export default function UseSessionStorageDemo() {  const [count, setCount, removeCount] = useSessionStorage('demo-count', 0);  const [prefs, setPrefs, removePrefs] = useSessionStorage<UserPrefs>('user-prefs', {    theme: 'light',    count: 0  });  const handleIncrement = () => {    setCount(x => x + 1);    setPrefs(p => ({ ...p, count: p.count + 1 }));    toast.success("Counter increased! 📈", {      description: "Value saved to session storage",    });  };  const handleDecrement = () => {    setCount(x => x - 1);    setPrefs(p => ({ ...p, count: p.count - 1 }));    toast.success("Counter decreased! 📉", {      description: "Value saved to session storage",    });  };  const handleToggleTheme = () => {    const newTheme = prefs.theme === 'light' ? 'dark' : 'light';    setPrefs(p => ({ ...p, theme: newTheme }));    toast.success(`Theme changed to ${newTheme}! 🎨`, {      description: "Preference saved to session storage",    });  };  const handleReset = () => {    removeCount();    removePrefs();    toast.success("Session data cleared! 🗑️", {      description: "All values reset to defaults",    });  };  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Session Storage Demo</h3>        <p className="text-sm text-muted-foreground">Temporary state across page reloads</p>      </div>            {/* Current Values */}      <div className="space-y-2">        <Label className="text-sm font-medium">Stored Values</Label>        <div className="bg-muted rounded p-2 min-h-[50px] flex items-center justify-center">          <div className="flex items-center gap-4">            <div className="text-center">              <div className="text-xl font-bold text-primary">{count}</div>              <Label className="text-xs text-muted-foreground">Counter</Label>            </div>            <div className="text-center">              <div className="text-sm font-mono">{prefs.theme}</div>              <Label className="text-xs text-muted-foreground">Theme</Label>            </div>          </div>        </div>      </div>      {/* Actions */}      <div className="space-y-2">        <Label className="text-sm font-medium">Actions</Label>        <div className="grid grid-cols-3 gap-2 h-10">          <Button            onClick={handleDecrement}            variant="outline"            size="sm"            className="h-10 text-xs"          >            Count -          </Button>          <Button            onClick={handleIncrement}            variant="default"            size="sm"            className="h-10 text-xs"          >            Count +          </Button>          <Button            onClick={handleToggleTheme}            variant="outline"            size="sm"            className="h-10 text-xs"          >            {prefs.theme === 'light' ? '🌙' : '☀️'}          </Button>        </div>      </div>      {/* Clear Action */}      <div className="space-y-2">        <Label className="text-sm font-medium">Reset</Label>        <div className="min-h-[40px] flex items-center">          <Button            onClick={handleReset}            variant="destructive"            size="sm"            className="w-full h-10"          >            Clear Session Data          </Button>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Refresh the page - values persist in this tab only!        </div>      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

This free open source React hook simplifies temporary state persistence with TypeScript support for modern JavaScript applications. Whether you're building form persistence, shopping carts, or user preferences in your Next.js projects, this React hook keeps your session data reliable and reactive.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-session-storage.json

npx shadcn@latest add https://www.shadcn.io/registry/use-session-storage.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-session-storage.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-session-storage.json

Why most sessionStorage implementations suck

Look, you could keep manually managing sessionStorage.setItem() and JSON parsing. But then you hit the session storage complexity—serialization errors breaking your app, stale data when other components update storage, SSR hydration mismatches, performance issues from repeated parsing in React applications.

Most developers manually call sessionStorage.setItem() with JSON.stringify() without proper error handling, causing app crashes when serialization fails in TypeScript components. Or they forget about cross-component synchronization and wonder why updating storage in one component doesn't reflect in others. Some skip SSR considerations entirely and get hydration mismatches when session data differs between server and client in Next.js projects.

This React hook uses optimized storage management under the hood, with automatic serialization and cross-component synchronization in JavaScript applications. The browser handles all the storage events, plus you get comprehensive error handling and type safety in one call.

Plus it handles all the edge cases—SSR compatibility with proper hydration, automatic JSON serialization with fallbacks, cross-component state sync, proper cleanup on unmount in React development. No more broken form data or inconsistent state management.

This free open source React hook manages session state while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable session storage keeps your JavaScript development smooth.

Features

• Session persistence maintaining state across page reloads within the same browser tab in React applications
• Type-safe storage with full TypeScript support for complex objects and primitives in TypeScript components
• Custom serialization allowing custom serializer and deserializer functions for complex types in Next.js projects
• Cross-component sync updating state when sessionStorage changes in other components in JavaScript development
• SSR compatibility with proper server-side rendering support and initialization options for React frameworks
• Error handling with graceful fallbacks and console warnings for debugging in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every temporary data need in React applications. React useState handles most component state perfectly. But when you need state persistence across page refreshes within a browser session, this React hook delivers in Next.js projects.

Perfect for:

• Form draft saving - Preserve form inputs during page reloads and navigation built with TypeScript
• Shopping cart sessions - Maintain cart items during the browsing session using React patterns
• Multi-step wizards - Save progress through complex form workflows in JavaScript applications
• User preferences - Store temporary UI settings and theme choices in React components
• Search filters - Remember applied filters and sorting across page loads in Next.js applications
• Draft content - Preserve unsaved articles, comments, or message drafts using TypeScript safety

API Reference

useSessionStorage

useSessionStorage<T>(
  key: string,
  initialValue: T | (() => T),
  options?: UseSessionStorageOptions<T>
): [T, Dispatch<SetStateAction<T>>, () => void]

UseSessionStorageOptions

Return Value

Returns a tuple with three elements:

Common gotchas

SessionStorage is tab-specific: Data stored in one browser tab won't be available in other tabs, even for the same website in React applications. This is different from localStorage which is shared across tabs. The isolation is actually a feature for temporary session data.

Serialization errors are handled gracefully: If JSON.stringify fails during storage or JSON.parse fails during retrieval, the React hook logs the error and uses fallback values in TypeScript components. Complex objects with circular references may need custom serializers.

Cross-component synchronization is automatic: When one component updates a storage key, all other components using the same key will re-render with the new value instantly in Next.js projects. This happens through custom events, not storage events.

SSR requires careful initialization: Use initializeWithValue: false to prevent hydration mismatches in JavaScript applications. The React hook will return your initial value during SSR and update with stored data after hydration.

Storage size limitations: SessionStorage has size limits (usually 5-10MB) in React frameworks. The hook handles quota exceeded errors gracefully but won't prevent them.

Tab closure clears data: All sessionStorage data is permanently lost when the user closes the tab in TypeScript projects. Consider this behavior when designing user flows that depend on session persistence.

Related hooks you will also like

Questions you might have