useCookie

Features

• Avoid Layout Shifts: The state is known by both the client and the server.
• Built-in Validation: Validate with zod, valibot, arktype or with a simple function.
• Tab Sync: The cookie state is synced across multiple browser tabs.
• Component Sync: The cookie state is synced across all components.
• Fullstack: Includes server-side utilities for end-to-end type safety.

Installation

npm install @1hook/use-cookie

Quick Start

'use client'
export { ServerCookieProvider } from '@1hook/use-cookie'

import { headers } from 'next/headers'
import { ServerCookieProvider } from './cookie-provider'

export async function Providers(props: { children: ReactNode }) {
  return (
    <ServerCookieProvider value={(await headers()).get('cookie')}>
      {props.children}
    </ServerCookieProvider>
  )
}

import { z } from 'zod'
import { defineCookie } from '@1hook/use-cookie'

export const [useSidebarWidth] = defineCookie({
  name: 'sidebar-width',
  validate: z.number().default(200),
  expires: 365, // days from now
  sameSite: 'lax',
})

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

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

Validation

To ensure data integrity, cookies should be validated.

👉 Functional validation

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

defineCookie({
  name: 'search',
  validate: (value) => String(value ?? ''),
})

👉 Schema validation

For more complex cases you can use a schema to validate the cookie value. 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'

defineCookie({
  name: 'search',
  validate: z.string().default(''),
})

Outside of React

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

export const [useCookie, Cookie] = defineCookie({
  name: 'my-cookie',
  validate: z.string().optional(),
  expires: 7,
})

Using it still triggers a React re-render.

import { Cookie } from './cookie'

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

// Read
Cookie.get()

// Clear
Cookie.clear()

On the server

The Cookie utility can read cookies from the cookie header.

const cookieHeader = (await headers()).get('cookie')

const token = Cookies.get(cookieHeader)

API Reference

👉 defineCookies

function defineCookie(options: DefineCookieOptions): [useCookie, Cookie]

👉 ServerCookieProvider

You can skip this component when building Single Page Applications (SPA).

In SSR frameworks it should be rendered at the top of the component tree, and must be used within a server component.

function CookieProvider(props: Props): ReactNode

👉 useCookie

Manage cookie state like with useState.

function useCookie(): [state, setState]

👉 Cookie

Read and write the cookie outside of React.