# Next.js

URL: https://privacyboard.io/docs/cookie-banner/nextjs

Last updated 2026-11-22.

Add the Privacyboard cookie banner, privacy policy and cookie policy to a Next.js app, with the App Router or the Pages Router, by hand or through a coding agent.

In a Next.js app, the banner is one plain `<script>` tag, first in the `<head>` of the root layout. The privacy policy and cookie policy are pages of your privacy center, linked from the footer. You can let a coding agent do all of it with one command, or add it by hand in two files.

## The fastest way: one command

From the project's folder:

```bash
npx privacyboard init --site acme.com
```

It reads the package names in `package.json` (never their values), recognises the tools that handle personal data, such as `stripe`, `posthog-js` or `@sentry/nextjs`, and prints the script, where it goes, the footer links and a link to claim the setup. Claude Code, Cursor and Codex can run it for you: see [Set up with an AI coding agent](/docs/getting-started/set-up-with-an-ai-agent). Nothing goes live until you claim the setup, check the tools found, validate your documents and publish.

If you already have a workspace, take the script from **Cookie banner → Install** instead, and follow the steps below.

## App Router

Put the script first in the `<head>` of `app/layout.tsx`, before any other tag:

```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts */}
        <script src="https://privacyboard.io/cmp/your-banner-id.js" />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Use a plain `<script>` tag, not `next/script`. The banner must run before your analytics and advertising code so it can hold them back, and `next/script` loads it later or out of order. The comment silences Next.js's lint rule against scripts that load before the page: here, that is the point.

## Pages Router

Put the same tag first in the `<Head>` of `pages/_document.tsx`:

```tsx
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts */}
        <script src="https://privacyboard.io/cmp/your-banner-id.js" />
      </Head>
      <body><Main /><NextScript /></body>
    </Html>
  );
}
```

Put it in `_document.tsx` rather than in `next/head` inside a page, so that it is on every page and comes before the rest of the head.

## Footer links

Link your privacy policy and cookie policy from the footer of every page, and add a link that reopens the banner:

```tsx
<footer>
  <a href="https://acme.privacyboard.io/privacy-policy">Privacy policy</a>
  <a href="https://acme.privacyboard.io/cookie-policy">Cookie policy</a>
  <a href="#" data-pb-open>Cookie settings</a>
</footer>
```

Use the addresses of your own privacy center, shown in **Privacy center**, or your own domain if you set one up. With the command above, the links point to short addresses that lead to your center once it is published.

## Analytics installed from npm

Tools bundled into your app from npm, such as `posthog-js`, `mixpanel-browser` or `@sentry/nextjs`, do not load a script tag the banner could hold. Most still send their data with `fetch`, `XMLHttpRequest` or `sendBeacon` to a known address, which the banner holds back until the visitor accepts the tool's category. See [Blocking before consent](/docs/cookie-banner/blocking-before-consent) for what is covered.

For full control, start the tool only once its category is allowed. The `privacyboard` npm package does it in one line:

```bash
npm i privacyboard
```

```tsx
'use client';
import posthog from 'posthog-js';
import { useWhenAllowed } from 'privacyboard/react';

export function Analytics() {
  useWhenAllowed('analytics', () => posthog.init('your-project-key', { api_host: 'https://eu.i.posthog.com' }));
  return null;
}
```

`useWhenAllowed` runs your code once, right away if analytics is already allowed, otherwise when the visitor accepts it. Outside React, `whenAllowed('analytics', start)` from `privacyboard` does the same, and `onConsent(listener)` gives you every change, for tools with their own opt-in and opt-out. Without the package, listen to the `privacyboard:consent` event the banner sends, and read `window.Privacyboard.getConsent()`.

Render `<Analytics />` once in the root layout. Each tool follows the category you give it among your banner's services: see [Services and categories](/docs/cookie-banner/services-and-categories).

## Content Security Policy

If your app sends a Content Security Policy, allow Privacyboard where scripts load and where the page connects: add `https://privacyboard.io` to `script-src` and `connect-src`. Without it, the browser blocks the banner and the page shows no choice.

## Check it

Run your app, open it in a private window and check that the banner appears. Then, once the site is online, run the [site scan](/docs/cookie-banner/site-scan): it shows what your pages contact before a visitor chooses.

## FAQ

### Can I use next/script with strategy="beforeInteractive"?
It runs before Next.js's own code, but Next.js decides where it goes in the page, so nothing guarantees it comes before the other scripts in your head. A plain `<script>` written first in the head is the placement that runs before everything else, so it is the one to use.

### Why does the banner have to load before the page?
To hold back a tool, the banner has to be running before that tool starts. A script that loads after the page, or after your analytics, finds them already running and can no longer stop what they have sent.

### Does it work with static export and the Edge runtime?
Yes. The banner runs in the visitor's browser, so it works the same with static export, server rendering or the Edge runtime.

### Which file does the coding agent change?
`app/layout.tsx` with the App Router, or `pages/_document.tsx` with the Pages Router, plus the component that renders your footer.
