Events

CookieBoss dispatches events whenever a visitor makes a consent choice. Use these to conditionally load scripts, update your UI, or integrate with tag managers.

cookieboss:update CustomEvent

A CustomEvent is dispatched on document every time consent changes (accept all, reject all, or custom selection):

javascript

document.addEventListener('cookieboss:update', (event) => {
const categories = event.detail.categories;

console.log('Consent updated:', categories);
// { necessary: true, analytics: true, marketing: false, functional: true }

if (categories.analytics) {
  // Initialize analytics
}

if (categories.marketing) {
  // Load marketing pixels
}
});

Event detail shape

Name	Type	Required	Default	Description
`categories.necessary`	`true`	Yes	-	Always true
`categories.analytics`	`boolean`	Yes	-	Analytics consent granted
`categories.marketing`	`boolean`	Yes	-	Marketing consent granted
`categories.functional`	`boolean`	Yes	-	Functional consent granted

GTM dataLayer events

If GTM integration is enabled in your dashboard, CookieBoss automatically pushes events to window.dataLayer:

Event names

Event	When it fires
`cookieboss_consent_update`	Every consent change (accept, reject, or custom)
`cookieboss_consent_accept_all`	Visitor clicks “Accept All”
`cookieboss_consent_reject_all`	Visitor clicks “Reject All”

dataLayer payload

dataLayer push shape javascript

{
event: "cookieboss_consent_update",
cookieboss: {
  siteId: "01KHJTD0CZG42333Z4P3F6X7Z4",
  consent: {
    necessary: true,
    analytics: true,
    marketing: false,
    functional: true
  }
}
}

Using in GTM

Create a Custom Event trigger for cookieboss_consent_update
Create Data Layer Variables to read cookieboss.consent.analytics, cookieboss.consent.marketing, etc.
Add firing conditions to your tags (e.g. only fire Google Analytics when cookieboss.consent.analytics equals true)

See the full GTM Integration guide for step-by-step instructions.

Listening on page load

The cookieboss:update event fires when the visitor interacts with the banner. If you need to check consent on initial page load (e.g. for a returning visitor who already consented), use getConsent():

javascript

// On page load: check existing consent
document.addEventListener('DOMContentLoaded', () => {
if (window.__cookieboss) {
  const consent = window.__cookieboss.getConsent();
  if (consent.analytics) {
    initAnalytics();
  }
}
});

// On consent change: react to updates
document.addEventListener('cookieboss:update', (event) => {
if (event.detail.categories.analytics) {
  initAnalytics();
}
});

onConsent callback

window.__cookieboss.onConsent(callback) registers a plain callback for code that cannot listen for a DOM event, such as a sandboxed Google Tag Manager template. The callback receives the same categories object as event.detail.categories:

once straight away, with the decision already applied on this page (a returning visitor’s stored choice, or a choice made before you registered);
with all optional categories false if the stored choice has expired or you asked visitors to consent again;
after that, on every change.

If nothing has been decided yet on this page, it is not called until the visitor chooses.

javascript

window.__cookieboss.onConsent((categories) => {
// { necessary: true, analytics: true, marketing: false, functional: true }
if (categories.marketing) {
  loadMarketingPixel();
}
});

Each call gets a fresh object, and an error thrown by one callback does not stop the others. window.__cookieboss exists once the CookieBoss script has run, so register after it has loaded.

For most integrations, you don’t need to manually listen for events. CookieBoss handles Google Consent Mode and script blocking automatically. Events are useful for custom integrations or when you need fine-grained control.