Programmatic API

The bundle.js produced by cookiepal build is the recommended deployment path, but everything it does is a thin wrapper around the public API in @cookiepal-oss/consent. You can import the package directly and drive the banner yourself — useful for SPAs, Shopify themes, or any setup where you'd rather ship through your own build.

Install

pnpm add @cookiepal-oss/consent

Create a manager

import { createConsentManager, type CookiepalConfig } from '@cookiepal-oss/consent';

const config: CookiepalConfig = {
  categories: [
    { slug: 'necessary', required: true },
    { slug: 'analytics' },
    { slug: 'advertisement' },
  ],
  banner: {
    notice: { layout: 'box', position: 'bottomLeft' },
    preferences: { layout: 'center' },
    accentColor: '#EF8600',
  },
  integrations: {
    gcm: { enabled: true },
  },
};

const manager = createConsentManager(config);

createConsentManager(config) is also exposed as cookiepal.run(config) on the IIFE bundle — the bootstrap line in bundle.js is literally window.cookiepal.run(config).

The `ConsentManager` interface

All methods are synchronous.

Reading state

manager.getConsent();
// => { necessary: true, analytics: false, advertisement: false }

manager.acceptAll();
manager.rejectAll();
manager.acceptCategory('analytics');
manager.rejectCategory('analytics');

Controlling the UI

manager.showBanner();
manager.hideBanner();
manager.showPreferences();
manager.hidePreferences();
manager.showFab();
manager.hideFab();

Reacting to changes

manager.on('consent', (state) => {
  console.log('consent changed:', state);
});

The manager dispatches a cookiepal_consent_update CustomEvent on document whenever consent changes; on('consent', cb) is a thin wrapper over that listener. A one-time cookiepal_banner_load CustomEvent fires after the banner first mounts.

import { CONSENT_EVENT, BANNER_LOAD_EVENT } from '@cookiepal-oss/consent';

document.addEventListener(CONSENT_EVENT, (e) => {
  const state = (e as CustomEvent).detail;
});

document.addEventListener(BANNER_LOAD_EVENT, () => {
  // banner is on the page
});

Custom action handlers

Buttons inside the banner dispatch named actions (e.g. accept, reject, customise). Override or augment the default handlers:

manager.setActionHandler((action) => {
  analytics.track('consent_click', { action });
});

manager.reconfigure({
  notice: { layout: 'popup' },
  accentColor: '#000000',
});

Takes a Partial<CookiepalConfig> | BannerConfig and remounts the banner with the merged config. Wrappers stay mounted across calls so transient visibility and CSS animations survive the swap. Useful for locale switches or theme toggles inside SPAs.

Teardown

manager.destroy();

Removes the banner, disables the script blocker, detaches integration listeners, and removes the consent-event listener. Call it before creating a new manager.

Preview mode

Set preview: true on the config to render the banner without activating side-effects — no script blocking, no backend POST, no cookie sweeping. The dashboard uses this internally for the live preview pane.

createConsentManager({ ...config, preview: true });

Debug mode

createConsentManager({ ...config, debug: true });

Turns on console.log tracing for the manager and every enabled integration. Logs are prefixed with [cookiepal] and [cookiepal:<integration>].

Script blocking

If you include a scriptBlocking array on the config, the manager intercepts <script> tags matching a pattern and only lets them execute when their category is consented. See the Configuration reference for the rule shape.

Backend logging

Set backendURL to enable consent logging. When a visitor changes consent, the manager POSTs { consentId, consent } to <backendURL>/consent. The server is responsible for stamping everything else (IP, User-Agent, timestamp). See Self-hosting the backend.