Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• src/index.ts
• src/modules/ConsentManager.ts
• src/modules/DOMConnector.ts
• src/modules/GrantsInterface.ts
• src/bundle.ts
• src/styles.scss

The consent-manager library 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 ready-to-use UI components and DOM integrations. This guide covers the installation and basic usage of the main modules: ConsentManager, DOMConnector, and GrantsInterface.

Sources: README.md:5-9, package.json:2

Installation

You can add the consent-manager to your project using a package manager or by directly including the script file in your HTML.

Package Manager:

# pnpm
pnpm i consent-manager

# yarn
yarn add consent-manager

# npm
npm i consent-manager

Sources: README.md:13-21

Direct Script Include:
You can include the bundled script from a CDN like unpkg or host it yourself. When using this method, the core classes (ConsentManager, DOMConnector, GrantsInterface) are attached to the window object.

<!-- Via CDN -->
<script src="https://unpkg.com/consent-manager@1/dist/consent-manager.min.js"></script>

<!-- Self-hosted -->
<script src="consent-manager.min.js"></script>

Sources: README.md:23-31, src/bundle.ts:2-8

Core Module: ConsentManager

The ConsentManager class is the heart of the library. It handles the state of user consent, manages cookie storage, and provides an event-driven interface for reacting to consent changes.

Sources: src/modules/ConsentManager.ts, README.md:33-35

Initialization

To begin, create an instance of ConsentManager, passing a configuration object. The version and categories properties are required.

import ConsentManager from 'consent-manager';

const consentManager = new ConsentManager({
  version: '2023-10-27',
  cookieName: 'my-app-consent',
  expires: 365,
  categories: [
    {
      id: 'essential',
      label: 'Essential Cookies',
      description: 'Required for basic functionality',
      required: true,
    },
    {
      id: 'analytics',
      label: 'Analytics Cookies',
      description: 'Visitor statistics used to improve content',
      required: false,
      default: false,
    }
  ]
});

Sources: README.md:37-75, src/modules/ConsentManager.ts:80-83

The following diagram illustrates the initialization process of the ConsentManager.

Configuration

The ConsentManager constructor accepts a configuration object with the following properties:

Property	Type	Default	Description	Required
version	string	'1'	The version of the configuration. If this changes, previous user consents are disregarded.	Yes
cookieName	string	'consent-manager'	The name of the cookie where preferences are stored.	No
expires	number | Date | 'session'	365	Cookie expiration in days, a specific Date, or 'session'.	No
categories	Array<object>	[]	An array of consent categories. Each object must have id, label, description, and required fields.	Yes

Sources: src/modules/ConsentManager.ts:63-74, README.md:41-75

Properties

Property	Type	Description
config	object	The configuration object passed to the constructor.
grants	Record<string, boolean>	A key-value object where keys are category IDs and values are booleans indicating if consent is granted.
isCustomized	boolean	true if the user has actively made a choice, false otherwise.

Sources: README.md:79-99, src/modules/ConsentManager.ts:80-82

Methods

setGrant(id, status)

This method updates the consent status for one or more categories.

Parameter	Type	Description
id	string | *	The category id to update, or * to update all non-required categories.
status	boolean	true to grant consent, false to revoke it.

The diagram below shows the sequence of actions when setGrant is called.

on(eventType, callback) & off(eventType, callback)

These methods allow you to listen for consent changes.

• on(eventType, callback): Registers an event listener.
• off(eventType, callback): Removes a previously registered event listener.

Available event types are:

• grant: Fired when a category is granted.
• revoke: Fired when a category is revoked.
• update: Fired for both grant and revoke actions.

Sources: src/modules/ConsentManager.ts:167-188, README.md:114-124

UI Module: GrantsInterface

The GrantsInterface module provides ready-to-use UI components, including a consent banner and a preferences modal, to interact with the ConsentManager.

Sources: README.md:167-171, src/modules/GrantsInterface.ts

Initialization

Instantiate GrantsInterface by passing your ConsentManager instance. You can also provide an optional configuration object. Remember to include the stylesheet.

import { GrantsInterface } from 'consent-manager';
import 'consent-manager/dist/consent-manager.css';

const gi = new GrantsInterface(consentManager, {
  autoShow: true, // Default
  languageStrings: {
    banner: {
      infoText: 'We use cookies for a better experience.',
      accept: 'Accept',
      reject: 'Decline',
      options: 'Settings'
    }
  }
});

Sources: README.md:173-176, 197-213, src/modules/GrantsInterface.ts:39-45

Configuration

Property	Type	Default	Description
autoShow	boolean	true	If true, the banner is shown automatically if the user has not yet customized their consent.
languageStrings	object	(see default config)	An object to override the default text for the banner and modal.

Sources: src/modules/GrantsInterface.ts:7-21, 35-37

UI Flow

By default, if consent is not customized, the banner appears. The user can accept all, reject non-essential, or open a modal for detailed preferences.

Methods

• showBanner() / hideBanner(): Manually control the visibility of the consent banner.
• showModal() / hideModal(): Manually control the visibility of the preferences modal.
• generateConsentTable(autoUpdate): Creates and returns an HTML <table> element with the consent categories, which can be inserted anywhere in your DOM.

Sources: README.md:189-201, 215-221, src/modules/GrantsInterface.ts:47-54, 111-117, 219-225, 263-269

DOMConnector Module

The DOMConnector links the consent state from ConsentManager directly to DOM elements using data-* attributes. It automatically updates elements when consent changes.

Sources: README.md:128-130, src/modules/DOMConnector.ts

Initialization

Instantiate DOMConnector by passing your ConsentManager instance. It will immediately scan the DOM and listen for future consent updates.

import { DOMConnector } from 'consent-manager';

new DOMConnector(consentManager);

Sources: README.md:134-136, src/modules/DOMConnector.ts:4-7

Data Attributes

Attribute	Description	Required
data-consent-manager	Marks the element to be managed by DOMConnector.	Yes
data-cm-categories	A comma-separated list of category IDs that enable the element.	Yes
data-cm-attribute	The name of the HTML attribute to set when consent is granted.	Yes
data-cm-value	The value for the specified data-cm-attribute.	Yes
data-cm-inverted	Inverts the logic; the attribute is set when consent is not granted.	No

Sources: README.md:140-148, src/modules/DOMConnector.ts:9-27, 33-42

Logic Flow

The DOMConnector's updateDOM method follows this logic for each managed element.

Usage Example: Conditional Script Loading

This example shows how to load an analytics script only when the user has consented to the analytics category.

<script
  data-consent-manager
  data-cm-categories="analytics"
  data-cm-attribute="src"
  data-cm-value="https://analytics-provider.com/script.js"
></script>

When consent for 'analytics' is granted, DOMConnector will set the src attribute, causing the browser to load and execute the script.

Sources: README.md:152-158