You are currently viewing documentation for the canary channel of Next.js

cookies

The cookies function allows you to read the HTTP incoming request cookies from a Server Component or write outgoing request cookies in a Server Action or Route Handler.

app/page.tsx

import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Reference

Methods

The following methods are available:

Method	Return Type	Description
`get('name')`	Object	Accepts a cookie name and returns an object with the name and value.
`getAll()`	Array of objects	Returns a list of all the cookies with a matching name.
`has('name')`	Boolean	Accepts a cookie name and returns a boolean based on if the cookie exists.
`set(name, value, options)`	-	Accepts a cookie name, value, and options and sets the outgoing request cookie.
`delete(name)`	-	Accepts a cookie name and deletes the cookie.
`clear()`	-	Deletes all cookies.
`toString()`	String	Returns a string representation of the cookies.

Options

When setting a cookie, the following properties from the options object are supported:

Option	Type	Description
`name`	String	Specifies the name of the cookie.
`value`	String	Specifies the value to be stored in the cookie.
`expires`	Date	Defines the exact date when the cookie will expire.
`maxAge`	Number	Sets the cookie’s lifespan in seconds.
`domain`	String	Specifies the domain where the cookie is available.
`path`	String	Limits the cookie's scope to a specific path within the domain.
`secure`	Boolean,	Ensures the cookie is sent only over HTTPS connections for added security.
`httpOnly`	Boolean	Restricts the cookie to HTTP requests, preventing client-side access.
`sameSite`	Boolean, `'lax'`, `'strict'`, `'none'`	Controls the cookie's cross-site request behavior.
`priority`	String (`"low"`, `"medium"`, `"high"`)	Specifies the cookie's priority
`encode('value')`	Function	Specifies a function that will be used to encode a cookie's value.
`partitioned`	Boolean	Indicates whether the cookie is partitioned.

To learn more about these options, see the MDN docs.

Caveats

cookies() is a Dynamic Function whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into dynamic rendering.
The .delete() method can only be called:
- In a Server Action or Route Handler.
- If it belongs to the same domain from which .set() is called. Additionally, the code must be executed on the same protocol (HTTP or HTTPS) as the cookie you want to delete.
HTTP does not allow setting cookies after streaming starts, so you must use .set() in a Server Action or Route Handler.

Examples

You can use the cookies().get('name') method to get a single cookie:

app/page.tsx

import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Getting all cookies

You can use the cookies().getAll() method to get all cookies with a matching name. If name is unspecified, it returns all the available cookies.

app/page.tsx

import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

You can use the cookies().set(name, value, options) method in a Server Action or Route Handler to set a cookie. The options object is optional.

app/actions.ts

'use server'
 
import { cookies } from 'next/headers'
 
async function create(data) {
  cookies().set('name', 'lee')
  // or
  cookies().set('name', 'lee', { secure: true })
  // or
  cookies().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

You can use the cookies().has(name) method to check if a cookie exists:

app/page.ts

import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = cookies()
  const hasCookie = cookieStore.has('theme')
  return '...'
}

Deleting cookies

There are three ways you can delete a cookie.

Using the delete() method:

app/actions.ts

'use server'
 
import { cookies } from 'next/headers'
 
async function delete(data) {
  cookies().delete('name')
}

Setting a new cookie with the same name and an empty value:

app/actions.ts

'use server'
 
import { cookies } from 'next/headers'
 
async function delete(data) {
  cookies().set('name', '')
}

Setting the maxAge to 0 will immediately expire a cookie. maxAge accepts a value in seconds.

app/actions.ts

'use server'
 
import { cookies } from 'next/headers'
 
async function delete(data) {
  cookies().set('name', 'value', { maxAge: 0 })
}

Version History

Version	Changes
`v13.0.0`	`cookies` introduced.