Skip to content
Getting StartedConfiguration

Configuration for Nuxt

Markdown
Loading…

Every option of initCookieYes(), grouped by what it changes.

The cookieyes key in nuxt.config.ts is where you configure CookieYes. It takes the same CookieYesConfig that initCookieYes() takes in the other packages. mode defaults to "cookie-only" here, so no option is required.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@cookieyes/nuxt"],
  cookieyes: {
    regulation: "GDPR",
    theme: { primaryColor: "#1863dc" },
  },
});

Options that hold functions, such as integrations, onConsentReady and onConsentUpdate, go under the same key in app/app.config.ts. nuxt.config.ts becomes runtime config, which is JSON and drops functions; in development the module warns when it finds one there.

app/app.config.ts
export default defineAppConfig({
  cookieyes: {
    onConsentUpdate: (state) => {
      console.log("Consent saved", state.categories);
    },
  },
});

The module merges the two files. app.config.ts wins for a key set in both, and one level of nesting is merged, so i18n.messages in one file and i18n.loadLanguage in the other both apply. Arrays are replaced, not combined.

Options

Module options

Two options exist only in the Nuxt module, under cookieyes in nuxt.config.ts:

OptionDefaultWhat it does
stylesHref"/cookieyes/styles.css"The path the module serves the full stylesheet from.
googleConsentModenot settrue, or Consent Mode options, adds Google's deny-by-default snippet right after <meta charset>, before any Google tag. See Google Consent Mode.

Setup

NameTypeDefaultDescription
moderequired"cookie-only" | "self-hosted"NoneWhere the choice is stored: "cookie-only" in a browser cookie only; "self-hosted" also sent to your server.
regulationoptionalRegulationNoneWhich privacy law applies: "GDPR" (opt-in) or "CCPA" (opt-out). Unset behaves as GDPR. Wins over region detection.
regionoptionalRegionConfigNoneOptional geo-detection: choose the active regulation from the visitor's region instead of hardcoding one.

Appearance

NameTypeDefaultDescription
colorSchemeoptionalColorScheme"system"Light, dark, or follow-the-OS theme mode for the banner and preferences dialog.
themeoptionalThemeConfigNoneColours, corner radius and font for every CookieYes surface.

Language

NameTypeDefaultDescription
i18noptionalI18nConfigNoneTranslations, active locale, and on-demand language loading.

Storage and blocking

NameTypeDefaultDescription
categoriesoptionalCategoryDef[]built-in fiveYour own consent-category taxonomy. Omit to get the built-in five (necessary, functional, analytics, performance, advertisement) unchanged.
networkBlockeroptionalNetworkBlockerConfigNoneBlock matching third-party network requests (fetch/XHR/sendBeacon) by category until consent is granted.
googleConsentMatchoptional"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.
apiUrloptionalstringNoneEndpoint each consent record (ConsentPayload) is POSTed to, under mode: "self-hosted". A 2xx response confirms it; otherwise it is kept in the browser and sent again.
apiKeyoptionalstringNoneSent as an Authorization: Bearer <apiKey> header on the apiUrl POST, if set.
backendoptionalConsentBackendNoneCustom persistence adapter (persist(payload)): full control over transport, headers, batching, or a non-HTTP destination. Resolve once the record is stored; throw or reject otherwise, and the SDK keeps it and sends it again.

Callbacks

NameTypeDefaultDescription
integrationsoptionalIntegration[]NoneReady-made, consent-gated third-party integrations (Segment, Meta, Google, more) built from a preset in @cookieyes/scripts.
customStopHandlersoptionalStopHandler[]NoneYour own scripts' stop instructions, for anything without a built-in integration or preset.
onConsentReadyoptional((state: ConsentSnapshot) => void)NoneFires once, when the initial consent state is known.
onConsentUpdateoptional((state: ConsentSnapshot) => void)NoneFires on every saved change, for the life of the page, and cannot be unsubscribed.
reloadOnRevokeoptionalbooleanfalseForce a full page reload when consent is revoked, instead of relying on clean runtime stops.

theme

Nine keys for colour, corner radius and font. Each is listed with its default on Theme tokens.

region

NameTypeDefaultDescription
region.detectoptionalRegionDetectorNoneReturn the visitor's region synchronously: e.g. from a hosting header you already have.
region.mapoptionalRecord<string, Regulation>NoneRegion → regulation mapping (your own). Matched most-specific first: "US-CA" is checked before "US".
region.honorGpcoptionalbooleantrueHonour the browser's Global Privacy Control "do not sell/share" signal (a CCPA opt-out).
region.strictestoptionalRegulation"GDPR"Regulation to apply when the region is unknown or detection fails.
region.debugoptionalbooleanfalseLog the region decision to the console at setup, for local debugging.

Put region.map in nuxt.config.ts. On a page the server renders per request, the module reads the region from the Vercel or Cloudflare geo headers, and those headers are the only region source, for the banner and for the browser alike. A region.detect in app/app.config.ts is used only where the server reads nothing (ssr: false, nuxt generate, and routes with swr, isr, cache or prerender route rules), once the page has loaded.

i18n

messages per language, locale, detectBrowserLanguage and loadLanguage. See Translations.

networkBlocker

rules for requests to block until a category is granted, plus onRequestBlocked and logBlockedRequests. Put rules in nuxt.config.ts: the module finds them there when it builds, registers the blocker itself and bundles it only then. onRequestBlocked is a function, so it goes in app/app.config.ts. See Network blocking.

Choosing a privacy law: the regulation option

"GDPR""CCPA"
Optional categories before the visitor choosesOff, the visitor opts inOn, the visitor opts out
Banner buttonsAccept All, Reject All, CustomiseDo Not Sell
Global Privacy ControlNot usedHonoured

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.

Under "CCPA", a browser that sends Global Privacy Control starts the visitor opted out until they choose; region.honorGpc: false turns this off. The signal never changes which banner shows. To read it yourself, readGpc() returns true while the browser is sending it, and every consent record carries it as gpc.

Under "CCPA", <CookieYesRoot /> renders <CookieOptOut /> for you, and so it does when region can resolve to "CCPA": Do Not Sell opens it.

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

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@cookieyes/nuxt"],
  cookieyes: {
    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 as a consent record, so you can keep proof of it. See Self-hosted mode for what your server receives and how to store it.

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

  • Translations: every text in every language, through i18n
  • Theme tokens: what each theme value changes
  • Integrations: load Google Analytics, Meta Pixel and other tags only after consent

On this page