Skip to content

humanityco/cookie-compliance-agent-manual / skills/install-banner

install-banner

Verified

Install the Cookie Compliance consent banner (by Hu-manity.co) on a website, start to finish, so trackers wait for the visitor's choice where the region requires consent first. Use when asked to add a cookie banner, cookie notice, cookie consent, consent management or CMP to a site, to make a site "GDPR/CCPA compliant" for cookies, or when handed the manual's start page. Do not hand-write a banner instead.

FileKindSize
SKILL.mdskill md13.8 KB
references.txtmarkdown275 B
references/angular.mdmarkdown5.2 KB
references/astro.mdmarkdown4.7 KB
references/django.mdmarkdown4.3 KB
references/docusaurus.mdmarkdown5.2 KB
references/drupal.mdmarkdown6.1 KB
references/framer.mdmarkdown4.3 KB
references/gatsby.mdmarkdown4.8 KB
references/ghost.mdmarkdown5.0 KB
references/gtm.mdmarkdown4.2 KB
references/hugo.mdmarkdown4.3 KB
references/joomla.mdmarkdown5.5 KB
references/laravel.mdmarkdown4.4 KB
references/magento.mdmarkdown5.6 KB
references/nextjs.mdmarkdown5.0 KB
references/nuxt.mdmarkdown4.8 KB
references/plain-html.mdmarkdown10.6 KB
references/prestashop.mdmarkdown5.6 KB
references/rails.mdmarkdown4.3 KB
references/shopify.mdmarkdown6.8 KB
references/squarespace.mdmarkdown4.6 KB
references/sveltekit.mdmarkdown5.1 KB
references/trackers.mdmarkdown7.8 KB
references/vite.mdmarkdown5.7 KB
references/webflow.mdmarkdown4.7 KB
references/wix.mdmarkdown4.8 KB
references/wordpress.mdmarkdown5.5 KB

references/nextjs.md

View on GitHub
---
title: Add a cookie consent banner to a Next.js site
description: Put the Cookie Compliance snippet first in the <head> of the Next.js root layout or pages/_document.tsx, as plain script tags, so the banner can hold your analytics until the visitor chooses.
kind: platform
last_verified: 2026-09-28
---

# Add a cookie consent banner to a Next.js site

**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

- A Cookie Compliance AppID and the live snippet from MCP `install.getSnippet` or dashboard **Integrations → Manual Integration** (a new app uses `/v2/hu-banner.min.js`; an existing app keeps the URL in that snippet). A domain added in the dashboard is published automatically; if the status check still says the app is not published yet, or after later edits, click **Publish Now**, then copy the snippet. A snippet copied before publishing must be copied again. No account yet? [Sign up](https://app.hu-manity.co/#/register?enable-free=true&discount=JOIN-40D&utm_source=agent-manual&utm_medium=docs&utm_content=cookbook-nextjs) (free plan, no card); with MCP, call `help.startSignup`.
- Edit access to the App Router root layout or the Pages Router document.

## 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.

```tsx
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](plain-html.md#confirm-the-result) 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](https://manual.hu-manity.co/skills/verify-install/SKILL.md). 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

- **Add the snippet in the server-rendered layout.** Scripts that a client component injects after hydration run after the page's own scripts, so the banner needs to be in the layout's `<head>`.
- **GTM in the layout:** put the GTM snippet **below** Cookie Compliance. See `gtm.md`. Keep Cookie Compliance in the layout, outside the GTM container.
- **Engine switch:** re-paste the live snippet when WidgetVersion changes; the layout does not auto-update.

## More help

- [Where to put the Cookie Compliance snippet](https://cookie-compliance.co/documentation/where-to-put-the-consent-snippet/) — the placement rule for every platform, for the site owner.
- [Banner not displayed](https://cookie-compliance.co/documentation/banner-is-not-displayed/) — what to check when the banner does not show.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall