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
autoShowconfig istrue(default)- Do Not Track is not enabled (if
respectDoNotTrackistrue)
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.',
},
},
},
});Privacy Settings Link
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):
- Banner checks
navigator.doNotTrack - If DNT is enabled, automatically rejects all non-necessary cookies
- 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
- Consent Manager - Manage consent state
- Audit Log - Track banner events
- Script Embed - Easy script integration