PRIV ProtocolPRIV Docs
Compliance SDK

Consent Banner

API reference for the ConsentBanner class - customizable, accessible GDPR cookie banner.

Consent Banner

The ConsentBanner provides a fully customizable, accessible cookie consent banner with a preferences modal.


Initialization

import {
  ConsentManager,
  ConsentBanner,
  createConsentBanner,
  AuditLog,
} from '@priv/compliance-sdk';

// Initialize consent manager first
const consent = new ConsentManager({ siteId: 'your-site-id' });

// Optional: Initialize audit log for tracking
const audit = new AuditLog({ siteId: 'your-site-id' });

// Create banner
const banner = new ConsentBanner(consent, {
  position: 'bottom-right',
  theme: {
    primaryColor: '#2563eb',
  },
}, audit);

// Initialize (auto-shows if no consent given)
banner.init();

Configuration

BannerConfig

interface BannerConfig {
  /** Banner position on screen */
  position?: 'bottom' | 'top' | 'bottom-left' | 'bottom-right' | 'center';

  /** Visual theme customization */
  theme?: BannerTheme;

  /** Text labels for internationalization */
  labels?: BannerLabels;

  /** Show close button (default: true) */
  showCloseButton?: boolean;

  /** Respect browser Do Not Track (default: true) */
  respectDoNotTrack?: boolean;

  /** Auto-show on init if no consent (default: true) */
  autoShow?: boolean;

  /** Cookie name for storage */
  cookieName?: string;

  /** Cookie expiration in days */
  cookieExpireDays?: number;
}

BannerTheme

interface BannerTheme {
  /** Primary button color */
  primaryColor?: string;    // Default: '#2563eb'

  /** Secondary text color */
  secondaryColor?: string;  // Default: '#64748b'

  /** Background color */
  backgroundColor?: string; // Default: '#ffffff'

  /** Text color */
  textColor?: string;       // Default: '#1e293b'

  /** Border radius */
  borderRadius?: string;    // Default: '12px'

  /** Font family */
  fontFamily?: string;      // Default: system fonts

  /** Base font size */
  fontSize?: string;        // Default: '14px'

  /** z-index for stacking */
  zIndex?: number;          // Default: 999999
}

BannerLabels

Customize all text for internationalization:

interface BannerLabels {
  title?: string;
  description?: string;
  acceptAll?: string;
  rejectAll?: string;
  customize?: string;
  save?: string;
  close?: string;
  privacyPolicy?: string;
  privacyPolicyUrl?: string;
  categories?: {
    necessary?: { label: string; description: string };
    analytics?: { label: string; description: string };
    marketing?: { label: string; description: string };
    personalization?: { label: string; description: string };
    social?: { label: string; description: string };
  };
}

Methods

init()

Initialize and auto-show the banner if needed.

// Will show banner if user hasn't given consent
await banner.init();

Returns: Promise<void>

The banner auto-shows if:

  • No consent has been given
  • autoShow config is true (default)
  • Do Not Track is not enabled (if respectDoNotTrack is true)

show()

Manually show the consent banner.

// Force show the banner
await banner.show();

Returns: Promise<void>

Will not show if:

  • Consent has already been given
  • Do Not Track is enabled (with respectDoNotTrack: true)
  • Banner is already visible

hide()

Hide the consent banner.

banner.hide();

Returns: void


showPreferences()

Show the preferences modal for granular consent control.

// Allow users to update preferences anytime
document.getElementById('cookie-settings')?.addEventListener('click', () => {
  banner.showPreferences();
});

Returns: void


destroy()

Remove the banner and clean up resources.

// Cleanup
banner.destroy();

Returns: void

This removes:

  • Banner element
  • Preferences modal
  • Injected styles

Full Example

Basic Setup

import { ConsentManager, ConsentBanner, AuditLog } from '@priv/compliance-sdk';

const consent = new ConsentManager({
  siteId: 'my-site',
  api: {
    endpoint: 'https://api.priv.io/v1',
    apiKey: 'pk_xxx',
  },
});

const audit = new AuditLog({
  siteId: 'my-site',
});

const banner = new ConsentBanner(consent, {
  position: 'bottom-right',
  respectDoNotTrack: true,
  showCloseButton: true,
}, audit);

