> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cookiechimp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> The complete client-side API — read the visitor's consent and the banner that was served, listen for consent events, and control the banner programmatically. Everything you can do from your own JavaScript, on one page.

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.

<Warning>
  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](#listening-for-events) such as `cc:onModalReady` or `cc:onConsented`,
  or after a check for `window.CookieChimp`.
</Warning>

## 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.

<Snippet file="visitor-properties.mdx" />

### `getConfig()`

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

```js theme={null}
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). |

<Tip>
  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](/advanced/banner-overrides).
</Tip>

## Reading the visitor's consent

### `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`

```typescript theme={null}
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.                             |

```js theme={null}
// 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;
```

```js theme={null}
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`.

```js theme={null}
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`.

```js theme={null}
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)

```js theme={null}
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](#consent-events)               | `cc:onFirstConsent`, `cc:onConsented`, `cc:onUpdate`                        | When the visitor accepts, rejects, or changes preferences.                                                                |
| [Modal events](#modal-events)                   | `cc:beforeModalShow`, `cc:onModalShow`, `cc:onModalHide`, `cc:onModalReady` | At each stage of the banner / preferences modal lifecycle.                                                                |
| [Consent string events](#consent-string-events) | `cc:consentStringUpdated`                                                   | When `window.cookieChimpConsentString` is (re)built — used by the [Adobe Launch](/installation/adobe-launch) integration. |

### Consent events

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).

```js theme={null}
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.

```js theme={null}
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.

```js theme={null}
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.              |

### Modal events

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)`.

```js theme={null}
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);
});
```

<Tip>
  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.
</Tip>

#### `cc:onModalShow`

The consent modal is visible.

```js theme={null}
window.addEventListener("cc:onModalShow", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});
```

#### `cc:onModalHide`

The consent modal is hidden.

```js theme={null}
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](#reading-visitor--banner-data), because those properties are guaranteed to be populated by the time it fires.

```js theme={null}
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). |

### Consent string events

CookieChimp also publishes the visitor's choices as a flat, comma-separated string on `window.cookieChimpConsentString`. The [Adobe Launch](/installation/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.

<Note>
  Google Tag Manager uses its own consent signal — a `cookiechimp_consent_update`
  push on `dataLayer`, not this DOM event. See the [Google Tag
  Manager](/installation/google-tag-manager) guide for the GTM-specific setup.
</Note>

#### `window.cookieChimpConsentString`

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

```js theme={null}
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.

```js theme={null}
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
  }
});
```

<Tip>
  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](/installation/adobe-launch) guide for a complete recipe.
</Tip>

## 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.

```js theme={null}
CookieChimp.show();

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

### `hide`

Hides the consent banner.

```js theme={null}
CookieChimp.hide();
```

### `showPreferences`

Shows the preferences modal.

```js theme={null}
CookieChimp.showPreferences();
```

### `hidePreferences`

Hides the preferences modal.

```js theme={null}
CookieChimp.hidePreferences();
```

### `acceptCategory`

Programmatically accept or reject a cookie category.

```js theme={null}
// 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.

```js theme={null}
// 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.

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

```js theme={null}
CookieChimp.reset(true);

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

## Next steps

* [Advanced Banner Overrides](/advanced/banner-overrides) — full end-to-end recipes built on the properties and events above.
* [Custom Update Consent Button](/advanced/custom-update-consent-button) — wire `showPreferences` to your own button.
* [Custom CSS](/advanced/custom-css) — the full list of CSS variables you can override.