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