API Reference

Global Object

All Zest methods are available on the global Zest object.

Initialization

Zest.init(config)

Manually initialize Zest with a configuration object. Only needed if autoInit is set to false.

Zest.init({
  position: 'bottom-right',
  theme: 'dark'
});

UI Control

Zest.show()

Show the consent banner.

Zest.show();

Zest.hide()

Hide the consent banner.

Zest.hide();

Zest.showSettings()

Open the settings modal where users can customize their preferences.

Zest.showSettings();

Zest.hideSettings()

Close the settings modal.

Zest.hideSettings();

Zest.reset()

Clear all consent data and show the banner again. Useful for “reset preferences” buttons.

Zest.reset();

Consent Management

Zest.getConsent()

Get the current consent state for all categories.

const consent = Zest.getConsent();
// Returns: { essential: true, functional: false, analytics: false, marketing: false }

Zest.hasConsent(category)

Check if a specific category has consent.

if (Zest.hasConsent('analytics')) {
  // Initialize analytics tracking
  initAnalytics();
}

Zest.hasConsentDecision()

Check if the user has made any consent decision (accept or reject).

if (!Zest.hasConsentDecision()) {
  // User hasn't decided yet
  console.log('Waiting for consent...');
}

Zest.acceptAll()

Programmatically accept all consent categories.

Zest.acceptAll();

Zest.rejectAll()

Programmatically reject all non-essential categories.

Zest.rejectAll();

Zest.getConsentProof()

Get consent proof data for compliance records.

const proof = Zest.getConsentProof();
// Returns: {
//   version: "1.0",
//   timestamp: 1234567890,
//   categories: { essential: true, ... }
// }

Zest.updateConsent(selections)

Since v2.0.0.

Save an arbitrary set of category selections. Useful when building a custom UI (especially with the headless entry) — pass the checkbox state from your own form.

Zest.updateConsent({
  analytics: true,
  marketing: false,
  functional: true
});

Categories you don’t include keep their previous state. Unknown keys are ignored. The cookie is written and the usual zest:change / zest:consent events are dispatched.

Geo Targeting

Zest.resolveGeo()

Since v2.4.0.

Resolve the visitor’s jurisdiction and act on it, returning a Promise of { action, verdict }. Only meaningful when geo gating is configured — resolves null when geo isn’t set or a consent decision already exists. init() triggers resolution automatically; this method lets you await the result directly (the primary pattern for the headless build, which renders no UI):

import Zest from '@freshjuice/zest/headless';

Zest.init({ geo: true });

const result = await Zest.resolveGeo();
if (result) {
  const { action, verdict } = result;
  // action: 'consent' | 'notice' | 'allow' | 'block'
  // verdict: { isEU, isEEA, isGDPR, isCCPA, isUSPrivacy, regulations } or null on failure
}

The same result also reaches you via the onGeo(action, verdict) callback and the zest:geo DOM event. When geo is configured, the init() snapshot reports geoPending: true until resolution completes.

Privacy Detection

Zest.isDoNotTrackEnabled()

Check if Do Not Track (DNT) or Global Privacy Control (GPC) is enabled.

if (Zest.isDoNotTrackEnabled()) {
  console.log('User has privacy signals enabled');
}

Zest.getDNTDetails()

Get details about which privacy signal is enabled.

const dnt = Zest.getDNTDetails();
// Returns: { enabled: true, source: 'gpc' }
// source can be: 'dnt', 'gpc', or null

Configuration

Zest.getConfig()

Get the current Zest configuration.

const config = Zest.getConfig();
console.log(config.position); // 'bottom-right'

Events

Zest.on(event, callback)

Since v2.0.0.

Subscribe to a Zest event. Returns an unsubscribe function.

const unsubscribe = Zest.on('consent', (consent) => {
  if (consent.analytics) initAnalytics();
});

// Later — stop listening
unsubscribe();

The event name can be passed with or without the zest: prefix ('consent' and 'zest:consent' are equivalent). Use Zest.EVENTS for constants.

Zest.once(event, callback)

Since v2.0.0.

Same as Zest.on(), but the callback fires at most once and then auto-unsubscribes.

Zest.once('ready', (consent) => {
  console.log('Zest is ready with:', consent);
});

Zest.EVENTS

Object containing all event names for reference.

console.log(Zest.EVENTS);
// {
//   READY: 'zest:ready',
//   CONSENT: 'zest:consent',
//   REJECT: 'zest:reject',
//   CHANGE: 'zest:change',
//   SHOW: 'zest:show',
//   HIDE: 'zest:hide',
//   GEO: 'zest:geo'
// }

// Use constants with on()/once()
Zest.on(Zest.EVENTS.CHANGE, handleChange);

Practical Examples

Conditional Script Loading

document.addEventListener('zest:consent', (e) => {
  if (e.detail.consent.analytics) {
    // Load Google Analytics
    const script = document.createElement('script');
    script.src = 'https://www.googletagmanager.com/gtag/js?id=GA-XXXXX';
    document.head.appendChild(script);
  }
});

Cookie Preferences Button

<button onclick="Zest.showSettings()">Cookie Preferences</button>

Reset Consent Link

<a href="#" onclick="Zest.reset(); return false;">Reset Cookie Settings</a>

Check Before Tracking

function trackEvent(name, data) {
  if (Zest.hasConsent('analytics')) {
    gtag('event', name, data);
  }
}

Wait for Consent

async function waitForAnalyticsConsent() {
  return new Promise((resolve) => {
    if (Zest.hasConsent('analytics')) {
      resolve(true);
      return;
    }

    document.addEventListener('zest:consent', (e) => {
      if (e.detail.consent.analytics) {
        resolve(true);
      }
    });

    document.addEventListener('zest:reject', () => {
      resolve(false);
    });
  });
}

// Usage
const hasAnalytics = await waitForAnalyticsConsent();
if (hasAnalytics) {
  initAnalytics();
}