Configuration Options

Relevant source files

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

• src/modules/ConsentManager.ts
• README.md
• src/modules/GrantsInterface.ts
• src/modules/DOMConnector.ts
• src/modules/ConsentManager.test.ts
• package.json

The consent-manager library is designed to be flexible and modular, with its behavior primarily controlled through configuration objects passed during instantiation. These options allow developers to define consent categories, manage cookie behavior, customize UI elements, and control DOM modifications based on user consent. The configuration is split across the main components: ConsentManager for core logic, GrantsInterface for UI, and DOMConnector for DOM manipulation via attributes.

This page details the configuration options available for each of these modules. The core configuration is handled by the ConsentManager class, which is then passed to other modules like GrantsInterface and DOMConnector to ensure consistent behavior across the application.

ConsentManager Configuration

The ConsentManager class is the core of the library and is initialized with a ConsentManagerConfig object. This configuration dictates the fundamental aspects of consent management, such as versioning, cookie storage, and the categories of consent that can be managed.

Sources: src/modules/ConsentManager.ts:57-67, README.md:27-74

ConsentManagerConfig Object Structure

The configuration object passed to the ConsentManager constructor defines its behavior. The structure of this object is defined by the ConsentManagerConfig<G> interface.

The following diagram illustrates the relationship between the main config object and its nested categories array.

ConsentManagerConfig Properties

The main properties of the configuration object are detailed below.

Property	Type	Default	Description
version	string	'1'	A version string for the configuration. If this changes, all existing user consent preferences will be disregarded. This is a required property.
cookieName	string	'consent-manager'	The name of the cookie used to store the user's consent preferences.
expires	number | Date | 'session'	365	The expiration of the consent cookie. Can be a number of days, a Date object, or the string 'session' for session cookies.
categories	object[]	[]	An array of category objects that define the different types of consent. This is a required property.

Sources: src/modules/ConsentManager.ts:57-74, README.md:31-43

categories Array Properties

Each object within the categories array defines a specific consent type.

Property	Type	Default	Description
id	string	-	A unique identifier for the category. Required.
label	string	-	A human-readable label for the category, used in the UI. Required.
description	string	-	A short explanation of the category's purpose. Required.
required	boolean	-	If true, the user cannot disable this category. Required.
default	boolean	false	The default consent state for this category if the user has not made a selection.

Sources: src/modules/ConsentManager.ts:61-66, README.md:47-73

Initialization and Cookie Parsing Flow

When a ConsentManager instance is created, it merges the provided configuration with defaults and then attempts to parse an existing consent cookie to determine the initial state.

GrantsInterface Configuration

The GrantsInterface class provides ready-to-use UI components (a banner and a modal) for managing consent. It is configured via an optional object passed as the second argument to its constructor.

Sources: src/modules/GrantsInterface.ts:5-20, README.md:188-212

GrantsInterfaceConfig Properties

Property	Type	Default	Description
autoShow	boolean	true	If true, the consent banner is automatically shown if the user has not yet customized their preferences (isCustomized is false).
languageStrings	object	(see below)	An object containing the text strings for the UI elements. Allows for customization and internationalization.

Sources: src/modules/GrantsInterface.ts:5-20

languageStrings Object Structure

This object allows for overriding the default text in the banner and modal.

The default values for languageStrings are:

{
  banner: {
    infoText: 'This website uses cookies to ensure you get the best experience on our website.',
    accept: 'Accept All',
    reject: 'Only required',
    options: 'More options'
  },
  modal: {
    title: 'Consent options',
    accept: 'Accept All',
    reject: 'Only required'
  }
}

Sources: src/modules/GrantsInterface.ts:22-38

DOMConnector Configuration

The DOMConnector module does not take a JavaScript configuration object. Instead, it is configured directly in the HTML using data-* attributes on the elements it manages. When initialized, it scans the DOM for elements with the data-consent-manager attribute and dynamically updates them based on the user's consent status.

Sources: src/modules/DOMConnector.ts:4-7, README.md:144-155

data-* Attributes

Attribute	Value	Description
data-consent-manager	(none)	A required attribute that marks an element to be managed by DOMConnector.
data-cm-categories	string	A comma-separated list of category ids. The element is considered "enabled" if consent is granted for at least one of these categories.
data-cm-inverted	(none)	An optional attribute that inverts the logic. The element will be "enabled" if consent is not granted for any of the specified categories.
data-cm-attribute	string	The name of the HTML attribute to set on the element when it is enabled (e.g., src, style).
data-cm-value	string	The value to set for the attribute specified in data-cm-attribute when the element is enabled.

Sources: README.md:148-155, src/modules/DOMConnector.ts:1-53

DOMConnector Processing Flow

The following diagram illustrates how DOMConnector processes a single DOM element.