README

Reusable, theme-overridable Drupal 11 module for cookie consent — a first-visit banner, a preferences dialog, a persistent reopen badge, and consent-gated iframes/scripts, built on vanilla-cookieconsent 3.1.0 used headlessly (as a consent-state engine only; all rendered UI is Drupal's own Twig/CSS).

Purpose

The module is intended to be reused across Drupal 11 projects by installing it as a Composer package and enabling it in the target site.

Requirements

Drupal 11
PHP 8.3+

Features

Renders a first-visit banner, a native <dialog> preferences modal, and a persistent "reopen settings" badge on every non-admin page automatically
Three consent categories: required (always on), marketing, external
Gates third-party <iframe> embeds behind consent, with a same-origin/ allowlisted-hosts check before ever loading one
Gates <script> tags that draw visible UI, showing a placeholder until their category is accepted
All copy, categories, cookie settings, embed allowlist, and policy links are editable via config — no template/PHP changes needed per project
Every piece of UI is its own theme hook, independently overridable per-theme
Colors and typography are public --cookie-consent-* CSS variables, overridable from theme CSS or the admin form — no need to replace the stylesheet for a rebrand

Structure

cookie_consent.module contains the theme, page, and preprocess hooks.
src/Form/ contains the admin settings form.
src/CssVariables.php defines the admin-overridable CSS variables and validates/emits them.
templates/ contains the banner/modal/badge/gate/embed Twig templates.
css/ and js/ contain the default styling and the ported consent behavior, plus the vendored vanilla-cookieconsent library.
config/ contains shipped defaults and config schema.
docs/module-architecture.md documents how the module is built — the gating mechanism, theme hook contract, and override points — for anyone changing or extending it.

Installation

composer require protonsystems/cookie-consent

Then enable the module in Drupal:

drush en cookie_consent

Configure categories, policy links, the embed allowlist, and all UI text at /admin/config/system/cookie-consent (permission: administer cookie consent), then drush cex to keep that configuration in config/sync.

Theme Integration

No theme changes are required to get a working, styled UI — the module ships its own default CSS and templates render automatically on every non-admin page.

Restyling with CSS variables

For a rebrand (colors, fonts) you don't need to touch templates or disable the stylesheet. Every variable prefixed --cookie-consent- is public API. Override them from your theme's CSS:

:root {
  --cookie-consent-accent: #c2185b;
  --cookie-consent-accent-fg: #fff;
  --cookie-consent-font-family: "Inter", sans-serif;
}

Or, without a theme change, at Appearance on /admin/config/system/cookie-consent (values are validated, then emitted as a :root rule in <head>; empty fields keep the default). If both set the same variable, theme CSS wins, then the admin form, then the module default.

Variable	Default	Used for
`--cookie-consent-bg`	`#fff`	Banner, modal card, badge, buttons
`--cookie-consent-fg`	`#1a1a1a`	Text
`--cookie-consent-muted`	`#5a5a5a`	Secondary text
`--cookie-consent-border`	`#d8d8d8`	Borders, dividers
`--cookie-consent-accent`	`#0f62fe`	Primary button, checkboxes, badge icon
`--cookie-consent-accent-fg`	`#fff`	Text on the accent color
`--cookie-consent-accent-hover`	accent darkened 15%	Primary button hover
`--cookie-consent-button-hover-bg`	`fg` mixed 8% into `bg`	Secondary button hover
`--cookie-consent-focus-ring`	`accent`	`:focus-visible` outline
`--cookie-consent-embed-bg`	`border` at 25%	Embed / script-gate placeholder
`--cookie-consent-backdrop`	`rgba(0, 0, 0, 0.5)`	Behind the modal
`--cookie-consent-attribution-fg`	`rgba(255, 255, 255, 0.85)`	Attribution line (sits on the backdrop)
`--cookie-consent-font-family`	`inherit`	All components
`--cookie-consent-font-size`	`inherit`	Base size
`--cookie-consent-font-size-small`	`0.9em`	Descriptions, links, badge label
`--cookie-consent-font-size-xsmall`	`0.8em`	Embed note, attribution
`--cookie-consent-line-height`	`inherit`	All components
`--cookie-consent-font-weight-strong`	`600`	Category and embed titles
`--cookie-consent-radius`	`8px`	Cards, buttons, placeholders
`--cookie-consent-badge-radius`	`3rem`	Reopen badge
`--cookie-consent-shadow`	`0 2px 16px rgba(0, 0, 0, 0.15)`	Banner, modal, badge
`--cookie-consent-z`	`99998`	Stacking (badge is one lower)

The last four (radius, badge radius, shadow, z-index) are themeable but not in the admin form.

Keep the pairings readable — the module does not check contrast for you. Aim for WCAG AA: fg/muted on bg and accent-fg on accent at 4.5:1; border and focus-ring against bg at 3:1; attribution-fg against the backdrop at 4.5:1. If you lighten the backdrop, set attribution-fg too — its default is white. If your CSP forbids inline styles, use theme CSS rather than the admin form.

Replacing the markup or the stylesheet

To restyle a piece of UI beyond what variables allow, copy its template into the theme's templates/ directory (Drupal's standard template discovery picks it up) and disable the module's default CSS via libraries-override in the theme's .info.yml.

To gate a specific embed server-side (e.g. a video field), render #theme => 'cookie_consent_embed' in place of the real iframe from a project-specific hook_preprocess_HOOK().

See docs/module-architecture.md for the full theme hook reference, configuration reference, and customization details.

Notes

The module currently uses Drupal core services directly and is designed to be consumed as a standard Drupal module package.

protonsystems / cookie-consent

Package info

Security

Statistics