JavaScript SDK

When the CookieChimp script loads, it exposes a global CookieChimp object (also available as window.CookieChimp). Everything on this page is read from — or called on — that object. Use it to:

Read data — what the visitor consented to, and which banner was served to them (country, region, consent mode).
Listen for events — react the moment consent is given, changed, or the modal is shown or hidden.
Control the banner — show, hide, accept, reject, or reset consent programmatically.

The CookieChimp object and its properties are populated once the script has initialised. If you read them too early — for example, at the very top of the page — they may be undefined. Read them inside an event handler such as cc:onModalReady or cc:onConsented, or after a check for window.CookieChimp.

CookieChimp exposes properties on the CookieChimp object that tell you about the visitor’s location and the banner that was served to them. They’re useful when you want to customise behaviour or tags based on country, region, or consent mode — without duplicating banners.

`CookieChimp.visitorCountry`

The ISO 3166-1 alpha-2 country code of the visitor (e.g. "US", "GB", "CN", "DE").

CookieChimp.visitorCountry; // 'US'

`CookieChimp.visitorRegion`

The region/subdivision code of the visitor (e.g. "NY" for New York, "CA" for California). Useful when compliance rules differ by region within a country — for example, US state privacy laws.

CookieChimp.visitorRegion; // 'NY'

`CookieChimp.visitorNeedsConsent`

true if a consent banner was shown to the visitor (either an opt-in or opt-out banner), false if the visitor's location does not require one.

CookieChimp.visitorNeedsConsent; // true

`CookieChimp.getConfig()['mode']`

Returns the consent mode that was applied to the visitor based on your geolocation rules:

"opt-in" — the visitor was shown an opt-in banner (e.g. EU/EEA visitors under GDPR).
"opt-out" — the visitor was shown an opt-out banner (e.g. US visitors under CCPA-style regulations).

CookieChimp.getConfig().mode; // 'opt-in'

These properties are populated once the CookieChimp script has initialised. If you read them before initialisation — for example, at the very top of the page — they may be undefined. Read them inside a callback or event handler such as cc:onModalReady, cc:onConsented, or after a check for window.CookieChimp.

`getConfig()`

Returns the resolved configuration for the banner that was served to the current visitor. The most commonly read field is mode:

CookieChimp.getConfig(); // { mode: 'opt-in', ... }

// the consent mode applied to this visitor
CookieChimp.getConfig().mode; // 'opt-in' or 'opt-out'

Field	Type	Description
`mode`	`string`	The consent mode applied to the visitor based on your geolocation rules — `'opt-in'` (e.g. GDPR) or `'opt-out'` (e.g. CCPA-style).

For end-to-end recipes that use these properties — hiding a button for visitors from one country, firing analytics tags by consent mode, or per-domain branding — see Advanced Banner Overrides.

`getUserPreferences`

Returns the visitor’s accepted/rejected categories and services. This is the primary way to read what the user consented to. Type: function(): object

function(): {
    acceptType: string,
    acceptedCategories: string[],
    rejectedCategories: string[],
    acceptedServices: { [category: string]: string[] },
    rejectedServices: { [category: string]: string[] }
}

Field	Type	Description
`acceptType`	`string`	The type of consent given — `'all'`, `'custom'`, `'necessary'`, or `''` if none yet.
`acceptedCategories`	`string[]`	Names of the categories the visitor accepted.
`rejectedCategories`	`string[]`	Names of the categories the visitor rejected.
`acceptedServices`	`{ [category]: string[] }`	Accepted services, keyed by the category they belong to.
`rejectedServices`	`{ [category]: string[] }`	Rejected services, keyed by the category they belong to.

// the full preferences object
CookieChimp.getUserPreferences();

// type of consent given ('', 'all', 'necessary' or 'custom')
CookieChimp.getUserPreferences().acceptType;

// accepted categories (array of accepted category names)
CookieChimp.getUserPreferences().acceptedCategories;

// rejected categories (array of rejected category names)
CookieChimp.getUserPreferences().rejectedCategories;

// accepted services (object of accepted services, keyed by category)
CookieChimp.getUserPreferences().acceptedServices;

// rejected services (object of rejected services, keyed by category)
CookieChimp.getUserPreferences().rejectedServices;

var preferences = CookieChimp.getUserPreferences();

if (preferences.acceptType === "all") {
  console.log("Everything has been accepted!");
}

if (preferences.acceptedCategories.includes("analytics")) {
  console.log("The analytics category was accepted!");
}

`acceptedCategory`

Returns true if the specified category was accepted by the user, otherwise false.

if (CookieChimp.acceptedCategory("analytics")) {
  // "analytics" category was accepted
} else {
  // not accepted
}

`acceptedService`

Returns true if the specified service was accepted by the user, otherwise false.

if (CookieChimp.acceptedService("Google Analytics", "analytics")) {
  // "Google Analytics" service was accepted
} else {
  // not accepted
}

