Configuration

Configuration Methods

Zest can be configured in three ways (in order of priority):

1. window.ZestConfig object - Highest priority
2. Data attributes on the script tag
3. Default values - Lowest priority

Using ZestConfig Object

<script>
  window.ZestConfig = {
    position: 'bottom-right',
    theme: 'auto',
    accentColor: '#0071e3',
    policyUrl: '/privacy-policy',
    mode: 'safe',
    expiration: 365
  };
</script>
<script src="https://unpkg.com/@freshjuice/zest"></script>

Using Data Attributes

<script
  src="https://unpkg.com/@freshjuice/zest"
  data-position="bottom-right"
  data-theme="auto"
  data-accent-color="#0071e3"
  data-policy-url="/privacy-policy"
  data-mode="safe"
  data-expiration="365"
  data-consent-mode-google
  data-consent-mode-microsoft
></script>

Complete Options Reference

UI Options

Option	Type	Default	Description
position	string	'bottom'	Banner position: 'bottom', 'bottom-left', 'bottom-right', 'top'
theme	string	'auto'	Color theme: 'light', 'dark', 'auto' (follows system preference)
accentColor	string	'#0071e3'	Primary button color. Validated — hex, named, rgb(), rgba(), hsl(), hsla()
showWidget	boolean	true	Show floating widget after consent is given

Behavior Options

Option	Type	Default	Description
autoInit	boolean	true	Automatically initialize on page load
expiration	number	365	Consent cookie expiration in days (1-365)
mode	string	'safe'	Script blocking mode (see below)
blockedDomains	array	[]	Additional domains to block

Consent Mode Integrations

Option	Type	Default	Description
consentModeGoogle	boolean	false	Enable Google Consent Mode v2 integration
consentModeMicrosoft	boolean	false	Enable Microsoft UET Consent Mode integration

When enabled, Zest automatically pushes a 'default' denied state on initialization and sends 'update' signals on every consent change. See Consent Mode examples for usage.

Privacy Options

Option	Type	Default	Description
respectDNT	boolean	true	Respect Do Not Track and Global Privacy Control signals
dntBehavior	string	'reject'	DNT behavior: 'reject', 'preselect', 'ignore'

Links

Option	Type	Default	Description
policyUrl	string	null	URL to privacy policy page. Validated — allowlist: http:, https:, mailto:, tel:, or relative
imprintUrl	string	null	URL to imprint/legal page. Same validation as policyUrl

Language Options

Option	Type	Default	Description
lang	string	'auto'	Language code or 'auto' for detection

Available languages: en, de, es, fr, it, pt, nl, pl, uk, ru, ja, zh

Advanced Options

Option	Type	Default	Description
customStyles	string	''	Custom CSS to inject into Shadow DOM. Sanitized (20 KB cap; strips @import, @charset, expression(), -moz-binding, external url(), accept/reject-button selectors)
labels	object	{}	Custom UI text labels. All interpolated values are HTML-escaped
categories	object	{}	Custom category definitions
callbacks	object	{}	Lifecycle callbacks. Exceptions are logged and swallowed
intercept	object	{ cookies: true, storage: true, scripts: true }	Disable individual interceptor channels. Headless integrations that gate optional scripts and storage themselves can opt out per channel (v2.2.0+)
essentialKeys	array	[]	Exact storage / cookie names to treat as strictly-necessary. Each is anchored as ^name$ and appended to the essential category — built-in essential patterns stay intact (v2.2.0+)
essentialPatterns	array	[]	Regex source strings appended to the essential category. Validated via safeRegExp; 500-char cap (v2.2.0+)
patterns	object	{}	Custom regex patterns for cookie categorization. Replaces the patterns for any category passed in. Prefer essentialKeys / essentialPatterns when you only want to add to the essential category. 500-char cap; catastrophic-backtracking patterns rejected

Headless integration example

When you bring your own UI and want Zest only for the consent state machine:

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

Zest.init({
  // Disable script blocking — you handle gating yourself
  intercept: { scripts: false },

  // Tell Zest your app's storage keys are strictly-necessary,
  // so the storage interceptor doesn't classify them as marketing
  // and block the user's explicit setItem() calls.
  essentialKeys: ['my_app_settings', 'theme_pref'],

  respectDNT: true,
  expiration: 365
});

Blocking Modes

Zest supports four script blocking modes:

Mode	Description
manual	Only blocks scripts with explicit data-consent-category attribute
safe	Manual + known major trackers (Google Analytics, Facebook, GTM)
strict	Safe + extended trackers (Hotjar, Mixpanel, Segment, etc.)
doomsday	Block ALL third-party scripts

window.ZestConfig = {
  mode: 'safe' // Recommended for most sites
};

DNT Behavior Options

When respectDNT is true, the dntBehavior option controls what happens:

Behavior	Description
'reject'	Auto-reject all non-essential cookies, don't show banner
'preselect'	Show banner with non-essential categories unchecked
'ignore'	Ignore DNT/GPC signals completely

Custom Blocked Domains

Add additional domains to block:

window.ZestConfig = {
  mode: 'safe',
  blockedDomains: [
    'custom-tracker.com',
    { domain: 'analytics-service.com', category: 'analytics' }
  ]
};

Custom Labels

Override any UI text:

window.ZestConfig = {
  labels: {
    banner: {
      title: 'Cookie Settings',
      description: 'We use cookies to improve your experience.',
      acceptAll: 'Accept All',
      rejectAll: 'Reject All',
      settings: 'Customize'
    },
    modal: {
      title: 'Privacy Preferences',
      save: 'Save Preferences',
      acceptAll: 'Accept All',
      rejectAll: 'Reject All'
    },
    widget: {
      label: 'Cookie Settings'
    }
  }
};

Callbacks

React to consent lifecycle events:

window.ZestConfig = {
  callbacks: {
    onReady: (consent) => {
      console.log('Zest initialized:', consent);
    },
    onAccept: (consent) => {
      console.log('User accepted:', consent);
    },
    onReject: () => {
      console.log('User rejected all');
    },
    onChange: (consent) => {
      console.log('Consent changed:', consent);
    }
  }
};

Full Example

window.ZestConfig = {
  // UI
  position: 'bottom-right',
  theme: 'auto',
  accentColor: '#0071e3',
  showWidget: true,

  // Behavior
  autoInit: true,
  expiration: 365,
  mode: 'safe',

  // Consent Mode
  consentModeGoogle: true,
  consentModeMicrosoft: false,

  // Privacy
  respectDNT: true,
  dntBehavior: 'reject',

  // Links
  policyUrl: '/privacy-policy',
  imprintUrl: '/legal',

  // Language
  lang: 'auto',

  // Callbacks
  callbacks: {
    onAccept: (consent) => {
      if (consent.analytics) {
        // Initialize analytics
      }
    }
  }
};