CookieBoss

Lightweight cookie consent manager for any website. GDPR, CCPA, and ePrivacy compliant — zero dependencies, under 5KB gzipped.

Installation

npm / yarn / pnpm

npm install cookieboss

CDN (script tag)

<script src="https://cdn.cookieboss.io/scripts/YOUR_SITE_ID/consent.js" async></script>

Get your Site ID at cookieboss.io

Quick Start

With a bundler (React, Vue, Next.js, etc.)

import { CookieBoss } from 'cookieboss';

const cb = CookieBoss.init({
  siteId: 'your-site-id',
});

// React to consent changes
cb.onConsentChange((categories) => {
  if (categories.analytics) {
    // Load Google Analytics, Plausible, etc.
  }
  if (categories.marketing) {
    // Load Facebook Pixel, Google Ads, etc.
  }
});

With a script tag

<script src="https://cdn.cookieboss.io/scripts/YOUR_SITE_ID/consent.js" async></script>

The CDN script auto-initializes with your dashboard configuration. No additional JavaScript needed.

API Reference

CookieBoss.init(config)

Creates and returns a CookieBoss instance. Loads the consent script and shows the banner automatically (unless autoShow: false).

const cb = CookieBoss.init({
  siteId: 'your-site-id',
  layout: 'modal',
  primaryColor: '#4F46E5',
  darkMode: 'auto',
});

cb.getConsent()

Returns the current consent categories, or null if the user hasn't consented yet.

const consent = cb.getConsent();
if (consent?.analytics) {
  // Analytics allowed
}

cb.hasConsent(category)

Check if a specific category has been granted.

if (cb.hasConsent('marketing')) {
  loadFacebookPixel();
}

cb.onConsentChange(callback)

Register a callback that fires whenever consent changes. Returns an unsubscribe function. Also fires when consent changes in another browser tab.

const unsubscribe = cb.onConsentChange((categories) => {
  console.log('Analytics:', categories.analytics);
  console.log('Marketing:', categories.marketing);
  console.log('Functional:', categories.functional);
});

// Later:
unsubscribe();

cb.acceptAll()

Programmatically accept all consent categories.

cb.rejectAll()

Programmatically reject all non-essential categories.

cb.savePreferences(prefs)

Save specific consent preferences.

cb.savePreferences({
  analytics: true,
  marketing: false,
  functional: true,
});

cb.resetConsent()

Clear all consent data. The banner will re-appear on next page load.

cb.show()

Show the consent banner programmatically (e.g., from a "Cookie Settings" link in your footer).

document.getElementById('cookie-settings').addEventListener('click', () => {
  cb.show();
});

cb.destroy()

Clean up the CookieBoss instance, remove the script element and all listeners.

Configuration

Option	Type	Default	Description
siteId	string	—	Required. Your CookieBoss site ID.
autoShow	boolean	true	Auto-load and show the banner on init.
layout	string	'bottom-bar'	Banner style: 'bottom-bar', 'modal', or 'preference-center'.
position	string	'bottom'	Position: 'bottom', 'top', or 'center'.
primaryColor	string	'#627D98'	Primary brand color (hex).
accentColor	string	'#27AB83'	Button/accent color (hex).
textColor	string	'#2D3748'	Text color (hex).
backgroundColor	string	'#FFFFFF'	Banner background color (hex).
animation	string	'slide-up'	Entry animation: 'none', 'fade', 'slide-up', 'slide-down', 'slide-left', 'slide-right'.
darkMode	boolean | 'auto'	false	Dark mode. 'auto' detects system preference.
showPoweredBy	boolean	true	Show "Powered by CookieBoss" attribution.
consentMode	string	'signal-only'	'signal-only' fires events; 'full-blocking' blocks scripts until consent.
gcmEnabled	boolean	false	Enable Google Consent Mode v2.
gtmEnabled	boolean	false	Enable Google Tag Manager dataLayer events.
gpcEnabled	boolean	false	Honor Global Privacy Control (GPC) signals.
uetEnabled	boolean	false	Enable Microsoft UET consent mode.
texts	object	—	Localized text strings keyed by language code.
defaultLanguage	string	'en'	Default language code.
geoRules	object	—	Geo-based compliance rules (EU opt-in, CA opt-out, etc.).
cookies	array	—	Cookie inventory shown in the preference center.
consentExpiryMs	number	5 years	How long consent is remembered.
cookieDomain	string	—	Cookie domain for cross-subdomain sharing (e.g., '.example.com').

Consent Categories

CookieBoss tracks four standard categories:

Category	Description	Can be disabled?
necessary	Essential cookies (auth, security, CSRF)	No — always enabled
analytics	Traffic analysis, performance monitoring	Yes
marketing	Advertising, retargeting, profiling	Yes
functional	Site features (maps, embeds, chat widgets)	Yes

Integrations

Google Consent Mode v2

const cb = CookieBoss.init({
  siteId: 'your-site-id',
  gcmEnabled: true,
});

CookieBoss automatically sets gtag('consent', 'default', ...) before GTM loads and updates consent state via gtag('consent', 'update', ...) when the user makes a choice.

Google Tag Manager

const cb = CookieBoss.init({
  siteId: 'your-site-id',
  gtmEnabled: true,
});

Pushes cookieboss_consent_update, cookieboss_consent_accept_all, and cookieboss_consent_reject_all events to window.dataLayer.

Script Blocking

const cb = CookieBoss.init({
  siteId: 'your-site-id',
  consentMode: 'full-blocking',
});

In full-blocking mode, add data-cookieboss-category to scripts you want to block until consent:

<script data-cookieboss-category="analytics" src="https://example.com/analytics.js"></script>
<script data-cookieboss-category="marketing" src="https://example.com/pixel.js"></script>

TypeScript

Full TypeScript support with exported types:

import type { CookieBossConfig, ConsentCategories } from 'cookieboss';

Why CookieBoss?

• Lightweight — Under 5KB gzipped. No bloated UI frameworks.
• GDPR & CCPA compliant — Geo-aware rules, opt-in/opt-out modes, GPC support.
• Zero dependencies — Pure vanilla JS. Works everywhere.
• Shadow DOM isolation — Banner styles never conflict with your site's CSS.
• Google Consent Mode v2 — First-class support, no extra setup.
• IAB TCF 2.3 — Full Transparency & Consent Framework support.
• Cross-domain consent — Share consent state across your domains.
• A/B testing — Built-in banner variant testing.
• Script & content blocking — Block third-party scripts and iframes until consent.

Learn more at cookieboss.io.

License

MIT © CookieBoss