Add a cookie consent banner to a Next.js site

Cookbook · platform Last verified View raw markdown (for agents)

In short: paste the live snippet into the document <head> of the root layout so it is the first script on every page, as classic synchronous script tags (plain <script>, not next/script).

You need #

Where it goes #

App Router (app/layout.tsx) #

Put the live snippet inside <head> of the root layout. Use raw <script> tags (or dangerouslySetInnerHTML for the inline huOptions block) so the tags are written straight into the page's HTML.

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* Paste LIVE snippet from install.getSnippet / Integrations — first scripts */}
        <script
          dangerouslySetInnerHTML={{
            __html: `var huOptions = ${JSON.stringify({
              appID: "YOUR_APP_ID",
              currentLanguage: "en",
              blocking: true,
              globalCookie: false,
            })};`,
          }}
        />
        <script
          src="https://cdn.hu-manity.co/v2/hu-banner.min.js"
          // A new app. If the live snippet has no /v2/, the app is on v1 — keep that URL.
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Prefer pasting the exact HTML string from MCP/dashboard into the layout (or a tiny server-only include) rather than rebuilding huOptions keys by hand: the live snippet may carry Consent Mode defaults and the correct CDN path.

Next.js versions differ in how the root layout renders the document head, so check the built page's source after you add the snippet.

Pages Router #

Put the same two tags in pages/_document.tsx inside <Head>, ahead of any other scripts. Prefer _document; it is the file that renders the document <head>.

If the snippet is currently in next/script, in a client component or in the <body>, move it to the top of the root layout's <head> (or pages/_document.tsx).

What the order controls #

The banner holds recognised trackers that load after it until the visitor chooses, in regions whose rule requires consent first. A script placed above the snippet runs straight away, and a script you mark data-hu-category="1" is treated as essential. What runs before consent is your decision, so keep analytics and pixels below the snippet.

Confirm the result #

View the page source (not the browser's Elements panel) on / and an inner route. Then run the browser checks in plain-html in a private window (banner shows, no tracking cookies before the visitor chooses in a region whose rule requires consent first, trackers start after Allow) and, for the full procedure, verify-install. Test from a region your strictest rule covers (for example the EU), or confirm region rules are off.

# Check Result
N1 View source on / and an inner route huOptions + hu-banner.min.js (or /v2/…) appear in <head> before gtag/GTM/pixels, with no async/defer on the Cookie Compliance tags.
N2 The banner's script tag The CDN tag is a plain classic script, written without next/script.

Gotchas #

More help #