@afex-dapps/cookie NPM

@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