Reference

Options

createCookieConsent(options)

Option	Type	Default	What it does
`categories`	`Category[]`	—	Required.
`version`	`string \| number`	`1`	A change re-asks everyone.
`storage`	`StorageOptions`	cookie, 182 days	Where the decision lives.
`regime`	`string \| Regime \| 'auto'`	`'default'`	Which rules apply.
`country`	`string \| () => string \| Promise<string>`	—	`'DE'`, `'US-CA'`.
`regimes`	`Record<string, Regime>`	—	Your own rule sets.
`honourSignals`	`boolean`	the regime decides	GPC and DNT as a refusal.
`consentMode`	`boolean \| ConsentModeOptions`	`false`	Google Consent Mode v2.
`nonce`	`string`	—	Copied onto every script we unblock.
`reloadOnWithdraw`	`boolean`	`false`	Reload when something already running loses consent.
`noticeHash`	`string`	—	Stored with the decision as proof of the wording.
`report`	`(record) => void`	—	Send the decision to your server.
`layout`	`'box' \| 'bar' \| 'center'`	`'box'`
`position`	`'bottom-left' \| … \| 'top-center'`	`'bottom-left'`
`modal`	`boolean`	`false`	Dim and block the page until a choice is made.
`language`	`string \| 'auto'`	`'auto'`	Reads `<html lang>`.
`policyUrl`	`string`	—	Link in the notice.
`headingTag`	`'h1'…'h4' \| 'p' \| 'div'`	`'h2'`	Keeps your page outline intact.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`
`container`	`HTMLElement`	`document.body`
`classNames`	`Partial<Record<ConsentPart, string>>`	—	Your classes on every part.
`strings` / `translations`	see below	English	Every word.
`autoShow`	`boolean`	`true`	Show the notice as soon as a decision is needed.

A category

{
  id: 'analytics',
  label: 'Analytics',                   // or { en: 'Analytics', ar: 'التحليلات' }
  description: 'How the site is used',
  required: false,                      // cannot be switched off
  preselected: false,                   // pre-ticked in an opt-out regime
  autoClear: [{ name: '_ga_.*', pattern: true }],
  cookies: [{ name: 'x', duration: '1 year', description: '…' }],
  services: [/* … */],
}

A service

{
  id: 'ga4',
  label: 'Google Analytics 4',
  description: 'Counts visits',
  url: 'https://policies.google.com/privacy',
  needs: ['gtm'],        // stays off until gtm is on
  defaultOn: true,       // on when its category is accepted wholesale
  cookies: [/* … */],
}

Storage

Option	Default
`name`	`'dx_consent'`	Cookie or storage key.
`mode`	`'cookie'`	`'local'` to use `localStorage` instead — your server then cannot read it.
`days`	`182`	Also how long before the decision expires and is asked again.
`domain`	—	`.example.com` shares one decision across subdomains.
`sameSite`, `secure`, `path`	`Lax`, on HTTPS, `/`

The instance

Call	Does
`record()`	The stored decision, or `null`.
`allowed()`	A set of category ids, service ids and `category/service` keys.
`accepted(key)`
`needsDecision()`	Nobody decided, it expired, or your version moved on.
`acceptAll()` / `rejectAll()` / `save(keys)` / `withdraw()`
`show()` / `hide()` / `showPreferences()` / `hidePreferences()`
`language()` / `setLanguage(code)`
`regime()`	The rule set in force.
`on(event, handler)`	`firstconsent`, `change`, `show`, `hide`, `showpreferences`, `hidepreferences`. Returns an unsubscribe.
`apply()`	Re-run blocking and Consent Mode — after you inject new markup.
`destroy()`

The record

{
  "id": "3f2a…",
  "createdAt": "2026-09-12T09:14:22.881Z",
  "updatedAt": "2026-09-12T09:14:22.881Z",
  "categories": ["necessary", "analytics"],
  "services": ["analytics/ga4"],
  "refused": ["marketing"],
  "version": 1,
  "via": "custom",
  "regime": "gdpr",
  "language": "en-GB",
  "noticeHash": "sha256-…",
  "revision": 2
}

via is one of accept-all, reject-all, custom, gpc, dnt, api or implied.

The core, with no UI

import { createConsentState, applyBlocking, consentModeUpdate, readConsent } from '@devix-labs/cookie-consent/core';

Drive consent from your own settings screen, or read the decision on the server from the dx_consent cookie — it is JSON.

Updated 15 Sep 2026

Options

createCookieConsent(options)#

A category#

A service#

Storage#

The instance#

The record#

The core, with no UI#