UI Widget

@consenti/ui is a zero-dependency TypeScript library that owns the complete frontend consent lifecycle. You call new ConsentiSetup(config) once and the widget handles everything else automatically.

New here? Start with the Quick Start for working code. This page explains how the widget thinks so the rest of the docs make sense.

Lifecycle

Every time new ConsentiSetup(config) runs in the browser, it executes these steps in order:

1  SSR guard          exit silently if not running in a browser
 2  Profile resolve    API fetch  →  local ConsentiProfile  →  built-in default
 3  profileOverride    deep-merge any runtime overrides on top
 4  Consent check      read stored record from cookie / localStorage
 5  GPC detection      read navigator.globalPrivacyControl
 6  Banner decision    show main banner, GPC banner, or nothing
 7  DOM mount          inject #consenti-root, render banner and modal
 8  onReady fires      your callbacks run
 9  User interacts     button click or modal toggle
10  Consent written    cookie / localStorage  +  API POST (if enabled)
11  Events fire        consenti:consentSubmitted  +  GTM dataLayer push
12  Cross-tab sync     BroadcastChannel closes banner in all open tabs

Three things you configure

1. Profile — what the widget shows

A profile defines which cookie purposes the widget manages, all banner and modal copy, button labels and actions, and locale-specific translations. You have three options:

• Built-in default — omit profileId. A fully working English GDPR profile ships with the package. No code needed.
• ConsentiProfile — define your own cookies, copy, and categories in code for frontend-only installations.
• API profile — create profiles in the admin dashboard; the widget fetches them at runtime when api.enabled: true.

profileOverride lets you patch any profile field at runtime — useful for per-page banner positions or A/B testing copy without touching the base profile.

→ Full Profiles reference

2. Config — how the widget behaves

ConsentiSetup accepts one config object with five top-level keys:

• core — regulation, locale, storage mode, GPC handling, cookie signing, theme tokens
• api — backend URL and auth token (omit entirely when not using the backend)
• utils.gtm — GTM container ID and Google Consent Mode v2 options
• plugins — frontend plugin instances
• profileOverride — runtime profile patches

→ Full Configuration reference

3. Events & methods — how you react

After initialisation the widget runs on its own. You interact with it in two ways:

• Listen to events — consenti:consentSubmitted fires every time consent changes. Gate your analytics and ad scripts here. Other events cover banner visibility and modal open/close.
• Call methods — widget.showModal()opens the preference modal from a "Cookie Settings" link. widget.getConsent() reads the current record. widget.reConsent() clears consent and re-shows the banner.

→ Events reference  ·  API Methods reference

Package exports

In this section