Cookies and Params

Reading Cookies, Headers, and Search Params

Three inputs come from the request rather than the file system, and in Next.js 16 10,514 all three are asynchronous: cookies() and headers() from next/headers, and the searchParams prop. They were synchronous through Next.js 14; the await lets Next.js render the static part of a route before the request exists.

Reading all three at once (app/greet/page.js)JavaScript

import { cookies, headers } from "next/headers";
export default async function Greet({ searchParams }) {
  const [jar, head, query] = await Promise.all([cookies(), headers(), searchParams]);
  const theme = jar.get("theme")?.value ?? "light";
  const lang = head.get("accept-language")?.split(",")[0] ?? "unknown";
  return <main><p>theme cookie: {theme}</p><p>language: {lang}</p>
    <p>all: {JSON.stringify(query)}</p></main>;
}

Output

$ curl -s "localhost:3310/greet?q=lem&tag=sci-fi&tag=classic" \
    -H "cookie: theme=dark" -H "accept-language: en-GB,en;q=0.9"
theme cookie: dark
language: en-GB
all: {"q":"lem","tag":["sci-fi","classic"]}

Note the shape: a repeated key arrives as an array, a single key as a string, so a filter that is usually one value and occasionally several needs [].concat(query.tag ?? []) rather than a cast. Both params and searchParams are plain objects of strings — validate them with Zod 44,027 (Validating Input with Zod) before they reach a query.

The cookie store offers get, getAll, has, set and delete, but only the readers work during rendering: HTTP cannot send Set-Cookie once the body is streaming, so set and delete belong in a Server Action (Server Actions and Mutations) or a Route Handler (Handler Cookies).

All three are request-time APIs, so reading one in a layout or page opts the whole route into dynamic rendering — next build marks it ƒ instead of ○. The usual mistake is reading a cookie in the root layout and wondering why nothing is prerendered any more; the narrow fix is to push the read into a small component wrapped in <Suspense> (Rendering Modes).

MENU

Cookies and Params