@xms-ai/real-cookies

Lightweight, GDPR / UK GDPR / LGPD / PIPEDA-compliant cookie consent banner for vanilla JavaScript projects. No dependencies. Optional Supabase integration for cross-device persistence.

Features

• Auto-detect jurisdiction — uses IP geolocation to show GDPR, UK GDPR, LGPD, or PIPEDA UI
• Granular consent — per-category toggles (Necessary, Functional, Analytics, Marketing)
• Supabase sync — stores consent records in your Supabase DB (free tier compatible)
• Zero runtime deps — vanilla JS, no jQuery, no frameworks
• Google Consent Mode v2 — automatically calls gtag('consent', 'update', …)
• Accessible — ARIA roles, keyboard navigation, focus-visible outlines
• Customizable — brand color, logo, dark/light theme, bottom/top/popup position

Installation

npm install @xms-ai/real-cookies

Or via CDN:

<script src="https://cdn.jsdelivr.net/npm/@xms-ai/real-cookies/dist/cookie-consent.min.js"></script>

Quick Start

ESM (npm)

import CookieConsent from '@xms-ai/real-cookies';

await CookieConsent.init({
  companyName:  'Acme Corp',
  primaryColor: '#1a73e8',
  privacyUrl:   '/privacy',

  // Optional: Supabase persistence
  supabaseUrl:  'https://xxxx.supabase.co',
  supabaseKey:  'your-anon-public-key',
});

Script tag

<script src="dist/cookie-consent.min.js"></script>
<script>
  CookieConsent.init({
    companyName: 'Acme Corp',
    privacyUrl:  '/privacy',
  });
</script>

All Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | companyName | string | 'Our Company' | Name shown in the banner | | companyLogo | string | null | URL to a logo image | | primaryColor | string | '#1a73e8' | Brand color for buttons/toggles | | theme | 'light'\|'dark' | 'light' | Banner color scheme | | position | 'bottom'\|'top'\|'popup' | 'bottom' | Banner placement | | privacyUrl | string | '#' | Link to your Privacy Policy | | cookiePolicyUrl | string | null | Link to your Cookie Policy | | supabaseUrl | string | null | Supabase project URL | | supabaseKey | string | null | Supabase anon public key | | categories | object | see below | Override/add cookie categories | | autoShow | boolean | true | Auto-show banner when no consent | | cookieExpiry | number | 365 | Days until re-consent required | | forceMode | string | null | Force compliance mode ('GDPR', 'UK_GDPR', 'LGPD', 'PIPEDA', 'BASIC') |

JavaScript API

// Check consent for a category
if (CookieConsent.hasConsent('analytics')) {
  // load analytics
}

// Get full consent object
const consent = CookieConsent.getConsent();
// { type: 'custom', categories: { necessary: true, analytics: false, … }, … }

// Open settings panel programmatically
CookieConsent.openSettings();

// Reset consent and re-show banner
CookieConsent.resetConsent();

// Listen for consent events
window.addEventListener('vc:consent', (e) => {
  console.log('User decision:', e.detail.type); // 'accept_all' | 'reject_all' | 'custom'
  console.log('Categories:', e.detail.categories);
});

// Per-category events
window.addEventListener('vc:consent:analytics', (e) => {
  if (e.detail.enabled) initGoogleAnalytics();
});

Supabase Setup

1. Open your Supabase SQL Editor
2. Run the contents of supabase-schema.sql
3. Pass your project URL and anon key to init()

The schema creates a cookie_consents table with Row Level Security enabled so anonymous users can only manage their own records.

Compliance Modes

| Mode | Triggered for | Behavior | |------|--------------|---------| | GDPR | EU / EEA / Switzerland | Opt-in, Reject All required, granular controls | | UK_GDPR | United Kingdom | Same as GDPR | | LGPD | Brazil | Opt-in, Portuguese text, granular controls | | PIPEDA | Canada | Opt-out model, granular controls | | BASIC | Rest of world | Simple notice, no reject button |

Custom Categories

CookieConsent.init({
  categories: {
    analytics: {
      name: 'Analytics',
      description: 'Help us understand how visitors use the site.',
      required: false,
      cookies: [
        { name: '_ga', domain: '.google.com', duration: '2 years', type: 'HTTP', description: 'Google Analytics' },
      ],
    },
    // Add entirely new categories:
    preferences: {
      name: 'Preferences',
      description: 'Remember your settings like language and region.',
      required: false,
      cookies: [],
    },
  },
});

Building from Source

npm install
npm run build
# → dist/cookie-consent.js       (IIFE, readable)
# → dist/cookie-consent.min.js   (IIFE, minified)
# → dist/cookie-consent.esm.js   (ES module)

Watch mode:

node build.js --watch

License

MIT © XMS Ai