Quickstart

Via CLI

npx @c15t/cli@rc

Manual Installation

Install package

npm install @c15t/nextjs

Optional: Configure Next.js rewrites

Proxy API requests through your Next.js server. This can prevent ad blockers from blocking requests to your c15t backend.

import type { NextConfig } from 'next';

const config: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/c15t/:path*',
        destination: `${process.env.NEXT_PUBLIC_C15T_URL}/:path*`,
      },
    ];
  },
};

export default config;

Info

Set NEXT_PUBLIC_C15T_URL in your .env file to point to your c15t backend (e.g., https://your-instance.c15t.dev).

Create a client provider component

Create a 'use client' component that accepts an ssrData prop. 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';
import type { ConsentManagerProps } from '@c15t/nextjs';

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

Info

Don't have a backend yet? Use mode: 'offline' to get started with local-only consent storage. See Client Modes for details.

Optional: SSR Initial Data (App Directory)

In a server component wrapping the provider, call fetchInitialData to pre-fetch consent data. Do not await the call — pass the Promise directly to the client component so Next.js can stream the response while data loads. By prefetching the data on the server the banner can appear visually sooner, however this can increase TTFB if your app is fully client-side rendered.

import { fetchInitialData } from '@c15t/nextjs';
import type { ReactNode } from 'react';
import ConsentManagerProvider from './provider';

export function ConsentManager({ children }: { children: ReactNode }) {
  const ssrData = fetchInitialData({
    backendURL: '/api/c15t',
    // Shows banner during development. Remove for production.
    overrides: { country: 'DE' },
  });

  return (
    <ConsentManagerProvider ssrData={ssrData}>
      {children}
    </ConsentManagerProvider>
  );
}

Then use it in your layout:

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

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

Info

Do not await fetchInitialData() in the Server Component. Passing the unresolved Promise lets Next.js stream the page while the consent data loads in parallel.

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

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.

Optional: Install Agent Skills

Install c15t agent skills to let AI agents help with styling, i18n, scripts & other configuration.

npx @c15t/cli@rc skills

See AI Tools for details.

Next steps

Script Loader

Gate third-party scripts like Google Analytics and Meta Pixel behind consent.

Styling

Customize colors, typography, spacing, and individual component slots.

Consent Categories

Understand the five consent categories and how to configure them.

Components

Explore the full set of pre-built consent UI components.

AI Agent Skills

Let AI assistants help configure styling, i18n, and scripts.