The Cookie Banner
Relevant source files
The following files were used as context for generating this wiki page:The Cookie Banner is a ready-to-use UI component provided by the GrantsInterface module. Its primary purpose is to present users with information about cookie usage and to capture their consent preferences. It is designed to work in tandem with the core ConsentManager module, which handles the logic and persistence of user consent.
By default, the banner is displayed automatically to any user who has not yet saved their preferences. It offers several actions, including accepting all cookies, rejecting non-essential ones, or opening a more detailed Preferences Modal for granular control. The banner's appearance and text can be customized during initialization.
Sources: src/modules/GrantsInterface.ts:44-50, README.md:129-132
Architecture
The Cookie Banner is not a standalone component; it is an integral part of the GrantsInterface class, which acts as a view controller for the ConsentManager. The ConsentManager instance holds the consent state and business logic, while GrantsInterface is responsible for rendering the UI (including the banner and modal) and translating user interactions into calls to the ConsentManager.
This diagram illustrates the relationship between the GrantsInterface and the ConsentManager.
Initialization and Configuration
To use the cookie banner, an instance of GrantsInterface must be created, passing an initialized ConsentManager object to its constructor. The behavior of the banner can be modified through a configuration object.
import ConsentManager, { GrantsInterface } from 'consent-manager';
import 'consent-manager/dist/consent-manager.css';
const consentManager = new ConsentManager({ /* ...config... */ });
// Initialize with default behavior (banner shows automatically)
new GrantsInterface(consentManager);
// Initialize with custom configuration
const gi = new GrantsInterface(consentManager, {
autoShow: false, // Manually control the banner
languageStrings: {
banner: {
infoText: 'We use cookies on this site.',
accept: 'Accept',
reject: 'Decline',
options: 'Settings'
}
}
});
Sources: README.md:129-158, src/modules/GrantsInterface.ts:42-46
Configuration Options
The GrantsInterface constructor accepts an optional configuration object with the following properties:
| Option | Type | Default | Description |
|---|---|---|---|
autoShow | boolean | true | If true, the banner is shown automatically if the user has not customized their preferences. |
languageStrings | object | (see below) | An object to override the default text strings for the banner and modal. |
The default languageStrings for the banner are:
- infoText: 'This website uses cookies to ensure you get the best experience on our website.'
- accept: 'Accept All'
- reject: 'Only required'
- options: 'More options'
Sources: src/modules/GrantsInterface.ts:7-20, src/modules/GrantsInterface.ts:28-35
Banner Display Logic
The showBanner() method is responsible for creating and injecting the banner into the DOM. The banner is only created if one does not already exist in the document.
By default (autoShow: true), the GrantsInterface constructor checks if client.isCustomized is false. If so, it calls showBanner() immediately. The isCustomized flag in ConsentManager becomes true only after a user explicitly saves their preferences or if a valid, version-matched cookie is found.
This flowchart shows the initial display logic when GrantsInterface is instantiated.
DOM Structure
The showBanner() method constructs the banner using standard DOM elements and appends it to document.body. The structure is an <aside> element containing sections for the information text and action buttons.
This diagram shows the HTML element structure created for the banner.
Sources: src/modules/GrantsInterface.ts:88-91
User Interaction and Event Handling
The banner provides three buttons for user interaction. Each button's click event is wired to perform a specific action.
| Button | CSS Class | Action |
|---|---|---|
| Accept All | .consent-manager--banner-accept | Calls this.client.setGrant('*', true) to grant all categories. |
| Only required | .consent-manager--banner-reject | Calls this.client.setGrant('*', false) to revoke all non-required categories. |
| More options | .consent-manager--banner-more | Calls this.showModal() and this.hideBanner() to open the detailed preferences modal. |
Sources: src/modules/GrantsInterface.ts:71-86
The following sequence diagram illustrates what happens when a user clicks the "Accept All" button.
Once a grant is set, ConsentManager dispatches an update event. The GrantsInterface listens for this event and calls hideBanner() as soon as client.isCustomized becomes true, ensuring the banner is dismissed after the user makes a choice.
Sources: src/modules/GrantsInterface.ts:93-97
Styling and Appearance
The visual appearance of the cookie banner is defined in src/styles.scss. The styles are scoped using BEM-like class names, such as .consent-manager--banner-wrapper. By default, the banner is a fixed-position element at the bottom-center of the viewport with a subtle box-shadow.
Key CSS Classes
| Class Name | Description | Default Styles |
|---|---|---|
.consent-manager--banner-wrapper | The main container for the banner. | position: fixed, bottom: 1rem, left: 50%, transform: translateX(-50%), background-color: #fff |
.consent-manager--banner-actions | Container for the action buttons. | margin-left: 1rem |
.consent-manager--banner-accept | The "Accept All" button. | border: 2px solid #777777 |
.consent-manager--banner-reject | The "Only required" button. | Basic button styles. |
.consent-manager--banner-more | The "More options" button. | Basic button styles. |
These styles can be overridden in a project's own stylesheet or by creating a custom theme, as the library provides an unminified CSS file.
Sources: src/styles.scss:1-20, src/styles.scss:40-42
The Preferences Modal
Clicking the "More options" button on the banner serves as a bridge to a more detailed consent management UI: the Preferences Modal. This action simultaneously hides the banner and displays the modal, which allows users to configure consent for each category individually. The modal's content is generated by the generateConsentTable() method.
Sources: src/modules/GrantsInterface.ts:82-87, src/modules/GrantsInterface.ts:232-234