use-cookie

Parse a Cookie request header (or document.cookie) into name/value pairs.

Usage

import { COOKIE_ADAPTER_KEY, parseCookieHeader, provideCookieAdapter, serializeCookie, useCookie } from "@vizejs/composable/use-cookie";

Runtime contract

API

parseCookieHeader

Parse a Cookie request header (or document.cookie) into name/value pairs. Values are percent-decoded; the first occurrence of a name wins, matching how browsers order more specific cookies first. Pure and SSR-safe.

function parseCookieHeader(header: string): Record<string, string>

serializeCookie

Serialize one cookie as a Set-Cookie header value (also accepted by document.cookie). The value is percent-encoded so any string is safe.

function serializeCookie( name: string, value: string, attributes: CookieAttributes = {}, ): string

COOKIE_ADAPTER_KEY

Injection key for an app- or subtree-wide CookieAdapter.

const COOKIE_ADAPTER_KEY: InjectionKey<CookieAdapter>

provideCookieAdapter

Provide a CookieAdapter to descendant components (for example the request/response pair of a server render). Must be called during setup; use app.provide(COOKIE_ADAPTER_KEY, adapter) for a whole app.

function provideCookieAdapter(adapter: CookieAdapter): void

useCookie

Read and write one cookie with a typed default.

function useCookie<Value>( name: string, options: UseCookieOptions<Value> & { readonly default: Value }, ): CookieControls<Value>

useCookie

Read and write one raw string cookie; absent cookies are undefined.

function useCookie( name: string, options?: UseCookieOptions<string>, ): CookieControls<string | undefined>

useCookie

Synchronize a typed reactive value with one cookie, on the server and in the browser. The adapter is resolved from options.adapter, then from COOKIE_ADAPTER_KEY (see provideCookieAdapter), then from document.cookie in browsers. During a server render with an adapter the value comes from the request Cookie header and assignments emit Set-Cookie headers through adapter.write, so server and client render the same value and hydrate without a mismatch. Without any adapter (plain SSR) the default is used and nothing is written. String defaults are stored raw; other defaults as JSON checked by validate (by default: same kind as the default). Assigning undefined (or calling remove) expires the cookie. Cookies are written with Path=/ unless path is given. Failures never throw; they are exposed through error and onError. The write watcher stops with the owning reactive scope.

function useCookie<Value>( name: string, options: UseCookieOptions<Value> = {}, ): CookieControls<Value | undefined>

// server entry: app.provide(COOKIE_ADAPTER_KEY, { read: () => req.headers.cookie ?? "",
//   write: (value) => res.appendHeader("Set-Cookie", value) });
const { state: locale } = useCookie("locale", { default: "en", maxAge: 31_536_000 });

Types

CookieAttributes

Attributes written with a cookie (RFC 6265bis).

CookieAdapter

Request/response bridge used by useCookie. On the server, read returns the incoming Cookie header and write appends a Set-Cookie header to the response. In the browser the default adapter reads and writes document.cookie.

CookieSerializer

Converts a cookie value to and from its string form.

CookieFailure

Failure observed while synchronizing a cookie.

UseCookieOptions

Options for useCookie.

CookieControls

Reactive state and controls returned by useCookie.