@afex-dapps/cookie

A modern, flexible cookie consent management library for React applications. This library simplifies cookie consent handling, ensuring GDPR compliance while providing a customizable and user-friendly experience.

Features

• 🎨 Customizable UI and Themes: Easily style the cookie banner using CSS variables or the styles prop.
• 🌐 Internationalization (i18n) Support: Define translations for multiple languages and auto-detect user preferences.
• 🔒 GDPR-Compliant Cookie Management: Manage cookies with opt-in/opt-out modes and auto-clear functionality.
• ⚡ Lightweight and Fast: Minimal performance overhead with efficient design.
• 🔄 Auto-Clearing Cookies: Automatically clear cookies based on user preferences.
• 🤖 Bot Detection: Prevent bots and crawlers from interacting with the cookie banner.
• 📱 Responsive Design: Fully responsive and mobile-friendly.

Installation

Install the library and its peer dependency using your preferred package manager:

npm install @afex-dapps/cookie vanilla-cookieconsent
# or
yarn add @afex-dapps/cookie vanilla-cookieconsent
# or
pnpm add @afex-dapps/cookie vanilla-cookieconsent

Quick Start

1. Import the Required CSS

import "vanilla-cookieconsent/dist/cookieconsent.css";

2. Basic Usage Example

import { useCookieBanner, createCookieConfiguration } from "@afex-dapps/cookie";
import { Fragment } from "react";

import "vanilla-cookieconsent/dist/cookieconsent.css";

const configuration = createCookieConfiguration({
  categories: {
    necessary: { enabled: true, readOnly: true },
    analytics: { enabled: true },
  },
  language: {
    default: "en",
    translations: {
      en: {
        consentModal: {
          title: "Cookie preferences",
          description: "We use cookies to enhance your experience.",
          acceptAllBtn: "Accept all",
          acceptNecessaryBtn: "Accept necessary only",
        },
      },
    },
  },
});

export function App() {
  const { userId, updateUserId } = useCookieBanner({ configuration });
  return <Fragment>{/* Your app content */}</Fragment>;
}

Customization

Theming & Styles

Via styles Prop

import { createCookieStyles } from "@afex-dapps/cookie";

const styles = createCookieStyles({
  ".cc--darkmode": {
    "--cc-bg": "#000",
    "--cc-color": "#fff",
  },
});

useCookieBanner({ styles, activeTheme: "dark" });

Via CSS Variables

#cc-main .cm__btn[data-role="all"] {
  --cc-btn-primary-bg: #093159;
}

#cc-main .cm__btn[data-role="necessary"] {
  --cc-btn-primary-color: #eaeff2;
  --cc-btn-primary-bg: #1c75e1;
}

#cc-main .cm__btn--secondary {
  --cc-btn-secondary-bg: transparent;

  &:hover {
    --cc-btn-secondary-bg: #1c75e1;
  }
}

Advanced Usage

Google Consent Mode

Integrate with Google Consent Mode for advanced analytics. See the Google Consent Mode Guide.

Working with User Preferences

import { useCookieBanner } from "@afex-dapps/cookie";
import * as CookieConsent from "vanilla-cookieconsent";

function CookieManager() {
  const { acceptCategory, acceptService, getUserPreferences, show, hide } =
    CookieConsent;
  const { updateUserId } = useCookieBanner();
  const preferences = getUserPreferences();

  return (
    <div>
      <h1>User Preferences</h1>
      <pre>{JSON.stringify(preferences, null, 2)}</pre>
      <button onClick={() => show()}>Show Cookie Banner</button>
      <button onClick={hide}>Hide Cookie Banner</button>
      <button onClick={() => acceptCategory("analytics")}>
        Accept Analytics Cookies
      </button>
      <button onClick={() => acceptService("ga")}>
        Accept Google Analytics Cookies
      </button>
      <button onClick={() => updateUserId("newUserId")}>Update User ID</button>
    </div>
  );
}

Advanced Configuration Example

const configuration = createCookieConfiguration({
  autoClearCookies: true,
  autoShow: true,
  manageScriptTags: true,
  hideFromBots: true,
  disablePageInteraction: false,
  cookie: {
    name: "cc_gdpr",
    path: "/",
    expiresAfterDays: 182,
    sameSite: "Lax",
    useLocalStorage: false,
  },
  categories: {
    necessary: { enabled: true, readOnly: true },
    analytics: {
      enabled: true,
      autoClear: { cookies: [{ name: /^(_ga|_gid|mp_)/ }] },
      services: {
        ga: {
          label: "Google Analytics",
          cookies: [{ name: /^(_ga|_gid)/ }],
        },
      },
    },
  },
});

useCookieBanner({ configuration });

Exports

Functions

• useCookieBanner: A React hook to manage the cookie banner lifecycle and user interactions.
• createCookieConfiguration: Utility to create a cookie consent configuration by merging defaults with custom options.
• createCookieStyles: Utility to define custom styles for the cookie banner.
• css: Helper function to generate CSS variable strings for cookie styles.

Types

• CookieBannerProps: Props for the useCookieBanner hook, including delay, configuration, and firebase options.
• CookieVariable: List of CSS variables available for styling the cookie banner.
• CookieConsentConfiguration: Configuration options for the cookie consent modal, including categories, language, and callbacks.
• FirebaseConfig: Configuration for integrating Firebase to store cookie consent data.

Constants

• cookieConsentAttributes: An object containing data attributes to control the cookie consent manager from HTML elements.
• cookieConsentEvents: An object containing event names dispatched by the cookie consent manager.

API Reference

useCookieBanner Hook

| Return Value | Type | Description | | ------------------------ | -------- | ---------------------------------------- | | userId | string | Unique identifier for the current user | | updateUserId | Function | Update the user's identifier | | retrieveUserCookieData | Function | Retrieve stored cookie data for the user | | updateUserCookieData | Function | Update the stored cookie data for user |

createCookieConfiguration

Merges the default configuration with custom options to create a complete cookie consent configuration.

createCookieStyles

Defines custom styles for the cookie banner using CSS properties and nested selectors.

css

Generates CSS variable strings for cookie styles, e.g., var(--cc-primary-color).

External Library

For more in-depth information about the underlying cookie consent functionality, refer to the vanilla-cookieconsent documentation.

License

MIT License - see the LICENSE file for details.