Home
Relevant source files
The following files were used as context for generating this wiki page:consent-manager is a comprehensive, flexible, and privacy-friendly cookie consent management solution. It is designed to be modular, allowing developers to use only the components they need, from the core consent management logic to a full suite of UI components and DOM integration tools. This modularity makes it adaptable to a wide variety of project designs and requirements.
The project is composed of three main parts: the core ConsentManager class that handles state, the DOMConnector for declarative DOM manipulation based on consent, and the GrantsInterface which provides ready-to-use UI elements like banners and modals.
Sources: README.md:5-9, package.json:2
Core Components
The library is structured around a central ConsentManager class, with optional modules for UI and DOM interaction.
This diagram shows the relationship between the core modules and their dependencies.
Sources: src/index.ts, package.json:49-52, src/modules/ConsentManager.ts:1, src/modules/GrantsInterface.ts:1
ConsentManager (Core Logic)
The ConsentManager class is the heart of the library. It is responsible for managing consent states, handling cookie storage, and providing an event-driven API for other parts of an application to react to consent changes.
Sources: src/modules/ConsentManager.ts
Initialization and Configuration
An instance is created with a configuration object. The version property is crucial; if it changes, all existing user consent preferences are disregarded, forcing a re-consent.
| Parameter | Type | Description | Default |
|---|---|---|---|
version | string | The version of the configuration. Changing this invalidates old consents. | 1 |
cookieName | string | The name of the cookie used to store preferences. | "consent-manager" |
expires | number | Date | 'session' | Expiration for the consent cookie in days, a specific Date, or 'session'. | 365 |
categories | object[] | An array defining the consent categories. | [] |
Sources: src/modules/ConsentManager.ts:60-70, 72-77, README.md:21-29
A category object has the following structure:
| Key | Type | Description |
|---|---|---|
id | string | Unique identifier for the category. |
label | string | Human-readable name for the category. |
description | string | Explanation of the category's purpose. |
required | boolean | If true, this category cannot be disabled by the user. |
default | boolean | The default consent state for this category if not required. Defaults to false. |
Sources: src/modules/ConsentManager.ts:64-69, README.md:33-62
Lifecycle and Data Flow
On initialization, ConsentManager attempts to parse an existing consent cookie. If a valid cookie matching the current version is found, its grants are loaded. Otherwise, it falls back to the default values defined in the configuration.
This diagram illustrates the initialization flow of the ConsentManager.
Sources: src/modules/ConsentManager.ts:83-119
Properties and Methods
| Property | Type | Description |
|---|---|---|
config | ConsentManagerConfig | The configuration object used to initialize the manager. |
grants | Record<string, boolean> | A key-value object where keys are category IDs and values are their boolean grant status. |
isCustomized | boolean | true if the user has made a choice, false otherwise. |
Sources: src/modules/ConsentManager.ts:79-81, README.md:69-84
Key methods for interacting with the ConsentManager:
| Method | Description |
|---|---|
setGrant(id, status) | Sets the grant status for a specific category ID. Use '*' as the ID to set all non-required categories. This action marks consent as customized and writes to the cookie. |
on(event, callback) | Registers an event listener for grant, revoke, or update events. |
off(event, callback) | Removes a previously registered event listener. |
Sources: src/modules/ConsentManager.ts:133-162, 164-184, README.md:88-115
DOMConnector
The DOMConnector module provides a declarative way to link DOM elements to consent grants. It automatically updates element attributes based on the user's consent choices, without requiring custom JavaScript logic.
Sources: src/modules/DOMConnector.ts, README.md:117-122
Usage
It is initialized by passing a ConsentManager instance. It then listens for update events to automatically refresh the DOM.
import ConsentManager, { DOMConnector } from 'consent-manager';
const consentManager = new ConsentManager({ ... });
new DOMConnector(consentManager);
Sources: src/modules/DOMConnector.ts:4-7, README.md:124-126
Attributes
The connector works by scanning for elements with the data-consent-manager attribute and interpreting other data-cm-* attributes.
| Attribute | Description |
|---|---|
data-consent-manager | Required attribute to make the element known to DOMConnector. |
data-cm-categories | A comma-separated list of category IDs. The element is considered "enabled" if at least one category is granted. |
data-cm-attribute | The name of the HTML attribute to set when enabled (e.g., src, style). |
data-cm-value | The value to apply to the attribute specified by data-cm-attribute. |
data-cm-inverted | If present, inverts the logic. The attribute is set when the required categories are not granted. |
Sources: README.md:128-137, src/modules/DOMConnector.ts:10, 15, 30, 35, 23
Logic Flow
The following diagram shows how DOMConnector processes an element.
This flow is executed on initialization and whenever a consent grant changes.
Sources: src/modules/DOMConnector.ts:26-44
GrantsInterface
This module provides pre-built UI components, including a cookie banner and a preferences modal, to allow users to manage their consent settings.
Sources: src/modules/GrantsInterface.ts, README.md:152-155
Usage and Configuration
It is initialized with a ConsentManager instance and an optional configuration object. By default, it automatically shows a banner if the user has not yet customized their consent.
| Parameter | Type | Description | Default |
|---|---|---|---|
autoShow | boolean | If true, the banner is shown automatically if consentManager.isCustomized is false. | true |
languageStrings | object | An object to override default text for the banner and modal. | (see default config) |
Sources: src/modules/GrantsInterface.ts:5-20, 22-41, README.md:166-191
UI Interaction Flow
The GrantsInterface listens for user actions and communicates them to the ConsentManager. It also listens to events from the ConsentManager to update its own state (e.g., hiding the banner after consent is given).
This diagram shows a typical user interaction with the consent banner.
Sources: src/modules/GrantsInterface.ts:45-47, 70-73, 102-106
Methods
If autoShow is disabled, the UI can be controlled manually:
| Method | Description |
|---|---|
showBanner() | Displays the consent banner. |
hideBanner() | Removes the consent banner from the DOM. |
showModal() | Displays the detailed preferences modal. |
hideModal() | Removes the preferences modal from the DOM. |
generateConsentTable(autoUpdate) | Creates and returns an HTML <table> element for managing consents. If autoUpdate is true, the table will automatically reflect changes made elsewhere. |
Sources: src/modules/GrantsInterface.ts:49, 108, 115, 239, 245, README.md:168-180, 193-199
Installation and Distribution
The project can be installed via a package manager or included directly in an HTML file via a CDN or local script.
Package Manager:
npm i consent-manager
Sources: README.md:13-19
CDN/Direct Include:
<!-- For use as a module -->
<script src="https://unpkg.com/consent-manager@1/dist/consent-manager.min.js"></script>
<!-- Stylesheet for GrantsInterface -->
<link rel="stylesheet" href="https://unpkg.com/consent-manager@1/dist/consent-manager.min.css">
When included directly, the classes ConsentManager, DOMConnector, and GrantsInterface are available on the global window object.
Sources: README.md:21-25, 162-164, src/bundle.ts:1-7
The project provides multiple builds to support different environments:
- CommonJS:
dist/main/index.js - ES Module:
dist/module/index.js - Browser UMD:
dist/consent-manager.min.js
Sources: package.json:5-8