use-cookie

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

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Remember a theme in a cookie

Store a small preference in a cookie that the server can read on the next request.

Open the interactive example

What to observe: Use dark theme writes the cookie and shows Saved theme: dark. Forget preference removes it.

String cookies are stored as written; other defaults are stored as JSON. Pass path, sameSite, maxAge and other attributes as options.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useCookie } from "@vizejs/composable/use-cookie";

const { state: theme, remove } = useCookie("docs-example-theme", { path: "/", sameSite: "lax" });
</script>

<template>
  <div class="composable-example">
    <p>Remember a preference in a cookie so the server can read it on the next request.</p>
    <div class="example-actions">
      <button type="button" @click="() => (theme = 'light')">Use light theme</button>
      <button type="button" @click="() => (theme = 'dark')">Use dark theme</button>
      <button type="button" @click="() => remove()">Forget preference</button>
    </div>
    <output aria-live="polite">{{ theme ? `Saved theme: ${theme}` : "No saved theme." }}</output>
  </div>
</template>

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.