Initialization Flow

When the consent provider mounts, it creates a cached consent runtime, reads any stored consent from the browser, fetches jurisdiction and translation data (via SSR or API), determines the applicable consent model, and decides whether to show the banner. This entire sequence completes before the first meaningful consent-aware render.

Lifecycle Sequence

How It Works

Mount — When the provider renders, it creates (or retrieves from cache) a consent runtime and store. Any existing consent is read from localStorage/cookies immediately. If consent already exists, the banner stays hidden and gating rules apply right away. See Client Modes for how the mode affects runtime creation.

Init — The store fetches jurisdiction, location, and translation data. In c15t mode this calls GET /init on your backend; in offline mode it uses hardcoded defaults. If SSR data was passed to the provider, the network fetch is skipped entirely. See Server-Side Utilities for SSR setup.

Model resolution — The jurisdiction from the init response is mapped to a consent model: opt-in (GDPR and similar), opt-out (CCPA), iab (TCF 2.3), or null (no regulation). For opt-out and null models, all categories are auto-granted — unless a Global Privacy Control signal is detected. See Consent Models for the full jurisdiction-to-model mapping.

Save — When the user interacts with the banner or dialog, their choices are persisted to localStorage/cookies and synced to the backend. Script, iframe, and network gating rules update immediately based on the new consent state. See the Script Loader, Iframe Blocking, and Network Blocker guides for gating details.

Revocation — If a user revokes a previously granted category, the page reloads by default to ensure a clean execution environment. The API sync is deferred to the fresh page load. See Cookie Management for revocation and persistence details.

When Does the Banner Show?

The banner appears when all three conditions are true:

1. No existing consent — the user has never consented (or their consent was cleared)
2. A regulation applies — the resolved model is opt-in or iab (not null or opt-out)
3. Storage is accessible — the browser allows localStorage (not blocked in private mode)

If the model is null (no regulation detected) or opt-out, consents are auto-granted and the banner never appears. See Consent Models for which jurisdictions map to which models.

Debugging the Lifecycle

Use the DevTools panel and callbacks to inspect each step of the initialization flow:

Configure callbacks in the provider to log lifecycle events, and add DevTools for a visual inspector:

import { type ReactNode } from 'react';
import {
  ConsentManagerProvider,
  ConsentBanner,
  ConsentDialog,
} from '@c15t/nextjs';
import { DevTools } from '@c15t/dev-tools/react';

export default function ConsentManager({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'c15t',
        backendURL: '/api/c15t',
        callbacks: {
          onBannerFetched: ({ jurisdiction, location }) => {
            console.log('Init complete:', { jurisdiction, location });
          },
          onConsentSet: ({ preferences }) => {
            console.log('Consent saved:', preferences);
          },
          onBeforeConsentRevocationReload: ({ preferences }) => {
            console.log('Reloading due to revocation:', preferences);
          },
          onError: ({ error }) => {
            console.error('Consent error:', error);
          },
        },
      }}
    >
      <ConsentBanner />
      <ConsentDialog />
      {process.env.NODE_ENV !== 'production' && <DevTools />}
      {children}
    </ConsentManagerProvider>
  );
}