Configuration

initCookieYes(config) is the one place you configure CookieYes. mode is the only required option; everything else has a sensible default.

initCookieYes({
  mode: "cookie-only",
  regulation: "GDPR",
  theme: { primaryColor: "#1863dc" },
});

Options

Setup

Name	Type	Default	Description
`mode`required	`"cookie-only" \| "self-hosted"`	None	Where the choice is stored: "cookie-only" in a browser cookie only; "self-hosted" also sent to your server.
`regulation`optional	`Regulation`	None	Which privacy law applies: "GDPR" (opt-in) or "CCPA" (opt-out). Unset behaves as GDPR. Wins over `region` detection.
`region`optional	`RegionConfig`	None	Optional geo-detection: choose the active regulation from the visitor's region instead of hardcoding one.

Appearance

Name	Type	Default	Description
`colorScheme`optional	`ColorScheme`	`"system"`	Light, dark, or follow-the-OS theme mode for the banner and preferences dialog.
`theme`optional	`ThemeConfig`	None	Colours, corner radius and font for every CookieYes surface.

Language

Name	Type	Default	Description
`i18n`optional	`I18nConfig`	None	Translations, active locale, and on-demand language loading.

Storage and blocking

Name	Type	Default	Description
`categories`optional	`CategoryDef[]`	`built-in five`	Your own consent-category taxonomy. Omit to get the built-in five (necessary, functional, analytics, performance, advertisement) unchanged.
`networkBlocker`optional	`NetworkBlockerConfig`	None	Block matching third-party network requests (fetch/XHR/sendBeacon) by category until consent is granted.
`googleConsentMatch`optional	`"all" \| "any"`	`"any"`	When several categories map to one Google Consent Mode signal: "any" grants it if any of them is granted, "all" only if all are.
`apiUrl`optional	`string`	None	Endpoint the ConsentPayload is POSTed to, under `mode: "self-hosted"`.
`apiKey`optional	`string`	None	Sent as an `Authorization: Bearer <apiKey>` header on the `apiUrl` POST, if set.
`backend`optional	`ConsentBackend`	None	Custom persistence adapter (`persist(payload)`): full control over transport, headers, batching, retries, or a non-HTTP destination.

Callbacks

Name	Type	Default	Description
`integrations`optional	`Integration[]`	None	Ready-made, consent-gated third-party integrations (Segment, Meta, Google, more) built from a preset in `@cookieyes/scripts`.
`customStopHandlers`optional	`StopHandler[]`	None	Your own scripts' stop instructions, for anything without a built-in integration or preset.
`onConsentReady`optional	`((state: ConsentSnapshot) => void)`	None	Fires once, when the initial consent state is known.
`onConsentUpdate`optional	`((state: ConsentSnapshot) => void)`	None	Fires on every saved change, for the life of the page, and cannot be unsubscribed.
`reloadOnRevoke`optional	`boolean`	`false`	Force a full page reload when consent is revoked, instead of relying on clean runtime stops.

`theme`

@cookieyes/core draws no UI, so it accepts theme and ignores it.

`region`

Name	Type	Default	Description
`region.detect`optional	`RegionDetector`	None	Return the visitor's region synchronously: e.g. from a hosting header you already have.
`region.map`optional	`Record<string, Regulation>`	None	Region → regulation mapping (your own). Matched most-specific first: "US-CA" is checked before "US".
`region.honorGpc`optional	`boolean`	`true`	Honour the browser's Global Privacy Control "do not sell/share" signal (a CCPA opt-out).
`region.strictest`optional	`Regulation`	`"GDPR"`	Regulation to apply when the region is unknown or detection fails.
`region.debug`optional	`boolean`	`false`	Log the region decision to the console at setup, for local debugging.

`i18n`

messages per language, each one partial with English filling the gaps; locale to pin the language; detectBrowserLanguage (default on); loadLanguage(tag) to fetch a language on demand.

rules for requests to block until a category is granted, plus onRequestBlocked and logBlockedRequests. Needs registerNetworkBlocker() called once before initCookieYes(). See Network blocking.

Choosing a privacy law: the `regulation` option

	`"GDPR"`	`"CCPA"`
Optional categories before the visitor chooses	Off, the visitor opts in	On, the visitor opts out
Banner buttons	Accept All, Reject All, Customise	Do Not Sell
Global Privacy Control	Not used	Honoured

Set the strictest law your visitors fall under, "GDPR" for most sites, and ship it for everyone. If you set nothing, the banner behaves as under "GDPR". To choose per visitor, set region instead: it maps the visitor's country to a regulation. A manual regulation always wins over region, so set one or the other.

Leave categories out and you get the built-in five: necessary (required), functional, analytics, performance and advertisement. To use your own list:

src/consent.ts

import { initCookieYes } from "@cookieyes/core";

initCookieYes({
  mode: "cookie-only",
  categories: [
    { id: "necessary", required: true, label: "Essential" },
    { id: "analytics", label: "Analytics", gcm: ["analytics_storage"] },
    { id: "marketing", label: "Marketing", gcm: ["ad_storage", "ad_user_data"] },
  ],
});

Ids must be unique and contain no , or :, and one category must be required: true; otherwise the list is rejected with a console warning and the built-in five are used. Decide your ids early: adding, removing or renaming an id later makes every returning visitor choose again. Labels and descriptions can change freely.

Where the choice is stored

cookie-only keeps the visitor's choice in a browser cookie and makes no network requests. Start here.

self-hosted also sends each choice to your server with one POST to apiUrl, so you can keep a record. apiKey goes in a Bearer header but is visible to anyone in the browser, so never treat it as a secret. For your own transport, pass a backend with a persist(payload) function instead of apiUrl.

Common mistakes

'apiUrl' does not exist in type 'CookieYesOfflineConfig'. You set apiUrl or backend under mode: "cookie-only". Switch to "self-hosted" or remove them.

regulation is set manually, so region detection is ignored. You set both regulation and region. Keep one.

A custom category does not appear. Your categories list broke one of the rules above; the console warning says which. The built-in five are shown instead.

Next steps

Using the store directly: read and change consent from the runtime initCookieYes() returns
Integrations: load Google Analytics, Meta Pixel and other tags only after consent