`validConsent`

Returns true if consent is valid. Consent is NOT valid when at least one of following situations occurs:

consent is missing (e.g. user has not yet made a choice)
CookieChimp’s cookie does not exist/has expired
CookieChimp’s cookie is structurally not valid (e.g. empty)

if (CookieChimp.validConsent()) {
  // consent is valid
} else {
  // consent is not valid
}

Listening for events

Every event is a standard DOM event dispatched on window. Subscribe with window.addEventListener and read the data from event.detail. CookieChimp dispatches three families of events:

Category	Events	When they fire
Consent events	`cc:onFirstConsent`, `cc:onConsented`, `cc:onUpdate`	When the visitor accepts, rejects, or changes preferences.
Modal events	`cc:beforeModalShow`, `cc:onModalShow`, `cc:onModalHide`, `cc:onModalReady`	At each stage of the banner / preferences modal lifecycle.
Consent string events	`cc:consentStringUpdated`	When `window.cookieChimpConsentString` is (re)built — used by the Adobe Launch integration.

These fire whenever the visitor’s consent state changes. For example, when the visitor gives consent for the first time, reloads a page on which consent is already stored, or changes their preferences from the privacy trigger.

`cc:onFirstConsent`

Triggered the first time the user expresses their choice of consent (accept/reject).

window.addEventListener("cc:onFirstConsent", function (event) {
  var detail = event.detail;
  // detail.cookie — the saved consent object (see getUserPreferences for parsed preferences)

  // do something
});

`cc:onConsented`

Triggered the very first time the user expresses their choice of consent — just like onFirstConsent — but also on every subsequent page load.

window.addEventListener("cc:onConsented", function (event) {
  var detail = event.detail;
  // detail.cookie — the saved consent object

  // do something
});

`cc:onUpdate`

Triggered when the user modifies their preferences, and only if consent has already been provided.

window.addEventListener("cc:onUpdate", function (event) {
  var detail = event.detail;
  /**
   * detail.cookie             — the saved consent object
   * detail.changedCategories  — array of category names that changed
   * detail.changedServices    — object of services that changed, keyed by category
   */

  // do something
});

The data carried by each consent event:

Property	Available on	Description
`detail.cookie`	all consent events	The saved consent object. Use `getUserPreferences()` for parsed preferences.
`detail.changedCategories`	`cc:onUpdate`	Array of category names whose acceptance changed.
`detail.changedServices`	`cc:onUpdate`	Object of services whose acceptance changed, keyed by category.

These cover the lifecycle of the consent banner and preferences modal — from being attached to the DOM to being shown and hidden.

`cc:beforeModalShow`

Dispatched right before the consent modal is shown. This event is cancelable — call event.preventDefault() to prevent the banner from appearing. You can then show it later programmatically via CookieChimp.show(true).

window.addEventListener("cc:beforeModalShow", function (event) {
  var detail = event.detail;
  // detail.modalName

  // Example: prevent the banner from showing automatically
  event.preventDefault();

  // ... and show it later when you're ready
  // CookieChimp.show(true);
});

This is useful when you want to delay the consent banner — for example, to wait until a user has completed onboarding, or to show it only after a certain interaction.

`cc:onModalShow`

The consent modal is visible.

