timdoddcool/cookiedialog

By timdoddcool

•Updated about 1 year ago

CookieDialog Documentation - GDPR Cookie Consent Library

Image

1.1K

Overview Tags

timdoddcool/cookiedialog repository overview

⁠CookieDialog

A lightweight, customizable GDPR cookie consent dialog with built-in geolocation support. Zero dependencies, easy integration via CDN or NPM.

⁠Features

🚀 Lightweight - Less than 20KB gzipped
📍 Geolocation Detection - Automatically detect if GDPR compliance is required
💾 Local Storage - Persistent consent management
🎨 Customizable - Multiple themes and full translation support
📱 Responsive - Mobile-friendly design
🔧 Zero Dependencies - Pure JavaScript, no external libraries required
⚡ Easy Integration - Simple CDN or NPM installation

⁠Quick Start

⁠CDN Installation

Add these lines to your HTML:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/cookiedialog.min.css">
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cookiedialog.min.js"></script>

<script>
  CookieDialog.init({
    enableLocation: true,
    privacyUrl: '/privacy',
    onAccept: (consent) => {
      console.log('Consent given:', consent);
    }
  });
</script>

⁠NPM Installation

npm install cookiedialog

import CookieDialog from 'cookiedialog';
import 'cookiedialog/dist/cookiedialog.min.css';

const dialog = new CookieDialog({
  enableLocation: true,
  theme: 'dark',
  position: 'bottom'
});

dialog.init();

⁠Configuration Options

Option	Type	Default	Description
`enableLocation`	boolean	false	Enable geolocation detection for GDPR regions
`autoShow`	boolean	true	Automatically show dialog on page load
`position`	string	'bottom'	Dialog position: 'bottom', 'top', or 'center'
`theme`	string	'light'	Theme: 'light' or 'dark'
`privacyUrl`	string	undefined	URL to your privacy policy
`cookiePolicyUrl`	string	undefined	URL to your cookie policy
`expiryDays`	number	365	Consent expiry in days
`forceShow`	boolean	false	Always show dialog regardless of consent
`categories`	array	[...]	Cookie categories configuration
`translations`	object	{...}	Custom translations
`onAccept`	function	undefined	Callback when user accepts (includes reason and location data)
`onReject`	function	undefined	Callback when user rejects
`onChange`	function	undefined	Callback when settings change
`onLocationNotRequired`	function	undefined	Callback when geolocation determines consent not needed

⁠API Methods

const dialog = CookieDialog.init(config);

// Show/hide dialog
dialog.show();
dialog.hide();

// Get consent status
const consent = dialog.getConsent();
// Returns: { 
//   timestamp: 123456789, 
//   categories: { necessary: true, analytics: false }, 
//   version: '1.0.0',
//   reason: 'user_accept' | 'user_reject' | 'location_not_required',
//   locationData?: { country: 'US', region: 'California', inEU: false, detectionMethod: 'ip_geolocation' }
// }

// Check if consent exists
const hasConsent = dialog.hasConsent(); // boolean

// Get specific category consent
const analyticsConsent = dialog.getCategoryConsent('analytics'); // boolean

// Reset consent
dialog.resetConsent();

// Destroy dialog
dialog.destroy();

⁠Custom Categories

CookieDialog.init({
  categories: [
    {
      id: 'necessary',
      name: 'Essential Cookies',
      description: 'Required for the website to function',
      required: true
    },
    {
      id: 'analytics',
      name: 'Analytics',
      description: 'Help us understand how you use our site',
      required: false
    },
    {
      id: 'marketing',
      name: 'Marketing',
      description: 'Used for targeted advertising',
      required: false
    }
  ]
});

⁠Custom Translations

CookieDialog.init({
  translations: {
    title: 'Cookie Preferences',
    description: 'We use cookies to improve your experience',
    acceptButton: 'Accept All',
    rejectButton: 'Reject All',
    settingsButton: 'Manage Settings',
    privacyLink: 'Privacy Policy',
    // ... more translations
  }
});

⁠Geolocation Detection

When enableLocation is enabled, the dialog will automatically detect if the user is in a GDPR-required region (EU/EEA) and only show the dialog if necessary.

CookieDialog.init({
  enableLocation: true,
  geolocationEndpoint: 'https://your-api.com/location', // Optional custom endpoint
  onLocationNotRequired: (locationData) => {
    console.log('GDPR not required for:', locationData);
    // User is not in EU/EEA - all cookies automatically accepted
  },
  onAccept: (consent) => {
    if (consent.reason === 'location_not_required') {
      console.log('Auto-accepted due to location:', consent.locationData);
    } else if (consent.reason === 'user_accept') {
      console.log('User manually accepted cookies');
    }
  }
});

⁠Browser Support

Chrome/Edge 88+
Firefox 78+
Safari 14+
Opera 74+

⁠Development

# Install dependencies
npm install

# Development build with watch
npm run dev

# Production build
npm run build

# Run tests
npm test

⁠License

MIT License - see LICENSE⁠ file for details.

⁠Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⁠Documentation

📚 Full documentation available at:

Docker (Self-hosted):

docker run -p 8080:80 timdoddcool/cookiedialog:latest
# Visit http://localhost:8080

Online: cookiedialog.com⁠

See DOCKER.md⁠ for detailed deployment instructions.

⁠Support

For issues and feature requests, please use the GitHub issues page⁠.

Tag summary

Recent tags

Content type

Image

Digest

sha256:a57c48431…

Size

22 MB

Last updated

about 1 year ago

docker pull timdoddcool/cookiedialog