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 provides a unified, isomorphic API for reading and writing browser cookies. On the server it parses the incoming Cookie request header; on the client it reads from document.cookie. Setting the returned Ref’s .value on the client automatically serializes and writes the cookie back to document.cookie using the options you supplied.
useCookie returns a reactive Ref. Assigning undefined to its .value removes the cookie by setting Max-Age=-1. Any other assignment serializes the new value and writes it to document.cookie.

​
Signature

useCookie(name: string, options?: CookieOptions): Ref<string | undefined>

​
Parameters

​
name
string
required
The name of the cookie to read and write.
​
options
CookieOptions
Standard cookie attributes applied when writing the cookie on the client.
​
options.maxAge
number
Maximum cookie lifetime in seconds (sets Max-Age). Use 0 or a negative value to delete the cookie immediately.
​
options.expires
Date
Absolute expiry date (sets Expires). maxAge takes precedence if both are supplied.
​
options.httpOnly
boolean
Marks the cookie as HttpOnly, preventing client-side JavaScript from reading it. Setting this to true via useCookie on the client has no practical effect because JavaScript cannot set HttpOnly cookies — it must be set by the server in a Set-Cookie response header.
​
options.secure
boolean
Marks the cookie as Secure, restricting it to HTTPS connections.
​
options.sameSite
'strict' | 'lax' | 'none'
Controls cross-site request behavior. 'lax' is the browser default for most cookies. Use 'none' with secure: true for third-party cookie contexts.
​
options.domain
string
The domain scope of the cookie. Defaults to the current host without a leading dot, meaning subdomains are excluded unless you set this explicitly.
​
options.path
string
The URL path scope of the cookie. Defaults to / when omitted from the Set-Cookie header, but serializeCookie does not add a Path automatically unless you supply one.

​
Return Values

​
(return value)
Ref<string | undefined>
A reactive Ref whose value is the decoded cookie string, or undefined if the cookie does not exist. Assigning a new string to .value writes the cookie; assigning undefined deletes it by setting Max-Age=-1.

​
Utility Functions

​
parseCookieValue

Parses a single named cookie from a raw Cookie header string. 
parseCookieValue(cookieHeader: string, name: string): string | undefined
​
cookieHeader
string
required
The raw value of the Cookie HTTP header (e.g. "session=abc; theme=dark").
​
name
string
required
The name of the cookie to extract.
Returns the URL-decoded cookie value, or undefined if the name is not present.

​
serializeCookie

Builds a Set-Cookie-compatible string from a name, value, and options. 
serializeCookie(name: string, value: string, options?: CookieOptions): string
​
name
string
required
Cookie name. URL-encoded automatically.
​
value
string
required
Cookie value. URL-encoded automatically.
​
options
CookieOptions
Same CookieOptions as useCookie. Attributes are appended in the order: Max-Age, Expires, Path, Domain, SameSite, Secure, HttpOnly.

​
Examples

​
Reading and writing a theme preference

<script setup lang="ts">
import { useCookie } from '@dvlkit/nuxe'

const theme = useCookie('theme', {
  maxAge: 60 * 60 * 24 * 365, // 1 year
  path: '/',
  sameSite: 'lax',
})

function toggleTheme() {
  theme.value = theme.value === 'dark' ? 'light' : 'dark'
}
</script>

<template>
  <button @click="toggleTheme">
    Current theme: {{ theme ?? 'not set' }}
  </button>
</template>

// composables/use-auth-token.ts
import { useCookie } from '@dvlkit/nuxe'

export function useAuthToken() {
  // 'auth-token' is an httpOnly cookie set by the server.
  // useCookie will read it from the request header during SSR.
  // On the client, value will be undefined (httpOnly cookies are inaccessible to JS).
  return useCookie('auth-token')
}

import { parseCookieValue } from '@dvlkit/nuxe'

const header = 'session=xyz123; theme=dark; locale=en'
const session = parseCookieValue(header, 'session') // 'xyz123'
const missing = parseCookieValue(header, 'user')    // undefined

import { serializeCookie } from '@dvlkit/nuxe'

const setCookieHeader = serializeCookie('session', 'abc123', {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',
  maxAge: 3600,
  path: '/',
})
// "session=abc123; Max-Age=3600; Path=/; SameSite=lax; Secure; HttpOnly"
HttpOnly cookies are set exclusively by the server via the Set-Cookie response header. useCookie on the client cannot read or write them. If your value is undefined on the client for a cookie you know exists, this is the most likely explanation.

Build docs developers (and LLMs) love

Get started for freeTalk to us