useStorage

Features

• Built-in Validation: Validate with zod, valibot, arktype or with a simple function.
• Tab Sync: The state is synced across multiple browser tabs when using the localStorage.
• Component Sync: The state is synced across all components.

Installation

npm install @1hook/use-storage

Quick Start

import { z } from 'zod'
import { defineStorage } from '@1hook/use-storage'

export const [useSidebarWidth] = defineStorage({
  key: 'sidebar-width',
  validate: z.number().default(200),
  type: 'local',
})

function Layout() {
  const [width, setWidth] = useSidebarWidth()

  return (
    <div>
      <Sidebar width={width} onResize={setWidth} />
      <main>...</main>
    </div>
  )
}

Validation

To ensure data integrity, the storage should be validated.

👉 Functional validation

For simple cases you can use a function to validate the storage.

defineStorage({
  key: 'search',
  validate: (value) => String(value ?? ''),
  type: 'local',
})

👉 Schema validation

For more complex cases you can use a schema to validate the storage. Compatible validation libraries include zod 3.24+, valibot 1.0+ or arktype 2.0+. Check out Standard Schema for more info.

import { z } from 'zod'

defineStorage({
  key: 'search',
  validate: z.string().default(''),
  type: 'local',
})

Outside of React

defineStorage returns a standalone utility object that provides methods to get, set or clear the value outside of React components.

export const [useStorage, Storage] = defineStorage({
  key: 'my-storage',
  validate: z.string().optional(),
  type: 'local',
})

Using it still triggers a React re-render.

import { Storage } from './storage'

// Write
Storage.set('new-value')

// Read
Storage.get()

// Clear
Storage.clear()

API Reference

👉 defineStorage

function defineStorage(options?: DefineStorageOptions): [useStorage, Storage]

👉 useStorage

Manage storage state like with useState.

function useStorage(): [state, setState]

👉 Storage

Read and write to the storage outside of React.