window.addEventListener("cc:onModalShow", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

`cc:onModalHide`

The consent modal is hidden.

window.addEventListener("cc:onModalHide", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

`cc:onModalReady`

The consent modal is created and appended to the DOM. This is the safest place to read visitor & banner data, because those properties are guaranteed to be populated by the time it fires.

window.addEventListener("cc:onModalReady", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

The data carried by each modal event:

Property	Description
`detail.modalName`	The name of the modal that triggered the event (e.g. the consent or preferences modal).

CookieChimp also publishes the visitor’s choices as a flat, comma-separated string on window.cookieChimpConsentString. The Adobe Launch integration is built on this property and the matching event below — it pairs well with any setup that prefers a single value over the structured getUserPreferences() object.

Google Tag Manager uses its own consent signal — a cookiechimp_consent_update push on dataLayer, not this DOM event. See the Google Tag Manager guide for the GTM-specific setup.

`window.cookieChimpConsentString`

A comma-separated list of every category and service the visitor has accepted, for example:

window.cookieChimpConsentString;
// => 'essential,analytics,marketing,Google Analytics,Hotjar,Facebook Pixel'

The string is rebuilt every time the visitor’s consent changes, so reading it inside a cc:consentStringUpdated listener (below) always reflects the latest state.

`cc:consentStringUpdated`

Triggered once consent has been granted and again every time the visitor changes their preferences, after window.cookieChimpConsentString has been rebuilt.

window.addEventListener("cc:consentStringUpdated", function () {
  // window.cookieChimpConsentString is up to date here
  var consent = window.cookieChimpConsentString || "";

  if (consent.split(",").indexOf("Google Analytics") !== -1) {
    // "Google Analytics" was accepted — fire the tag
  }
});

Tag managers usually need both pieces — read window.cookieChimpConsentString on page load to handle visitors who already consented on a previous visit, and listen for cc:consentStringUpdated to handle real-time changes. See the Adobe Launch guide for a complete recipe.

`show`

Shows the consent banner. If consent was previously expressed, the consent modal will not be generated; you’ll have to pass the argument true to generate it on the fly.

CookieChimp.show();

// show modal (if it doesn't exist, create it)
CookieChimp.show(true);

`hide`

Hides the consent banner.

CookieChimp.hide();

`showPreferences`

Shows the preferences modal.

CookieChimp.showPreferences();

`hidePreferences`

Hides the preferences modal.

CookieChimp.hidePreferences();

`acceptCategory`

Programmatically accept or reject a cookie category.

// accept all categories
CookieChimp.acceptCategory("all");

// reject all (accept only categories marked as readOnly/necessary)
CookieChimp.acceptCategory([]);

// accept currently selected categories inside the preferences modal
CookieChimp.acceptCategory();

// accept only the "analytics" category
CookieChimp.acceptCategory("analytics");

// accept only these 2 categories
CookieChimp.acceptCategory(["analytics", "marketing"]);

// accept all categories except the "analytics" category
CookieChimp.acceptCategory("all", ["analytics"]);

// accept all categories except these 2
CookieChimp.acceptCategory("all", ["analytics", "marketing"]);

`acceptService`

Accepts or rejects services.

// accept all services in the 'analytics' category
CookieChimp.acceptService("all", "analytics");

// reject all services
CookieChimp.acceptService([], "analytics");

// accept only specified service and reject all the others
CookieChimp.acceptService("Google Analytics", "analytics");

// accept only these 2 services and reject all the others
CookieChimp.acceptService(["service1", "service2"], "analytics");

`reset`

Resets CookieConsent by dropping all internal pointers and config. You can pass the argument true to delete CookieChimp’s cookie which holds the user’s consent & preferences. The user will be prompted again to express their consent.

Once this method is called, CookieChimp won’t be functional on the page. The webpage needs to be fully reloaded to re-initialise CookieChimp.

CookieChimp.reset(true);

// Reload the page
window.location.reload();

Next steps

Advanced Banner Overrides — full end-to-end recipes built on the properties and events above.
Custom Update Consent Button — wire showPreferences to your own button.
Custom CSS — the full list of CSS variables you can override.

Get Started

Platform Specific Installation

Features

Integrations

Advanced

Reading visitor & banner data

`CookieChimp.visitorCountry`

`CookieChimp.visitorRegion`

`CookieChimp.visitorNeedsConsent`

`CookieChimp.getConfig()['mode']`

`getConfig()`

`getUserPreferences`

`acceptedCategory`

`acceptedService`

`validConsent`

Listening for events

`cc:onFirstConsent`

`cc:onConsented`

`cc:onUpdate`

`cc:beforeModalShow`

`cc:onModalShow`

`cc:onModalHide`

`cc:onModalReady`

`window.cookieChimpConsentString`

`cc:consentStringUpdated`

Controlling the banner

`show`

`hide`

`showPreferences`

`hidePreferences`

`acceptCategory`

`acceptService`

`reset`

Next steps

​Reading visitor & banner data

​CookieChimp.visitorCountry

​CookieChimp.visitorRegion

​CookieChimp.visitorNeedsConsent

​CookieChimp.getConfig()['mode']

​getConfig()

​Reading the visitor’s consent

​getUserPreferences

​acceptedCategory

​acceptedService

​validConsent

​Listening for events

​Consent events

​cc:onFirstConsent

​cc:onConsented

​cc:onUpdate

​Modal events

​cc:beforeModalShow

​cc:onModalShow

​cc:onModalHide

​cc:onModalReady

​Consent string events

​window.cookieChimpConsentString

​cc:consentStringUpdated

​Controlling the banner

​show

​hide

​showPreferences

​hidePreferences

​acceptCategory

​acceptService

​reset

​Next steps

Reading visitor & banner data

`CookieChimp.visitorCountry`

`CookieChimp.visitorRegion`

`CookieChimp.visitorNeedsConsent`

`CookieChimp.getConfig()['mode']`

`getConfig()`

Reading the visitor’s consent

`getUserPreferences`

`acceptedCategory`

`acceptedService`

`validConsent`

Listening for events

Consent events

`cc:onFirstConsent`

`cc:onConsented`

`cc:onUpdate`

Modal events

`cc:beforeModalShow`

`cc:onModalShow`

`cc:onModalHide`

`cc:onModalReady`

Consent string events

`window.cookieChimpConsentString`

`cc:consentStringUpdated`

Controlling the banner

`show`

`hide`

`showPreferences`

`hidePreferences`

`acceptCategory`

`acceptService`

`reset`

Next steps