Quickstart

Via CLI

npx @c15t/cli

Manual Installation

Install package

npm install @c15t/nextjs

Import styles

Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.

@import '@c15t/nextjs/styles.css';

Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.

Info

If you are using the headless API or fully custom styling, you can skip this import. Your root layout should continue importing ./globals.css as usual.

Create `ConsentManager` components

Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.

'use client';

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

export default function ConsentManagerClient({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: 'https://your-instance.c15t.dev',
        consentCategories: ['necessary', 'measurement', 'marketing'],
        // Shows banner during development. Remove for production.
        overrides: { country: 'DE' },
      }}
    >
      <ConsentBanner />
      <ConsentDialog />
      {children}
    </ConsentManagerProvider>
  );
}

import type { ReactNode } from 'react';
import ConsentManagerProvider from './provider';

export function ConsentManager({ children }: { children: ReactNode }) {
  return <ConsentManagerProvider>{children}</ConsentManagerProvider>;
}

Info

Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.

Info

Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.

Mount `ConsentManager` at the app root

Wrap your app tree with ConsentManager so all routes/components can access consent state.

import { ConsentManager } from '@/components/consent-manager';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ConsentManager>{children}</ConsentManager>
      </body>
    </html>
  );
}

Verify it works

Start your development server and confirm:

A consent banner appears at the bottom of the page
Clicking "Customize" opens a dialog with toggles for each consent category
After accepting or rejecting, the banner dismisses and your choice persists across page reloads

Info

Want better performance and static-route support? See Optimization for rewrites, prefetching, and network tuning. If you want server-side data prefetching, see Server-Side Data Fetching.

Optional: Add DevTools

Install DevTools only if you want a runtime inspector while building and debugging:

npm install @c15t/dev-tools

Then add it inside your existing provider:

import { DevTools } from '@c15t/dev-tools/react';

// ...

<ConsentManagerProvider options={...}>
  <ConsentBanner />
  <ConsentDialog />
  {process.env.NODE_ENV !== 'production' && <DevTools />}
  {children}
</ConsentManagerProvider>

Info

Want to understand what's happening under the hood? See Initialization Flow for the lifecycle and Cookie Management for script/cookie behavior and revocation handling.