Next.js install guide
Add Velo to Next.js
Install the Velo cookie banner and Google Consent Mode v2 on Next.js with one line in your root layout. With admin access to the site, most installs take a few minutes. If you use Google Tag Manager, this page covers that route too.
Instructions and image sources reviewed 7 November 2026.
What you need on Next.js
Before you start
- Where. app/layout.tsx → head
- Plan. App Router or Pages Router
- Goes live. After your next deploy
- Typical time. About five minutes
Once it is live
- Your banner follows the defaults you set for each visitor’s region.
- Tags wait until the visitor has chosen.
- Every choice is recorded, and Consent Mode v2 passes it on to your Google tags.
Two ways to install Velo on Next.js
Pick the route that matches how your site already loads its tags. Both end with the same banner and the same signals.
Paste one line into your root layout
Add your site’s snippet to the site-wide head, then publish and test it on the live site. If your measurement tags already run through Google Tag Manager, use the route further down instead.
Use Tag Manager? Skip the code
If Google Tag Manager is already on your site, this is the easiest way to add Velo. There’s no code to touch, it takes four short steps, and all your tags stay in one place.
Load the snippet once, from the root layout. A tag in a useEffect runs after your other tags can fire, and next/script without a strategy waits for hydration. Test a page you reach through a Link as well as a full reload. The banner should stay put, with no second copy.
Everything a consent setup needs
The same banner, records and scans on every plan. Pro adds unlimited sites, unlimited scans and your own logo.
Your banner asks in the visitor’s language and follows the defaults you set for their region.
Every choice is recorded, and Consent Mode v2 passes it on to your Google tags.
Paste one line into your root layout
Add your site’s snippet to the site-wide head, then publish and test it on the live site. If your measurement tags already run through Google Tag Manager, use the route further down instead.
Copy the line
Copy the complete installation snippet for this site from your Velo dashboard. The example below shows the format; replace your-site-id before using it. Keep the API endpoint supplied by your dashboard.
<script src="https://cdn.veloconsent.com/v1/velo.js" data-api="https://app-staging.veloconsent.com" data-velo-site="your-site-id" async></script>
Paste it into your root layout
With the App Router, open the root layout (app/layout.tsx or src/app/layout.tsx). If it has no <head> element, add one above <body>, then paste your complete Velo snippet inside it, above any analytics or advertising tags. With the Pages Router, paste it inside <Head> in pages/_document.tsx, and create that file if the project doesn’t have one. The snippet is valid JSX as it is. Don’t put it in a useEffect or in next/script with the default strategy, because both load it after your other tags can fire. Deploy, then test a page you reach through a Link as well as a full reload.
// app/layout.tsx on the App Router. On the Pages Router, the same
// line goes inside <Head> in pages/_document.tsx.
export default function RootLayout({ children }) {
return (
<html lang="en">
<head>
{/* Paste the complete Velo snippet from your dashboard here. */}
<script src="https://cdn.veloconsent.com/v1/velo.js"
data-api="https://app-staging.veloconsent.com"
data-velo-site="your-site-id" async></script>
</head>
<body>{children}</body>
</html>
);
}Publish and check the live site
Save and publish the change using the platform steps above, then clear any site or CDN cache. Open the published URL in a fresh browser session. Check the banner where your region rules require it, test accepting and rejecting, and verify consent defaults and updates before your measurement tags run. Confirm the site appears as installed in your Velo dashboard.
Velo’s banner with its default look. Your banner’s copy, colours and region settings may differ.Use Tag Manager? Skip the code
If Google Tag Manager is already on your site, this is the easiest way to add Velo. There’s no code to touch, it takes four short steps, and all your tags stay in one place.
The complete Tag Manager guideAdd Velo to Tag Manager
Open the Velo template, click Add to workspace, then pick your container. Open the Velo template ↗
Paste your site ID
In Tag Manager, open Tags and click New. Click Tag Configuration, choose Velo CMP and paste your site ID. You’ll find it in your Velo dashboard. Leave everything else as it is.
Make it load first
Click Triggering, choose Consent Initialization – All Pages, then click Save. This lets Velo start before your other tags.
Publish and check it
Click Submit, then Publish. Preview alone doesn’t put Velo live. Then open your site in a private window, try the banner, and check that it shows as installed in your Velo dashboard.
Or hand it to an agent
Copy the prompt into Claude, ChatGPT, Cursor or whichever assistant you already use. It carries everything on this page: both routes, the order the tags have to load in, and the checks that prove it worked.
Install with AIThe prompt
Paste this prompt into your assistant, then provide your site ID and the complete installation snippet or GTM settings from your Velo dashboard.
Install Velo on Next.js. Current guide: https://veloconsent.com/nextjs Before editing, get my site ID and complete installation snippet or GTM settings from the Velo dashboard. Confirm which consent tool and measurement tags already run on the site. Choose one installation route: A. If the site already uses Google Tag Manager, add the Velo CMP template (published by veloconsent) from the Community Template Gallery. Set my site ID, theme and API endpoint from the dashboard. Review the advanced options; ads_data_redaction and url_passthrough default to off. Use Consent Initialization – All Pages, then Preview and verify consent before publishing. Full steps: https://veloconsent.com/google-tag-manager B. For direct installation: With the App Router, open the root layout, app/layout.tsx or src/app/layout.tsx, add a <head> element above <body> if there is none, and paste your complete Velo snippet inside it, above any analytics or advertising tags. With the Pages Router, paste it inside <Head> in pages/_document.tsx, creating that file if the project has none. The snippet is valid JSX as it stands. Keep it out of useEffect and out of next/script with the default strategy, which both load it after your other tags can fire. Deploy, then test a page reached through a Link as well as a full reload. Preserve unrelated code. Avoid duplicate Velo installs or competing consent defaults. Do not assume a head placement or async loading alone guarantees tag order. Check the published site in a fresh session. Verify the banner under the configured region rules, initial consent defaults, accept/reject updates and the velo_consent_update event. Check that non-Google tags follow their assigned categories. Test a second page and any separate checkout surface. Confirm signals reach the Velo dashboard. Report what changed, where it changed and the result of each check. Describe any missing access or checks you could not complete.
From the journal
Notes on cookie banners, Consent Mode and the data that goes missing between them.
Do Canadian websites need Google Consent Mode v2?
Google Consent Mode v2 in Velo: what is new
How to set up Google Consent Mode v2 on Shopify
Common questions about Velo on Next.js
Does this work with the App Router and the Pages Router?
Yes. The App Router takes the snippet in the root layout and the Pages Router in pages/_document.tsx. We tested both on Next.js 16, with full reloads and with Link navigation.
Should I use next/script instead?
Only with strategy="beforeInteractive" in the root layout, which also worked in our tests. A plain tag is simpler, because it’s in the HTML from the first byte, while beforeInteractive is started by Next.js’s own loader. Avoid the default afterInteractive and lazyOnload, which load after your other tags can fire.
Does the banner survive client-side navigation?
Yes. Link navigation keeps the same document, so the banner, the button that reopens it and the visitor’s choice all stay in place, and the tag in the layout does not load again.
My site sets a Content Security Policy.
The snippet needs https://cdn.veloconsent.com in script-src and https://app-staging.veloconsent.com in connect-src. Check the browser console after publishing and allow anything else your policy blocks.
Will it slow the site down?
The dashboard snippet loads asynchronously. As with any script, measure its effect on your site and check your tag order; asynchronous loading alone does not guarantee consent defaults run before other tags.
Can an AI assistant do this for me?
Yes. Copy the prompt in Install with agents, just below, into Claude, ChatGPT, Cursor or whichever assistant you already use. It carries the steps on this page, the order the tags have to load in, and the checks the agent has to run before it tells you the job is done.
Free for one site
Banner, scan and consent records for one site, free. Pro from €7 a month, plus VAT, for unlimited sites.