Privacyboard

PostHog cookie consent in Next.js: wait for consent, step by step

By the Privacyboard teamPublished 22 November 20265 min read
Short answer

In Next.js, start PostHog with cookieless_mode set to "on_reject" so it sets no cookies before a choice, then call opt_in_capturing() when the visitor accepts analytics and opt_out_capturing() when they refuse. A cookie banner gives you that choice and records it as proof. Load the banner before PostHog.

PostHog can wait for consent: it has methods to opt a visitor in or out, and a cookieless mode that stores nothing until the visitor chooses. In a Next.js app, the work is to start PostHog in that waiting state, connect it to a cookie banner, and make sure nothing else sends data before the choice. Here is how, as of 22 November 2026.

By default, PostHog's JavaScript library stores an identifier in a cookie or in local storage so it can recognise a visitor across pages and visits. In the EU, storing or reading information on a visitor's device needs consent unless it is strictly necessary for the service they asked for (Article 5(3) of the ePrivacy Directive). Product analytics is not strictly necessary, so the default setup needs consent before it runs.

The GDPR applies on top: PostHog itself says a persistent visitor ID, the IP address and the user agent are personal data.

#What are your options in PostHog?

PostHog documents three ways to handle it:

SetupWhat happens before a choiceBanner needed?
DefaultCookies or local storage set, events capturedYes, and it must hold PostHog back
cookieless_mode: "on_reject"Nothing stored on the device, no events capturedYes
cookieless_mode: "always"Nothing stored on the device; visitors counted with a server-side hashPostHog presents it as the no-banner option

The middle option is the one PostHog's own Next.js tutorial uses: no cookies until the visitor decides, full analytics after they accept, and a count of refusing visitors with a hash that PostHog does not treat as personal data.

The "always" mode deserves care. PostHog states it needs no banner because nothing is stored on the device. The European Data Protection Board's guidelines on the technical scope of Article 5(3) (version 2, October 2024) take a wide view of what counts as accessing a device, beyond cookies. Whether a given cookieless setup needs consent can depend on your country's regulator, so check before you drop the banner on the strength of a vendor's claim.

#How do you set it up in Next.js?

With the App Router, recent PostHog setups start the library in instrumentation-client.js (or .ts) at the project root. Start it in the waiting state:

// instrumentation-client.ts
import posthog from 'posthog-js';

posthog.init('your-project-key', {
  api_host: 'https://eu.i.posthog.com',
  cookieless_mode: 'on_reject',
});

Cookieless mode must also be enabled in PostHog, in the project's web analytics settings.

Then record the visitor's choice. posthog.get_explicit_consent_status() returns "pending" until they decide; opt_in_capturing() and opt_out_capturing() record the decision.

A banner shows the choice, records it as proof and tells your code. If you use a banner that sends an event when the choice changes, a small client component is enough. With the Privacyboard banner, the event is privacyboard:consent, and window.Privacyboard.getConsent() returns the current choice:

'use client';
import { useEffect } from 'react';
import posthog from 'posthog-js';

export function PostHogConsent() {
  useEffect(() => {
    const apply = (analytics: boolean) => (analytics ? posthog.opt_in_capturing() : posthog.opt_out_capturing());
    const pb = (window as any).Privacyboard;
    if (pb?.getConsent().decided) apply(pb.getConsent().analytics);
    const onChoice = (e: Event) => apply((e as CustomEvent).detail.analytics);
    window.addEventListener('privacyboard:consent', onChoice);
    return () => window.removeEventListener('privacyboard:consent', onChoice);
  }, []);
  return null;
}

With the Privacyboard banner, the privacyboard npm package does the same in one line. useWhenAllowed runs your code once, as soon as analytics is allowed; with cookieless_mode: "on_reject" you can also opt the visitor in from there:

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

export function PostHogConsent() {
  useWhenAllowed('analytics', () => posthog.opt_in_capturing());
  return null;
}

For a visitor who withdraws consent later, keep the event listener above, or use onConsent from the same package, which reports every change.

Render it once in app/layout.tsx, and put the banner's script first in the <head> of that same layout, as a plain <script> tag rather than next/script, so it runs before anything it has to hold back. Other banners work the same way with their own event or callback.

If you build your own buttons instead, call opt_in_capturing() from the Accept button and opt_out_capturing() from the Refuse button, and keep a way to change the choice later, such as a "Cookie settings" link in the footer. You then also need to keep proof of each choice yourself.

PostHog is rarely alone. Before you call the setup done, check:

  • Session replay and surveys: part of the same library, so they follow the same opt-in. Check them anyway in the network panel.
  • Other analytics or ad tags added in the layout or through a tag manager: each needs to wait too.
  • Server-side capture: events sent from your API routes with the Node library are not covered by the browser's opt-out. Only send them for visitors who accepted, or keep them free of personal data.
  • Feature flags: evaluating flags for an identified user sends data to PostHog. Decide whether that is part of the service the visitor asked for or analytics.
  • cookieless_mode: "on_reject" set, and enabled in the PostHog project
  • The banner script is the first tag in the <head> of the root layout
  • Accepting analytics calls opt_in_capturing(), refusing calls opt_out_capturing()
  • A footer link lets visitors change their choice
  • The network panel shows no PostHog requests with an identifier before a choice
  • Server-side events only for visitors who accepted
  • PostHog is in your vendor list, with its data processing agreement, and in your cookie policy

#What to do this week

  1. Open your site in a private window, open the network panel and note every request sent before you click anything.
  2. Switch PostHog to cookieless_mode: "on_reject" and connect it to your banner's choice.
  3. Repeat step 1 and check that PostHog only sends events after you accept.
  4. Add PostHog to your cookie policy and vendor list, with the region you chose (EU or US) and its agreement.

#FAQ

PostHog offers a cookieless "always" mode that it presents as needing no banner. EU regulators read the ePrivacy rule broadly, so check with your advisor or your regulator's guidance before relying on it. Other EU tracking on your site may still need a banner anyway.

#What is the difference between opt_out_capturing and cookieless mode?

opt_out_capturing() records that a visitor refused, and PostHog stops capturing for them. Cookieless mode controls what PostHog stores on the device: with "on_reject", nothing until a choice is made.

No. Hosting in the EU affects data transfers, not the consent rule for storing information on the visitor's device.

#Where should the PostHog init code go in the Next.js App Router?

PostHog's current Next.js guide uses instrumentation-client.js at the project root. Older setups use a client provider component in the root layout; both work if the library starts in the waiting state.

#Can a coding agent set this up for me?

Yes. Running npx privacyboard init in the project recognises PostHog among your packages, places the banner script and the policy links, and gives you a link to check and publish. You still connect PostHog's opt-in to the banner as shown above.

#Sources

Privacyboard is a guidance tool, not legal advice. This article explains general rules in plain language and was accurate on the date above; laws and guidance change. For an unusual situation, ask a qualified professional. Spotted a mistake? Write to hello@privacyboard.io.

Keep reading