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.
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
Getting a cookie
You can use the cookies().get('name')
method to get a single cookie:
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.
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>
))
}
Setting a cookie
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.
'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: '/',
})
}
Check if a cookie exists
You can use the cookies().has(name)
method to check if a cookie exists:
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:
'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:
'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.
'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. |
Was this helpful?