// Auto-initialize
banner.init();

Custom Theme

const banner = new ConsentBanner(consent, {
  position: 'bottom',
  theme: {
    primaryColor: '#10b981',      // Green
    secondaryColor: '#6b7280',
    backgroundColor: '#1f2937',   // Dark background
    textColor: '#f9fafb',         // Light text
    borderRadius: '0',            // Full width
    fontFamily: '"Inter", sans-serif',
    fontSize: '15px',
  },
});

Custom Labels (Internationalization)

// German example
const banner = new ConsentBanner(consent, {
  labels: {
    title: 'Wir respektieren Ihre Privatsphare',
    description: 'Wir verwenden Cookies, um Ihre Erfahrung zu verbessern.',
    acceptAll: 'Alle akzeptieren',
    rejectAll: 'Alle ablehnen',
    customize: 'Anpassen',
    save: 'Speichern',
    close: 'Schliessen',
    privacyPolicy: 'Datenschutz',
    privacyPolicyUrl: '/datenschutz',
    categories: {
      necessary: {
        label: 'Notwendig',
        description: 'Erforderlich fur die Funktionalitat der Website.',
      },
      analytics: {
        label: 'Analytik',
        description: 'Hilft uns zu verstehen, wie Besucher die Website nutzen.',
      },
      marketing: {
        label: 'Marketing',
        description: 'Wird fur personalisierte Werbung verwendet.',
      },
      personalization: {
        label: 'Personalisierung',
        description: 'Ermoglicht personalisierte Funktionen.',
      },
      social: {
        label: 'Soziale Medien',
        description: 'Ermoglicht die Integration sozialer Medien.',
      },
    },
  },
});

Add a link in your footer to reopen preferences:

<footer>
  <a href="#" id="cookie-settings">Cookie Settings</a>
</footer>

<script>
  document.getElementById('cookie-settings').addEventListener('click', (e) => {
    e.preventDefault();
    banner.showPreferences();
  });
</script>

Accessibility

The banner includes accessibility features:

  • ARIA roles: dialog, aria-labelledby, aria-describedby
  • Keyboard navigation: Tab through buttons
  • Escape key: Closes preferences modal
  • Focus management: Focus trapped in modal
  • Semantic HTML: Proper heading structure

Styling

CSS Classes

The banner uses these CSS classes you can target:

/* Main banner */
#priv-consent-banner { }
.priv-banner-header { }
.priv-banner-title { }
.priv-banner-description { }
.priv-banner-buttons { }
.priv-banner-footer { }

/* Buttons */
.priv-btn { }
.priv-btn-primary { }
.priv-btn-secondary { }
.priv-btn-outline { }

/* Preferences modal */
#priv-consent-preferences { }
.priv-preferences-modal { }
.priv-preferences-title { }
.priv-category { }
.priv-category-header { }
.priv-category-title { }
.priv-category-description { }
.priv-toggle { }
.priv-toggle-slider { }

Override Styles

/* Custom overrides */
#priv-consent-banner {
  font-family: 'Your Font', sans-serif !important;
}

#priv-consent-banner .priv-btn-primary {
  background: linear-gradient(to right, #6366f1, #8b5cf6) !important;
}

Do Not Track

When respectDoNotTrack: true (default):

  1. Banner checks navigator.doNotTrack
  2. If DNT is enabled, automatically rejects all non-necessary cookies
  3. Banner is not shown to the user
const banner = new ConsentBanner(consent, {
  respectDoNotTrack: true, // Honor browser DNT setting
});

Type Definitions

/** Banner position options */
type BannerPosition =
  | 'bottom'
  | 'top'
  | 'bottom-left'
  | 'bottom-right'
  | 'center';

/** Category label and description */
interface CategoryLabel {
  readonly label: string;
  readonly description: string;
}

/** ConsentBanner class interface */
class ConsentBanner {
  constructor(
    consentManager: IConsentManager,
    config?: BannerConfig,
    auditLog?: AuditLog
  );

  init(): Promise<void>;
  show(): Promise<void>;
  hide(): void;
  showPreferences(): void;
  destroy(): void;
}

Next Steps