Skip to main content
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.

​
Reading visitor & banner data

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'
FieldTypeDescription
modestringThe 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[] }
}
FieldTypeDescription
acceptTypestringThe type of consent given — 'all', 'custom', 'necessary', or '' if none yet.
acceptedCategoriesstring[]Names of the categories the visitor accepted.
rejectedCategoriesstring[]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.

​
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:
PropertyAvailable onDescription
detail.cookieall consent eventsThe saved consent object. Use getUserPreferences() for parsed preferences.
detail.changedCategoriescc:onUpdateArray of category names whose acceptance changed.
detail.changedServicescc:onUpdateObject of services whose acceptance changed, keyed by category.

​
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:
PropertyDescription
detail.modalNameThe name of the modal that triggered the event (e.g. the consent or preferences modal).

​
Controlling the banner

​
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