Next.js - headers() Function

---

---

The headers() Function

The Next.js headers() function is used to read the HTTP incoming request headers from a Server Component. This function is helpful when you want to access the headers of the incoming request and use them to customize the response based on the user's device or browser settings.

Syntax

Following is the syntax of headers() function:

import { headers } from 'next/headers'
 
export default async function Page() {
    const headersList = await headers()
    const userAgent = headersList.get('user-agent')
}

Parameters

The headers() function does not take any parameters.

Return Value

The headers() function returns a read-only Web Headers object, which is a collection of key/value pairs representing the headers of the incoming request.

• Headers.entries(): Returns an iterator allowing to go through all key/value pairs contained in this object.
• Headers.forEach(): Executes a provided function once for each key/value pair in this Headers object.
• Headers.get(): Returns a String sequence of all the values of a header within a Headers object with a given name.
• Headers.has(): Returns a boolean stating whether a Headers object contains a certain header.
• Headers.keys(): Returns an iterator allowing you to go through all keys of the key/value pairs contained in this object.
• Headers.values(): Returns an iterator allowing you to go through all values of the key/value pairs contained in this object.

Key Points

• The headers is an asynchronous function that returns a promise. You must use async/await or React's use function.
• In version 14 and earlier, headers 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.
• Since headers is read-only, you cannot set or delete the outgoing request headers.
• The headers() is a Dynamic API whose returned values cannot be known ahead of time. Using it in will opt a route into dynamic rendering.

Example 1

In the code below, we used authorization header to fetch user data from an API. The headers() function is used to read the HTTP incoming request headers from a Server Component and get the authorization header value.

import { headers } from 'next/headers'
 
export default async function Page() {
    const authorization = (await headers()).get('authorization')
    const res = await fetch('...', {
        headers: { authorization }, // Forward the authorization header
    })
    const user = await res.json()
    
    return <h1>{user.name}</h1>
}

Example 2

In the code below, we used the headers() function to read the HTTP incoming request headers from a Server Component and get the user-agent header value.

import { headers } from 'next/headers'

export default async function Page() {
    const headersList = await headers()
    const userAgent = headersList.get('user-agent')
    
    return <h1>{userAgent}</h1>
}