Headless Mode

c15t's headless mode means using the hooks (useConsentManager, useTranslations, etc.) without any pre-built UI components. This gives you complete control over the consent experience.

There are three levels of customization:

Props - Use pre-built components with custom text and configuration
noStyle - Use pre-built components with their structure but strip all styles
Headless - Use only hooks and build the entire UI yourself

When to Go Headless

Go headless when:

Your design system requires complete control over markup
You need a consent flow that doesn't fit the banner/dialog pattern
You want to embed consent choices inline rather than as overlays

Use noStyle instead when:

The component structure works but the styling doesn't
You want to apply your own CSS/Tailwind without fighting defaults

import { useConsentManager, useTranslations } from '@c15t/nextjs';

function CustomConsentBanner() {
  const {
    activeUI,
    consents,
    consentCategories,
    consentTypes,
    saveConsents,
    setSelectedConsent,
    selectedConsents,
  } = useConsentManager();
  const translations = useTranslations();

  if (activeUI !== 'banner') return null;

  const displayedTypes = consentTypes.filter(
    (t) => consentCategories.includes(t.name) && t.display
  );

  return (
    <div className="fixed bottom-0 inset-x-0 bg-white border-t p-6 shadow-lg z-50">
      <h2 className="text-lg font-semibold">
        {translations.cookieBanner.title}
      </h2>
      <p className="text-sm text-gray-600 mt-1">
        {translations.cookieBanner.description}
      </p>

      <div className="mt-4 space-y-3">
        {displayedTypes.map((type) => (
          <label key={type.name} className="flex items-center gap-3">
            <input
              type="checkbox"
              checked={
                selectedConsents[type.name] ?? consents[type.name] ?? false
              }
              disabled={type.disabled}
              onChange={(e) => setSelectedConsent(type.name, e.target.checked)}
            />
            <div>
              <span className="font-medium">
                {translations.consentTypes[type.name]?.title ?? type.name}
              </span>
              <p className="text-xs text-gray-500">{type.description}</p>
            </div>
          </label>
        ))}
      </div>

      <div className="mt-4 flex gap-3">
        <button
          onClick={() => saveConsents('necessary')}
          className="px-4 py-2 border rounded"
        >
          {translations.common.rejectAll}
        </button>
        <button
          onClick={() => saveConsents('custom')}
          className="px-4 py-2 border rounded"
        >
          {translations.common.save}
        </button>
        <button
          onClick={() => saveConsents('all')}
          className="px-4 py-2 bg-blue-600 text-white rounded"
        >
          {translations.common.acceptAll}
        </button>
      </div>
    </div>
  );
}

Usage with Provider

The headless UI still needs a ConsentManagerProvider:

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

export function ConsentManager({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'c15t',
        backendURL: '/api/c15t',
        consentCategories: ['necessary', 'measurement', 'marketing'],
      }}
    >
      <CustomConsentBanner />
      {children}
    </ConsentManagerProvider>
  );
}

Custom Dialog

Build a custom consent dialog for detailed category management:

import { useConsentManager, useTranslations } from '@c15t/nextjs';

function CustomConsentDialog() {
  const {
    activeUI,
    setActiveUI,
    consentTypes,
    consentCategories,
    selectedConsents,
    consents,
    setSelectedConsent,
    saveConsents,
    has,
  } = useConsentManager();
  const translations = useTranslations();

  if (activeUI !== 'dialog') return null;

  return (
    <div className="fixed inset-0 z-50 flex items-center justify-center">
      <div
        className="absolute inset-0 bg-black/50"
        onClick={() => setActiveUI('none')}
      />
      <div className="relative bg-white rounded-xl p-6 max-w-md w-full">
        <h2 className="text-lg font-semibold">
          {translations.consentManagerDialog.title}
        </h2>

        {consentTypes
          .filter((t) => consentCategories.includes(t.name))
          .map((type) => (
            <div
              key={type.name}
              className="flex items-center justify-between py-3 border-b"
            >
              <div>
                <p className="font-medium">
                  {translations.consentTypes[type.name]?.title}
                </p>
                <p className="text-sm text-gray-500">{type.description}</p>
              </div>
              <input
                type="checkbox"
                checked={
                  selectedConsents[type.name] ?? consents[type.name] ?? false
                }
                disabled={type.disabled}
                onChange={(e) =>
                  setSelectedConsent(type.name, e.target.checked)
                }
              />
            </div>
          ))}

        <div className="mt-4 flex justify-end gap-2">
          <button onClick={() => saveConsents('necessary')}>Reject</button>
          <button onClick={() => saveConsents('custom')}>Save</button>
          <button onClick={() => saveConsents('all')}>Accept All</button>
        </div>
      </div>
    </div>
  );
}

Headless Mode

When to Go Headless

Full Example: Custom Consent Banner

Usage with Provider

Custom Dialog