Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

useCookie gives you a unified reactive API for cookies that works identically during SSR and in the browser. On the server it reads from the incoming Cookie request header; on the client it reads document.cookie and installs a watcher that writes back to document.cookie whenever the ref value changes. The result is a single ref you can bind to form controls or update programmatically without thinking about the environment.

​
useCookie

​
Signature

useCookie(name: string, options?: CookieOptions): Ref<string | undefined>
​
name
string
required
The cookie name. Used as-is to match against the Cookie header on the server and against document.cookie on the client.
​
options
CookieOptions
Optional attributes applied when writing the cookie on the client. See CookieOptions below.
The returned Ref<string | undefined> is:
  • undefined when the cookie is absent.
  • string with the decoded cookie value when present.
Assigning undefined to the ref removes the cookie by setting Max-Age=-1.

​
Example — persisting a theme preference

<script setup lang="ts">
const theme = useCookie('theme', { maxAge: 60 * 60 * 24 * 365 })
</script>

<template>
  <select v-model="theme">
    <option value="light">Light</option>
    <option value="dark">Dark</option>
  </select>
</template>
Selecting an option updates theme.value, which the watcher immediately serializes into document.cookie. On the next page load the server reads the Cookie header and useCookie initializes with the persisted value. 
<script setup lang="ts">
const session = useCookie('session')

function setSession() {
  session.value = `sess-${Math.random().toString(36).slice(2, 8)}`
}

function clearSession() {
  session.value = undefined // removes the cookie
}
</script>

<template>
  <p>Session: {{ session ?? 'not set' }}</p>
  <button @click="setSession">Set session cookie</button>
  <button @click="clearSession">Clear session cookie</button>
</template>

​
CookieOptions

All seven fields are optional. They are appended to the Set-Cookie string in the order: Max-Age, Expires, Path, Domain, SameSite, Secure, HttpOnly.
​
maxAge
number
Number of seconds until the cookie expires. Takes precedence over expires in most browsers. Setting this to a negative number removes the cookie.
​
expires
Date
Exact Date at which the cookie expires. Use maxAge when you want a relative TTL; use expires when you need a fixed timestamp.
​
httpOnly
boolean
When true, the cookie is flagged HttpOnly — it is sent with requests but is not accessible via JavaScript (document.cookie). Only meaningful for cookies set by server-side code.
​
secure
boolean
When true, the cookie is only sent over HTTPS connections.
​
sameSite
'strict' | 'lax' | 'none'
Controls when the cookie is sent with cross-site requests.
  • 'strict' — only sent on same-site requests.
  • 'lax' — sent on same-site requests and top-level navigations.
  • 'none' — sent on all requests; requires secure: true.
​
domain
string
Restricts the cookie to the specified domain and its subdomains (e.g. 'example.com').
​
path
string
Restricts the cookie to the specified path prefix (e.g. '/' for the whole site or '/app' for a sub-path). Defaults to the current path in browsers when omitted.

​
SSR behavior

1

Server reads the request header

When useCookie is called during SSR, Nuxe reads the Cookie header from the incoming HTTP request and parses the named cookie using parseCookieValue. The ref is initialized with that value (or undefined if the cookie is absent).
2

Component renders with the correct value

Because the ref is populated before the template renders, the initial HTML reflects the real cookie value — no flash of incorrect content.
3

Client hydration and reactivity

On the client, useCookie reads document.cookie directly and installs a watch. Any assignment to cookie.value is serialized with serializeCookie and written to document.cookie immediately.

​
Low-level helpers

These functions are exported for cases where you need to work with cookie strings directly — for example, in server middleware or custom response handlers.

​
parseCookieValue

Parses a single named cookie out of a raw Cookie header string. 
parseCookieValue(cookieHeader: string, name: string): string | undefined

const cookieHeader = 'theme=dark; session=abc123'
const theme = parseCookieValue(cookieHeader, 'theme') // 'dark'
const missing = parseCookieValue(cookieHeader, 'other') // undefined
The value is URL-decoded before it is returned. If the cookie name is not found, undefined is returned.

​
serializeCookie

Serializes a cookie name, value, and options into a Set-Cookie header string. 
serializeCookie(name: string, value: string, options?: CookieOptions): string

const header = serializeCookie('theme', 'dark', {
  maxAge: 31_536_000,
  path: '/',
  sameSite: 'lax',
})
// 'theme=dark; Max-Age=31536000; Path=/; SameSite=lax'
Both the name and value are URL-encoded via encodeURIComponent. Options are appended in the order: Max-Age, Expires, Path, Domain, SameSite, Secure, HttpOnly.
Cookies marked httpOnly are set by server-side handlers (e.g. Set-Cookie response headers from your API routes) and are intentionally invisible to document.cookie. Because useCookie reads document.cookie on the client, it will always see undefined for httpOnly cookies — this is expected browser security behavior, not a Nuxe limitation. Use useCookie for client-accessible cookies and manage httpOnly session tokens entirely within your server routes.

Build docs developers (and LLMs) love

Get started for freeTalk to us