cookies

cookies is an async function that allows you to read the HTTP incoming request cookies in Server Component, and read/write outgoing request cookies in Server Actions or Route Handlers.

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

Reference

Methods

The following methods are available:

Options

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

The only option with a default value is path.

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

Good to know

• cookies is an asynchronous function that returns a promise. You must use async/await or React's use function to access cookies.
  • In version 14 and earlier, cookies was a synchronous function. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.
• cookies is a Dynamic API 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.

Understanding Cookie Behavior in Server Components

When working with cookies in Server Components, it's important to understand that cookies are fundamentally a client-side storage mechanism:

• Reading cookies works in Server Components because you're accessing the cookie data that the client's browser sends to the server in the HTTP request headers.
• Setting cookies cannot be done directly in a Server Component, even when using a Route Handler or Server Action. This is because cookies are actually stored by the browser, not the server.

The server can only send instructions (via Set-Cookie headers) to tell the browser to store cookies - the actual storage happens on the client side. This is why cookie operations that modify state (.set, .delete, .clear) must be performed in a Route Handler or Server Action where the response headers can be properly set.

Examples

Getting a cookie

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

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

Getting all cookies

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

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

Setting a cookie

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

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

Checking if a cookie exists

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

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

Deleting cookies

There are three ways you can delete a cookie.

Using the delete() method:

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

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

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

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

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

Version History