Cookies Consent Library

The @lumio/cookies-consent shared package provides a GDPR-compliant cookie-consent UX for Lumio's external frontend apps (apps/web and apps/id).

It wraps a provider, banner, preferences modal, floating settings button, and detection hooks, with one additive feature (exemptPathPrefixes) to silence the banner on OBS overlay routes where a consent dialog would be inappropriate.

When to use

Wrap your app's root layout with <ConsentProvider>.
The provider renders <ConsentBanner /> and <CookieSettingsButton /> automatically (controlled by showFloatingButton — default true).
Use useConsent() from any client component to gate loading of non-essential scripts / cookies.

Consumer apps must mount `<TooltipProvider />`

The CookieSettingsButton floating tooltip uses Lumio's shared <TooltipProvider /> (from @lumio/ui) which reads data-tooltip / data-tooltip-pos attributes. Mount the provider once at your app's root layout.

Public API

Symbol	Kind	Purpose
`ConsentProvider`	Component	Wraps the app, loads/persists state, renders banner + floating button.
`useConsent()`	Hook	Returns `hasConsented`, `isAllowed(category)`, `consent`, `openPreferences`, `isExempt`.
`ConsentBanner`, `CookieSettingsButton`, `CookieStatusIndicator`	Component	Standalone UI pieces if you need them outside the provider's auto-render.
`ConditionalScript`, `ConditionalContent`, `EssentialScript`	Component	Only mount `<script>`-like content when a category is allowed.
`GoogleAnalytics`, `FacebookPixel`, `Hotjar`, `Matomo`, `Plausible`	Component	Pre-wired analytics integrations that respect consent.
`defaultTranslations`	Data	`{ en, de }` default copy.
`getStoredConsent`, `setStoredConsent`, `clearStoredConsent`	Util	Low-level localStorage access.
`getDetectedCookies`, `getCookiesByCategory`, `getCookiesByService`, `hasServiceCookies`, `getCookieSummary`	Util	Runtime cookie detection (drives the preferences modal).
`getDetectedStorage`, `getDetectedLocalStorage`, `getDetectedSessionStorage`, `getStorageByCategory`, `getStorageByType`, `getStorageByService`, `hasServiceStorage`, `getStorageSummary`	Util	Same for localStorage / sessionStorage.

Integration status

As of this doc, the library is mounted in two consumer apps:

App	`appName`	`exemptPathPrefixes`	Policy URL
`apps/web`	`"Web"`	`["/overlay", "/popout", "/api"]`	`/legal/cookies` (relative)
`apps/id`	`"ID"`	none	`${NEXT_PUBLIC_WEB_URL}/legal/cookies`

Each app wraps its root layout with <TooltipProvider /> + <ConsentProvider>. The provider renders the banner and floating settings button internally — consumers do NOT pass them as children.

apps/admin does NOT integrate the consent library. Admin is an internal, auth-gated tool for the zaflun team — no external end-users reach it, so no GDPR consent prompt is required.

Bot apps and apps/docs do not integrate the library either (server-only / Docusaurus).

`exemptPathPrefixes`

Pass this prop to the provider to suppress the consent UI on specific pathname prefixes (e.g. OBS browser-source routes at /overlay/* where a banner would break the embed).

On matching paths:

<ConsentBanner /> and <CookieSettingsButton /> do not render.
useConsent().isExempt === true.
isAllowed("essential") returns true; all other categories return false.
acceptAll / acceptEssentialOnly / openPreferences / openBanner / closeBanner are no-ops.

<ConsentProvider
  translations={defaultTranslations[locale]}
  policyUrl="/legal/cookies"
  appName="Web"
  exemptPathPrefixes={["/overlay", "/api"]}
  footerLinks={{ privacyUrl: "/legal/privacy", imprintUrl: "/legal/imprint" }}
>
  {children}
</ConsentProvider>

Edit shared/cookies-consent/src/utils/cookieDetector.ts. Append to the cookiePatterns array:

{ pattern: /^your_cookie_name$/, category: "functional", service: "Your Service" }

Also add a matching entry to src/i18n/en.json (and de.json) under the appropriate category's cookies array so the preferences modal shows the human-friendly name + purpose + duration.

Storage key

Persistent state is stored under localStorage["lumio_cookie_consent"] with an internal version number. Read via getStoredConsent() (returns ConsentState | null).

When to use​

Consumer apps must mount <TooltipProvider />​

Public API​

Integration status​

exemptPathPrefixes​

Adding a cookie​

Storage key​

Categories​