How to install the TermsBox cookie banner on Next.js

This guide is for websites built with Next.js. It covers both the App Router (the app folder) and the Pages Router (the pages folder). Follow the section that matches your project.

Next.js has its own way of loading scripts, so you do not paste a plain HTML <script> tag. You use the built-in Next.js Script component. This guide shows you exactly how.

What you need

Your TermsBox site id (also called your site key). It looks like a short random string of letters and numbers.
Where to find it: log in to TermsBox, then go to Dashboard, open Consent Banner, and click the Install tab. Your site id is already filled into the ready-to-copy script there. The same snippet also appears during first-time setup, on the Getting Started card on your dashboard home, and on the success page right after checkout.

Note: the site id is not shown on its own anywhere. It is always inside the copyable script tag. It is not listed under Settings, so do not look there. When you copy from the Install tab you get a plain HTML tag. For Next.js you will use the site id from that snippet inside the Next.js code shown below.

The important setting

You must load the banner with strategy="beforeInteractive". This tells Next.js to load the banner early, before the rest of your page becomes interactive, so it can block trackers until the visitor makes a choice. Do not use any other strategy, and do not add async or defer. Using the wrong setting will break the banner.

Replace YOUR_SITE_KEY in the examples below with your real site id from the dashboard.

App Router (you have an `app` folder)

In your project, open the app folder.
Open the file named layout.tsx (or layout.js). This is your root layout, the file that wraps every page.
At the very top of the file, add this import line:
```
import Script from 'next/script';
```

Inside the layout, place the banner script inside the <head> of your document, using the Script component. Your file should look like this:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <Script
          src="https://termsbox.com/cmp/termsbox-cmp.js"
          strategy="beforeInteractive"
          data-site-id="YOUR_SITE_KEY"
          data-auto-block="on"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Replace YOUR_SITE_KEY with your real site id.
Save the file.

You only add this once in the root layout. It then applies to every page of your site automatically.

Pages Router (you have a `pages` folder)

In your project, open the pages folder.
Open the file named _document.tsx (or _document.js). If it does not exist, create it with the content below. This special file lets you control the shared HTML <head>.

Add the banner script inside the <Head> section using the Script component with strategy="beforeInteractive". Your file should look like this:

import { Html, Head, Main, NextScript } from 'next/document';
import Script from 'next/script';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <Script
          src="https://termsbox.com/cmp/termsbox-cmp.js"
          strategy="beforeInteractive"
          data-site-id="YOUR_SITE_KEY"
          data-auto-block="on"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Replace YOUR_SITE_KEY with your real site id.
Save the file.

You only add this once. It then applies to every page of your site automatically. When visitors move between pages, the banner keeps working. You do not need to add it to individual pages.

Verify it works

Deploy your site so the change is live, or run your production build locally. The beforeInteractive setting behaves correctly on a real deployed build.
Open your website in a browser and do a hard refresh (hold Shift and click reload, or use a private or incognito window so nothing is cached).
Look for the cookie banner to appear. If it shows up, the script is loading.
Go back to TermsBox, open Dashboard, then Consent Banner, then the Install tab, and click the Verify Installation button. TermsBox will visit your site and check that the script is present. When it finds it, the status changes to verified.

The Verify Installation button is the only thing that marks your site as verified. Just loading the banner on your site does not flip the status by itself, so click the button after you install.

Troubleshooting

The banner does not appear: make sure you used strategy="beforeInteractive" and that the script sits in the root layout (app/layout.tsx) or in pages/_document.tsx. Placing it in a normal page instead of the shared layout is the most common mistake.
The banner appears but looks blank or does nothing: this usually means the site id is missing or empty. Confirm that data-site-id holds your real site id, with no typos. An empty or dropped site id makes the banner load in a broken default state without any error message.
You used a different strategy: change it to beforeInteractive. Other strategies load the banner too late, which lets trackers run before the visitor consents.
Verify Installation says it cannot find the script: make sure the change is deployed to the live web address stored in TermsBox, then hard refresh and try again. The verifier checks your main site address, so that page must include the script. Note that some Next.js scripts only render fully on the deployed production build, so verify against your live site rather than a local development server.
Verify Installation says it could not reach your site: if your site is password protected, not yet published, or protected by strong bot or firewall rules, the checker may be blocked. Make sure the page is publicly reachable, then try again.

Install the TermsBox cookie banner on a Next.js site

What you need

The important setting

App Router (you have an `app` folder)

Pages Router (you have a `pages` folder)

Verify it works

Troubleshooting

Install the TermsBox cookie banner on a Next.js site

What you need

The important setting

App Router (you have an `app` folder)

Pages Router (you have a `pages` folder)

Verify it works

Troubleshooting