@zerakicreative/cookie-consent

A beautiful, GDPR-compliant cookie consent widget with GSAP animations. Supports CCPA, LGPD, PDPA, POPIA, PIPEDA and Google Analytics Consent Mode v2 out of the box.

Install

npm install @zerakicreative/cookie-consent

Quick start

ES Module (React / Vue / Svelte / TypeScript)

import { CookieBanner } from '@zerakicreative/cookie-consent';

new CookieBanner({
  logo:             '/logo.png',
  primaryColor:     '#2563EB',
  privacyPolicyUrl: '/privacy',
  cookiePolicyUrl:  '/cookies',
  googleAnalytics: {
    measurementId:      'G-XXXXXXXXXX',
    consentModeVersion: 'v2',
    autoLoad:           true,
  },
}).init();

Script tag (CDN / self-hosted)

<!-- Before </body> -->
<script src="https://cdn.jsdelivr.net/npm/@zerakicreative/cookie-consent/dist/zeraki-cookie-consent.iife.js"></script>
<script>
  ZerakiCookieBanner.init({
    primaryColor:     '#2563EB',
    privacyPolicyUrl: '/privacy',
    cookiePolicyUrl:  '/cookies',
  });
</script>

Configuration

new CookieBanner({
  // Branding
  logo:             '/logo.png',       // URL to your logo image
  companyName:      'Your Company',    // Used in modal and aria labels

  // Legal links
  privacyPolicyUrl: '/privacy',
  cookiePolicyUrl:  '/cookies',

  // Appearance
  primaryColor:     '#2563EB',         // Any CSS colour value
  theme:            'light',           // 'light' | 'dark' | 'auto'
  position:         'bottom-bar',      // See positions below
  customStyles:     '',                // Inject extra CSS

  // Floating cookie button
  showFloatingButton:     true,
  floatingButtonPosition: 'bottom-right', // 'bottom-right' | 'bottom-left'

  // Behaviour
  autoShow:          true,             // Show banner on first visit
  autoDetectRegion:  true,             // Auto-detect regulation by timezone
  forcedRegion:      'gdpr',           // Override: 'gdpr' | 'ccpa' | 'lgpd' | 'pdpa' | 'pipeda' | 'popia' | 'other'
  cookieExpiry:      365,              // Days before consent expires
  consentVersion:    '1',             // Bump to re-prompt after policy changes

  // Google Analytics
  googleAnalytics: {
    measurementId:      'G-XXXXXXXXXX',
    tagManagerId:       'GTM-XXXXXXX', // Optional — GTM instead of direct GA
    consentModeVersion: 'v2',          // 'v1' | 'v2'
    autoLoad:           true,          // Load GA script automatically
  },

  // Callbacks
  onReady:         ()          => {},
  onConsentChange: (consent)   => console.log(consent),
  onAcceptAll:     (consent)   => {},
  onRejectAll:     ()          => {},
}).init();

Banner positions

| Value | Description | |---|---| | bottom-bar | Full-width bar at the bottom (default) | | top-bar | Full-width bar at the top | | bottom-left | Floating card, bottom-left | | bottom-right | Floating card, bottom-right | | bottom-center | Floating card, bottom-center |

Consent object

The onConsentChange callback receives a ConsentState:

{
  necessary:   true,           // always true
  analytics:   boolean,
  marketing:   boolean,
  preferences: boolean,
  timestamp:   string,         // ISO 8601
  version:     string,
  region?:     RegionCode,
}

Custom translations

new CookieBanner({
  translations: {
    bannerTitle: 'We value your privacy',
    bannerText:  'We use cookies to improve your experience.',
    acceptAll:   'Accept all',
    rejectAll:   'Reject all',
    customize:   'Manage preferences',
    categories: {
      analytics: {
        name:        'Analytics',
        description: 'Help us understand how visitors use our site.',
      },
    },
  },
}).init();

Programmatic control

const banner = new CookieBanner({ ... }).init();

banner.show();           // Show the consent banner
banner.hide();           // Hide the banner
banner.showModal();      // Open the preferences modal
banner.acceptAll();      // Accept all categories
banner.rejectAll();      // Reject all non-essential
banner.getConsent();     // Returns current ConsentState | null
banner.resetConsent();   // Clear saved consent and re-show banner

License

MIT © Zeraki