Docs
useCookieStorage

Store, retrieve, and synchronize data from the browser's Cookie Store API with useCookieStorage.

Cookie Store API
Loading...

Installation

pnpm dlx shadcn@latest add https://usekit.kiron.dev/k/use-cookie-storage

Usage

"use client"
 
import { useCookieStorage } from "@/hooks/use-cookie-storage"
 
interface UserPreferences {
  theme: "light" | "dark"
  fontSize: number
}
 
export function Component() {
  const [username, setUsername] = useCookieStorage("username", "guest", {
    path: "/",
    expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
    sameSite: "Lax",
  })
 
  const [preferences, setPreferences] = useCookieStorage<UserPreferences>(
    "preferences",
    { theme: "light", fontSize: 16 },
    { path: "/", secure: true }
  )
 
  return (
    <div>
      <div>
        <h2>Username</h2>
        <input value={username} onChange={(e) => setUsername(e.target.value)} />
      </div>
 
      <div>
        <h2>Preferences</h2>
        <select
          value={preferences.theme}
          onChange={(e) =>
            setPreferences((prev) => ({
              ...prev,
              theme: e.target.value as "light" | "dark",
            }))
          }
        >
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </select>
 
        <input
          type="number"
          value={preferences.fontSize}
          onChange={(e) =>
            setPreferences((prev) => ({
              ...prev,
              fontSize: Number(e.target.value),
            }))
          }
        />
      </div>
    </div>
  )
}

Example Usage

Storing a Primitive Value (e.g., a counter)

export function CounterExample() {
  const [counter, setCounter] = useCookieStorage("counter", 0, {
    path: "/",
    expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // Expires in 7 days
  })
 
  return (
    <div>
      <p>Counter: {counter}</p>
      <button onClick={() => setCounter((c) => c + 1)}>Increment</button>
    </div>
  )
}

Storing an Object (e.g., user preferences)

interface UserPreferences {
  theme: "light" | "dark"
  fontSize: number
}
 
export function PreferencesExample() {
  const [preferences, setPreferences] = useCookieStorage<UserPreferences>(
    "preferences",
    { theme: "light", fontSize: 16 }
  )
 
  return (
    <div>
      <label>
        Theme:
        <select
          value={preferences.theme}
          onChange={(e) =>
            setPreferences((prev) => ({
              ...prev,
              theme: e.target.value as "light" | "dark",
            }))
          }
        >
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </select>
      </label>
 
      <label>
        Font Size:
        <input
          type="number"
          value={preferences.fontSize}
          onChange={(e) =>
            setPreferences((prev) => ({
              ...prev,
              fontSize: Number(e.target.value),
            }))
          }
        />
      </label>
    </div>
  )
}

API Reference

Parameters

NameTypeDescriptionDefault ValueOptional
keystringThe key used to access the cookie value.-No
initialValueTThe initial value to use if no cookie exists with the provided key.-No
optionsobjectConfiguration options for the cookie.{}Yes

CookieOptions Interface

PropertyTypeDescription
expires?Date(Optional) The expiration date of the cookie.
path?string(Optional) The path where the cookie is accessible. Defaults to /.
domain?string(Optional) The domain where the cookie is accessible.
secure?boolean(Optional) If true, the cookie is only sent over HTTPS.
sameSite?"strict" | "lax" | "none"(Optional) Controls whether the cookie is sent with cross-site requests.

Return Values

NameTypeDescription
cookieStateTThe current value stored in the cookie.
setCookie(value: T | ((prev: T) => T)) => voidA function to update the cookie value. Accepts either a new value or a function that returns a new value.
useControlledStateuseCopyToClipboard