# c15t Full Context

> All generated markdown documentation pages flattened into one file.

## Included Pages

- [Introduction](https://c15t.com/docs): c15t adds a consent banner, a preference dialog and consent-gated scripts to JavaScript, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start sites.
- [Choose your setup](https://c15t.com/docs/concepts/choose-your-setup): Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.
- [Examples](https://c15t.com/docs/examples): Runnable c15t apps from the c15t repository. Starters show the smallest setup for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML and JavaScript. Showcases show custom banners, preference centers, gated embeds, analytics, IAB TCF, experiments and multilingual sites.
- [How consent works](https://c15t.com/docs/concepts/how-consent-works): What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.
- [Consent categories](https://c15t.com/docs/concepts/consent-categories): Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.
- [Policies](https://c15t.com/docs/concepts/policies): How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.
- [Consent modes](https://c15t.com/docs/concepts/modes): Reference for manifest(), hosted() and offline() in every c15t framework package, where each one resolves the visitor's policy, what it adds to first-load JavaScript, the build-time manifest fetch and its failure policy, and the backend URL variable each framework reads.
- [Data fetching](https://c15t.com/docs/concepts/data-fetching): Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or offline rules, and understand where consent choices are saved.
- [Consent state reference](https://c15t.com/docs/concepts/consent-state): How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.
- [Customize the interface](https://c15t.com/docs/customization/overview): Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.
- [Banner designs](https://c15t.com/docs/customization/recipes): Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.
- [Theme tokens](https://c15t.com/docs/customization/tokens): Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.
- [Dark mode](https://c15t.com/docs/customization/dark-mode): Switch c15t's banner and dialog to dark colors with colorScheme, set your own dark tokens, follow your site's theme switch, and paint dark on the first frame in every framework.
- [Motion and animation](https://c15t.com/docs/customization/motion): Change how fast c15t's banner and dialog animate with duration and easing tokens, turn animations off per surface with disableAnimation, and check reduced-motion behavior in each framework.
- [Stylesheets and CSS layers](https://c15t.com/docs/customization/stylesheets): See how c15t delivers its styles in each framework without a render-blocking stylesheet, when to import styles.css yourself with styles false, which file holds the dialog's rules, and how c15t's cascade layer meets your own.
- [Component parts](https://c15t.com/docs/customization/slots): Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.
- [Class names and CSS-in-JS](https://c15t.com/docs/customization/class-names): Style c15t's component parts with CSS Modules, vanilla-extract, StyleX, Emotion or plain class names, and see which approach works in each framework.
- [Tailwind CSS](https://c15t.com/docs/customization/tailwind): Use c15t's styles with Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.
- [Copy and translations](https://c15t.com/docs/customization/translations): Change consent wording through i18n and test the complete prompt and preferences flow.
- [Banner experiments](https://c15t.com/docs/guides/banner-experiments): Run A/B tests on consent banner presentation with any feature-flag provider or built-in weighted assignment, and attribute every impression and choice to its arm.
- [Verify consent](https://c15t.com/docs/guides/verify-consent): Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.
- [Troubleshooting](https://c15t.com/docs/guides/troubleshooting): Fix a missing banner, analytics that load before consent, choices lost on reload, CORS errors, hydration differences, failed manifest downloads, mode errors and failed static builds in c15t v3.
- [Frameworks](https://c15t.com/docs/frameworks): c15t setup guides for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, plain HTML and JavaScript.
- [Quickstart](https://c15t.com/docs/frameworks/next/quickstart): Add c15t consent management to a Next.js App Router app with Inth, a build-time policy manifest and consent-gated scripts, then check it works. Links to the Pages Router and static export guides.
- [App Router](https://c15t.com/docs/frameworks/next/app-router): Set up c15t in the Next.js App Router with Inth, a build-time policy manifest, consent-gated scripts and a streamed or awaited root layout.
- [Pages Router](https://c15t.com/docs/frameworks/next/pages-router): Set up c15t in the Next.js Pages Router with Inth, a build-time policy manifest, getServerSideProps and consent-gated scripts.
- [Static export](https://c15t.com/docs/frameworks/next/static-export): Add c15t to a Next.js site built with output export, where the browser resolves consent through Inth without request helpers or API routes.
- [Client-side initialization](https://c15t.com/docs/frameworks/next/client-side): Initialize c15t in the browser in a Next.js app with hosted() mode, without server prefetch, a consent route or API handlers.
- [Rendering and deployment](https://c15t.com/docs/frameworks/next/rendering): Choose how Next.js resolves consent for your router, rendering mode and hosting, from streamed App Router layouts to static export, ISR, Cache Components and ensureStatic.
- [Upgrade from v2](https://c15t.com/docs/frameworks/next/upgrade-v3): Upgrade a Next.js app from c15t v2 (@c15t/nextjs) to v3. Covers packages, ConsentRoot or ConsentProvider, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.
- [Scripts](https://c15t.com/docs/frameworks/next/scripts): Register vendor scripts in a Next.js ConsentRoot, check how each vendor loads, let visitors turn off one vendor, clear stored data after revocation and replace @next/third-parties.
- [Embeds](https://c15t.com/docs/frameworks/next/embeds): Keep YouTube videos, maps and other iframes out of a Next.js page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.
- [Network blocker](https://c15t.com/docs/frameworks/next/network-blocker): Hold fetch and XMLHttpRequest calls in a Next.js app until their consent category is allowed, with networkBlocker rules in c15t.config.ts.
- [Vendor consent](https://c15t.com/docs/frameworks/next/vendor-consent): Let visitors allow a category such as marketing in a Next.js app and still turn off one vendor in it, with vendors in c15t.config.ts and useVendorAllowed.
- [Clear on revocation](https://c15t.com/docs/frameworks/next/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a Next.js app when that category is denied, with clearOnRevocation in c15t.config.ts.
- [Customize](https://c15t.com/docs/frameworks/next/customize): Load the c15t stylesheet yourself in Next.js when you need to, and change colors, radius, button roles, component parts, dark mode and banner shape with ConsentTheme and ConsentRoot options.
- [Translations](https://c15t.com/docs/frameworks/next/translations): Where c15t banner and dialog copy comes from in Next.js, how the server and browser pick the visitor's language, and how to override copy and switch languages from a Client Component.
- [Compose your own banner](https://c15t.com/docs/frameworks/next/compose): Build a Next.js consent banner as a Client Component from the ConsentBanner parts in c15t/next, with your own markup and buttons, rendered inside ConsentRoot.
- [Headless](https://c15t.com/docs/frameworks/next/headless): Build a custom consent banner in Next.js with the c15t/next/headless hooks inside your existing ConsentRoot.
- [Components](https://c15t.com/docs/frameworks/next/components): Every c15t component a Next.js app imports from c15t/next, what each renders, which ones are Client Components, and where to start.
- [ConsentRoot](https://c15t.com/docs/frameworks/next/components/consent-root): Render the Next.js ConsentRoot once from a Server Component layout, pass it the server-resolved state, and see how it reads c15t.config.ts and picks the consent mode.
- [ConsentBanner](https://c15t.com/docs/frameworks/next/components/consent-banner): Render the pre-built ConsentBanner inside a Next.js ConsentRoot and configure its variants, per-policy buttons and compound parts.
- [ConsentDialog](https://c15t.com/docs/frameworks/next/components/consent-dialog): Mount ConsentDialog as a Client Component inside a Next.js ConsentRoot to open the preference center from the banner, links and triggers.
- [ConsentWidget](https://c15t.com/docs/frameworks/next/components/consent-widget): Render ConsentWidget on a Next.js privacy page inside ConsentRoot as an inline preference center, server-rendered when the route resolves consent.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/next/components/consent-dialog-link): Open the preference center from a Next.js footer with ConsentDialogLink, a Client Component that renders an unstyled button inside ConsentRoot.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/next/components/consent-dialog-trigger): Add the floating ConsentDialogTrigger button or toolbar to a Next.js ConsentRoot so visitors can reopen the preference center.
- [ConsentGate](https://c15t.com/docs/frameworks/next/components/consent-gate): Consent-gate an iframe in Next.js with ConsentGate inside ConsentRoot; with server prefetch the server HTML carries the placeholder for a denied category, and a granted embed mounts after hydration.
- [Hooks](https://c15t.com/docs/frameworks/next/hooks): Gate features and save consent choices in Next.js Client Components with the focused hooks exported from c15t/next.
- [Callbacks](https://c15t.com/docs/frameworks/next/callbacks): Run code in a Next.js app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, from c15t.config.ts.
- [IAB TCF](https://c15t.com/docs/frameworks/next/iab): Mount the IAB TCF banner and dialog inside a Next.js ConsentRoot and configure the CMP ID, policy and vendor data.
- [IAB GPP](https://c15t.com/docs/frameworks/next/gpp): Add the IAB Global Privacy Platform API (__gpp) to a Next.js app with ConsentGPP from c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Geography headers](https://c15t.com/docs/frameworks/next/geography-headers): Use c15tProxy in Next.js proxy.ts or middleware.ts so Server Components and Route Handlers receive the visitor's country and region.
- [Content Security Policy](https://c15t.com/docs/frameworks/next/content-security-policy): Pass a per-request CSP nonce to ConsentRoot in Next.js and allow the consent backend in connect-src.
- [Performance](https://c15t.com/docs/frameworks/next/optimization): Bundle policy at build time to avoid manifest fetch latency, use runtime caching when policies must refresh without a rebuild, and optionally keep browser consent requests on your origin.
- [Data fetching reference](https://c15t.com/docs/frameworks/next/data-fetching-reference): Reference for the Next.js c15t.config.ts options, modes, resolveConsent, withConsentProps, the consent route, manifest resolution, request geography and offline configuration.
- [DevTools](https://c15t.com/docs/frameworks/next/components/dev-tools): Load the c15t DevTools panel only in Next.js development builds to inspect consent state, scripts, policy and events inside ConsentRoot.
- [Troubleshooting](https://c15t.com/docs/frameworks/next/troubleshooting): Diagnose failed c15t consent prefetch and build-time manifest downloads in Next.js, verify manifest requests, and fix a missing c15t.config.ts, config errors, unknown server location and prerendering errors.
- [Quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart): Resolve consent on the server in a TanStack Start root loader, render the banner in the first HTML, and gate vendor scripts, using Inth as the consent backend.
- [Rendering and deployment](https://c15t.com/docs/frameworks/tanstack-start/rendering): Choose how a TanStack Start app resolves consent, with an awaited or streamed root loader, a same-origin consent route, or SPA mode, prerendered pages and static hosting.
- [Scripts](https://c15t.com/docs/frameworks/tanstack-start/scripts): Load vendor scripts by consent category in a TanStack Start app with ConsentRoot, and clear stored data or reload the page when a visitor withdraws consent.
- [Embeds](https://c15t.com/docs/frameworks/tanstack-start/embeds): Keep YouTube videos, maps and other iframes out of a TanStack Start page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.
- [Network blocker](https://c15t.com/docs/frameworks/tanstack-start/network-blocker): Hold fetch and XMLHttpRequest calls in a TanStack Start app until their consent category is allowed, with networkBlocker rules on ConsentRoot.
- [Vendor consent](https://c15t.com/docs/frameworks/tanstack-start/vendor-consent): Let visitors allow a category such as marketing in a TanStack Start app and still turn off one vendor in it, with the vendors prop on ConsentRoot and useVendorAllowed.
- [Clear on revocation](https://c15t.com/docs/frameworks/tanstack-start/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a TanStack Start app when that category is denied, with the clearOnRevocation prop on ConsentRoot.
- [Customize](https://c15t.com/docs/frameworks/tanstack-start/customize): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a TanStack Start app with theme tokens, ConsentRoot options and component parts, and load the stylesheet yourself when you need to.
- [Translations](https://c15t.com/docs/frameworks/tanstack-start/translations): Where c15t banner and dialog copy comes from in TanStack Start, how the server and browser pick the visitor's language, and how to override copy and switch languages from the root route.
- [Compose your own banner](https://c15t.com/docs/frameworks/tanstack-start/compose): Build a TanStack Start consent banner from the ConsentBanner parts in c15t/tanstack-start, with your own markup and buttons, rendered inside ConsentRoot in the root route.
- [Headless](https://c15t.com/docs/frameworks/tanstack-start/headless): Build your own consent banner markup in a TanStack Start app with the c15t/tanstack-start/headless hooks inside ConsentRoot.
- [Components](https://c15t.com/docs/frameworks/tanstack-start/components): ConsentRoot and the consent banner, dialog, widget, links, gate and DevTools components a TanStack Start app imports from c15t/tanstack-start.
- [ConsentBanner](https://c15t.com/docs/frameworks/tanstack-start/components/consent-banner): Render the c15t consent banner in a TanStack Start app, set its variant and position, and override its labels.
- [ConsentDialog](https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog): Open the c15t preference dialog in a TanStack Start app, reopen it from your own controls, and control blocking, focus and policy gating.
- [ConsentWidget](https://c15t.com/docs/frameworks/tanstack-start/components/consent-widget): Embed the c15t preference controls inline on a TanStack Start privacy page with ConsentWidget, recording a choice only when the visitor saves.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog-link): Add a ConsentDialogLink to a TanStack Start footer so visitors can reopen the c15t preference dialog from your own text link.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog-trigger): Add a floating button or toolbar to a TanStack Start app that reopens the c15t preference dialog after the first prompt.
- [ConsentGate](https://c15t.com/docs/frameworks/tanstack-start/components/consent-gate): Gate a YouTube video, map or other iframe behind consent in a TanStack Start app with ConsentGate, showing a placeholder until the category is allowed.
- [Hooks](https://c15t.com/docs/frameworks/tanstack-start/hooks): Read consent permissions, open the preference dialog and save choices in TanStack Start components with the hooks exported from c15t/tanstack-start.
- [Callbacks](https://c15t.com/docs/frameworks/tanstack-start/callbacks): Run code in a TanStack Start app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, from ConsentRoot in the root route.
- [IAB TCF](https://c15t.com/docs/frameworks/tanstack-start/iab): Show the IAB TCF banner and dialog in a TanStack Start app for visitors whose policy uses the IAB model, with c15t/react/iab inside ConsentRoot.
- [IAB GPP](https://c15t.com/docs/frameworks/tanstack-start/gpp): Add the IAB Global Privacy Platform API (__gpp) to a TanStack Start app with ConsentGPP from c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Geography headers](https://c15t.com/docs/frameworks/tanstack-start/geography-headers): Which request headers c15t reads for country, region, language and Global Privacy Control in TanStack Start, where the server functions and consent route send them, and how to test another location.
- [Content Security Policy](https://c15t.com/docs/frameworks/tanstack-start/content-security-policy): Run c15t in a TanStack Start app under a Content Security Policy, pass the router's per-request nonce to ConsentRoot, and allow the consent backend and vendor hosts.
- [DevTools](https://c15t.com/docs/frameworks/tanstack-start/components/dev-tools): Inspect consent state, location, loaded scripts and consent events in a TanStack Start app during development, on its own or inside TanStack Devtools.
- [Troubleshooting](https://c15t.com/docs/frameworks/tanstack-start/troubleshooting): Fix build-time manifest failures, a missing server-rendered banner, server function errors, proxy and firewall failures, and early vendor requests in a TanStack Start app that uses c15t.
- [Quickstart](https://c15t.com/docs/frameworks/react/quickstart): Add a consent banner, preferences dialog and consent-gated scripts to a React single-page app built with Vite, using Inth as the consent backend.
- [Rendering and deployment](https://c15t.com/docs/frameworks/react/rendering): How c15t resolves consent in client-rendered React apps, React Router framework mode, Remix and other server-rendered React apps without a c15t adapter.
- [Upgrade from v2](https://c15t.com/docs/frameworks/react/upgrade-v3): Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers packages, ConsentProvider and transports, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.
- [Scripts](https://c15t.com/docs/frameworks/react/scripts): Load vendor scripts by consent category in a React app with ConsentProvider, and clear stored data or reload the page when a visitor withdraws consent.
- [Embeds](https://c15t.com/docs/frameworks/react/embeds): Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.
- [Network blocker](https://c15t.com/docs/frameworks/react/network-blocker): Hold fetch and XMLHttpRequest calls in a React app until their consent category is allowed, with networkBlocker rules in the ConsentProvider options.
- [Vendor consent](https://c15t.com/docs/frameworks/react/vendor-consent): Let visitors allow a category such as marketing in a React app and still turn off one vendor in it, with the vendors option on ConsentProvider and useVendorAllowed.
- [Clear on revocation](https://c15t.com/docs/frameworks/react/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a React app when that category is denied, with the clearOnRevocation option on ConsentProvider.
- [Customize](https://c15t.com/docs/frameworks/react/customize): Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with theme tokens, provider options and slots, and load the stylesheet yourself when you need to.
- [Translations](https://c15t.com/docs/frameworks/react/translations): Where c15t banner and dialog copy comes from in a React app, how the browser picks the visitor's language, and how to override copy and switch languages with the provider's i18n option and hooks.
- [Compose your own banner](https://c15t.com/docs/frameworks/react/compose): Build a React consent banner from the ConsentBanner parts in c15t/react, with your own markup and buttons, while the policy still decides which actions appear.
- [Headless](https://c15t.com/docs/frameworks/react/headless): Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.
- [Components](https://c15t.com/docs/frameworks/react/components): Every c15t component a React app imports from c15t/react, what each renders, where each one mounts, and which to start with.
- [ConsentProvider](https://c15t.com/docs/frameworks/react/components/consent-provider): Mount ConsentProvider in a React app and configure its backend, scripts, storage, blocking and presentation options.
- [ConsentBanner](https://c15t.com/docs/frameworks/react/components/consent-banner): Render the c15t consent banner in a React app, choose its variant and position, and compose its parts.
- [ConsentDialog](https://c15t.com/docs/frameworks/react/components/consent-dialog): Open the c15t preference center as a modal ConsentDialog in a React app, wire its triggers and control blocking, focus and policy gating.
- [ConsentWidget](https://c15t.com/docs/frameworks/react/components/consent-widget): Embed the c15t preference center inline with ConsentWidget on a React privacy page, with draft toggles that record a choice only on Save.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/react/components/consent-dialog-link): Add a ConsentDialogLink to a React footer so visitors reopen the c15t preference center from your own text link, with asChild and rights data.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/react/components/consent-dialog-trigger): Add the c15t ConsentDialogTrigger floating button or toolbar inside a React ConsentProvider so visitors can reopen the preference center after the first prompt.
- [ConsentGate](https://c15t.com/docs/frameworks/react/components/consent-gate): Gate a YouTube or map iframe behind consent with ConsentGate in React, showing a placeholder that opens the preference center until the category is allowed.
- [Hooks](https://c15t.com/docs/frameworks/react/hooks): Gate features and save consent choices in React components with the focused hooks exported from c15t/react.
- [Callbacks](https://c15t.com/docs/frameworks/react/callbacks): Run code in a React app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, with the ConsentProvider callbacks option.
- [IAB TCF](https://c15t.com/docs/frameworks/react/iab): Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.
- [IAB GPP](https://c15t.com/docs/frameworks/react/gpp): Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Content Security Policy](https://c15t.com/docs/frameworks/react/content-security-policy): Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.
- [DevTools](https://c15t.com/docs/frameworks/react/components/dev-tools): Inspect consent state, location, loaded scripts and consent events in a React app during development with the c15t DevTools panel.
- [Troubleshooting](https://c15t.com/docs/frameworks/react/troubleshooting): Fix a missing banner, early vendor requests, unstyled components and theme warnings in a React app that uses c15t/react.
- [Quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart): Add c15t to a server-rendered Nuxt app with the Nuxt module, Inth, consent-gated scripts and a preferences link.
- [Nuxt module](https://c15t.com/docs/frameworks/nuxt/module): What the c15t Nuxt module registers, where each option goes between nuxt.config.ts and app.config.ts, and every module option.
- [Rendering and deployment](https://c15t.com/docs/frameworks/nuxt/rendering): Choose the c15t Nuxt module's mode and routePrefix for server rendering, prerendered and cached routes, nuxt generate on static hosting, and ssr false.
- [Scripts](https://c15t.com/docs/frameworks/nuxt/scripts): Load vendor scripts by consent category in a Nuxt app with the c15t Nuxt module, what happens when a visitor withdraws consent, and how to move off @nuxt/scripts and nuxt-gtag.
- [Embeds](https://c15t.com/docs/frameworks/nuxt/embeds): Keep YouTube videos, maps and other iframes out of a Nuxt page until their consent category is allowed, with ConsentGate or the iframe blocker.
- [Network blocker](https://c15t.com/docs/frameworks/nuxt/network-blocker): Hold fetch and XMLHttpRequest calls in a Nuxt app until their consent category is allowed, with rules in the c15t module options.
- [Vendor consent](https://c15t.com/docs/frameworks/nuxt/vendor-consent): Let visitors allow a category such as marketing in a Nuxt app and still turn off one vendor in it, with the vendors option of the c15t Nuxt module and useConsentDraft.
- [Clear on revocation](https://c15t.com/docs/frameworks/nuxt/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a Nuxt app when that category is denied, with the clearOnRevocation option of the c15t Nuxt module.
- [Customize](https://c15t.com/docs/frameworks/nuxt/customize): Change the c15t banner and dialog in Nuxt with theme tokens, layout presentation, component slots and copy.
- [Translations](https://c15t.com/docs/frameworks/nuxt/translations): Where the c15t banner and dialog text comes from in Nuxt, how the server picks the visitor's language, and how to switch it at runtime.
- [Headless](https://c15t.com/docs/frameworks/nuxt/headless): Build your own consent banner and preference form in Nuxt with the auto-imported c15t composables instead of ConsentRoot.
- [Components](https://c15t.com/docs/frameworks/nuxt/components): Every c15t component in Nuxt, which ones the Nuxt module registers globally, which you import, and a page for each one's props and behavior.
- [ConsentRoot](https://c15t.com/docs/frameworks/nuxt/components/consent-root): Mount the c15t banner, preference dialog and floating trigger in Nuxt with the globally registered ConsentRoot, rendered on the server.
- [ConsentBanner](https://c15t.com/docs/frameworks/nuxt/components/consent-banner): Render the c15t consent banner in Nuxt, choose its variant and position, and understand what it shows for each policy.
- [ConsentManager](https://c15t.com/docs/frameworks/nuxt/components/consent-manager): Render the c15t preference dialog in Nuxt, open it from your own code, and understand its actions, focus handling and styling.
- [ConsentWidget](https://c15t.com/docs/frameworks/nuxt/components/consent-widget): Put the c15t category switches and save actions inline on a Nuxt privacy settings page with the globally registered ConsentWidget.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/nuxt/components/consent-dialog-link): Add a Privacy settings button that reopens the c15t preference dialog in Nuxt, and hide it when the policy offers no preferences.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/nuxt/components/consent-dialog-trigger): Show a floating, draggable button that reopens the c15t preference dialog in Nuxt, and configure its corner, size, icon and label.
- [ConsentGate](https://c15t.com/docs/frameworks/nuxt/components/consent-gate): Render an iframe or widget in Nuxt only while its consent category is allowed, with the globally registered ConsentGate and a placeholder slot.
- [IABConsentBanner](https://c15t.com/docs/frameworks/nuxt/components/iab-consent-banner): Render the IAB TCF first layer in Nuxt with IABConsentBanner, when to import it instead of relying on ConsentRoot, and its props.
- [IABConsentDialog](https://c15t.com/docs/frameworks/nuxt/components/iab-consent-dialog): Render the IAB TCF preference centre in Nuxt with IABConsentDialog, choose its first tab, and build a custom one with composables.
- [Composables](https://c15t.com/docs/frameworks/nuxt/composables): Every c15t composable the Nuxt module auto-imports, grouped by task, with the difference between a permission and a recorded choice.
- [Callbacks](https://c15t.com/docs/frameworks/nuxt/callbacks): Run code in a Nuxt app when a visitor records a consent choice, when permissions change, before a revocation reload, and when c15t reports an error.
- [IAB TCF](https://c15t.com/docs/frameworks/nuxt/iab): Turn on IAB TCF in Nuxt with the c15t module's iab option, so visitors under an IAB policy get the IAB banner, preference centre and __tcfapi.
- [IAB GPP](https://c15t.com/docs/frameworks/nuxt/gpp): Turn on the IAB Global Privacy Platform API (__gpp) in Nuxt with the c15t Nuxt module's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Geography headers](https://c15t.com/docs/frameworks/nuxt/geography-headers): Which request headers the c15t Nuxt module reads for the visitor's country, region, language and Global Privacy Control, and how to trust and test them.
- [Content Security Policy](https://c15t.com/docs/frameworks/nuxt/content-security-policy): Allow c15t in a Nuxt app under a Content Security Policy, including the theme token style tag, same-origin routes, the backend and vendor scripts.
- [DevTools](https://c15t.com/docs/frameworks/nuxt/components/dev-tools): Inspect consent state, the resolved policy, location, scripts and consent events in a Nuxt app during development with ConsentDevTools.
- [Troubleshooting](https://c15t.com/docs/frameworks/nuxt/troubleshooting): Fix common c15t Nuxt module problems, from a missing banner and scripts that never load to returning banners and static hosting.
- [Quickstart](https://c15t.com/docs/frameworks/vue/quickstart): Add c15t to a Vue 3 app built with Vite, using the Vue plugin, Inth, consent-gated scripts and a preferences link.
- [c15tVue plugin](https://c15t.com/docs/frameworks/vue/plugin): Install c15t in a Vue app with app.use(c15tVue), what the plugin starts when the app mounts, and every option it accepts.
- [Rendering and deployment](https://c15t.com/docs/frameworks/vue/rendering): Pick where a Vue app's consent policy comes from with the plugin's mode option, host it statically, and why server-rendered Vue apps should use Nuxt.
- [Scripts](https://c15t.com/docs/frameworks/vue/scripts): Load vendor scripts by consent category in a Vue app with the c15t Vue plugin, and what happens when a visitor withdraws consent.
- [Embeds](https://c15t.com/docs/frameworks/vue/embeds): Keep YouTube videos, maps and other iframes out of a Vue page until their consent category is allowed, with ConsentGate or the iframe blocker.
- [Network blocker](https://c15t.com/docs/frameworks/vue/network-blocker): Hold fetch and XMLHttpRequest calls in a Vue app until their consent category is allowed, with rules passed to the c15t Vue plugin.
- [Vendor consent](https://c15t.com/docs/frameworks/vue/vendor-consent): Let visitors allow a category such as marketing in a Vue app and still turn off one vendor in it, with the vendors option on the c15tVue plugin and useConsentDraft.
- [Clear on revocation](https://c15t.com/docs/frameworks/vue/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a Vue app when that category is denied, with the clearOnRevocation option on the c15tVue plugin.
- [Customize](https://c15t.com/docs/frameworks/vue/customize): Change the c15t banner and dialog in a Vue app with theme tokens, layout presentation, component slots and copy.
- [Translations](https://c15t.com/docs/frameworks/vue/translations): Where the c15t banner and dialog text comes from in a Vue app, how c15t picks the visitor's language, and how to switch it at runtime.
- [Headless](https://c15t.com/docs/frameworks/vue/headless): Build your own consent banner and preference form in a Vue app with the c15t composables instead of ConsentRoot.
- [Components](https://c15t.com/docs/frameworks/vue/components): Every c15t Vue component, its import path and what it renders, with a page for each one's props, behavior, accessibility and styling.
- [ConsentRoot](https://c15t.com/docs/frameworks/vue/components/consent-root): Mount the c15t banner, preference dialog and floating trigger in a Vue app with one ConsentRoot component from c15t/vue/vue-plugin.
- [ConsentBanner](https://c15t.com/docs/frameworks/vue/components/consent-banner): Render the c15t consent banner in a Vue app, choose its variant and position, and understand what it shows for each policy.
- [ConsentManager](https://c15t.com/docs/frameworks/vue/components/consent-manager): Render the c15t preference dialog in a Vue app, open it from your own code, and understand its actions, focus handling and styling.
- [ConsentWidget](https://c15t.com/docs/frameworks/vue/components/consent-widget): Put the c15t category switches and save actions inline on a Vue privacy settings page with ConsentWidget from c15t/vue/vue-plugin.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/vue/components/consent-dialog-link): Add a Privacy settings button that reopens the c15t preference dialog in a Vue app, and hide it when the policy offers no preferences.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/vue/components/consent-dialog-trigger): Show a floating, draggable button that reopens the c15t preference dialog in a Vue app, and configure its corner, size, icon and label.
- [ConsentGate](https://c15t.com/docs/frameworks/vue/components/consent-gate): Render an iframe or widget in a Vue app only while its consent category is allowed, with a placeholder slot until then.
- [IABConsentBanner](https://c15t.com/docs/frameworks/vue/components/iab-consent-banner): Render the IAB TCF first layer in a Vue app with IABConsentBanner, when to import it instead of relying on ConsentRoot, and its props.
- [IABConsentDialog](https://c15t.com/docs/frameworks/vue/components/iab-consent-dialog): Render the IAB TCF preference centre in a Vue app with IABConsentDialog, choose its first tab, and build a custom one with composables.
- [Composables](https://c15t.com/docs/frameworks/vue/composables): Every c15t composable for a Vue app, grouped by task, with the difference between a permission and a recorded choice.
- [Callbacks](https://c15t.com/docs/frameworks/vue/callbacks): Run code in a Vue app when a visitor records a consent choice, when permissions change, before a revocation reload, and when c15t reports an error.
- [IAB TCF](https://c15t.com/docs/frameworks/vue/iab): Turn on IAB TCF in a Vue app with the c15t Vue plugin's iab option, so visitors under an IAB policy get the IAB banner, preference centre and __tcfapi.
- [IAB GPP](https://c15t.com/docs/frameworks/vue/gpp): Turn on the IAB Global Privacy Platform API (__gpp) in a Vue app with the c15t Vue plugin's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Content Security Policy](https://c15t.com/docs/frameworks/vue/content-security-policy): Allow c15t in a Vue app under a Content Security Policy, with a script nonce, the backend in connect-src, and the styles the components inject.
- [DevTools](https://c15t.com/docs/frameworks/vue/components/dev-tools): Inspect consent state, the resolved policy, location, scripts and consent events in a Vue app during development with ConsentDevTools.
- [Troubleshooting](https://c15t.com/docs/frameworks/vue/troubleshooting): Fix common c15t Vue plugin problems, from unresolved imports and a missing banner to tokens that do not apply and scripts that load twice.
- [Quickstart](https://c15t.com/docs/frameworks/astro/quickstart): Add a c15t consent banner, preference dialog and consent-gated scripts to an Astro 5, 6 or 7 site with the c15t integration and Inth, on static or server output.
- [Rendering and deployment](https://c15t.com/docs/frameworks/astro/rendering): Choose how c15t resolves consent on an Astro site, from static output with hosted() or browser-resolved manifest() to server output with manifest(), prerendered pages, server islands, ClientRouter and offline development.
- [Scripts](https://c15t.com/docs/frameworks/astro/scripts): Load vendor scripts and gated inline scripts on an Astro site only after the visitor allows their consent category, and stop them when consent is withdrawn.
- [Embeds](https://c15t.com/docs/frameworks/astro/embeds): Gate YouTube videos, maps, social posts and other iframes on an Astro site so they load only after the visitor allows their consent category, with a custom element or the c15t iframe blocker.
- [Network blocker](https://c15t.com/docs/frameworks/astro/network-blocker): Block fetch and XMLHttpRequest calls to tracking hosts on an Astro site until the visitor allows their consent category, with c15t's network blocker rules and an onRequestBlocked handler.
- [Vendor consent](https://c15t.com/docs/frameworks/astro/vendor-consent): Let visitors allow a category such as marketing on an Astro site and still turn off one vendor in it, with the vendors option on the c15t() integration and the page client from c15t/astro/client.
- [Clear on revocation](https://c15t.com/docs/frameworks/astro/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns on an Astro site when that category is denied, with the clearOnRevocation option of the c15t integration.
- [Customize](https://c15t.com/docs/frameworks/astro/customize): Change the c15t banner and preference dialog on an Astro site with theme tokens, button styles, copy, dark mode, legal links and your own stylesheet order, all from the integration options.
- [Translations](https://c15t.com/docs/frameworks/astro/translations): Set the language and wording of the c15t banner and preference dialog on an Astro site with the integration's i18n option, from Accept-Language negotiation to per-language message overrides and banner props.
- [Components](https://c15t.com/docs/frameworks/astro/components): Every c15t Astro component, from ConsentScript and ConsentBanner to the server island banner, the preference dialog, its link and the IAB TCF surfaces, with import paths and links to each reference.
- [ConsentScript](https://c15t.com/docs/frameworks/astro/components/consent-script): Put the c15t ConsentScript component in the head of an Astro layout so the browser starts with the server's consent decision, the right color scheme and your theme tokens.
- [ConsentBanner](https://c15t.com/docs/frameworks/astro/components/consent-banner): Render the c15t consent banner as server HTML on an Astro site, with props for copy, legal links and branding, the policy-driven actions, accessibility behavior and the attributes to style it.
- [ConsentBannerDeferred](https://c15t.com/docs/frameworks/astro/components/consent-banner-deferred): Render the c15t consent banner in an Astro server island, so a cached or prerendered page still shows each visitor the banner for their own location and stored choice.
- [ConsentDialog](https://c15t.com/docs/frameworks/astro/components/consent-dialog): Add the c15t preference dialog to an Astro site as an island that downloads only when a visitor opens it, and control when it loads, which framework renders it, how it opens and which legal links it shows.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/astro/components/consent-dialog-link): Add a footer button or link that reopens the c15t preference dialog or the IAB TCF preference center on an Astro site, with no JavaScript of its own.
- [IABConsentBanner](https://c15t.com/docs/frameworks/astro/components/iab-consent-banner): Render the IAB TCF 2.4 banner as server HTML on an Astro site with c15t, with the purposes, partner count and actions TCF requires, its props, accessibility and styling attributes.
- [IABConsentDialog](https://c15t.com/docs/frameworks/astro/components/iab-consent-dialog): Add the IAB TCF 2.4 preference center to an Astro site with c15t as an island that loads the TCF code only when a visitor opens it.
- [Client API](https://c15t.com/docs/frameworks/astro/client-api): Reference for c15t/astro/client on an Astro site, grouped by task, from reading permissions and recorded choices to opening dialogs, saving consent, gated scripts, the page runtime and analytics events.
- [Callbacks](https://c15t.com/docs/frameworks/astro/callbacks): Run your own code on an Astro site when a visitor records a consent choice, when permissions change, before a revocation reload and on errors, with c15t callbacks in the client entrypoint.
- [IAB TCF](https://c15t.com/docs/frameworks/astro/iab): Render the IAB TCF 2.4 banner and preference center on an Astro site with the c15t integration, and configure the CMP ID, vendor list source and publisher restrictions.
- [IAB GPP](https://c15t.com/docs/frameworks/astro/gpp): Expose the IAB Global Privacy Platform API (__gpp) on an Astro site with the c15t integration's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Geography headers](https://c15t.com/docs/frameworks/astro/geography-headers): Which request headers the c15t Astro middleware reads for the visitor's country, region, language and Global Privacy Control, how to check your host sends them, and how to test a region locally.
- [Content Security Policy](https://c15t.com/docs/frameworks/astro/content-security-policy): Run c15t on an Astro site under a strict Content Security Policy, with a per-request nonce from your middleware or with Astro's own hash-based CSP, and allow the consent backend and vendors.
- [Islands](https://c15t.com/docs/frameworks/astro/islands): Choose whether React, Vue or Svelte renders the c15t preference dialog on an Astro site, and read consent from your own framework islands through the page's shared consent runtime.
- [Integration options](https://c15t.com/docs/frameworks/astro/integration): Reference for every option of the c15t() Astro integration, the Astro equivalent of a consent provider, from backendURL, mode and routePrefix to ui, theme, i18n, middleware and the client entrypoint.
- [Server API](https://c15t.com/docs/frameworks/astro/server): How the c15t middleware resolves consent for each Astro request, what Astro.locals.c15t holds, the helpers in c15t/astro/server, the injected consent route, and how to cache server-rendered pages safely.
- [Troubleshooting](https://c15t.com/docs/frameworks/astro/troubleshooting): Fix common c15t problems on Astro sites, from build errors about adapters and UI integrations to a missing banner, scripts that run too early, unstyled dialogs and saves that fail.
- [Quickstart](https://c15t.com/docs/frameworks/svelte/quickstart): Add a c15t cookie banner, preference dialog and consent-gated scripts to a Svelte 5 app built with Vite, with your Inth policy bundled at build time.
- [Scripts](https://c15t.com/docs/frameworks/svelte/scripts): Load vendor scripts, iframes and network requests in a Svelte app only after the visitor allows their consent category, and stop them when consent is withdrawn.
- [Embeds](https://c15t.com/docs/frameworks/svelte/embeds): Keep YouTube videos, maps and other iframes out of a Svelte page until their consent category is allowed, with ConsentGate or the iframe blocker.
- [Network blocker](https://c15t.com/docs/frameworks/svelte/network-blocker): Hold fetch and XMLHttpRequest calls to tracking domains in a Svelte app until their consent category is allowed, with the provider's networkBlocker option.
- [Vendor consent](https://c15t.com/docs/frameworks/svelte/vendor-consent): Let visitors allow a category such as marketing in a Svelte app and still turn off one vendor in it, with the vendors prop on ConsentProvider and getConsentManager.
- [Clear on revocation](https://c15t.com/docs/frameworks/svelte/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a Svelte app when that category is denied, with the clearOnRevocation prop on ConsentProvider.
- [Customize](https://c15t.com/docs/frameworks/svelte/customize): Change c15t's colors, shape, button styles and copy in a Svelte app with a token stylesheet, theme slots, presentation props and translations.
- [Translations](https://c15t.com/docs/frameworks/svelte/translations): Change c15t banner and dialog copy in a Svelte app with component text props or the provider's i18n option, and switch languages at runtime.
- [Primitives](https://c15t.com/docs/frameworks/svelte/components/primitives): Build your own accessible consent dialog in Svelte with the Dialog, Switch, Tabs, Accordion and PreferenceItem primitives and the focusTrap, scrollLock and portal actions.
- [Headless](https://c15t.com/docs/frameworks/svelte/headless): Replace the c15t banner or preference dialog with your own Svelte markup while the provider keeps policy, storage and script loading.
- [Components](https://c15t.com/docs/frameworks/svelte/components): Props and behavior of every @c15t/svelte component in a Svelte app, from ConsentProvider and ConsentBanner to ConsentGate and DevTools.
- [ConsentProvider](https://c15t.com/docs/frameworks/svelte/components/consent-provider): Mount ConsentProvider at the root of a Svelte app to start c15t, with every prop, its default, and which options update after mount.
- [ConsentBanner](https://c15t.com/docs/frameworks/svelte/components/consent-banner): Show the c15t cookie banner in a Svelte app with ConsentBanner, and set its variant, position, button layout, copy, accessibility and styling hooks.
- [ConsentDialog](https://c15t.com/docs/frameworks/svelte/components/consent-dialog): Add the c15t preference dialog to a Svelte app with ConsentDialog, including how it loads on first use, its props, keyboard behavior and theme slots.
- [ConsentWidget](https://c15t.com/docs/frameworks/svelte/components/consent-widget): Put c15t's category switches inline on a Svelte privacy settings page with ConsentWidget, and how its draft, vendors and stale-policy alert behave.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/svelte/components/consent-dialog-link): Let visitors reopen c15t preferences from a Svelte footer with ConsentDialogLink, an unstyled button that renders only when the policy offers preferences.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/svelte/components/consent-dialog-trigger): Add a floating, draggable privacy button to a Svelte app with ConsentDialogTrigger, and set its corner, size, saved position, accessible name and callbacks.
- [ConsentGate](https://c15t.com/docs/frameworks/svelte/components/consent-gate): Keep a YouTube video or map out of a Svelte page until its consent category is allowed with ConsentGate, and replace its placeholder.
- [ConsentButton](https://c15t.com/docs/frameworks/svelte/components/consent-button): Accept, reject, save or open preferences from your own Svelte markup with ConsentButton, and what each action records.
- [IABConsentBanner](https://c15t.com/docs/frameworks/svelte/components/iab-consent-banner): Show the IAB TCF 2.4 first-layer banner to visitors under an IAB policy in a Svelte app with IABConsentBanner, its props and behavior.
- [IABConsentDialog](https://c15t.com/docs/frameworks/svelte/components/iab-consent-dialog): Show the IAB TCF 2.4 preference center with purposes, features and vendors in a Svelte app with IABConsentDialog.
- [Context getters](https://c15t.com/docs/frameworks/svelte/getters): Reference for every @c15t/svelte context getter in a Svelte app, from reading permissions and recorded choices to saving, the draft, IAB state and kernel events.
- [Callbacks](https://c15t.com/docs/frameworks/svelte/callbacks): Run your own code in a Svelte app when a visitor records a choice or permissions change, with onChoiceRecorded, onPermissionsChanged and script callbacks.
- [IAB TCF](https://c15t.com/docs/frameworks/svelte/iab): Turn on the IAB TCF 2.4 banner and preference center in a Svelte app with IABConsentBanner, IABConsentDialog and the provider's iab option.
- [IAB GPP](https://c15t.com/docs/frameworks/svelte/gpp): Expose the IAB Global Privacy Platform API (__gpp) from a Svelte app with the provider's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Content Security Policy](https://c15t.com/docs/frameworks/svelte/content-security-policy): Write a Content Security Policy for a Svelte app using c15t, with the hosts to allow, the provider's nonce option and what c15t injects.
- [DevTools](https://c15t.com/docs/frameworks/svelte/components/dev-tools): Inspect consent, scripts, location and events in a Svelte app with ConsentDevTools from @c15t/svelte/devtools, loaded only in development.
- [Troubleshooting](https://c15t.com/docs/frameworks/svelte/troubleshooting): Fix a Vite build that cannot fetch the c15t manifest, a missing bundled policy, a missing banner, a wrong backend URL, ignored theme colors and vendors that load before consent in a Svelte app.
- [Quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart): Bundle your c15t policy into a SvelteKit server at build time, resolve consent in the root layout load so the banner is in the server HTML, then hydrate ConsentRoot with consent-gated scripts and a preferences link.
- [Rendering and deployment](https://c15t.com/docs/frameworks/sveltekit/rendering): Use the recommended build-time manifest for SvelteKit server rendering, choose runtime fetching for policy updates without a rebuild, and handle prerendered pages, static sites and SPA mode.
- [Scripts](https://c15t.com/docs/frameworks/sveltekit/scripts): Load vendor scripts, iframes and network requests in a SvelteKit app only after the visitor allows their consent category, and stop them when consent is withdrawn.
- [Embeds](https://c15t.com/docs/frameworks/sveltekit/embeds): Keep YouTube videos, maps and other iframes out of SvelteKit server HTML and the browser until their consent category is allowed.
- [Network blocker](https://c15t.com/docs/frameworks/sveltekit/network-blocker): Hold browser fetch and XMLHttpRequest calls to tracking domains in a SvelteKit app until their consent category is allowed, with the networkBlocker option.
- [Vendor consent](https://c15t.com/docs/frameworks/sveltekit/vendor-consent): Let visitors allow a category such as marketing in a SvelteKit app and still turn off one vendor in it, with the vendors prop on ConsentRoot and getConsentManager.
- [Clear on revocation](https://c15t.com/docs/frameworks/sveltekit/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a SvelteKit app when that category is denied, with the clearOnRevocation prop on ConsentRoot.
- [Customize](https://c15t.com/docs/frameworks/sveltekit/customize): Render c15t brand colors on the SvelteKit server with generateThemeCSS, and change slots, button styles, banner shape and copy.
- [Translations](https://c15t.com/docs/frameworks/sveltekit/translations): Change c15t banner and dialog copy in a SvelteKit app, where the server-resolved consent carries the translations for the request's language.
- [Primitives](https://c15t.com/docs/frameworks/sveltekit/components/primitives): Build your own accessible consent dialog in SvelteKit with the Dialog, Switch, Tabs, Accordion and PreferenceItem primitives and the focusTrap, scrollLock and portal actions.
- [Headless](https://c15t.com/docs/frameworks/sveltekit/headless): Replace the c15t banner or preference dialog with your own markup in a SvelteKit app while the provider keeps policy, storage and script loading.
- [Components](https://c15t.com/docs/frameworks/sveltekit/components): Props and behavior of every @c15t/svelte component in a SvelteKit app, from ConsentRoot and ConsentBanner to ConsentGate and DevTools.
- [ConsentRoot](https://c15t.com/docs/frameworks/sveltekit/components/consent-root): Mount ConsentRoot in a SvelteKit root layout with the state loadConsent returns, so the banner is in the first HTML, with every prop and its default.
- [ConsentBanner](https://c15t.com/docs/frameworks/sveltekit/components/consent-banner): Show the c15t cookie banner in SvelteKit server HTML with ConsentBanner, and set its variant, position, button layout, copy, accessibility and styling hooks.
- [ConsentDialog](https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog): Add the c15t preference dialog to a SvelteKit root layout with ConsentDialog, including how it loads after hydration, its props, keyboard behavior and theme slots.
- [ConsentWidget](https://c15t.com/docs/frameworks/sveltekit/components/consent-widget): Put c15t's category switches inline on a SvelteKit privacy settings route with ConsentWidget, and how its draft, vendors and stale-policy alert behave.
- [ConsentDialogLink](https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog-link): Let visitors reopen c15t preferences from a SvelteKit layout footer with ConsentDialogLink, rendered in server HTML when the policy offers preferences.
- [ConsentDialogTrigger](https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog-trigger): Add a floating, draggable privacy button to a SvelteKit layout with ConsentDialogTrigger, and set its corner, size, saved position, accessible name and callbacks.
- [ConsentGate](https://c15t.com/docs/frameworks/sveltekit/components/consent-gate): Keep a YouTube video or map out of SvelteKit server HTML until its consent category is allowed with ConsentGate, and replace its placeholder.
- [ConsentButton](https://c15t.com/docs/frameworks/sveltekit/components/consent-button): Accept, reject, save or open preferences from SvelteKit pages with ConsentButton, and what each action records.
- [IABConsentBanner](https://c15t.com/docs/frameworks/sveltekit/components/iab-consent-banner): Show the IAB TCF 2.4 first-layer banner to visitors under an IAB policy in a SvelteKit app with IABConsentBanner, its props and behavior.
- [IABConsentDialog](https://c15t.com/docs/frameworks/sveltekit/components/iab-consent-dialog): Show the IAB TCF 2.4 preference center with purposes, features and vendors in a SvelteKit app with IABConsentDialog.
- [Context getters](https://c15t.com/docs/frameworks/sveltekit/getters): Reference for every @c15t/svelte context getter in SvelteKit components, from reading permissions and recorded choices to saving, the draft, IAB state and events.
- [Callbacks](https://c15t.com/docs/frameworks/sveltekit/callbacks): Run your own code in a SvelteKit app when a visitor records a choice or permissions change, with onChoiceRecorded, onPermissionsChanged and script callbacks.
- [IAB TCF](https://c15t.com/docs/frameworks/sveltekit/iab): Turn on the IAB TCF 2.4 banner and preference center in a SvelteKit app with IABConsentBanner, IABConsentDialog and the provider's iab option.
- [IAB GPP](https://c15t.com/docs/frameworks/sveltekit/gpp): Expose the IAB Global Privacy Platform API (__gpp) from a SvelteKit app with the provider's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Geography headers](https://c15t.com/docs/frameworks/sveltekit/geography-headers): Which request headers SvelteKit's c15t helpers read for country, region, language and Global Privacy Control, how to trust them, and how to test another location.
- [Content Security Policy](https://c15t.com/docs/frameworks/sveltekit/content-security-policy): Write a Content Security Policy for a SvelteKit app using c15t with SvelteKit's csp option, covering vendor hosts, c15t's style elements, the server-rendered theme style and style attributes.
- [Server API](https://c15t.com/docs/frameworks/sveltekit/server-api): Reference for c15tHandle, loadConsent, createConsentRoute and resolveConsent from @c15t/svelte/kit and @c15t/svelte/server, with every option and default.
- [DevTools](https://c15t.com/docs/frameworks/sveltekit/components/dev-tools): Inspect consent, scripts, location and events in a SvelteKit app with ConsentDevTools, imported only when $app/env reports development.
- [Troubleshooting](https://c15t.com/docs/frameworks/sveltekit/troubleshooting): Fix a SvelteKit build that cannot fetch the c15t manifest, a missing bundled policy, a banner missing from server HTML, failed saves through the consent route, a wrong backend URL and ignored theme colors.
- [Quickstart](https://c15t.com/docs/frameworks/html/quickstart): Add the c15t banner, preferences and script gating to a plain HTML site, CMS theme, page builder or static site generator with one script tag and no build step.
- [Install on your platform](https://c15t.com/docs/frameworks/html/platforms): Where to paste the c15t script tag, gated vendor snippets and the privacy settings link in WordPress, Webflow, Shopify, Squarespace, Wix, Framer, Ghost, Hugo, Eleventy and Jekyll.
- [Scripts](https://c15t.com/docs/frameworks/html/scripts): Hold vendor scripts on a plain HTML page until the visitor allows their category, load scripts with callbacks, handle withdrawal and clear vendor cookies with the c15t script tag and no build step.
- [Embeds](https://c15t.com/docs/frameworks/html/embeds): Hold YouTube videos, maps and other iframes on a plain HTML page until their consent category is allowed with data-src and data-category, show a placeholder, and configure the c15t iframe blocker.
- [Network blocker](https://c15t.com/docs/frameworks/html/network-blocker): Hold fetch and XMLHttpRequest calls from a plain HTML page until their consent category is allowed, with network blocker rules queued on the c15t script tag.
- [Vendor consent](https://c15t.com/docs/frameworks/html/vendor-consent): Let visitors allow a category such as marketing on a plain HTML page and still turn off one vendor in it, with the vendors option, data-c15t-vendor on gated tags and the vendor switches in the c15t script tag's preference dialog.
- [Clear on revocation](https://c15t.com/docs/frameworks/html/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns on a plain HTML page when that category is denied, with the clearOnRevocation option of the c15t script tag.
- [Customize](https://c15t.com/docs/frameworks/html/customize): Change the c15t script tag banner on a plain HTML site with theme tokens, extra CSS, layout, copy and legal links, or replace it with your own HTML.
- [Translations](https://c15t.com/docs/frameworks/html/translations): Choose the language of the c15t banner and preference dialog on a plain HTML site, change its wording, and add languages in hosted and offline mode with the script tag.
- [Headless](https://c15t.com/docs/frameworks/html/headless): Render your own consent banner and preferences in plain HTML with c15t.headless.js, the ui event and data-c15t-action buttons, while c15t keeps resolving the policy, storing choices and gating scripts.
- [Components](https://c15t.com/docs/frameworks/html/components): Every consent surface and page hook the c15t script tag gives a plain HTML site, from the stock banner and preference dialog to data-c15t-action buttons and gated scripts and iframes.
- [Banner](https://c15t.com/docs/frameworks/html/components/banner): The stock consent banner the c15t script tag shows on a plain HTML site, with its options, layouts, policy-driven buttons, keyboard behavior and data-testid styling hooks.
- [Preference dialog](https://c15t.com/docs/frameworks/html/components/dialog): The stock c15t preference dialog on a plain HTML site, where visitors change each consent category, with how it opens, which categories it lists, its options, keyboard behavior and styling hooks.
- [Floating trigger](https://c15t.com/docs/frameworks/html/components/trigger): Add the c15t floating button that reopens the preference dialog on a plain HTML site, and set its corner, size, visibility and accessible name.
- [Action buttons](https://c15t.com/docs/frameworks/html/components/action-buttons): Make your own HTML buttons accept, reject, open preferences, dismiss a notice or reopen the banner with the data-c15t-action attribute and the c15t script tag, with no JavaScript.
- [Preferences link](https://c15t.com/docs/frameworks/html/components/preferences-link): Let visitors reopen c15t privacy settings on a plain HTML site from a footer link, a CMS menu item or a page builder link to the c15t-preferences fragment, with no JavaScript.
- [Gated scripts](https://c15t.com/docs/frameworks/html/components/gated-script): Hold a vendor's script tag on a plain HTML page until its consent category is allowed with type="text/plain" and data-c15t-category, including load order, copied attributes and what happens on withdrawal.
- [window.c15t API](https://c15t.com/docs/frameworks/html/api): Reference for window.c15t on a plain HTML page, covering the call queue, manual start, reading permissions and recorded choices, saving choices, opening the banner and dialog, and properties.
- [Callbacks](https://c15t.com/docs/frameworks/html/callbacks): Run code on a plain HTML page when c15t resolves the policy, when a visitor records a choice, when permissions change or when a request fails, with window.c15t events, DOM events and config callbacks.
- [IAB TCF](https://c15t.com/docs/frameworks/html/iab): Load the c15t IAB TCF build on a plain HTML page with one script tag, configure the CMP ID and vendors, and confirm TC strings from your own code.
- [IAB GPP](https://c15t.com/docs/frameworks/html/gpp): Add the IAB Global Privacy Platform API (__gpp) to a plain HTML page with the c15t.gpp.js script tag, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Content Security Policy](https://c15t.com/docs/frameworks/html/content-security-policy): Allow the c15t script tag, its stylesheet, backend requests, gated scripts and embeds under a Content Security Policy on a plain HTML site, with nonces or allowed origins.
- [Script tag attributes](https://c15t.com/docs/frameworks/html/attributes-and-api): Reference for the c15t script tag on plain HTML pages, covering the bundle files, every data attribute on the script tag, the DevTools tag and your own markup, and the modes the attributes select.
- [Configuration](https://c15t.com/docs/frameworks/html/configuration): Every option you can pass to the c15t script tag on a plain HTML page through a queued config call, including scripts with callbacks, the network blocker, theme tokens, presentation, translations and storage.
- [DevTools](https://c15t.com/docs/frameworks/html/dev-tools): Add the c15t DevTools panel to a plain HTML page with a second script tag to inspect consent, gated scripts, the resolved policy and events, and to test other countries.
- [Troubleshooting](https://c15t.com/docs/frameworks/html/troubleshooting): Fix a missing banner, vendor scripts that run before consent, script tag errors and blocked requests on a plain HTML site that uses the c15t script tag.
- [Quickstart](https://c15t.com/docs/frameworks/javascript/quickstart): Add the stock c15t banner, preferences and script gating to a JavaScript app built with Vite or another bundler, with no UI framework, using @c15t/browser.
- [Upgrade from v2](https://c15t.com/docs/frameworks/javascript/upgrade-v3): Upgrade a JavaScript app from the c15t v2 store and getOrCreateConsentRuntime to v3. Covers @c15t/browser, createConsentRuntime, the consent kernel, moved exports, callbacks, policies and stored consent.
- [Scripts](https://c15t.com/docs/frameworks/javascript/scripts): Register vendor scripts with @c15t/browser, createConsentRuntime or a consent kernel in JavaScript, and control what happens when a visitor withdraws permission.
- [Iframe blocker](https://c15t.com/docs/frameworks/javascript/modules/iframe-blocker): Hold YouTube videos, maps and other embeds in a JavaScript app until their consent category is allowed, with data-src iframes and the c15t iframe blocker in @c15t/browser, createConsentRuntime or your own kernel.
- [Network blocker](https://c15t.com/docs/frameworks/javascript/modules/network-blocker): Hold fetch and XMLHttpRequest calls in a JavaScript app until their consent category is allowed, with networkBlocker rules in @c15t/browser or createConsentRuntime, or createNetworkBlocker on your own kernel.
- [Vendor consent](https://c15t.com/docs/frameworks/javascript/vendor-consent): Let visitors allow a category such as marketing in a JavaScript app and still turn off one vendor in it, with the vendors option on createConsentRuntime and a vendor switch you render yourself.
- [Clear on revocation](https://c15t.com/docs/frameworks/javascript/clear-on-revocation): Delete the first-party cookies and Web Storage keys a consent category owns in a JavaScript app when that category is denied, with clearOnRevocation on init() or createConsentRuntime, or createClearOnRevocation on your own kernel.
- [Customize](https://c15t.com/docs/frameworks/javascript/customize): Change the stock @c15t/browser banner, preference dialog and floating trigger in a bundled JavaScript app with theme tokens, CSS, layout, copy, legal links and UI options.
- [Translations](https://c15t.com/docs/frameworks/javascript/translations): Choose the language of the c15t banner and preference dialog in a JavaScript app, change its wording with i18n, and add languages with @c15t/browser or createConsentRuntime.
- [Headless](https://c15t.com/docs/frameworks/javascript/headless): Render your own consent banner and preferences in JavaScript, or connect a framework without a c15t adapter such as Solid, with createConsentRuntime from c15t/runtime.
- [@c15t/browser API](https://c15t.com/docs/frameworks/javascript/api/browser): Reference for the @c15t/browser ES module in a bundled JavaScript app, covering its entry points, init and createConsentClient, the client's methods and properties, events, page hooks and helper exports.
- [Callbacks](https://c15t.com/docs/frameworks/javascript/callbacks): Run code in a JavaScript app when a visitor records a consent choice, when permissions change, when a request fails or before the withdrawal reload, with c15t callbacks, client events and kernel events.
- [IAB TCF](https://c15t.com/docs/frameworks/javascript/iab): Add IAB TCF to a JavaScript app with the @c15t/browser IAB build, or attach the IAB module to a consent runtime or kernel you own.
- [IAB GPP](https://c15t.com/docs/frameworks/javascript/gpp): Add the IAB Global Privacy Platform API (__gpp) to a JavaScript app with mountGPP from @c15t/browser/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.
- [Transports](https://c15t.com/docs/frameworks/javascript/transports): Choose where a JavaScript app's c15t policy comes from and where choices go, with the hosted, manifest, offline and custom transports for @c15t/browser, createConsentRuntime and your own kernel.
- [Content Security Policy](https://c15t.com/docs/frameworks/javascript/content-security-policy): Allow c15t in a JavaScript app under a Content Security Policy, covering backend requests, the stock UI's styles, nonces for vendor scripts and gated snippets, and embeds.
- [@c15t/browser options](https://c15t.com/docs/frameworks/javascript/api/browser-options): Every option init() and createConsentClient() from @c15t/browser accept in a bundled JavaScript app, from the mode to scripts, blockers, callbacks, storage, presentation and the stock UI.
- [createConsentRuntime](https://c15t.com/docs/frameworks/javascript/api/runtime): Reference for createConsentRuntime from c15t/runtime, the framework-agnostic consent runtime behind every c15t adapter, with every option, what start and dispose do, and the runtime handle's methods.
- [Kernel API](https://c15t.com/docs/frameworks/javascript/api/kernel): Reference for the c15t consent kernel in JavaScript, covering how to get or create one, its snapshot and subscriptions, commands, setters, hydration, events and listener ordering.
- [Consent snapshot](https://c15t.com/docs/frameworks/javascript/api/snapshot): Reference for every field of the c15t consent snapshot a JavaScript app reads from the kernel, @c15t/browser or createConsentRuntime, grouped by the question each field answers.
- [Script loader](https://c15t.com/docs/frameworks/javascript/modules/script-loader): Reference for the c15t script loader in JavaScript, covering every Script field, lifecycle callbacks, updateScripts, disposal and createScriptLoader for a kernel you own.
- [Persistence](https://c15t.com/docs/frameworks/javascript/modules/persistence): How c15t stores consent choices in a JavaScript app, with the storage key, cookie domain and lifetime options, multi-tab sync, reconcile and clear, and createPersistence for your own kernel.
- [DevTools](https://c15t.com/docs/frameworks/javascript/dev-tools): Mount the c15t DevTools panel in a JavaScript app to inspect consent, scripts, policy and events for @c15t/browser, a consent runtime or a kernel.
- [Troubleshooting](https://c15t.com/docs/frameworks/javascript/troubleshooting): Diagnose vendor scripts that run early, unexpected reloads, empty custom banners, CORS errors, duplicate consent owners and policy resolution in a JavaScript app that uses @c15t/browser or c15t/runtime.
- [Integrations](https://c15t.com/docs/integrations/overview): Find all c15t integrations for analytics, tag managers, advertising, email and SMS, chat and embedded content.
- [Custom integrations](https://c15t.com/docs/integrations/building-integrations): Gate a vendor that has no @c15t/integrations helper, or sync consent with an SDK your app already loads, using a c15t script configuration.
- [Google Maps](https://c15t.com/docs/integrations/google-maps): Gate a Google Maps iframe embed with c15t v3 so the map loads only after the visitor allows its consent category, in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.
- [YouTube](https://c15t.com/docs/integrations/youtube): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
- [Google Tag Manager](https://c15t.com/docs/integrations/google-tag-manager): Load a Google Tag Manager container before or after consent with c15t Consent Mode v2 signals, configure consent checks inside the container, and verify both in DevTools.
- [Cloudflare Zaraz](https://c15t.com/docs/integrations/cloudflare-zaraz): Sync c15t permissions to Cloudflare Zaraz purposes with the c15t cloudflareZaraz bridge, which runs on every page without loading a script, and check the tools it controls.
- [Google Tag](https://c15t.com/docs/integrations/google-tag): Load gtag.js for Google Analytics or Google Ads before or after consent with c15t Consent Mode v2 signals, and verify the consent commands in DevTools.
- [Ahrefs Analytics](https://c15t.com/docs/integrations/ahrefs-analytics): Load Ahrefs Web Analytics only after measurement consent with the c15t ahrefsAnalytics helper, and check it in DevTools.
- [Adobe Analytics](https://c15t.com/docs/integrations/adobe-analytics): Load an Adobe Data Collection Tags property only after measurement consent with the c15t adobeAnalytics helper, and check its extensions in DevTools.
- [Amplitude](https://c15t.com/docs/integrations/amplitude): Load the Amplitude Browser SDK 2 only after measurement consent with the c15t amplitude helper, which opts the SDK out on revocation and back in on a new grant.
- [Cloudflare Web Analytics](https://c15t.com/docs/integrations/cloudflare-web-analytics): Load the Cloudflare Web Analytics beacon only after measurement consent with the c15t cloudflareWebAnalytics helper, and check it in DevTools.
- [Clearbit](https://c15t.com/docs/integrations/clearbit): Load the Clearbit enrichment tag only after marketing consent with the c15t clearbit helper, and check it in DevTools.
- [Microsoft Clarity](https://c15t.com/docs/integrations/microsoft-clarity): Load Microsoft Clarity only after measurement consent with the c15t clarity helper, send Consent V2 storage signals and check them in DevTools.
- [Databuddy](https://c15t.com/docs/integrations/databuddy): Load the Databuddy SDK on every page with the c15t databuddy helper, switch its disabled flag and config from measurement consent, and check both in DevTools.
- [Fathom Analytics](https://c15t.com/docs/integrations/fathom-analytics): Load Fathom Analytics only after measurement consent with the c15t fathomAnalytics helper, set its SPA mode, and check it in DevTools.
- [Heap](https://c15t.com/docs/integrations/heap): Load the Heap config script and heap.js only after measurement consent with the c15t heap helper, and check it in DevTools.
- [Matomo Analytics](https://c15t.com/docs/integrations/matomo-analytics): Load Matomo after measurement consent with the c15t matomoAnalytics helper, or use Matomo's own consent mode, and check each mode in DevTools.
- [Mixpanel](https://c15t.com/docs/integrations/mixpanel-analytics): Load the Mixpanel SDK on every page with the c15t mixpanelAnalytics helper, which switches Mixpanel tracking on and off with measurement consent, and check it in DevTools.
- [OneDollarStats](https://c15t.com/docs/integrations/one-dollar-stats): Load the OneDollarStats tracker only after measurement consent with the c15t oneDollarStats helper, forward its data-attribute settings, and check it in DevTools.
- [Hotjar](https://c15t.com/docs/integrations/hotjar): Load Hotjar only after measurement consent with the c15t hotjar helper, and check its loader and recordings in DevTools.
- [Hightouch](https://c15t.com/docs/integrations/hightouch): Load the Hightouch Events browser SDK only after measurement consent with the c15t hightouch helper, and check page events in DevTools.
- [LogRocket](https://c15t.com/docs/integrations/logrocket): Load LogRocket session replay only after measurement consent with the c15t logRocket helper, including proxied setups, and check it in DevTools.
- [Plausible Analytics](https://c15t.com/docs/integrations/plausible-analytics): Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.
- [PostHog](https://c15t.com/docs/integrations/posthog): Load PostHog before or after measurement consent with the c15t posthog helper, choose its cookieless behavior, turn off PostHog modules you do not use, and sync consent with an SDK you already initialize.
- [Promptwatch](https://c15t.com/docs/integrations/promptwatch): Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.
- [Pirsch](https://c15t.com/docs/integrations/pirsch): Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.
- [RudderStack](https://c15t.com/docs/integrations/rudderstack): Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.
- [Segment](https://c15t.com/docs/integrations/segment): Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.
- [Sentry](https://c15t.com/docs/integrations/sentry): Configure Sentry's CDN or your own SDK with consent for error monitoring, Session Replay and user data.
- [Rybbit Analytics](https://c15t.com/docs/integrations/rybbit-analytics): Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.
- [Umami Analytics](https://c15t.com/docs/integrations/umami-analytics): Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.
- [Vercel Analytics](https://c15t.com/docs/integrations/vercel-analytics): Load the Vercel Web Analytics script only after measurement consent with the c15t vercelAnalytics helper, choose the debug script, and check it in DevTools.
- [Crisp](https://c15t.com/docs/integrations/crisp): Load the Crisp chat widget only after functionality consent with the c15t crisp helper, pass its runtime settings and check it in DevTools.
- [Front Chat](https://c15t.com/docs/integrations/front-chat): Load the Front Chat widget only after functionality consent with the c15t frontChat helper, forward CSP nonces, clear the session on revocation and check it in DevTools.
- [Intercom](https://c15t.com/docs/integrations/intercom): Load the Intercom messenger only after functionality consent with the c15t intercom helper, set its region and check it in DevTools.
- [Klaviyo](https://c15t.com/docs/integrations/klaviyo): Load Klaviyo signup forms and onsite tracking only after marketing and measurement consent with the c15t klaviyo helper, gate your own events, and check it in DevTools.
- [Meta Pixel](https://c15t.com/docs/integrations/meta-pixel): Load the Meta Pixel only after marketing consent with the c15t metaPixel helper, guard fbq event calls, and check it in DevTools.
- [OpenAI Pixel](https://c15t.com/docs/integrations/openai-pixel): Load the ChatGPT Ads Measurement Pixel only after marketing consent with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in DevTools.
- [Pinterest Tag](https://c15t.com/docs/integrations/pinterest-tag): Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.
- [Reddit Pixel](https://c15t.com/docs/integrations/reddit-pixel): Load the Reddit Pixel only after marketing consent with the c15t redditPixel helper, guard rdt conversion calls, and check it in DevTools.
- [TikTok Pixel](https://c15t.com/docs/integrations/tiktok-pixel): Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.
- [LinkedIn Insight Tag](https://c15t.com/docs/integrations/linkedin-insights): Load the LinkedIn Insight Tag only after marketing consent with the c15t linkedinInsights helper, guard lintrk conversion calls, and check it in DevTools.
- [Microsoft UET](https://c15t.com/docs/integrations/microsoft-uet): Load Microsoft Advertising UET on every page with the c15t microsoftUet helper, send ad_storage consent defaults and updates, and verify both in DevTools.
- [Snapchat Pixel](https://c15t.com/docs/integrations/snapchat-pixel): Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.
- [X Pixel](https://c15t.com/docs/integrations/x-pixel): Load the X Pixel only after marketing consent with the c15t xPixel helper, guard twq conversion events, and check it in DevTools.
- [Backend overview](https://c15t.com/docs/self-host/overview): What the c15t consent backend does, and when to use Inth or run @c15t/backend yourself with your own SQL database.
- [Self-host the backend](https://c15t.com/docs/self-host/quickstart): Run the c15t consent backend yourself with @c15t/backend, create its database schema with the CLI, mount it in Next.js, TanStack Start, Nuxt, SvelteKit or another server, and point your app at it.
- [Upgrade from v2](https://c15t.com/docs/self-host/upgrade-v3): Upgrade a self-hosted c15t backend (@c15t/backend) and the Node.js SDK (@c15t/node-sdk) from v2 to v3. Covers the database config, the schema migration, moved backend options, policy rules and the new createC15tClient() client.
- [Backend database setup](https://c15t.com/docs/self-host/guides/database-setup): Connect a self-hosted c15t backend to PostgreSQL, MySQL or SQLite, apply migrations, and upgrade a v2 backend database.
- [Policy configuration](https://c15t.com/docs/self-host/guides/policy-packs): Author and validate the policy rules published by a self-hosted backend manifest.
- [Caching](https://c15t.com/docs/self-host/guides/caching): Cache public manifests and vendor lists while keeping request-specific initialization and subject state private.
- [Deployment runtimes](https://c15t.com/docs/self-host/guides/edge-deployment): Choose a backend runtime that supports your SQL driver and deploy static or edge-rendered clients against its HTTP endpoint.
- [IAB backend configuration](https://c15t.com/docs/self-host/guides/iab-tcf): Publish an IAB TCF policy and serve a cached Global Vendor List from a self-hosted c15t backend.
- [Legal-document snapshots](https://c15t.com/docs/self-host/guides/legal-document-snapshot-integration): Publish legal-document versions and sign evidence of the exact document shown by your application.
- [Request logging](https://c15t.com/docs/self-host/guides/observability): Inspect failed backend requests, enable request logs and send events to your existing logging pipeline.
- [Backend configuration](https://c15t.com/docs/self-host/api/configuration): Options for a self-hosted c15t backend in c15t-backend.config.ts and c15tInstance, covering SQL storage, trusted origins, policies, signing, script routes and request logging.
- [HTTP endpoints](https://c15t.com/docs/self-host/api/endpoints): HTTP endpoints of a self-hosted c15t v3 backend for the manifest, /init, session reports, consent saves, identity links, the script tag and legal-document releases.
- [Node.js SDK](https://c15t.com/docs/self-host/api/node-sdk): Call the c15t consent API from server code with @c15t/node-sdk. Check consent before sending email, link users after sign-in, export a user's records, publish legal documents from CI and read experiment results.
- [CLI overview](https://c15t.com/docs/cli/overview): Run the c15t CLI from @c15t/cli to add c15t to an app, migrate v2 code, manage Inth projects and migrate a self-hosted database.
- [CLI quickstart](https://c15t.com/docs/cli/quickstart): Use the c15t CLI to plan, review and apply c15t setup in an existing Next.js or React app, connected to an Inth backend.
- [Agents and automation](https://c15t.com/docs/cli/automation): Read JSON results from the c15t CLI, call it from another program with runCli, and give a coding agent a v3 setup or migration task.
- [setup](https://c15t.com/docs/cli/commands/setup): Flags and file handling for c15t setup, which plans and applies c15t integration files in Next.js, React and JavaScript apps.
- [Framework boilerplate](https://c15t.com/docs/cli/commands/boilerplate): Generate the c15t quickstart files for Next.js, Nuxt, TanStack Start, Astro, React, JavaScript, a script tag, Vue, Svelte, SvelteKit or Solid with the c15t CLI.
- [Codemods](https://c15t.com/docs/cli/commands/codemods): Migrate source from c15t v2 to v3 with the c15t CLI codemods command, covering package imports, the provider, transports, moved exports, dev tools, policy presets, CSS variables, Tailwind CSS 3, callbacks, the Node.js SDK and backend config, and run the v1 to v2 source transforms.
- [Hosted projects and authentication](https://c15t.com/docs/cli/commands/hosted): Use Inth authentication and provisioning from the c15t setup workflow.
- [Self-hosted migrations](https://c15t.com/docs/cli/commands/self-host): Plan and apply database migrations for a self-hosted c15t backend with the c15t CLI self-host migrate command.
- [Global flags](https://c15t.com/docs/cli/global-flags): Flags every c15t CLI command accepts, for JSON output, the project directory, prompts and telemetry, plus exit codes.
- [Compare c15t with consent tools and custom code](https://c15t.com/docs/comparisons): Compare c15t with consent platforms, browser libraries and custom code. See its strengths, setup requirements and the features its packages do not include.
- [c15t vs building consent yourself](https://c15t.com/docs/comparisons/build-your-own): Keep your own consent design without building every layer from scratch. Compare c15t with a custom implementation, including AI-assisted code.
- [c15t vs Axeptio](https://c15t.com/docs/comparisons/axeptio): Choose c15t to own your consent interface, application behaviour and backend. Compare Axeptio's visual editor, vendor APIs, scans and banner experiments.
- [c15t vs Borlabs Cookie](https://c15t.com/docs/comparisons/borlabs-cookie): Choose c15t for consent beyond WordPress, with native web components and a separate backend. Compare Borlabs Cookie's local records, service controls and scanner.
- [c15t vs Complianz](https://c15t.com/docs/comparisons/complianz): Choose c15t for consent across custom web applications. Compare Complianz's WordPress plugin and Shopify app, with clear differences in scans, records and legal tools.
- [c15t vs consentmanager](https://c15t.com/docs/comparisons/consentmanager): Choose c15t to own consent inside your web application. Compare consentmanager's site operations, custom interfaces, scans, experiments and connected-TV tools.
- [c15t vs Cookie Control](https://c15t.com/docs/comparisons/cookie-control): Choose c15t for native web components, individual vendor choices and backend ownership. Compare CIVIC's Cookie Control Premium and v9 accurately.
- [c15t vs Cookiebot](https://c15t.com/docs/comparisons/cookiebot): Choose c15t for native application components, explicit vendor controls and backend ownership. Compare Cookiebot's scan-based setup and the gaps c15t leaves.
- [c15t vs CookieConsent v3](https://c15t.com/docs/comparisons/cookieconsent-v3): Choose c15t when your application needs native consent state and a record backend. Compare CookieConsent's browser controls and the extra setup each approach needs.
- [c15t vs CookieFirst](https://c15t.com/docs/comparisons/cookiefirst): Choose c15t for native web framework coverage and a backend you can run. Compare CookieFirst's React support, service choices, scans and cookie-policy tools.
- [c15t vs CookieHub](https://c15t.com/docs/comparisons/cookiehub): Choose c15t for native web framework coverage and backend ownership. Compare CookieHub's React components, consent APIs, automatic scans and hosted logs.
- [c15t vs CookieScript](https://c15t.com/docs/comparisons/cookiescript): Choose c15t to own the consent engine, framework components and backend. Compare CookieScript's scans, developer controls and self-hosted banner option.
- [c15t vs CookieYes](https://c15t.com/docs/comparisons/cookieyes): Choose c15t for broader framework support, individual vendor choices and a supplied consent backend. Compare CookieYes SDKs and hosted services fairly.
- [c15t vs Didomi](https://c15t.com/docs/comparisons/didomi): Choose c15t for native framework components, open-source consent logic and backend ownership. Compare Didomi's SDKs, notice console and experiments.
- [c15t vs Enzuzo](https://c15t.com/docs/comparisons/enzuzo): Choose c15t for native consent components, custom product interfaces and backend ownership. Compare Enzuzo's hosted scans, legal policies and privacy operations.
- [c15t vs Ethyca](https://c15t.com/docs/comparisons/ethyca): Choose c15t for native web consent components and a deployable backend. Compare Ethyca's Fides code and Janus platform without confusing their scope.
- [c15t vs iubenda](https://c15t.com/docs/comparisons/iubenda): Compare c15t and iubenda to choose how much control you need over consent, your application, and your records.
- [c15t vs Ketch](https://c15t.com/docs/comparisons/ketch): Choose c15t to own consent components, vendor rules and the backend. Compare Ketch's connected privacy platform and the services c15t does not supply.
- [c15t vs Klaro](https://c15t.com/docs/comparisons/klaro): Choose c15t for native framework state and a backend you can run. Compare Klaro's open-source service controls, hosted records and scanning.
- [c15t vs OneTrust](https://c15t.com/docs/comparisons/onetrust): Choose c15t to own the consent engine, framework components and backend. Compare OneTrust's headless API, cookie scans and broader privacy operations.
- [c15t vs Osano](https://c15t.com/docs/comparisons/osano): Choose c15t for native consent components and control of vendor code and records. Compare Osano's classification, managed operations and service guarantees.
- [c15t vs react-cookie-consent](https://c15t.com/docs/comparisons/react-cookie-consent): Choose c15t when a React application needs consent rules, vendor controls and backend records beyond an accept-and-decline banner.
- [c15t vs Silktide Consent Manager](https://c15t.com/docs/comparisons/silktide-consent-manager): Choose c15t for native application state, regional policy and backend records. Compare Silktide's free browser manager and the setup c15t adds.
- [c15t vs Sourcepoint](https://c15t.com/docs/comparisons/sourcepoint): Choose c15t for consent inside a web product that your team owns. Compare Sourcepoint by Didomi's publisher campaigns, vendor controls, records and TV support.
- [c15t vs tarteaucitron.js](https://c15t.com/docs/comparisons/tarteaucitron): Choose c15t for native framework state and a deployable record backend. Compare tarteaucitron.js service controls and its separate Pro service.
- [c15t vs Termly](https://c15t.com/docs/comparisons/termly): Choose c15t for native application consent and control of your backend. Compare Termly's policy generators, site scans, hosted records and consent APIs.
- [c15t vs TrustArc](https://c15t.com/docs/comparisons/trustarc): Choose c15t for consent that your product team can change and host. Compare TrustArc's React integration, tracker scans, managed records and privacy operations.
- [c15t vs Usercentrics](https://c15t.com/docs/comparisons/usercentrics): Choose c15t for native framework components and control of the consent engine. Compare Usercentrics Web CMP features, service scope and costs.
- [Contribute to c15t documentation](https://c15t.com/docs/contributing): Edit the MDX source, validate both rendered and agent-readable outputs, and submit a focused change.
- [Open source](https://c15t.com/docs/oss/why-open-source): Which parts of c15t are open source, the Apache-2.0 license, where the code lives, and how the hosted Inth backend relates to the self-hostable c15t backend.
- [Contribute to c15t](https://c15t.com/docs/oss/contributing): Open an issue, set up the c15t monorepo with Bun, branch from canary, run the checks and add a Tegami release note for package changes.
- [c15t Community Code of Conduct](https://c15t.com/docs/oss/code-of-conduct): Guidelines for fostering an inclusive, respectful, and collaborative open-source community
- [License](https://c15t.com/docs/oss/license): Apache License 2.0 applies to c15t open source packages and this repository.
- [Cookie Policy](https://c15t.com/docs/legals/cookie-policy): Which cookies and similar technologies c15t.com uses, why, and how to manage them.
- [Privacy Policy](https://c15t.com/docs/legals/privacy-policy): How Consent Management Inc collects, uses, shares and protects personal information on c15t.com, and how to contact us about it.
- [v1.1.1 — Bundle Reduction Update](https://c15t.com/changelog/1.1.1): Performance-focused release achieving a massive 58.9% bundle size reduction while introducing a new headless package for custom implementations. Removed framer-motion and Tailwind variants for faster load times with zero UX compromise.
- [v1.1.2 — Optimistic UI & Bundle Optimization](https://c15t.com/changelog/1.1.2): Performance-focused release introducing optimistic UI updates for instant user feedback, massive 58.9% bundle size reduction, and a new headless package for custom implementations with improved event handling.
- [v1.1.3 — Enhanced Theming & Callback Improvements](https://c15t.com/changelog/1.1.3): Major release introducing comprehensive theming support with dark/light/system detection, improved consent callbacks with structured data, and enhanced color scheme integration. Includes breaking changes for theme system and callback data structure.
- [v1.1.4 — Translation System Fixes & Core Improvements](https://c15t.com/changelog/1.1.4): Patch release addressing critical translation functionality issues across core and react packages. Introduces better modularity, improved fallback behavior, comprehensive test coverage, and enhanced translation utility functions.
- [v1.1.5 — Tailwind CSS v3 Compatibility & Style Fixes](https://c15t.com/changelog/1.1.5): Patch release fixing critical Tailwind CSS v3 compatibility issues by removing CSS layers and improving noStyle theme handling. Ensures proper style application and prevents conflicts with modern Tailwind configurations.
- [v1.2.0 — Backend Architecture Overhaul & Translation System Refactor](https://c15t.com/changelog/1.2.0): Major release introducing a complete backend refactor to oRPC client/server architecture with OpenAPI support, CORS middleware, and streamlined translation system with common strings consolidation. Includes breaking changes for translation structure.
- [v1.2.1 — API Architecture Hardening, Translations Cleanup, and Tailwind v3 Fix](https://c15t.com/changelog/1.2.1): Patch release refining the new API architecture with oRPC + OpenAPI, consolidating translations into common keys, fixing Tailwind v3 layer collision, and improving schema validation and configuration defaults. Introduces a type-safe Node.js SDK and centralized routing.
- [v1.3.0 — Translations Package, SSR Consent, CLI Telemetry, and Next.js Restructure](https://c15t.com/changelog/1.3.0): Minor release introducing the new @c15t/translations package with 8 languages, server-side consent initialization, CLI telemetry and onboarding upgrades, and a Next.js package restructuring that removes middleware exports. Includes backend translation support, improved schemas, and infrastructure/tooling updates.
- [v1.3.1 — Next.js Data Fetching Refinements, Docs Fixes, and zh Translations](https://c15t.com/changelog/1.3.1): Patch release refining Next.js initial data fetching in c15t mode, fixing quickstart links, improving core fallbacks, and adding Chinese (zh) translations. Includes dependency updates across packages.
- [v1.3.2 — Next.js Relative URL Fix](https://c15t.com/changelog/1.3.2): Patch release fixing a relative URL error in the Next.js integration.
- [v1.3.3 — GTM Support, CookieBanner Focus Toggle, Next.js URL Validation](https://c15t.com/changelog/1.3.3): Patch release adding Google Tag Manager support in core, allowing trapFocus={false} in CookieBanner, improving URL validation in Next.js, and updating React dependency.
- [v1.4.0 — Ignore Geo, Provider DX, Store Config, A11y, CLI Fixes](https://c15t.com/changelog/1.4.0): Minor release improving developer experience with ignoreGeoLocation and consentCategories, adding a debug-friendly store config prop, enhancing accessibility, and fixing CLI onboarding issues.
- [v1.4.1 — Next.js: Custom c15t Headers for Initial Fetch](https://c15t.com/changelog/1.4.1): Patch release adding custom c15t headers to Next.js initial data fetch, enabling backend provider overrides and more reliable initialization.
- [v1.4.2 — Indonesian Translations, Provider Render Fixes, URL Normalization](https://c15t.com/changelog/1.4.2): Patch release adding Bahasa Indonesia translations, improving provider rendering to prevent duplicate requests, normalizing URLs to remove trailing slashes, correcting consent logic, and refining banner animations. Includes dependency updates, caching improvements, and expanded tests.
- [v1.4.3 — Theme Inheritance Fixes for Provider-Scoped Themes](https://c15t.com/changelog/1.4.3): Patch release ensuring provider-level themes set in ConsentManagerProvider are correctly inherited by CookieBanner, ConsentManagerDialog, and ConsentManagerWidget for consistent styling.
- [v1.4.4 — Theme Inheritance Stability and Maintenance Updates](https://c15t.com/changelog/1.4.4): Patch release fixing theme inheritance in ConsentManager and related components, plus dependency updates and stronger tests to prevent regressions.
- [v1.5.0 — Next.js Pages Support, GDPR Button Order, Backend Enhancements](https://c15t.com/changelog/1.5.0): Minor release adding Next.js Pages Directory support and updating cookie banner button order for GDPR guidance, alongside backend and integration improvements.
- [v1.6.0 – New Docs, Rebuilt Self-Hosting Backend, Better Callbacks, and More](https://c15t.com/changelog/1.6.0): Minor release with a rebuilt self-hosting backend, a brand new docs site, improved consent checking, and callback improvements.
- [v1.6.1 - React Scroll Lock Fix](https://c15t.com/changelog/1.6.1): Patch release fixing a bug where the scroll lock persisted after the dialog has been dismissed.
- [v1.7.0 - Script Loader & iFrame Blocking](https://c15t.com/changelog/1.7.0): Minor release with a new approach to script loader and iFrame blocking.
- [v1.7.1 - CLI Improvements & Bug Fixes](https://c15t.com/changelog/1.7.1): Patch release with CLI improvements including bun support and bug fixes.
- [v1.8.0 - Cross-Subdomain Consent, Legal Links, User Identification & EU Languages](https://c15t.com/changelog/1.8.0): Feature release adding cross-subdomain consent persistence via cookies, configurable legal links in components, user identification tracking, and comprehensive language support with all 24 EU official languages.
- [v1.8.2 - React Bug Fixes](https://c15t.com/changelog/1.8.2): Patch release with bug fixes and improvements.
- [v1.8.3 - Experimental Global Privacy Control Support & Bug Fixes](https://c15t.com/changelog/1.8.3): Patch release with experimental Global Privacy Control support and bug fixes.
- [v2.0.0 - New Styling System, Policy Packs, Backend v2 & More](https://c15t.com/changelog/2.0.0): Stable release notes for c15t 2.0, covering the token-based styling system, policy packs, GPC, IAB TCF 2.3, bundled docs, c15t/skills, dev tools, backend v2, migration tooling, and the prebuilt UI.
- [v2.0.0-rc.0 — New Styling System, IAB TCF, Dev Tools, Backend v2 & More](https://c15t.com/changelog/2.0.0-rc.0): Release candidate introducing a token-based styling system, IAB TCF 2.3 support, dev tools, backend v2, network blocker, GPC support and a complete documentation overhaul.
- [v2.0.0-rc.5 — Policy Packs, Per-Policy GPC, Fallback Policies & Dev-Tools Improvements](https://c15t.com/changelog/2.0.0-rc.5): Release candidate introducing policy packs for regional consent resolution, per-policy GPC support, fallback policies, policy inspection, and developer-experience improvements.
- [v2.0.0-rc.6 — Smaller Client Bundles, Modular IAB, UI Primitives, and Flexible Policy Actions](https://c15t.com/changelog/2.0.0-rc.6): Release candidate focused on smaller client bundles, extracted IAB support, shared UI primitives with framework adapters, flexible policy action layouts, and cleaner package styling/toolchain boundaries.
- [v2.0.0-rc.7 — Theming Fixes, Simpler Tailwind Setup, and Clearer Customization Guidance](https://c15t.com/changelog/2.0.0-rc.7): Release candidate focused on fixing theming regressions in the prebuilt UI, simplifying the Tailwind setup contract, clarifying the recommended customization ladder, and adding better manual coverage for CSS behavior across Tailwind 3, Tailwind 4, and plain CSS.
- [v2.0.1 - TanStack Devtools Support & Tailwind Import Ordering](https://c15t.com/changelog/2.0.1): Patch release adding official TanStack Devtools support for @c15t/dev-tools and improving Tailwind v4 stylesheet import ordering in the c15t CLI.
- [v2.1.0 - Expanded Script Integrations and Provider Registry](https://c15t.com/changelog/2.1.0): Minor release expanding the consent-aware script loader with a registry-backed provider system, more prebuilt integrations, stronger lifecycle utilities, CLI discovery updates, and German translation refinements.
- [v2.1.0 Draft - v3 API Preview and Faster React Runtime](https://c15t.com/changelog/2.1.0-v3-api-preview): Draft release notes for the opt-in v3 API preview, covering the kernel contract, React render isolation, v3 hosted transport alignment, and benchmark results from the @c15t/react v3 examples.
- [v2.2.0 - Consent-Aware Embeds, Configurable Controls, and More Integrations](https://c15t.com/changelog/2.2.0): Minor release adding consent-aware Google Maps and YouTube components, a configurable consent controls toolbar, eight script integrations, a reusable SDK hook, policy-aware action styling, CSP nonce support, reliability fixes, and new translations.
- [v3.0.0 - The Open Standard for Cookie Banners](https://c15t.com/changelog/3.0.0): Major release notes for c15t 3.0. One consent engine for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit and plain HTML, banners in the server HTML, the consent manifest, policy rules, GPP, publisher restrictions, new integrations and a rewritten self-hosted backend.
- [@c15t/browser client options](https://c15t.com/docs/shared/browser/client-options): Shared option tables for the @c15t/browser client, used by the HTML and JavaScript guides.
- [Astro](https://c15t.com/docs/shared/build-manifests/astro): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Javascript](https://c15t.com/docs/shared/build-manifests/javascript): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Next](https://c15t.com/docs/shared/build-manifests/next): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Next Config](https://c15t.com/docs/shared/build-manifests/next-config): Wrap your Next.js config in `withConsentManifest`. An existing config object or function goes in as the first argument, unchanged:
- [Next Pages](https://c15t.com/docs/shared/build-manifests/next-pages): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Nuxt](https://c15t.com/docs/shared/build-manifests/nuxt): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [React](https://c15t.com/docs/shared/build-manifests/react): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Sveltekit](https://c15t.com/docs/shared/build-manifests/sveltekit): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Tanstack Start](https://c15t.com/docs/shared/build-manifests/tanstack-start): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Vue](https://c15t.com/docs/shared/build-manifests/vue): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Build Time Manifest](https://c15t.com/docs/shared/build-time-manifest): The build fetches your public policy once and bundles it, so the server never fetches it at runtime.
- [Build Time Manifest Notes](https://c15t.com/docs/shared/build-time-manifest-notes): The snapshot is fixed at build time:
- [Inth Hosting](https://c15t.com/docs/shared/comparisons/inth-hosting): You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.
- [Static Config](https://c15t.com/docs/shared/examples/astro-static/static-config): Entry point for Static Config documentation.
- [Analytics Events](https://c15t.com/docs/shared/examples/astro/analytics-events): Entry point for Analytics Events documentation.
- [Cached Layout](https://c15t.com/docs/shared/examples/astro/cached-layout): Entry point for Cached Layout documentation.
- [Client Entrypoint](https://c15t.com/docs/shared/examples/astro/client-entrypoint): Entry point for Client Entrypoint documentation.
- [Consent Video](https://c15t.com/docs/shared/examples/astro/consent-video): Entry point for Consent Video documentation.
- [Gated Inline Script](https://c15t.com/docs/shared/examples/astro/gated-inline-script): Entry point for Gated Inline Script documentation.
- [Iab Layout](https://c15t.com/docs/shared/examples/astro/iab-layout): Entry point for Iab Layout documentation.
- [Layout](https://c15t.com/docs/shared/examples/astro/layout): Entry point for Layout documentation.
- [Server Config](https://c15t.com/docs/shared/examples/astro/server-config): Entry point for Server Config documentation.
- [Vendors Option](https://c15t.com/docs/shared/examples/astro/vendors-option): Entry point for Vendors Option documentation.
- [Embed](https://c15t.com/docs/shared/examples/html/embed): Entry point for Embed documentation.
- [Gated Scripts](https://c15t.com/docs/shared/examples/html/gated-scripts): Entry point for Gated Scripts documentation.
- [Headless Bar](https://c15t.com/docs/shared/examples/html/headless-bar): Entry point for Headless Bar documentation.
- [Preferences Link](https://c15t.com/docs/shared/examples/html/preferences-link): Entry point for Preferences Link documentation.
- [Script Tag](https://c15t.com/docs/shared/examples/html/script-tag): Entry point for Script Tag documentation.
- [Tailwind Classes](https://c15t.com/docs/shared/examples/html/tailwind-classes): Entry point for Tailwind Classes documentation.
- [Theme](https://c15t.com/docs/shared/examples/html/theme): Entry point for Theme documentation.
- [Vendor Gated Embed](https://c15t.com/docs/shared/examples/html/vendor-gated-embed): Entry point for Vendor Gated Embed documentation.
- [Vendor Gated Scripts](https://c15t.com/docs/shared/examples/html/vendor-gated-scripts): Entry point for Vendor Gated Scripts documentation.
- [Vendor Scripts](https://c15t.com/docs/shared/examples/html/vendor-scripts): Entry point for Vendor Scripts documentation.
- [Vendors](https://c15t.com/docs/shared/examples/html/vendors): Entry point for Vendors documentation.
- [Actions](https://c15t.com/docs/shared/examples/javascript/actions): Entry point for Actions documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/javascript/callbacks): Entry point for Callbacks documentation.
- [Clear On Revocation](https://c15t.com/docs/shared/examples/javascript/clear-on-revocation): Entry point for Clear On Revocation documentation.
- [Devtools](https://c15t.com/docs/shared/examples/javascript/devtools): Entry point for Devtools documentation.
- [Embed](https://c15t.com/docs/shared/examples/javascript/embed): Entry point for Embed documentation.
- [Gpp](https://c15t.com/docs/shared/examples/javascript/gpp): Entry point for Gpp documentation.
- [Iframe Blocker](https://c15t.com/docs/shared/examples/javascript/iframe-blocker): Entry point for Iframe Blocker documentation.
- [Init](https://c15t.com/docs/shared/examples/javascript/init): Entry point for Init documentation.
- [Kernel](https://c15t.com/docs/shared/examples/javascript/kernel): Entry point for Kernel documentation.
- [Lifecycle](https://c15t.com/docs/shared/examples/javascript/lifecycle): Entry point for Lifecycle documentation.
- [Network Blocker](https://c15t.com/docs/shared/examples/javascript/network-blocker): Entry point for Network Blocker documentation.
- [Preference Draft](https://c15t.com/docs/shared/examples/javascript/preference-draft): Entry point for Preference Draft documentation.
- [Preferences Link](https://c15t.com/docs/shared/examples/javascript/preferences-link): Entry point for Preferences Link documentation.
- [Runtime](https://c15t.com/docs/shared/examples/javascript/runtime): Entry point for Runtime documentation.
- [Runtime Devtools](https://c15t.com/docs/shared/examples/javascript/runtime-devtools): Entry point for Runtime Devtools documentation.
- [Sentry Scripts](https://c15t.com/docs/shared/examples/javascript/sentry-scripts): Entry point for Sentry Scripts documentation.
- [Theme](https://c15t.com/docs/shared/examples/javascript/theme): Entry point for Theme documentation.
- [Translations](https://c15t.com/docs/shared/examples/javascript/translations): Entry point for Translations documentation.
- [Transport Custom](https://c15t.com/docs/shared/examples/javascript/transport-custom): Entry point for Transport Custom documentation.
- [Transport Manifest](https://c15t.com/docs/shared/examples/javascript/transport-manifest): Entry point for Transport Manifest documentation.
- [Transport Offline](https://c15t.com/docs/shared/examples/javascript/transport-offline): Entry point for Transport Offline documentation.
- [Vendor Consent](https://c15t.com/docs/shared/examples/javascript/vendor-consent): Entry point for Vendor Consent documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/javascript/vite-config): Entry point for Vite Config documentation.
- [Pages App](https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-app): Entry point for Pages App documentation.
- [Pages Config](https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-config): Entry point for Pages Config documentation.
- [Pages Consent Route](https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-consent-route): Entry point for Pages Consent Route documentation.
- [Pages Ssr](https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-ssr): Entry point for Pages Ssr documentation.
- [App Router Awaited Layout](https://c15t.com/docs/shared/examples/nextjs/app-router-awaited-layout): Entry point for App Router Awaited Layout documentation.
- [Branded Layout](https://c15t.com/docs/shared/examples/nextjs/branded-layout): Entry point for Branded Layout documentation.
- [Browser Layout](https://c15t.com/docs/shared/examples/nextjs/browser-layout): Entry point for Browser Layout documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/nextjs/callbacks): Entry point for Callbacks documentation.
- [Client Side Config](https://c15t.com/docs/shared/examples/nextjs/client-side-config): Entry point for Client Side Config documentation.
- [Compose Banner](https://c15t.com/docs/shared/examples/nextjs/compose-banner): Entry point for Compose Banner documentation.
- [Compose Button](https://c15t.com/docs/shared/examples/nextjs/compose-button): Entry point for Compose Button documentation.
- [Config](https://c15t.com/docs/shared/examples/nextjs/config): Entry point for Config documentation.
- [Consent Route](https://c15t.com/docs/shared/examples/nextjs/consent-route): Entry point for Consent Route documentation.
- [Experiment Layout](https://c15t.com/docs/shared/examples/nextjs/experiment-layout): Entry point for Experiment Layout documentation.
- [I18n](https://c15t.com/docs/shared/examples/nextjs/i18n): Entry point for I18n documentation.
- [Iab Consent](https://c15t.com/docs/shared/examples/nextjs/iab-consent): Entry point for Iab Consent documentation.
- [Iab Publisher Restrictions](https://c15t.com/docs/shared/examples/nextjs/iab-publisher-restrictions): Entry point for Iab Publisher Restrictions documentation.
- [Language Switcher](https://c15t.com/docs/shared/examples/nextjs/language-switcher): Entry point for Language Switcher documentation.
- [Next Config](https://c15t.com/docs/shared/examples/nextjs/next-config): Entry point for Next Config documentation.
- [Quickstart Config](https://c15t.com/docs/shared/examples/nextjs/quickstart-config): Entry point for Quickstart Config documentation.
- [Quickstart Layout](https://c15t.com/docs/shared/examples/nextjs/quickstart-layout): Entry point for Quickstart Layout documentation.
- [Quickstart Next Config](https://c15t.com/docs/shared/examples/nextjs/quickstart-next-config): Entry point for Quickstart Next Config documentation.
- [Static Export Next Config](https://c15t.com/docs/shared/examples/nextjs/static-export-next-config): Entry point for Static Export Next Config documentation.
- [Theme](https://c15t.com/docs/shared/examples/nextjs/theme): Entry point for Theme documentation.
- [Third Parties Scripts](https://c15t.com/docs/shared/examples/nextjs/third-parties-scripts): Entry point for Third Parties Scripts documentation.
- [Video Embed](https://c15t.com/docs/shared/examples/nextjs/video-embed): Entry point for Video Embed documentation.
- [Static Config](https://c15t.com/docs/shared/examples/nuxt-static/static-config): Entry point for Static Config documentation.
- [App Config](https://c15t.com/docs/shared/examples/nuxt/app-config): Entry point for App Config documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/nuxt/callbacks): Entry point for Callbacks documentation.
- [Color Scheme](https://c15t.com/docs/shared/examples/nuxt/color-scheme): Entry point for Color Scheme documentation.
- [Consent Status](https://c15t.com/docs/shared/examples/nuxt/consent-status): Entry point for Consent Status documentation.
- [Consent Surfaces](https://c15t.com/docs/shared/examples/nuxt/consent-surfaces): Entry point for Consent Surfaces documentation.
- [Devtools](https://c15t.com/docs/shared/examples/nuxt/devtools): Entry point for Devtools documentation.
- [Embed](https://c15t.com/docs/shared/examples/nuxt/embed): Entry point for Embed documentation.
- [Headless Prompt](https://c15t.com/docs/shared/examples/nuxt/headless-prompt): Entry point for Headless Prompt documentation.
- [Iab Opt In](https://c15t.com/docs/shared/examples/nuxt/iab-opt-in): Entry point for Iab Opt In documentation.
- [Iab Surfaces](https://c15t.com/docs/shared/examples/nuxt/iab-surfaces): Entry point for Iab Surfaces documentation.
- [Language Switcher](https://c15t.com/docs/shared/examples/nuxt/language-switcher): Entry point for Language Switcher documentation.
- [Nuxt Config](https://c15t.com/docs/shared/examples/nuxt/nuxt-config): Entry point for Nuxt Config documentation.
- [Nuxt Gtag Scripts](https://c15t.com/docs/shared/examples/nuxt/nuxt-gtag-scripts): Entry point for Nuxt Gtag Scripts documentation.
- [Nuxt Scripts Events](https://c15t.com/docs/shared/examples/nuxt/nuxt-scripts-events): Entry point for Nuxt Scripts Events documentation.
- [Nuxt Scripts Registry](https://c15t.com/docs/shared/examples/nuxt/nuxt-scripts-registry): Entry point for Nuxt Scripts Registry documentation.
- [Privacy Page](https://c15t.com/docs/shared/examples/nuxt/privacy-page): Entry point for Privacy Page documentation.
- [Root](https://c15t.com/docs/shared/examples/nuxt/root): Entry point for Root documentation.
- [Self Host Route](https://c15t.com/docs/shared/examples/nuxt/self-host-route): Entry point for Self Host Route documentation.
- [Vapor Embed](https://c15t.com/docs/shared/examples/nuxt/vapor-embed): Entry point for Vapor Embed documentation.
- [Vapor Nuxt Config](https://c15t.com/docs/shared/examples/nuxt/vapor-nuxt-config): Entry point for Vapor Nuxt Config documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/react/callbacks): Entry point for Callbacks documentation.
- [Consent](https://c15t.com/docs/shared/examples/react/consent): Entry point for Consent documentation.
- [Experiment Consent](https://c15t.com/docs/shared/examples/react/experiment-consent): Entry point for Experiment Consent documentation.
- [Headless Banner](https://c15t.com/docs/shared/examples/react/headless-banner): Entry point for Headless Banner documentation.
- [I18n](https://c15t.com/docs/shared/examples/react/i18n): Entry point for I18n documentation.
- [Iab Consent](https://c15t.com/docs/shared/examples/react/iab-consent): Entry point for Iab Consent documentation.
- [Iab Publisher Restrictions](https://c15t.com/docs/shared/examples/react/iab-publisher-restrictions): Entry point for Iab Publisher Restrictions documentation.
- [Language Switcher](https://c15t.com/docs/shared/examples/react/language-switcher): Entry point for Language Switcher documentation.
- [Main](https://c15t.com/docs/shared/examples/react/main): Entry point for Main documentation.
- [Optional Feature](https://c15t.com/docs/shared/examples/react/optional-feature): Entry point for Optional Feature documentation.
- [Reject Button](https://c15t.com/docs/shared/examples/react/reject-button): Entry point for Reject Button documentation.
- [Video Embed](https://c15t.com/docs/shared/examples/react/video-embed): Entry point for Video Embed documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/react/vite-config): Entry point for Vite Config documentation.
- [Nextjs Route](https://c15t.com/docs/shared/examples/self-host/nextjs-route): Entry point for Nextjs Route documentation.
- [Bottom Bar](https://c15t.com/docs/shared/examples/storybook-astro/bottom-bar): Entry point for Bottom Bar documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/storybook-astro/callbacks): Entry point for Callbacks documentation.
- [React Island](https://c15t.com/docs/shared/examples/storybook-astro/react-island): Entry point for React Island documentation.
- [Bottom Bar](https://c15t.com/docs/shared/examples/storybook-react/bottom-bar): Entry point for Bottom Bar documentation.
- [Brand Card](https://c15t.com/docs/shared/examples/storybook-react/brand-card): Entry point for Brand Card documentation.
- [Brand Theme](https://c15t.com/docs/shared/examples/storybook-react/brand-theme): Entry point for Brand Theme documentation.
- [Choice Wall](https://c15t.com/docs/shared/examples/storybook-react/choice-wall): Entry point for Choice Wall documentation.
- [Class Names Css Modules](https://c15t.com/docs/shared/examples/storybook-react/class-names-css-modules): Entry point for Class Names Css Modules documentation.
- [Class Names Css Modules Css](https://c15t.com/docs/shared/examples/storybook-react/class-names-css-modules-css): Entry point for Class Names Css Modules Css documentation.
- [Class Names Emotion](https://c15t.com/docs/shared/examples/storybook-react/class-names-emotion): Entry point for Class Names Emotion documentation.
- [Class Names Stylex](https://c15t.com/docs/shared/examples/storybook-react/class-names-stylex): Entry point for Class Names Stylex documentation.
- [Class Names Vanilla Extract](https://c15t.com/docs/shared/examples/storybook-react/class-names-vanilla-extract): Entry point for Class Names Vanilla Extract documentation.
- [Compose Banner](https://c15t.com/docs/shared/examples/storybook-react/compose-banner): Entry point for Compose Banner documentation.
- [Compose Button](https://c15t.com/docs/shared/examples/storybook-react/compose-button): Entry point for Compose Button documentation.
- [Headless Bar](https://c15t.com/docs/shared/examples/storybook-react/headless-bar): Entry point for Headless Bar documentation.
- [Headless Bar Css](https://c15t.com/docs/shared/examples/storybook-react/headless-bar-css): Entry point for Headless Bar Css documentation.
- [Slim Bar](https://c15t.com/docs/shared/examples/storybook-react/slim-bar): Entry point for Slim Bar documentation.
- [Slim Bar Css](https://c15t.com/docs/shared/examples/storybook-react/slim-bar-css): Entry point for Slim Bar Css documentation.
- [Bottom Bar](https://c15t.com/docs/shared/examples/storybook-svelte/bottom-bar): Entry point for Bottom Bar documentation.
- [Consent Actions](https://c15t.com/docs/shared/examples/storybook-svelte/consent-actions): Entry point for Consent Actions documentation.
- [Consent Callbacks](https://c15t.com/docs/shared/examples/storybook-svelte/consent-callbacks): Entry point for Consent Callbacks documentation.
- [Consent Events](https://c15t.com/docs/shared/examples/storybook-svelte/consent-events): Entry point for Consent Events documentation.
- [Consent I18n](https://c15t.com/docs/shared/examples/storybook-svelte/consent-i18n): Entry point for Consent I18n documentation.
- [Consent Status](https://c15t.com/docs/shared/examples/storybook-svelte/consent-status): Entry point for Consent Status documentation.
- [Floating Trigger](https://c15t.com/docs/shared/examples/storybook-svelte/floating-trigger): Entry point for Floating Trigger documentation.
- [Headless Bar](https://c15t.com/docs/shared/examples/storybook-svelte/headless-bar): Entry point for Headless Bar documentation.
- [Headless Bar Css](https://c15t.com/docs/shared/examples/storybook-svelte/headless-bar-css): Entry point for Headless Bar Css documentation.
- [Iab Surfaces](https://c15t.com/docs/shared/examples/storybook-svelte/iab-surfaces): Entry point for Iab Surfaces documentation.
- [Network Blocker](https://c15t.com/docs/shared/examples/storybook-svelte/network-blocker): Entry point for Network Blocker documentation.
- [Own Preferences](https://c15t.com/docs/shared/examples/storybook-svelte/own-preferences): Entry point for Own Preferences documentation.
- [Privacy Controls](https://c15t.com/docs/shared/examples/storybook-svelte/privacy-controls): Entry point for Privacy Controls documentation.
- [Privacy Settings Page](https://c15t.com/docs/shared/examples/storybook-svelte/privacy-settings-page): Entry point for Privacy Settings Page documentation.
- [Slim Bar](https://c15t.com/docs/shared/examples/storybook-svelte/slim-bar): Entry point for Slim Bar documentation.
- [Slim Bar Css](https://c15t.com/docs/shared/examples/storybook-svelte/slim-bar-css): Entry point for Slim Bar Css documentation.
- [Bottom Bar](https://c15t.com/docs/shared/examples/storybook-vue/bottom-bar): Entry point for Bottom Bar documentation.
- [Headless Bar](https://c15t.com/docs/shared/examples/storybook-vue/headless-bar): Entry point for Headless Bar documentation.
- [Headless Bar Css](https://c15t.com/docs/shared/examples/storybook-vue/headless-bar-css): Entry point for Headless Bar Css documentation.
- [Slim Bar](https://c15t.com/docs/shared/examples/storybook-vue/slim-bar): Entry point for Slim Bar documentation.
- [Slim Bar Css](https://c15t.com/docs/shared/examples/storybook-vue/slim-bar-css): Entry point for Slim Bar Css documentation.
- [App](https://c15t.com/docs/shared/examples/svelte/app): Entry point for App documentation.
- [Scripts](https://c15t.com/docs/shared/examples/svelte/scripts): Entry point for Scripts documentation.
- [Theme Css](https://c15t.com/docs/shared/examples/svelte/theme-css): Entry point for Theme Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/svelte/vite-config): Entry point for Vite Config documentation.
- [Youtube Embed](https://c15t.com/docs/shared/examples/svelte/youtube-embed): Entry point for Youtube Embed documentation.
- [App Locals](https://c15t.com/docs/shared/examples/sveltekit/app-locals): Entry point for App Locals documentation.
- [Custom Banner](https://c15t.com/docs/shared/examples/sveltekit/custom-banner): Entry point for Custom Banner documentation.
- [Dev Tools](https://c15t.com/docs/shared/examples/sveltekit/dev-tools): Entry point for Dev Tools documentation.
- [Headless Layout](https://c15t.com/docs/shared/examples/sveltekit/headless-layout): Entry point for Headless Layout documentation.
- [Hooks](https://c15t.com/docs/shared/examples/sveltekit/hooks): Entry point for Hooks documentation.
- [Layout](https://c15t.com/docs/shared/examples/sveltekit/layout): Entry point for Layout documentation.
- [Layout Server](https://c15t.com/docs/shared/examples/sveltekit/layout-server): Entry point for Layout Server documentation.
- [Manifest Layout Server](https://c15t.com/docs/shared/examples/sveltekit/manifest-layout-server): Entry point for Manifest Layout Server documentation.
- [Node Sdk Client](https://c15t.com/docs/shared/examples/sveltekit/node-sdk-client): Entry point for Node Sdk Client documentation.
- [Prerender](https://c15t.com/docs/shared/examples/sveltekit/prerender): Entry point for Prerender documentation.
- [Route Handlers](https://c15t.com/docs/shared/examples/sveltekit/route-handlers): Entry point for Route Handlers documentation.
- [Scripts](https://c15t.com/docs/shared/examples/sveltekit/scripts): Entry point for Scripts documentation.
- [Self Host Route](https://c15t.com/docs/shared/examples/sveltekit/self-host-route): Entry point for Self Host Route documentation.
- [Theme](https://c15t.com/docs/shared/examples/sveltekit/theme): Entry point for Theme documentation.
- [Theme Load](https://c15t.com/docs/shared/examples/sveltekit/theme-load): Entry point for Theme Load documentation.
- [Theme Style](https://c15t.com/docs/shared/examples/sveltekit/theme-style): Entry point for Theme Style documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/sveltekit/vite-config): Entry point for Vite Config documentation.
- [Astro Config](https://c15t.com/docs/shared/examples/tailwind-v3/astro/astro-config): Entry point for Astro Config documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/astro/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/astro/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/astro/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/astro/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/html/postcss-config): Entry point for Postcss Config documentation.
- [Script Tag](https://c15t.com/docs/shared/examples/tailwind-v3/html/script-tag): Entry point for Script Tag documentation.
- [Script Tag Light Dom](https://c15t.com/docs/shared/examples/tailwind-v3/html/script-tag-light-dom): Entry point for Script Tag Light Dom documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-css): Entry point for Tailwind Css documentation.
- [Tailwind Css Light Dom](https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-css-light-dom): Entry point for Tailwind Css Light Dom documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-15/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/next-15/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-15/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/next-15/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/tailwind-css): Entry point for Tailwind Css documentation.
- [Nuxt Config](https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/nuxt-config): Entry point for Nuxt Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/react/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/react/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/react/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/react/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v3/react/vite-config): Entry point for Vite Config documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/svelte/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/svelte/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/svelte/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/svelte/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v3/svelte/vite-config): Entry point for Vite Config documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/vite-config): Entry point for Vite Config documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/vite-config): Entry point for Vite Config documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v3/vue/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v3/vue/slot): Entry point for Slot documentation.
- [Tailwind Config](https://c15t.com/docs/shared/examples/tailwind-v3/vue/tailwind-config): Entry point for Tailwind Config documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v3/vue/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v3/vue/vite-config): Entry point for Vite Config documentation.
- [Astro Config](https://c15t.com/docs/shared/examples/tailwind-v4/astro/astro-config): Entry point for Astro Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/astro/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/astro/tailwind-css): Entry point for Tailwind Css documentation.
- [Script Tag](https://c15t.com/docs/shared/examples/tailwind-v4/html/script-tag): Entry point for Script Tag documentation.
- [Script Tag Light Dom](https://c15t.com/docs/shared/examples/tailwind-v4/html/script-tag-light-dom): Entry point for Script Tag Light Dom documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/html/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v4/next-15/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/next-15/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/next-15/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/tailwind-css): Entry point for Tailwind Css documentation.
- [Postcss Config](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/postcss-config): Entry point for Postcss Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/tailwind-css): Entry point for Tailwind Css documentation.
- [Nuxt Config](https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/nuxt-config): Entry point for Nuxt Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/tailwind-css): Entry point for Tailwind Css documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/react/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/react/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v4/react/vite-config): Entry point for Vite Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/svelte/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/svelte/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v4/svelte/vite-config): Entry point for Vite Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/vite-config): Entry point for Vite Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/vite-config): Entry point for Vite Config documentation.
- [Slot](https://c15t.com/docs/shared/examples/tailwind-v4/vue/slot): Entry point for Slot documentation.
- [Tailwind Css](https://c15t.com/docs/shared/examples/tailwind-v4/vue/tailwind-css): Entry point for Tailwind Css documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tailwind-v4/vue/vite-config): Entry point for Vite Config documentation.
- [Build Manifest Server Fn](https://c15t.com/docs/shared/examples/tanstack-start/build-manifest-server-fn): Entry point for Build Manifest Server Fn documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/tanstack-start/callbacks): Entry point for Callbacks documentation.
- [Compose Banner](https://c15t.com/docs/shared/examples/tanstack-start/compose-banner): Entry point for Compose Banner documentation.
- [Compose Button](https://c15t.com/docs/shared/examples/tanstack-start/compose-button): Entry point for Compose Button documentation.
- [Consent Route](https://c15t.com/docs/shared/examples/tanstack-start/consent-route): Entry point for Consent Route documentation.
- [I18n](https://c15t.com/docs/shared/examples/tanstack-start/i18n): Entry point for I18n documentation.
- [Iab Consent](https://c15t.com/docs/shared/examples/tanstack-start/iab-consent): Entry point for Iab Consent documentation.
- [Language Switcher](https://c15t.com/docs/shared/examples/tanstack-start/language-switcher): Entry point for Language Switcher documentation.
- [Root](https://c15t.com/docs/shared/examples/tanstack-start/root): Entry point for Root documentation.
- [Same Origin Root](https://c15t.com/docs/shared/examples/tanstack-start/same-origin-root): Entry point for Same Origin Root documentation.
- [Scripts](https://c15t.com/docs/shared/examples/tanstack-start/scripts): Entry point for Scripts documentation.
- [Self Host Route](https://c15t.com/docs/shared/examples/tanstack-start/self-host-route): Entry point for Self Host Route documentation.
- [Start](https://c15t.com/docs/shared/examples/tanstack-start/start): Entry point for Start documentation.
- [Static Root](https://c15t.com/docs/shared/examples/tanstack-start/static-root): Entry point for Static Root documentation.
- [Streamed Root](https://c15t.com/docs/shared/examples/tanstack-start/streamed-root): Entry point for Streamed Root documentation.
- [Video Embed](https://c15t.com/docs/shared/examples/tanstack-start/video-embed): Entry point for Video Embed documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/tanstack-start/vite-config): Entry point for Vite Config documentation.
- [App](https://c15t.com/docs/shared/examples/vue/app): Entry point for App documentation.
- [Callbacks](https://c15t.com/docs/shared/examples/vue/callbacks): Entry point for Callbacks documentation.
- [Consent Status](https://c15t.com/docs/shared/examples/vue/consent-status): Entry point for Consent Status documentation.
- [Consent Surfaces](https://c15t.com/docs/shared/examples/vue/consent-surfaces): Entry point for Consent Surfaces documentation.
- [Customize](https://c15t.com/docs/shared/examples/vue/customize): Entry point for Customize documentation.
- [Devtools](https://c15t.com/docs/shared/examples/vue/devtools): Entry point for Devtools documentation.
- [Embed](https://c15t.com/docs/shared/examples/vue/embed): Entry point for Embed documentation.
- [Headless App](https://c15t.com/docs/shared/examples/vue/headless-app): Entry point for Headless App documentation.
- [Headless Main](https://c15t.com/docs/shared/examples/vue/headless-main): Entry point for Headless Main documentation.
- [Headless Prompt](https://c15t.com/docs/shared/examples/vue/headless-prompt): Entry point for Headless Prompt documentation.
- [Iab Opt In](https://c15t.com/docs/shared/examples/vue/iab-opt-in): Entry point for Iab Opt In documentation.
- [Iab Surfaces](https://c15t.com/docs/shared/examples/vue/iab-surfaces): Entry point for Iab Surfaces documentation.
- [Language Switcher](https://c15t.com/docs/shared/examples/vue/language-switcher): Entry point for Language Switcher documentation.
- [Main](https://c15t.com/docs/shared/examples/vue/main): Entry point for Main documentation.
- [Network Blocker](https://c15t.com/docs/shared/examples/vue/network-blocker): Entry point for Network Blocker documentation.
- [Privacy Settings](https://c15t.com/docs/shared/examples/vue/privacy-settings): Entry point for Privacy Settings documentation.
- [Vite Config](https://c15t.com/docs/shared/examples/vue/vite-config): Entry point for Vite Config documentation.
- [Iab Gpp](https://c15t.com/docs/shared/iab-gpp): The policy rule c15t matched for the visitor decides whether a section applies. The visitor's location only picks which US section carries it.
- [Iab Publisher Restrictions](https://c15t.com/docs/shared/iab-publisher-restrictions): Each restriction type has a requirement that depends on the vendor list:
- [Iab Tcf 2 4](https://c15t.com/docs/shared/iab-tcf-2-4): The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their locked section with a lock icon, because the visitor cannot object to them.
- [Embed content by framework](https://c15t.com/docs/shared/integrations/consent-embed): Mount remote iframe content only while the configured category is allowed.
- [Google Consent Mode in c15t helpers](https://c15t.com/docs/shared/integrations/google-consent-mode): When the Google helpers load, what they send before a choice, and how c15t categories map to Google consent types.
- [Register vendor scripts](https://c15t.com/docs/shared/integrations/register-scripts): Add a vendor script configuration to the c15t provider you already have, in each framework.
- [Check a consent-gated vendor helper](https://c15t.com/docs/shared/integrations/vendor-revocation-and-verify): The shared browser test and revocation behavior for vendor helpers that wait for consent.
- [Next.js consent and scripts](https://c15t.com/docs/shared/next-consent-wrapper): Register scripts in the Next.js c15t.config.ts used by the router guides.
- [ConsentBanner](https://c15t.com/docs/shared/react/components/consent-banner): Shared ConsentBanner reference tables for the React and Next.js adapters.
- [ConsentDialog](https://c15t.com/docs/shared/react/components/consent-dialog): Shared ConsentDialog reference for the React and Next.js adapters.
- [ConsentDialogLink](https://c15t.com/docs/shared/react/components/consent-dialog-link): Shared ConsentDialogLink reference for the React and Next.js adapters.
- [ConsentDialogTrigger](https://c15t.com/docs/shared/react/components/consent-dialog-trigger): Shared ConsentDialogTrigger reference tables for the React and Next.js adapters.
- [ConsentGate](https://c15t.com/docs/shared/react/components/consent-gate): Shared ConsentGate reference for the React and Next.js adapters.
- [ConsentWidget](https://c15t.com/docs/shared/react/components/consent-widget): Shared ConsentWidget reference for the React and Next.js adapters.
- [Dev Tools](https://c15t.com/docs/shared/react/components/dev-tools): Shared DevTools reference for the React and Next.js adapters.
- [Compose your own banner](https://c15t.com/docs/shared/react/compose): Shared compound-component content for the React, Next.js and TanStack Start compose pages.
- [Headless](https://c15t.com/docs/shared/react/headless): Shared headless consent UI content for the React and Next.js adapters.
- [Hooks](https://c15t.com/docs/shared/react/hooks/overview): Shared consent hook guidance for the React and Next.js adapters.
- [IAB TCF](https://c15t.com/docs/shared/react/iab/overview): Shared IAB TCF setup guidance for the React and Next.js adapters.
- [Network blocker](https://c15t.com/docs/shared/react/network-blocker): Shared network blocker reference for the React and Next.js adapters.
- [Styling](https://c15t.com/docs/shared/react/styling/overview): Shared token, slot and class-name styling guidance for the React and Next.js adapters.
- [Theme Tokens](https://c15t.com/docs/shared/reference/theme-tokens): Entry point for Theme Tokens documentation.
- [Clear on revocation](https://c15t.com/docs/shared/scripts/clear-on-revocation): Shared clearOnRevocation explanation for the framework clear on revocation pages.
- [Google load mode](https://c15t.com/docs/shared/scripts/google-load-mode): Shared explanation of the loadMode option on the gtag and googleTagManager helpers, for the framework migration sections.
- [Vendor consent](https://c15t.com/docs/shared/scripts/vendor-consent): Shared vendor consent explanation for the framework vendor consent pages.
- [Callbacks](https://c15t.com/docs/shared/svelte/callbacks): Run your own code when consent changes through the provider's `callbacks` prop, a script's own callbacks, or a kernel event in one component:
- [Components](https://c15t.com/docs/shared/svelte/components): Import every component from `@c15t/svelte`, except the dev tools panel, which comes from `@c15t/svelte/devtools`. Render them inside the provider: `ConsentProvider` in a Svelte app, or `ConsentRoot`, which renders `ConsentProvider`, in a SvelteKit root layout. A component outside it throws `c15t: no v3 consent context`.
- [Consent Banner](https://c15t.com/docs/shared/svelte/components/consent-banner): `variant` and `position` set the shape for one banner. The provider's `presentation` prop sets them for every surface; a prop on `ConsentBanner` wins. This banner is a full-width bar along the bottom edge:
- [Consent Button](https://c15t.com/docs/shared/svelte/components/consent-button): `ConsentButton` is a button that performs one consent action, styled like the banner's buttons. Use it on a cookie policy page, an onboarding step or anywhere visitors should accept, reject or open preferences outside the banner:
- [Consent Dialog](https://c15t.com/docs/shared/svelte/components/consent-dialog): `ConsentDialog` is not part of the first page load. The component you render is a small loader; the dialog itself is a separate chunk that it imports:
- [Consent Dialog Link](https://c15t.com/docs/shared/svelte/components/consent-dialog-link): `ConsentDialogLink` takes its label as children and passes every other attribute, such as `class`, `id` or `aria-describedby`, to the `<button>` it renders.
- [Consent Dialog Trigger](https://c15t.com/docs/shared/svelte/components/consent-dialog-trigger): `ConsentDialogTrigger` is a small round button, fixed to a corner of the viewport, that opens the preference dialog. It keeps preferences one click away on every page without a footer link. Render it next to `ConsentDialog`:
- [Consent Gate](https://c15t.com/docs/shared/svelte/components/consent-gate): `ConsentGate` renders a `<div>` wrapper. Inside it, it renders the children while the visitor's effective permission for `category` is granted, and the placeholder otherwise. The permission is the same value as `getConsentManager().has(category)`. It can be granted before the visitor chooses, under an opt-out policy, and a recorded grant can be overridden by a privacy signal such as Global Privacy Control.
- [Consent Provider](https://c15t.com/docs/shared/svelte/components/consent-provider): Pass each option as a top-level prop, or group them in `options`. When both set the same option, the top-level prop wins. The `ConsentManagerOptions` type from `@c15t/svelte` lists every option. SvelteKit's `ConsentRoot` takes the same props, except that `state` replaces `mode` and `prefetch`.
- [Consent Widget](https://c15t.com/docs/shared/svelte/components/consent-widget): `ConsentWidget` renders the preference controls inline: one switch per category, an expandable description for each, and the save buttons the policy allows. It is the same widget `ConsentDialog` shows, without the dialog around it. Use it for a privacy settings page:
- [Dev Tools](https://c15t.com/docs/shared/svelte/components/dev-tools): The panel is a floating inspector for the provider's consent runtime. Its tabs:
- [Iab Consent Banner](https://c15t.com/docs/shared/svelte/components/iab-consent-banner): `IABConsentBanner` is the first layer of the IAB TCF 2.4 consent flow. It lists the purposes, special features and number of vendors from the Global Vendor List, and offers Accept All, Reject All and Customize. It renders only for visitors whose resolved policy uses the `iab` model, so render it next to the standard `ConsentBanner`, which covers everyone else:
- [Iab Consent Dialog](https://c15t.com/docs/shared/svelte/components/iab-consent-dialog): `IABConsentDialog` is the IAB TCF 2.4 preference center. It has two tabs: purposes, with stacks, special features and legitimate interest objections, and vendors, with each vendor's purposes, data retention and privacy policy. Render it next to `IABConsentBanner`; the banner's Customize button opens it:
- [Primitives](https://c15t.com/docs/shared/svelte/components/primitives): The stock consent components are built from a set of unstyled, accessible building blocks that `@c15t/svelte` also exports. Reach for them when you build your own preference dialog or settings page with the [headless getters](../headless) and want the same keyboard and focus behavior as the stock dialog. For the consent state itself, use `getConsentManager()`; the primitives know nothing about consent.
- [Content Security Policy](https://c15t.com/docs/shared/svelte/content-security-policy): A Content Security Policy has to allow each thing c15t or your vendors put on the page:
- [Customize](https://c15t.com/docs/shared/svelte/customize): The provider's `colorScheme` prop switches on the dark token set: `'dark'` always, `'system'` when the operating system prefers dark, `'light'` never. It toggles a `c15t-dark` class on `<html>`. Left unset, the provider copies a `dark` class on `<html>` into `c15t-dark`, so an app with its own dark mode toggle gets the dark tokens without the prop. Pass `null` if your app sets `c15t-dark` itself. Override dark values under `:root.dark` and `:root.c15t-dark` in your stylesheet. [Dark mode](/docs/customization/dark-mode) covers a dark first paint.
- [Embeds](https://c15t.com/docs/shared/svelte/embeds): A YouTube video, a map or a social post in an iframe contacts its vendor as soon as it loads. c15t offers two ways to keep it from loading before consent:
- [Getters](https://c15t.com/docs/shared/svelte/getters): Svelte has no consent hooks or stores. `@c15t/svelte` exports context getters instead. Call one at the top level of a component's `<script>`, inside `ConsentProvider`, and read its properties in markup or in `$derived`. The properties read the provider's `$state`, so the component updates when consent changes.
- [Headless](https://c15t.com/docs/shared/svelte/headless): Try [customization](/docs/customization/overview) first: tokens, slots, `presentation` and translations change most banners without new markup. Go headless when you need markup the stock components cannot produce.
- [Iab](https://c15t.com/docs/shared/svelte/iab): Use IAB TCF when your ad partners require a TC String. It needs an IAB policy in your Inth project and a CMP ID. IAB Europe assigns a CMP ID to a company when it registers as a CMP ([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC String names the CMP that wrote it, so an ID you did not register attributes your visitors' consent to someone else. Example CMP IDs in c15t demos are not production configuration.
- [Network Blocker](https://c15t.com/docs/shared/svelte/network-blocker): The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you list until their consent category is allowed. Use it as a backstop for tracking calls from code that is already on the page, such as your own analytics wrapper or an SDK you import. It is off until you configure it.
- [Scripts](https://c15t.com/docs/shared/svelte/scripts): The provider's `scripts` prop takes an array of script configurations. Each has a category. The loader adds a script to the page when its category becomes allowed and removes it when the category is withdrawn. Nothing optional loads while the policy is still resolving, or when it fails.
- [Translations](https://c15t.com/docs/shared/svelte/translations): The banner, dialog, widget, gate placeholder and IAB surfaces read their text from one set of translations for the visitor's language. Which set depends on the provider's `mode`:
- [Troubleshooting](https://c15t.com/docs/shared/svelte/troubleshooting): **Check.** Read `getConsentManager().policyRule.prompt` and `.location`, or open DevTools. In the Network panel, find the `/init` request.
- [Callbacks](https://c15t.com/docs/shared/upgrade-v3/callbacks): Callbacks stay under `callbacks` in your options, with new names:
- [Check](https://c15t.com/docs/shared/upgrade-v3/check): codemod fail the build until you resolve them.
- [Cli](https://c15t.com/docs/shared/upgrade-v3/cli): reads sessions saved by v2.
- [Earlier Alpha Frame](https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-frame): Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside production, log a one-time warning such as `` c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead. ``
- [Earlier Alpha Intro](https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-intro): The v3 alphas renamed and removed APIs that never shipped in a stable release. Names that were in stable v2 keep a deprecated alias. Every other renamed name is removed with no alias, so a build that still uses one fails to type-check or throws at runtime.
- [Earlier Alpha Modes](https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-modes): Entry point for Earlier Alpha Modes documentation.
- [Headless](https://c15t.com/docs/shared/upgrade-v3/headless): `useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`. The `root-exports-to-subpaths` codemod moves the import. Some of its methods take different arguments:
- [Iab](https://c15t.com/docs/shared/upgrade-v3/iab): React, Next.js and TanStack Start no longer take an `iab` provider option. Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or `ConsentRoot`, around the IAB components. Its props are the options you passed to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new `publisherRestrictions`.
- [Integrations](https://c15t.com/docs/shared/upgrade-v3/integrations): v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts` from your dependencies and install `@c15t/integrations` from the `alpha` dist-tag:
- [Options And Components](https://c15t.com/docs/shared/upgrade-v3/options-and-components): The `consent-provider-options` codemod renames `ConsentManagerProvider` and its option and prop types, turns `mode` and `backendURL` into `hosted()` or `offline()`, and renames `iframeBlockerConfig`. v2 still accepted the deprecated `translations` option; the `translations-to-i18n` codemod moves it to `i18n`.
- [Policies](https://c15t.com/docs/shared/upgrade-v3/policies): v2 policy packs become policy rules, and `policyPackPresets` becomes `policyRulePresets`, exported from `c15t`. Where the rules live depends on your backend:
- [Stored Consent](https://c15t.com/docs/shared/upgrade-v3/stored-consent): v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It does not rewrite them on page load; the next accept, reject or save writes a v3 record.
- [Styles](https://c15t.com/docs/shared/upgrade-v3/styles): In v2 the provider built CSS from `options.theme` in the browser. In v3 it doesn't. Without a change, custom colors, fonts and radii fall back to the defaults, and you only see a development warning.
- [Translations](https://c15t.com/docs/shared/upgrade-v3/translations): Partial overrides through `i18n.messages` and objects typed as `Translations` need no change. A complete translation object typed as `CompleteTranslations` fails type-checking until you add the new sections and keys: `consentGate`, which replaces `frame`, `rights`, the notice and dismiss strings such as `common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves `frame` copy to `consentGate`.
- [Use Consent Manager](https://c15t.com/docs/shared/upgrade-v3/use-consent-manager): `useConsentManager()` returned the whole consent state, so every component that called it re-rendered on every change. v3 has one hook per field. Run the codemod first:
- [Vite Build Manifest](https://c15t.com/docs/shared/vite-build-manifest): `vite build` and `vite dev` fetch the manifest when they start. `vite preview` serves the last build without fetching. The plugin writes no file into your app, so there is nothing to keep out of Git. `c15t/generated` ships its own types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without a build first.
- [Vite Build Manifest Troubleshooting](https://c15t.com/docs/shared/vite-build-manifest-troubleshooting): **Check.** `vite build` stops with an error from `consentManifest` that starts with the plugin's name, such as `@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite` for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps going. The part in parentheses names the cause:
- [ConsentBanner](https://c15t.com/docs/shared/vue/components/consent-banner): Shared ConsentBanner reference for the c15t Vue plugin and Nuxt module.
- [ConsentDialogLink](https://c15t.com/docs/shared/vue/components/consent-dialog-link): Shared ConsentDialogLink reference for the c15t Vue plugin and Nuxt module.
- [ConsentDialogTrigger](https://c15t.com/docs/shared/vue/components/consent-dialog-trigger): Shared ConsentDialogTrigger reference for the c15t Vue plugin and Nuxt module.
- [ConsentGate](https://c15t.com/docs/shared/vue/components/consent-gate): Shared ConsentGate reference for the c15t Vue plugin and Nuxt module.
- [ConsentManager](https://c15t.com/docs/shared/vue/components/consent-manager): Shared ConsentManager reference for the c15t Vue plugin and Nuxt module.
- [ConsentWidget](https://c15t.com/docs/shared/vue/components/consent-widget): Shared ConsentWidget reference for the c15t Vue plugin and Nuxt module.
- [ConsentDevTools](https://c15t.com/docs/shared/vue/components/dev-tools): Shared ConsentDevTools reference for the c15t Vue plugin and Nuxt module.
- [IABConsentBanner](https://c15t.com/docs/shared/vue/components/iab-consent-banner): Shared IABConsentBanner reference for the c15t Vue plugin and Nuxt module.
- [IABConsentDialog](https://c15t.com/docs/shared/vue/components/iab-consent-dialog): Shared IABConsentDialog reference for the c15t Vue plugin and Nuxt module.
- [Vue and Nuxt composables](https://c15t.com/docs/shared/vue/composables): Shared composable reference for the c15t Vue plugin and Nuxt module.

## Content

# Introduction
URL: https://c15t.com/docs
c15t adds a consent banner, a preference dialog and consent-gated scripts to JavaScript, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start sites.

## What c15t does

c15t is an open-source consent manager. It shows visitors a banner and a
preference dialog, remembers their choice, and holds back analytics, ads,
pixels and embeds until they allow them. The rules for who sees what come from
a policy: opt-in for visitors in the EU, opt-out for some US states, or
whatever your project configures.

You get:

* Banner, dialog and preferences link components for your framework, with a
  theme system and slots for your design.
* Script loading that waits for consent, for [30+ vendors](/docs/integrations/overview)
  or your own scripts.
* Consent records stored by [Inth](https://inth.com) or a
  [backend you run](/docs/self-host/overview).
* Google Consent Mode v2 and IAB TCF 2.4 support.

## Get started

* [Choose your setup](/docs/concepts/choose-your-setup)
* [How consent works](/docs/concepts/how-consent-works)
* [Customize the interface](/docs/customization/overview)
* [Upgrade from v2](/changelog/3.0.0#upgrading)

A working setup takes four steps in every framework: install c15t, point it at
your Inth project's backend URL, mount the consent components once near the
root of your app, and move your analytics and marketing scripts into c15t so
they wait for consent. Then [verify it](/docs/guides/verify-consent) by
watching network requests, not just the banner.

## Using a coding agent

Each c15t package ships its docs as Markdown. After installing, agents can read
`node_modules/c15t/AGENTS.md` for an index of version-matched guides. On the
website, every page has a Markdown version, and
[llms.txt](https://c15t.com/docs/llms.txt) lists them all.

Tell the agent your framework, router and hosting before it picks a recipe. A
Next.js App Router app on Vercel and a static Astro site need different setups.

# Choose your setup
URL: https://c15t.com/docs/concepts/choose-your-setup
Pick the c15t setup for your framework, rendering mode and hosting, and decide who runs the consent backend.

## Find your app in this table

Most apps need one row. Follow its guide from start to finish; each guide links
to the alternatives it rules out.

|Your app|Setup|Guide|
|--|--|--|
|Next.js App Router with a Next.js server|Server resolves consent from a build-time manifest and streams it to the page|[App Router](/docs/frameworks/next/quickstart)|
|Next.js App Router, page must arrive with its banner|Await consent inside `Suspense`|[Stream or await](/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)|
|Next.js with static, ISR, `'use cache'` or `ensureStatic = 'navigation'` pages|Browser resolves consent on those pages|[Static, ISR and cached pages](/docs/frameworks/next/rendering#render-static-isr-and-cached-pages)|
|Next.js Pages Router|Resolve consent in `getServerSideProps`|[Pages Router](/docs/frameworks/next/rendering#pick-your-rendering-path)|
|Next.js with `output: 'export'`|Browser resolves consent|[Static export](/docs/frameworks/next/static-export)|
|TanStack Start with a server|Root loader resolves consent on the server|[TanStack Start](/docs/frameworks/tanstack-start/quickstart)|
|TanStack Start on a serverless host, banner may follow the page|Root loader streams consent|[TanStack Start rendering](/docs/frameworks/tanstack-start/rendering#stream-the-page-while-consent-resolves)|
|TanStack Start in SPA mode or prerendered|Browser resolves consent|[TanStack Start rendering](/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts)|
|React with Vite, or another single-page app|Browser resolves consent|[React](/docs/frameworks/react/quickstart)|
|React Router framework mode, Remix, or another server-rendered React app|Browser resolves consent after hydration|[React rendering](/docs/frameworks/react/rendering#react-router-remix-and-other-server-rendered-apps)|
|Nuxt with a Nuxt server|Nuxt module resolves consent on the server from a build-time manifest|[Nuxt](/docs/frameworks/nuxt/quickstart)|
|Nuxt with prerendered or cached routes|Nuxt server for most pages, the browser on prerendered and cached routes|[Nuxt prerendered and cached routes](/docs/frameworks/nuxt/rendering#prerendered-and-cached-routes)|
|Nuxt with `nuxt generate` on static hosting|Nuxt module, browser resolves consent from the manifest or `/init`|[Nuxt static hosting](/docs/frameworks/nuxt/rendering#deploy-to-static-hosting)|
|Nuxt with `ssr: false`|Nuxt module, browser resolves consent from the manifest|[Nuxt single-page app](/docs/frameworks/nuxt/rendering#build-a-single-page-app-with-ssr-false)|
|Vue with Vite|Vue plugin, browser resolves consent|[Vue](/docs/frameworks/vue/quickstart)|
|Vue rendered on the server without Nuxt|Vue plugin; the banner mounts after hydration. Use Nuxt for the banner in server HTML.|[Vue rendering](/docs/frameworks/vue/rendering#server-rendering-without-nuxt)|
|Astro with static output|Browser resolves consent through the hosted backend|[Astro static output](/docs/frameworks/astro/rendering#static-output-with-hosted)|
|Astro with server output and an adapter|Middleware resolves consent from a build-time manifest|[Astro server output](/docs/frameworks/astro/rendering#server-output-with-manifest)|
|Svelte with Vite|Svelte provider, browser resolves consent|[Svelte](/docs/frameworks/svelte/quickstart)|
|SvelteKit with a server|Root layout load resolves consent on the server|[SvelteKit](/docs/frameworks/sveltekit/quickstart)|
|SvelteKit with `adapter-static`, prerendered pages or SPA mode|Browser resolves consent|[SvelteKit rendering](/docs/frameworks/sveltekit/rendering#build-a-static-site)|
|Plain HTML, a CMS, a page builder, or a static site generator such as Hugo or Eleventy|One script tag, stock banner included|[HTML](/docs/frameworks/html/quickstart)|
|JavaScript with a bundler and no UI framework|`@c15t/browser` module, stock banner included|[JavaScript](/docs/frameworks/javascript/quickstart)|
|Your own UI, or a framework without an adapter such as Solid|Headless runtime|[JavaScript headless](/docs/frameworks/javascript/headless)|

Solid has no c15t adapter. Use the [headless runtime](/docs/frameworks/javascript/headless#use-c15t-with-solid)
and subscribe to it from your components.

## Decide who runs the consent backend

The backend supplies policies and stores consent records. Every setup above
works with each option; only the URL changes.

|Option|Use it when|
|--|--|
|[Inth](https://inth.com)|You want hosted policies and consent records. The guides use this.|
|[Self-hosted c15t backend](/docs/self-host/overview)|You need to run the service and its database yourself.|
|Offline mode|Local development and tests. Policies live in your code and choices stay in the browser, with no consent records. Not recommended for production environments.|

To use Inth, create a project, set its policy rules, add your site's origin to
its trusted origins, and copy the backend URL. The guides use the placeholder
`https://your-project.inth.app`; replace it with your project's backend URL,
including any path prefix.

## Server rendering or browser rendering

Where consent resolves decides what the visitor's first HTML contains.

|Rendering|What the visitor gets|
|--|--|
|The server resolves consent for each request|The server reads the visitor's cookie and location headers, so the browser starts with the answer. Gated scripts can run right after hydration, and the banner can be part of the HTML.|
|The browser resolves consent|The HTML is the same for everyone. After the page loads, the browser requests the policy, then shows the banner or runs gated scripts.|

A static or prerendered page cannot contain one visitor's consent, because the
same HTML goes to everyone. Static sites still use Inth; the browser talks to it
directly. A same-origin `/api/c15t` route only works where a server runs it.

Pages that are cached and shared between visitors, such as Next.js ISR or
`'use cache'` routes, need browser resolution for the same reason. Cache the
public policy manifest, never a response that contains a visitor's consent.

## How the server gets the policy

Use a build-time manifest as the default for supported production builds.
`manifest()` is the default mode in Next.js, TanStack Start, Nuxt, Astro and
SvelteKit, so their servers resolve requests from the deployment's snapshot.
Vite apps can bundle it for browser resolution too; location-based policies
may still need a location request. The framework quickstarts show the build
integration. [Consent modes](/docs/concepts/modes) lists every mode, its
options and the backend URL variable each framework reads.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

For deployments that need policy updates without a rebuild, choose a runtime
path:

* **Cached manifest**, `manifest({ source: 'runtime' })`.
  Your server downloads the project's public policy file, caches it, and
  resolves each visitor locally. Consent saves still go to the backend.
* **`/init`**, `hosted()`. Each visit asks the backend to resolve the visitor.
  Simpler, but every page load makes a request to the backend.

[Data fetching](/docs/concepts/data-fetching) compares them in detail,
including proxies and custom transports.

# Examples
URL: https://c15t.com/docs/examples
Runnable c15t apps from the c15t repository. Starters show the smallest setup for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML and JavaScript. Showcases show custom banners, preference centers, gated embeds, analytics, IAB TCF, experiments and multilingual sites.

## Run an example from the c15t repository

The examples live in the [`examples` directory](https://github.com/c15t/c15t/tree/v3/examples)
of the c15t repository. They build against the packages in the repository, not
against npm, so you clone the repository and build the packages first:

```sh
git clone --branch v3 https://github.com/c15t/c15t.git
cd c15t
bun install
bun run build:libs
```

You need [Bun](https://bun.sh). Then run any example by its directory:

```sh
bun run --cwd examples/nextjs dev
```

Each example has a README that names the two or three files worth reading and
how to point it at your backend. To add c15t to your own app, follow your
[framework quickstart](/docs/frameworks) instead; its setup code comes from the
starters below.

## Starters

A starter is the smallest correct setup for one framework and one rendering
mode. Each one connects to Inth, shows the stock banner and dialog, keeps a
**Privacy settings** control on the page after the banner closes, and loads
PostHog only after the visitor allows measurement.

|Framework|Directory|What it shows|
|--|--|--|
|Next.js|`examples/nextjs`|App Router with a server-prefetched manifest|
|Next.js|`examples/nextjs-pages-router`|Pages Router with `getServerSideProps`|
|TanStack Start|`examples/tanstack-start`|Request middleware, a server function and the root route|
|React|`examples/react`|A Vite single-page app|
|Nuxt|`examples/nuxt`|The Nuxt module with the policy bundled at build time and resolved on the server|
|Nuxt|`examples/nuxt-static`|`nuxt generate` with the manifest resolved in the browser|
|Vue|`examples/vue`|The Vue plugin in a Vite single-page app|
|Astro|`examples/astro`|Server output with the Node adapter|
|Astro|`examples/astro-static`|Static output with every page prerendered|
|Svelte|`examples/svelte`|`@c15t/svelte` in a Vite single-page app|
|SvelteKit|`examples/sveltekit`|Server hooks and server-rendered layouts|
|HTML|`examples/html`|The script tag on plain HTML pages|
|JavaScript|`examples/javascript`|`@c15t/browser` with a bundler|

Replace `https://your-project.inth.app` with the backend URL from your Inth
project, including any path prefix, and add the example's origin to the
project's trusted origins. Server-rendered starters also read the URL from the
framework's public environment variable; the README names it. Starters that
download the policy when they build commit a `.env` that sets that variable to
the `https://example-inth.inth.app` demo project, so they build on a fresh
clone. Set your own URL in `.env.local`, which overrides it. Replace the
placeholder PostHog key with your own, or remove the script.

`examples/self-host` is a Next.js App Router app with `@c15t/backend` mounted
at `/api/c15t` in the same app. It runs on an embedded PGlite database in
development and Postgres from `DATABASE_URL` when deployed. The
[backend quickstart](/docs/self-host/quickstart) publishes its route handler.

## Showcases

Showcases are apps for Northwind Coffee, a made-up coffee roaster. Each one
shows one thing c15t can do inside a believable product. All but one are
Next.js apps.

|Showcase|Directory|What it shows|
|--|--|--|
|Custom banner|`examples/showcase-custom-banner`|A banner and preferences sheet built on the headless hooks, with no c15t stylesheet|
|Preference center|`examples/showcase-preference-center`|Consent settings as a page in account settings, with categories, vendors and the last saved time|
|Gated embeds|`examples/showcase-gated-embeds`|YouTube, Google Maps and a support chat behind designed placeholders that load in place|
|Analytics|`examples/showcase-analytics`|Google Tag Manager with Consent Mode v2, GA4, PostHog and the Meta Pixel, with DevTools showing each script's state|
|IAB TCF|`examples/showcase-iab`|A publisher's ad slots filled from the TC string, with GPP|
|Banner experiment|`examples/showcase-experiment`|An A/B test between two banner layouts, with exposure and choice events per arm|
|Multilingual|`examples/showcase-multilingual`|Banner language from the route and policy from the visitor's region|
|Nuxt theme|`examples/showcase-nuxt-theme`|The stock Nuxt banner and dialog in a brand's colors, layout and dark mode, styled through module options|

The Next.js showcases run in offline mode, so they work without an Inth
project. Offline mode keeps choices in the browser and records nothing on a
server. Not recommended for production environments. Each README shows the
one-line swap to `hosted({ backendURL: 'https://your-project.inth.app' })`. The Nuxt
module has no offline mode, so the Nuxt showcase talks to a demo Inth project
and reads `NUXT_PUBLIC_C15T_BACKEND_URL` for your own.

The IAB showcase serves a three-vendor list from `public/vendor-list.json` and
uses a demonstration CMP ID. Its README lists what changes for production.

## What to try

Replace the placeholder PostHog key in
`examples/showcase-analytics/lib/scripts.ts` with your own. Open the analytics
showcase in a private window with DevTools Network open:

1. Before you choose, no PostHog request appears.
2. Reject optional categories and reload. The banner stays closed and PostHog
   stays absent.
3. Open **Privacy settings** and allow **Analytics** (the `measurement`
   category). PostHog loads.
4. Withdraw it again. The page reloads without PostHog. Reloading cannot undo
   code that already ran, which is why c15t reloads by default.

## Tests

CI smoke-tests selected starters and checks that the banner renders, that Accept
persists across a reload and that **Privacy settings** opens the dialog:

```sh
bunx playwright@1.61.1 install chromium
STARTER_TARGET=nextjs bun run --cwd internals/fixtures/acceptance test:starters
```

The full consent journeys run against separate test apps in
`internals/fixtures`, which carry the test hooks the examples leave out:

```sh
EXAMPLE_TARGET=nextjs bun run --cwd internals/fixtures/acceptance test
```

Both variables take a comma-separated list of targets, such as
`react,tanstack-start`, or `all`. See the
[verification guide](/docs/guides/verify-consent) for the checks to run against
your own backend and vendor accounts before you ship.

# How consent works
URL: https://c15t.com/docs/concepts/how-consent-works
What c15t decides on each page load, the difference between a permission and a recorded choice, and what happens when a visitor saves.

## What c15t decides on each page load

On every page load c15t answers one question for each consent category: is
this allowed right now? To answer it, c15t:

1. Selects a **policy** for the visitor, usually by country and region. The
   policy says whether optional categories start denied (opt-in) or allowed
   (opt-out), and whether to show a banner.
2. Reads the visitor's **stored choice** from a cookie and localStorage, if
   there is one that still matches the policy.
3. Reads **privacy signals** such as Global Privacy Control (GPC).

The result is a set of **permissions**, one per category. Components, script
loaders, embeds and your own code read those permissions. Nothing optional
runs until the policy has resolved: while it loads, and if it fails, every
optional category is denied.

A banner is only the interface. It does not stop a script you load with a
plain `<script>` tag or a vendor SDK you initialize yourself. To gate that code,
register it with c15t. See [integrations](/docs/integrations/overview).

## Categories

|Category|Use it for|
|--|--|
|`necessary`|Code the site cannot work without. Always allowed.|
|`functionality`|Optional features such as support chat.|
|`measurement`|Analytics and usage measurement.|
|`experience`|Personalization.|
|`marketing`|Advertising, retargeting and pixels.|

Assign a category by what the code does, not by what would be convenient.
Calling analytics `necessary` does not make it necessary.
[Consent categories](/docs/concepts/consent-categories) explains which
categories the preference dialog shows and how policy scope affects them.

## Policies

A policy has a **model** and a **prompt**:

|Model|Optional categories before a choice|
|--|--|
|`opt-in`|Denied until the visitor allows them.|
|`opt-out`|Allowed until the visitor refuses them or sends a privacy signal.|
|`iab`|Controlled by an IAB TCF consent string.|
|`none`|Allowed, with no prompt.|

|Prompt|What the visitor sees|
|--|--|
|`choice`|A banner asking for a decision.|
|`notice`|A notice they can dismiss. Dismissing records an acknowledgement, not consent.|
|`none`|Nothing on load. The policy can still require a way to open preferences.|

With [Inth](https://inth.com) you manage policies in your project, and the app
receives them from the backend. Changing a stylesheet or importing a preset in
the browser does not override a hosted policy.
[Policies](/docs/concepts/policies) covers presets, scope, and why a banner may
not appear.

## A permission is not a recorded choice

These two values answer different questions, and mixing them up is the most
common integration bug:

* **Permission** (`effectivePermissions`, `useConsent('measurement')`) answers
  "may this run now?" Under an opt-out policy it can be `true` before the
  visitor has done anything.
* **Recorded choice** (`explicitChoice`) answers "what did the visitor decide?"
  It only changes when the visitor accepts, rejects or saves preferences.

|Task|Read|
|--|--|
|Load a script or render an optional feature|Permission|
|Show what the visitor chose, or report consent rates|Recorded choice|
|Decide whether a prompt is needed|`promptRequirement`|
|Find out why a region behaves differently|`policyRule`|
|Check that the policy loaded|`resolution.status`|

Never turn a permission into a saved choice. Hydrating server state, reading a
cookie or rendering a component does not count as a visitor action.
`onChoiceRecorded` fires only for a visitor's action; `onPermissionsChanged`
also fires when a choice expires or a privacy signal changes.

## Notices and privacy signals

Dismissing a notice acknowledges it. It grants nothing and leaves earlier
refusals in place.

GPC is a browser setting that asks sites not to sell or share data. c15t reads
it live on every evaluation and applies the restrictions your policy configures
for it. It never becomes a stored refusal: when the browser stops sending GPC,
the restriction ends. The backend also sees the current value.

## What happens when a visitor saves

When a visitor clicks Accept, Reject or Save, c15t:

1. Updates permissions and closes the banner or dialog in the same click.
   Scripts, embeds and network rules follow the new permissions immediately.
2. Writes the choice to the cookie and localStorage.
3. Sends the choice to the consent backend. If the request fails, the choice
   stays saved in the browser and the request is retried later.
4. Reloads the page if the visitor turned off something they had allowed.
   Code that already ran cannot be unloaded, so the reload starts a page with
   only permitted code. Set `reloadOnConsentRevoked: false` to handle revocation
   yourself.

The [consent state reference](/docs/concepts/consent-state) documents the exact
ordering, retries, server hydration and how open tabs stay in step.

## Where consent data comes from

A consent backend supplies policies and stores consent records. Use Inth, run
the [c15t backend](/docs/self-host/overview) yourself, or keep policies in the
browser for local development. [Choose your setup](/docs/concepts/choose-your-setup)
walks through the options for your framework and hosting.

# Consent categories
URL: https://c15t.com/docs/concepts/consent-categories
Assign scripts, embeds and features to c15t consent categories, and understand which categories the preference dialog shows.

## Choose categories by purpose

|Category|Purpose|
|--|--|
|`necessary`|Functionality required for the site to operate|
|`functionality`|Optional features such as support widgets|
|`measurement`|Analytics and usage measurement|
|`experience`|Optional personalization|
|`marketing`|Advertising and marketing|

`necessary` is always permitted. Assign categories based on what an integration
does in your application; renaming analytics to necessary does not change its
purpose.

c15t discovers categories from registered scripts, network rules, React `ConsentGate`
components, and iframes with `data-category` handled by the iframe blocker.
The browser client also discovers inert scripts tagged with `data-c15t-category`.
Compound script and network conditions contribute every category they reference.

Discovered categories are added to `consentCategories`, when supplied. The dialog
always includes Necessary and offers the optional categories in that combined
set that are also in the resolved policy scope. Choice completion uses the same
set.

If neither configuration nor integrations supply categories, the result depends
on the policy's `scopeMode`:

* Under a permissive policy, the dialog lists only Necessary. The banner still
  appears when the policy prompts for a choice. Accept All, Reject All and Save
  each record that the visitor saw it, send a consent receipt for Necessary
  alone in hosted and manifest modes, and keep the banner dismissed after
  reload. The acknowledgement expires with the policy's choice validity and
  after a policy change, like a choice would. A stored choice that is still
  valid under the current policy also counts as an acknowledgement.
* Under a strict policy, or an IAB TCF policy, the dialog uses the full policy
  scope. TCF consent is given per purpose and recorded in the TC string.

A category declared after that acknowledgement, such as a newly registered
script or a discovered iframe, needs a choice, so the banner asks again.

Categories discovered later are added immediately and retained until the provider
or runtime is recreated. Adding a category can require a new choice; removing a
script or unmounting a frame does not remove its category or erase consent.
Discovery does not grant consent or change backend permission restrictions.

## Respect policy scope

A strict scope denies categories outside the rule. A permissive scope can allow
out-of-scope categories unless another restriction applies. When a rule selects
only some optional categories, set `scopeMode` explicitly. An omitted scope,
`['*']`, or a list containing only `necessary` expands to the default optional
categories; a necessary-only list is not a shortcut for disabling all tracking.

For example, a backend rule with `categories: ['necessary']` and scripts assigned
to `marketing` and `measurement` displays Necessary, Marketing, and Analytics,
even without `consentCategories`. Accept All records both optional choices and
keeps the banner dismissed after reload. An explicit list of
`['necessary', 'measurement']` with no other integrations displays Necessary and
Analytics.

Hidden optional categories do not need a choice to dismiss the banner. Their
permissions still follow the backend policy, so hidden opt-in categories remain
denied without a valid grant. React providers enable DOM iframe blocking and
discovery by default. The blocker loads when the first iframe with
`data-category` or `data-vendor` is on the page, so pages without one never
download it; until it runs, such an iframe that arrives with a `src` consent
does not allow is paused. Write gated iframes with `data-src`, not `src`. The
browser requests a `src` as soon as the iframe is in the document, before the
blocker can pause it, whether the iframe comes from the server HTML or a
client render. Set
`iframeBlocker: false` to disable it, or
`iframeBlocker: { disableAutomaticBlocking: true }` to scan manually with
`useIframeBlocker({ disableAutomaticBlocking: true }).processAllIframes()`.

Use effective permissions to gate work and explicit choices to inspect what the
visitor confirmed. Read [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) for that
distinction and [policies](/docs/concepts/policies) for v3 policy configuration.

# Policies
URL: https://c15t.com/docs/concepts/policies
How policy models, prompts and scope decide what c15t asks visitors, where to change the rules, and why a banner may not appear.

## What the policy controls

A policy rule selects the permission model, categories, prompt and persistent
privacy controls for a visitor. Your app reads the resolved rule and effective
permissions. It should not choose a different rule just to hide a banner.

|Policy setting|What your app should expect|
|--|--|
|`model: 'opt-in'`|Optional categories in scope wait for consent.|
|`model: 'opt-out'`|Categories in scope can be allowed before a choice. Saved refusals and privacy signals can restrict them.|
|`model: 'none'`|Categories in scope are allowed without an initial prompt. Stock consent controls stay hidden unless the rule grants privacy rights.|
|`prompt: 'choice'`|The banner asks for a choice when the current state requires one.|
|`prompt: 'notice'`|Dismissing the notice records an acknowledgement, not a consent grant.|
|`prompt: 'none'`|No automatic prompt. The rule can still require a way to open preferences.|
|`scopeMode: 'strict'`|Optional categories outside the rule's scope stay denied.|

Keep a persistent preferences entry point wherever the policy provides that
right. A visitor who dismissed a notice or rejected tracking still needs a way
to revisit their choice. Stock components read the rule's rights; custom UI
must do the same.

Use `effectivePermissions` to gate a script or embed. A `true` value under an
opt-out rule does not mean the visitor clicked Accept. Read `explicitChoice`
when you need the visitor's recorded decision. See
[how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) for these distinctions.

## Where to change the rules

For Inth, configure policy rules on your hosted project. The app receives those
rules through the configured [data-fetching path](/docs/concepts/data-fetching). Importing
`recommendedPolicyRules()` or changing browser styling does not override the
hosted policy.

For a backend you operate, use the
[policy packs guide](/docs/self-host/guides/policy-packs). It covers
`manifest.policyRules`, preset selection and custom matchers. Browser-only
setups own their rules locally; see
[choose your setup](/docs/concepts/choose-your-setup).

Presets are starting configurations. Select them for your actual processing,
and review their assumptions before allowing optional categories by default.
A country match does not establish a legal basis for a vendor's data use.

## Why the banner may be absent

A missing banner can be an expected policy outcome or an initialization problem.
Check `resolution.status` before interpreting the active model.

|State|What to check|
|--|--|
|A policy matched and `promptRequirement.kind` is `none`|The rule does not ask for an initial prompt, or the stored records already satisfy it. Check persistent preferences separately.|
|A policy matched but a category is denied|Inspect `effectivePermissions`, `explicitChoice`, `privacySignals` and `restrictions`. A saved refusal or GPC can keep it denied.|
|No policy has matched|Check backend connectivity, location inputs and policy configuration. Optional categories stay denied while resolution is unresolved.|

Do not treat `policyRule` alone as proof that a policy resolved. The snapshot
also carries a safe rule for evaluation while resolution is pending or failed.
Use `resolution.policy` only after checking for `status: 'matched'`.

The local `recommendedPolicyRules()` pack uses opt-in rules for Europe and
Québec, opt-out for its supported US privacy states, and a no-prompt `none`
default for other known locations. An unknown country uses its strict opt-in
fallback. A US country with a missing state gets the US opt-out fallback.
These are the local pack's defaults, not a promise about your Inth project.
Browser-only mode does not discover a visitor's country from their IP address.

# Consent modes
URL: https://c15t.com/docs/concepts/modes
Reference for manifest(), hosted() and offline() in every c15t framework package, where each one resolves the visitor's policy, what it adds to first-load JavaScript, the build-time manifest fetch and its failure policy, and the backend URL variable each framework reads.

## Choose a mode

A mode decides how c15t finds the policy that applies to a visitor. Every
framework package exports the same three factories, `manifest()`, `hosted()`
and `offline()`. Consent choices go to the backend in `manifest()` and
`hosted()`, whether that backend is [Inth](https://inth.com) or a
[self-hosted c15t backend](/docs/self-host/quickstart).

|Mode|Where the policy resolves|Backend requests on a first visit|Use it when|
|--|--|--|--|
|`manifest()`, the default|Your server, from the policy the build downloaded. With `resolve: 'browser'`, or in a single-page app, the browser.|None to resolve the policy. Choices post to `/subjects`.|Most apps. Rebuild to ship policy changes, or set `source: 'runtime'`.|
|`hosted()`|The backend's `GET /init`|One `/init` per page that resolves consent.|Static hosting without a server, or a policy that changes without a rebuild and needs the backend's geolocation.|
|`offline()`|The browser, from rules in your bundle|None. Choices stay in the browser.|Local development, tests and demos. Not recommended for production environments.|

`manifest()` is the default in Next.js, TanStack Start, Nuxt, Astro and
SvelteKit. React, Vue, Svelte and `@c15t/browser` have no default: pass a
mode yourself. Their quickstarts use `manifest()`. The script tag picks its
mode from the bundle file; see
[choose a mode](/docs/frameworks/html/attributes-and-api#choose-a-mode).

[Data fetching](/docs/concepts/data-fetching) compares these paths with the
custom transport and same-origin proxies.

## Import the factories from your framework package

There are two kinds of factory, and each framework package exports the kind it
needs under the same three names.

|Framework|Import from|Pass the mode to|Kind|
|--|--|--|--|
|Next.js|`c15t/next`|`mode` in `c15t.config.ts`|Data|
|TanStack Start|`c15t/tanstack-start`|`createConsentStateHandler({ mode })`|Data|
|Nuxt|`c15t/vue`|`c15t.mode` in `nuxt.config.ts`|Data|
|Astro|`c15t/astro`|`c15t({ mode })` in `astro.config.mjs`|Data|
|SvelteKit|`@c15t/svelte/kit`|`c15tHandle({ mode })` in `src/hooks.server.ts`|Data|
|React|`c15t/react`|`ConsentProvider`'s `options.mode`|Transport|
|Vue|`c15t/vue/vue-plugin`|`app.use(c15tVue, { mode })`|Transport|
|Svelte|`@c15t/svelte`|`<ConsentProvider mode={...}>`|Transport|
|JavaScript|`@c15t/browser`|`init({ mode })`|Transport|
|Script tag|none|The bundle file: `c15t.js` is hosted, `c15t.offline.js` offline. The headless and IAB scripts also take `data-mode="manifest"`.|Name|

**Data factories** return a plain object such as `{ type: 'manifest' }`.
Server-rendered frameworks read their config on the server and in the
browser, and Nuxt and Astro serialize it, so the mode has to be data. The
framework turns it into a transport in the browser and loads the code of
any mode other than the default with `import()`. The same factories are
available from `c15t/modes` (or `@c15t/core/modes`) for shared code.

**Transport factories** return the transport itself, with the same `type` and
options attached as properties. A single-page app has one environment, so
the bundler keeps only the mode you import and drops the others.

A server-rendered root that receives a transport factory still works, for
example `hosted()` from `c15t/react` passed to Next.js `ConsentRoot` as
`options.mode`. Outside production it warns that the transport's code is now
in the first-load bundle. `custom(transport)` exists only as a transport, so
it cannot go in a serializable config. Pass it through the root's
`options.mode` instead.

## manifest()

`manifest()` resolves the visitor's policy from the backend's public consent
manifest instead of asking the backend's `/init`. A
[consent manifest](/docs/concepts/data-fetching#what-is-a-consent-manifest)
holds your policy rules and copy, and no visitor data.

|Option|Default|Behavior|
|--|--|--|
|`source`|`'build'`|`'build'` uses the snapshot the build integration downloaded. Without one, such as in dev after a failed fetch, it fetches the manifest at runtime. `'runtime'` always fetches at runtime, so policy edits apply without a rebuild.|
|`snapshot`|none|A manifest you supply. You can pass `snapshot` or `source`, not both.|
|`resolve`|`'server'`|`'server'` resolves each visitor on the server and ships no resolver to the browser. `'browser'` resolves in the browser, for pages the server does not render per visitor. Server-rendered frameworks only.|
|`manifestURL`|see below|Where to fetch the manifest at runtime. On the server, `${backendURL}/manifest`. In the browser, `${routePrefix}/manifest`, else `${backendURL}/manifest`.|
|`geoURL`|none|A same-origin route that answers with the visitor's `{ country, region }`. Browser resolution only.|
|`inputs`|none|`{ country, region }` when the page already knows the visitor's location, for example from an edge worker. Browser resolution only.|

The transport `manifest()` from `c15t/react`, `c15t/vue/vue-plugin`,
`@c15t/svelte` and `@c15t/browser` always resolves in the browser, so it has
no `resolve` option. It also takes `backendURL`, `headers`, `credentials`,
`domain`, `fetch` and `initFallback`. With no options it reads the snapshot
and the backend URL your build integration downloaded. With `manifestURL`,
the browser fetches that URL when the page loads and the build's snapshot is
not used. Saves still go to `backendURL`, or the build's backend URL.

When the policy depends on where the visitor is, and the browser does not
know the country or region, browser resolution asks `geoURL`, then the
backend's `/init`. Set `initFallback: false` to resolve for an unknown location
instead. A policy with location rules therefore saves no request in a
single-page app unless you pass `inputs` or `geoURL`. The `consentManifest()`
plugins from `c15t/build`, `c15t/vue/vite` and `@c15t/svelte/vite` warn
about this when a single-page app build bundles such a policy.

## hosted()

`hosted()` asks the backend's `GET /init` for each visitor's policy and posts
choices to `${backendURL}/subjects`.

|Option|Default|Behavior|
|--|--|--|
|`backendURL`|the framework's backend URL|Backend URL, absolute or relative such as `/api/c15t`.|
|`headers`|none|Headers sent with `GET /init`.|

The transport `hosted()` also takes `initURL`, `assertDecisionInputs`,
`domain` and `fetch`. `initURL` sends `GET /init` to another URL, usually a
same-origin route that resolves the manifest, while saves keep going to
`${backendURL}/subjects`. `assertDecisionInputs` defaults to `true` when
`initURL` is set, so each save carries the policy decision it was made
against and the backend can reject a save made against a stale policy.

`hosted()` from `c15t` (`@c15t/core`) is the plain transport and requires
`backendURL`. The framework exports fill it in from your config or your
build.

## offline()

Not recommended for production environments.

`offline()` resolves policy rules in the browser and stores choices in browser
storage. Nothing reaches a backend, so there is no consent record, no
cross-device history and no IP geolocation.

|Option|Default|Behavior|
|--|--|--|
|`policyRules`|the recommended rule pack|Rules to resolve. Passing rules replaces the pack entirely.|

Unknown country and region are real inputs: test the missing-location case
against your rules. See [policy rules](/docs/concepts/policies).

## What each mode adds to first-load JavaScript

In a server-rendered framework, the browser receives the resolved state with
the page. It only needs the code to save a choice, and loads the rest when it
runs:

|Mode|First-load JavaScript|Loaded with `import()` when it runs|
|--|--|--|
|`manifest()`|The code that saves choices and builds an init request|The hosted init path, if the browser has to resolve consent again|
|`manifest({ resolve: 'browser' })`|The code that saves choices|The browser resolver, English copy and the fetch of `${routePrefix}/manifest` or `${backendURL}/manifest`. Other languages load per language.|
|`hosted()`|The code that saves choices|The hosted init path|
|`offline()`|Nothing mode-specific|The offline transport, the rule pack and its copy|

With `manifest()` resolved on the server, the manifest snapshot, the resolver,
the offline rule pack and other languages stay out of the browser bundle.

In a single-page app the bundle contains the mode you imported:

|Mode|In the bundle|
|--|--|
|`manifest()`|The snapshot, when the build downloaded one, and the code that saves choices. The resolver starts loading when `manifest()` runs, unless the policy needs a location the page does not know. English copy is bundled; other languages load the first time a visitor needs one.|
|`hosted()`|The hosted transport|
|`offline()`|The offline transport, the recommended rule pack and its copy|

## Set the backend URL

Each framework reads its backend URL from a public environment variable, so
the quickstarts never write it in code. Put it in `.env` or your host's build
settings. The value is public configuration, not a secret.

|Framework|Variable|Inth alternative|
|--|--|--|
|Next.js|`NEXT_PUBLIC_C15T_BACKEND_URL`|`NEXT_PUBLIC_INTH_PROJECT_URL`|
|Nuxt|`NUXT_PUBLIC_C15T_BACKEND_URL`|`NUXT_PUBLIC_INTH_PROJECT_URL`|
|Astro|`PUBLIC_C15T_BACKEND_URL`|`PUBLIC_INTH_PROJECT_URL`|
|SvelteKit and Svelte|`PUBLIC_C15T_BACKEND_URL`, then `VITE_C15T_BACKEND_URL`|`PUBLIC_INTH_PROJECT_URL`, then `VITE_INTH_PROJECT_URL`|
|TanStack Start, React, Vue and JavaScript with Vite|`VITE_C15T_BACKEND_URL`|`VITE_INTH_PROJECT_URL`|
|Script tag|`data-backend-url` on the script element|–|

Set either variable. The Inth one holds your Inth project URL, so other Inth
SDKs in the same app can read it too. When both are set, the c15t variable
wins.

A backend URL resolves in this order: the mode's own `backendURL`, then the
framework's top-level `backendURL` option, then the c15t variable, then the
Inth variable. The build reads each variable from the process environment,
then from `.env.[mode].local`, `.env.[mode]`, `.env.local` and `.env` in the
project root, so a c15t variable in `.env` still beats an Inth variable in
the environment. The Vite plugins set an unset `VITE_C15T_BACKEND_URL` to the
URL they used, so `import.meta.env.VITE_C15T_BACKEND_URL` in app code reads
the same value. `withConsentManifest()` does the same for
`NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js.

Next.js inlines `NEXT_PUBLIC_` variables at build time. Changing the variable
on a built app has no effect until you rebuild.

## Download the manifest at build time

`manifest()` with the default `source: 'build'` resolves from a snapshot that a
build integration downloads from `${backendURL}/manifest`:

|Framework|Build integration|Name in messages|
|--|--|--|
|Next.js|`withConsentManifest()` from `c15t/next/build`, in `next.config.ts`|`@c15t/nextjs/build`|
|TanStack Start|`consentManifest()` from `c15t/tanstack-start/build`|`@c15t/tanstack-start/build`|
|React and JavaScript|`consentManifest()` from `c15t/build`|`@c15t/core/build`|
|Vue|`consentManifest()` from `c15t/vue/vite`|`@c15t/vue/vite`|
|Svelte and SvelteKit|`consentManifest()` from `@c15t/svelte/vite`|`@c15t/svelte/vite`|
|Nuxt|the `c15t/vue` module|`@c15t/vue`|
|Astro|the `c15t()` integration|`@c15t/astro`|

The integration downloads the manifest when the production build or the dev
server starts, and waits at most 10 seconds. Nothing is written into your
source tree. App code reads the result from `c15t/generated`:

```ts
import { backendURL, snapshot } from 'c15t/generated';
```

Both exports are `undefined` when the build has no snapshot, so imports
compile on a fresh checkout. In the browser bundle of a server-rendered
framework, `snapshot` is always `undefined`. Next.js goes further: a client
component that imports `c15t/generated` fails the build.

Rebuild after you change policies, translations or vendors in your project. If
your CI caches build output, force a fresh build.

## What happens when the download fails

The same policy applies in every framework:

|Command|Default when the download fails or no backend URL is set|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning. The server, or a single-page app's browser, fetches the manifest at runtime.|

`onBuildError` picks one behavior for both commands:

* `'fail'` stops dev too.
* `'runtime'` lets a production build finish without a snapshot. The manifest
  is then fetched at runtime.

Pass it where you configure the integration: the second argument of
`withConsentManifest()`, `consentManifest({ onBuildError })`, the `c15t` key
in `nuxt.config.ts`, or `c15t({ onBuildError })` in Astro.

The `C15T_ON_BUILD_ERROR` environment variable overrides the option, so you
can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Any value other than `fail` or `runtime` stops the command. Turborepo's strict
environment mode hides undeclared variables from tasks, so list
`C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

A missing backend URL follows the same policy as a failed download: a
production build stops, dev warns, and an explicit `'runtime'` logs a notice
and continues. Astro and Nuxt are stricter in `manifest()` mode, including
`manifest({ snapshot })`: the browser saves consent to the backend, so a
missing backend URL stops `astro dev` and `nuxt dev` as well.

The download is skipped without an error when the build cannot use a
snapshot:

* The backend URL is relative, such as `/api/c15t`. With an explicit
  `onBuildError: 'fail'`, a relative URL stops the build instead.
* Next.js builds with `output: 'export'`, which has no server.
* The mode is `hosted()`, `offline()`, `manifest({ snapshot })` or
  `manifest({ source: 'runtime' })` in Next.js, Nuxt and Astro. Next.js reads
  the mode from `c15t.config.ts`.
* A single-page app built with Vite (React, Vue, Svelte, JavaScript) does
  not use `manifest()`. The mode is set in app code, so the plugin downloads
  the manifest only once the bundle turns out to read it, after unused code
  is dropped. A `hosted()` or `offline()` build never contacts the backend.
  SvelteKit and TanStack Start choose the mode on the server at runtime, so
  their builds always download it.

A failed download never reuses an older snapshot. The
[troubleshooting guide](/docs/guides/troubleshooting#why-does-the-build-fail-to-download-the-manifest)
lists each message and its fix.

# Data fetching
URL: https://c15t.com/docs/concepts/data-fetching
Choose the recommended build-time policy snapshot or runtime manifest fetching, backend /init, browser resolution or offline rules, and understand where consent choices are saved.

## Compare the fetching paths

Where policy resolves and where choices are saved are separate from who runs
the backend. Inth and a [self-hosted backend](/docs/self-host/quickstart) speak
the same protocol, so every path below works with either. Only `offline()`
removes backend requests. For a recommendation by framework, start with
[choose your setup](/docs/concepts/choose-your-setup).

|Fetching path|Where policy resolves|Where choices are submitted|Choose it when|
|--|--|--|--|
|Build-time manifest, recommended|Your server or browser resolves a bundled policy snapshot with each visitor's inputs|Inth or your c15t backend|Your framework supports a build integration and policy changes can ship with a rebuild|
|Cached manifest on your server|Your application resolves public policy data with each request's location and signals|Inth or your c15t backend|Policy changes must reach the app without rebuilding, or builds cannot access the backend|
|Regular backend `/init`|The consent backend|The same backend|You want the fewest moving parts, need backend-owned request resolution, or have no application server|
|Manifest in the browser|The browser, using supplied or unknown location|Inth or your c15t backend|You deliberately want client resolution and have planned geography, bundle size and policy refresh|
|Offline|The browser or local runtime, using bundled rules|No backend submission|Local development and tests. Not recommended for production environments.|
|Custom transport|Your implementation|Your implementation|An existing service cannot use the c15t backend protocol|

## What is a consent manifest?

A manifest is a versioned policy document served by `GET /manifest`. It contains
policy rules, translation configuration and related consent configuration. It
is public configuration, not a visitor's saved choices. A resolver combines the
manifest with country, region, language and privacy signals to produce an init
result for one visitor.

Reusing the public document avoids asking the consent backend to resolve policy
for every application request. Cache misses and revalidation still fetch the
manifest, and consent writes still need the backend. Measure the deployed
request path before promising a latency improvement.

Do not put secrets, visitor identifiers or consent records into a manifest.
Keep personalized init responses out of shared caches. Changing a policy also
requires a refresh strategy for cached or build-time manifests.

## Use a build-time manifest by default

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

`manifest()` is the default mode in every server-rendered framework.
[Consent modes](/docs/concepts/modes#download-the-manifest-at-build-time)
covers each framework's build integration and what happens when the
download fails.

The framework quickstarts include the build integration for supported
deployments. Server resolution uses the snapshot without an upstream manifest
request. Browser resolution includes the policy and resolver in the client
bundle, and may still request location for regional policies. Static Nuxt and
Astro sites and script-tag sites keep the runtime setup from their guides.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

## How manifest mode counts visitors

The backend counts visitors from `/init` requests, and manifest resolution
skips them. To keep the count, the server adapters send a session report after
each resolution: the host posts to the backend's `POST /sessions` from the
server, after the response. The browser sends nothing, and the report stores
no identity; the visitor's IP address and user agent are forwarded under the
backend's usual IP handling. Static output resolves in the browser and sends
no report. Set `reportSessions: false` on an adapter to turn it off.

## Link an init to the save that follows

Each page load gets a journey id, a random UUID sent on requests c15t already
makes:

|Request|Query parameters|
|--|--|
|`GET /init`|`journey`, `journeyScope`, `stored` (`1` if a choice or notice dismissal was stored)|
|`POST /subjects`|`journey`, `journeyScope`|

Session reports carry it as `journey: { id, scope, storedChoice, prompt, domain }`.
A report and a save with the same `id` belong to one page load. `prompt` is
`due`, `stored` or `not-required`; a page that falls back to the default opt-in
banner counts as `due` or `stored`. A stored answer counts as `stored` even if a
policy change makes c15t ask again.

The id is random, is never the subject id and is never written to a cookie.
Every save that carries one follows an `/init` or report with the same id.
Saves replayed after going offline carry none.

|`journey`|Behavior|
|--|--|
|`'page'` (default)|One id per page load, in memory.|
|`'tab'`|Kept in `sessionStorage` while a prompt is due, and removed once the visitor chooses or no prompt is due. Only when the browser resolves init; server-rendered pages use `'page'`.|
|`false`|No journey.|

Set it on the runtime or provider. In Next.js use `defineConsentConfig({ journey })`;
in TanStack Start pass the same value to `resolveConsent` and `ConsentRoot`; with
the inline prefetch script, pass it to `buildPrefetchScript`. Vue, Svelte, Astro
and the script tag use `'page'`. A manifest that resolves locally in the
browser reports no init, so it sends no journey.

If you pass a transport `hosted()` a `fetch`, match on the path: URLs now carry a query string.

## What does regular `/init` do?

`hosted()` uses `${backendURL}/init` for initialization and
`${backendURL}/subjects` for consent submissions. The name `hosted` describes
the protocol; the URL can belong to Inth or your own c15t backend.

```ts title="c15t.config.ts"
import { defineConsentConfig, hosted } from 'c15t/next';

export default defineConsentConfig({ mode: hosted() });
```

Each framework passes the mode in a different place, and server-rendered
frameworks take the data `hosted()` from their own package.
[Consent modes](/docs/concepts/modes#import-the-factories-from-your-framework-package)
lists where each one goes.

A regular backend `/init` request lets the backend resolve the visitor context.
A same-origin URL named `/api/c15t/init` can instead resolve from a cached
manifest in your application. The URL name alone does not tell you which path
runs.

## How do transports and proxies differ?

A transport implements initialization, saving and optional record operations.
A proxy changes where HTTP requests travel. It does not change the policy
resolver or make personalized responses safe to cache.

For a same-origin init route that resolves a manifest, the hosted transport can
separate policy reads and record writes. With a backend rewrite mounted at
`/api/c15t`, a single-page app can use the transport `hosted()` from
`c15t`:

```ts title="src/consent-mode.ts"
import { hosted } from 'c15t';

export const mode = hosted({
	backendURL: '/api/c15t',
	initURL: '/api/c15t/init',
});
```

The route must return the c15t init response contract. c15t adds its inputs to
`initURL` as query parameters, replacing any of your own with the same name.
See [query parameters and CORS](/docs/self-host/api/endpoints#query-parameters-and-cors)
for the names. Because `initURL` is set, `assertDecisionInputs` defaults to
`true`: saves carry the policy decision they were made against when init
returned no signed policy snapshot token, so the backend can reject a save
made against a stale policy. Server-rendered frameworks do this for you when
you set `routePrefix`: the browser re-inits through `${routePrefix}/init`.
Every framework rejects `routePrefix: '/'` when it sets up, because a
catch-all consent route at the site root would catch every page.

The init route resolves policy; the backend rewrite forwards `/api/c15t/subjects`
and other record endpoints. Configure both if you choose this optional proxy
variant. Server-rendered frameworks do both with one option: `proxy: true` in
Next.js `c15t.config.ts` or TanStack Start's `createConsentStateHandler`,
with a consent route created with `proxy: true`. The
[Next.js recipe](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
shows the configuration. A direct absolute backend URL works
without a rewrite.

This optional optimization keeps c15t requests on the app's origin and avoids a separate browser DNS lookup
and TLS connection to the consent backend. The app server still connects to
the upstream backend for manifest refreshes and consent writes. Vendor scripts
and vendor requests keep their own origins.

The rewrite destination and the init route use the absolute upstream endpoint,
such as `https://your-project.inth.app`. The browser uses `/api/c15t` without
needing the upstream URL. A static export cannot serve a Next.js route or
rewrite at runtime; use the absolute Inth URL or a proxy provided by the static
host instead.

## When should I use offline mode?

Not recommended for production environments. Use Inth or a self-hosted backend
for production policy and consent records.

`offline()` resolves bundled policy rules without an init request and acknowledges
saves locally. The runtime's persistence module stores the choice in browser
storage. There is no backend audit history, cross-device record service or IP
geolocation supplied by this transport.

Use your framework's `offline()` so its translations and provider context are
included. In a React app it replaces the mode passed to `ConsentProvider`:

```ts title="src/consent-mode.ts"
import { offline } from 'c15t/react';

export const mode = offline();
```

In Next.js, TanStack Start, Nuxt, Astro and SvelteKit, pass the data
`offline()` from the framework package where the config takes `mode`; see
[consent modes](/docs/concepts/modes#import-the-factories-from-your-framework-package).

With no `policyRules`, the current offline transport uses the recommended rule
pack. Supplying `policyRules` replaces that pack. Unknown country and region are
real resolution inputs; offline mode does not discover a visitor's location.
Use [policy rules](/docs/concepts/policies) to understand
matching and defaults, and test the missing-location case.

Offline mode is an explicit architecture choice, not an automatic fallback for
a failed Inth request. If hosted initialization fails before a policy resolves,
optional permissions remain denied and the stock prompt stays hidden. Observe
initialization failures instead of silently changing policy sources.

## Can I provide my own transport?

`custom(transport)` accepts a `KernelTransport` with the v3 `init` and `save`
contract. It does not accept v2 endpoint handlers such as `setConsent`. Keep
policy resolution, record acknowledgments and failure behavior consistent with
the kernel contract. Prefer a built-in transport when your backend supports it.

## Verify the selected path

Inspect browser and server requests separately. A server manifest fetch will
not appear in the browser's Network panel. With a build-time snapshot, start a
fresh production server and confirm it makes no upstream `/manifest` request.
After a policy edit, rebuild and confirm the new policy appears. On a runtime
manifest path, check that
page requests do not call the backend `/init`, a visitor's choice still reaches
the backend's `/subjects`, and policy changes become visible after the configured
refresh. With a same-origin consent proxy, the browser should call only
`/api/c15t` paths for consent HTTP traffic; inspect server logs to verify their
upstream destinations.

Test different locations, missing location headers, GPC, returning choices and
backend failure. See [verification](/docs/guides/verify-consent).

# Consent state reference
URL: https://c15t.com/docs/concepts/consent-state
How c15t saves choices, gates IAB vendors, hydrates server records and keeps browser tabs and storage in step.

This reference covers the edge cases behind the model in
[how consent works](/docs/concepts/how-consent-works). You need it when you
build custom consent UI, run c15t across subdomains, or debug a choice that
changes between tabs.

## Gate IAB vendors on the TC string

Under an IAB policy, a script, network rule or iframe that names a `vendorId`
or IAB purposes is an IAB target. It runs only while a confirmed TC string
grants what it declares: purpose and vendor consent for `iabPurposes`, purpose
and vendor legitimate interest for `iabLegIntPurposes`, and opt-ins for
`iabSpecialFeatures`. Every category it names must also be free of
restrictions, so GPC or strict scope blocks it.

A refused category is the one exception. It does not block an IAB target that
processes only on legitimate interest, after publisher restrictions, because
the TCF lets that processing run without consent. The visitor's control for it
is the objection, which the legitimate interest signals record. The category
itself stays refused: its `effectivePermissions` entry is `false`, and targets
that name only the category, or that also declare a consent purpose or special
feature, stay blocked.

## Categories under an IAB policy

Under an IAB policy the visitor chooses TCF purposes, and c15t derives each
category from them when the choice is saved. A category is granted when the
visitor consented to every purpose in it that a listed vendor processes on
consent:

|Category|TCF purposes|
|--|--|
|`marketing`|2, 3, 4|
|`measurement`|7, 8, 9|
|`experience`|5, 6|
|`functionality`|10, 11|

`necessary` is always granted. Purpose 1, device storage, decides no category.

Accept All consents only to the purposes and special features that the vendors
in your list declare, because the TCF Policies allow no consent signal for a
purpose the visitor was not shown. A category whose purposes no listed vendor
processes on consent therefore stays denied after Accept All, and so does every
script, iframe or network rule gated on it. With a vendor list whose vendors
declare only purposes 1 to 4 and 7, for example, `experience` and
`functionality` stay denied.

If your own scripts depend on such a category, do one of these:

* Declare the processing. Add a custom vendor for it, with the purposes it
  uses, through the `customVendors` option of your IAB setup. The preference
  centre then lists those purposes, and Accept All and the purpose switches
  can grant the category.
* Gate the script on a category that your listed vendors' purposes cover, or on
  `necessary` if it needs no consent.

Check `effectivePermissions` after Accept All on a fresh visit to see which
categories your vendor list leaves denied.

## When a choice is saved

A save records the choice in the browser first and sends it to the backend
afterwards. The stock banner, preference dialog and IAB surfaces in every
framework adapter, and the `acceptAll()`, `rejectAll()` and `save()` methods
of the browser and Astro clients, close without waiting for the backend. In
order:

1. In the click task, the explicit choice and effective permissions change,
   `onChoiceRecorded` and `onPermissionsChanged` run, gated scripts, iframes
   and network rules follow the new permissions, and the surface leaves the
   active state. Its exit animation still plays.
2. In the next task, the choice is written to the cookie and localStorage.
3. After that write is queued, the request to the backend starts.
4. When the request settles, the kernel emits `command:save:completed`. The
   promise returned by `kernel.commands.save()`, React's `performAction()` and
   Svelte's `saveConsents()` resolves or rejects only then.
5. If the save turned off a category or vendor that was granted, the page
   reloads in the next task, after `onBeforeConsentRevocationReload` runs.
   Removing a script cannot stop code that already ran, so the reload starts a
   page with only permitted code. With several saves in flight, it waits for
   the last one. Set `reloadOnConsentRevoked: false` to handle revocation
   yourself.

A failed request does not reopen the surface or roll the choice back. The
kernel emits `command:error`, which reaches the `onError` callback in adapters
that accept one, and queues the payload in localStorage. Where localStorage is
unavailable, the queue lives in memory until the page unloads. The queue is
replayed after the next successful initialization and when the browser comes
back online, up to 10 attempts over 7 days. A replay carries the original action
time and policy snapshot token, so the backend records when the visitor
decided, and a duplicate submission resolves to the same consent record. A
backend that signs policy snapshot tokens rejects a replay made after the
token expires, which is 30 minutes by default for the self-hosted backend. A
save still queued by then is recorded only in the browser.

A replay that fails and stays queued emits `save:replayed` with `ok: false` but
not `command:error`, since the save already reported its first failure. A save
that leaves the queue without the backend recording it, because it ran out of
attempts, waited more than 7 days or was refused, emits `command:error` once.
Development builds also log a `[c15t]` console warning for each of these.

IAB surfaces close in the click task too, but an IAB choice is recorded only
after its TC string is encoded, which can wait for the TCF library to load.
If that local step records nothing, for example because the vendor list
failed to load, the surface comes back so the visitor can try again.

Every adapter leaves the same surface after a save: the banner while the
policy still owes a choice or a notice, and nothing once no prompt is owed,
while the policy is still loading, or after it failed to resolve. A banner
the visitor reopened closes too. A save that records nothing new, such as an
unchanged selection, closes the surface when it resolves successfully. Opening
or closing a surface, or starting another save, before then leaves the surface
as the visitor set it.

Closing the dialog without saving, with Escape or the adapter's close call,
leaves the same surface a save would. A visitor who opens preferences from the
banner and backs out still owes a choice, so the banner comes back. Once a
choice is recorded, closing the dialog leaves nothing open.

## Preserve records during hydration

Server helpers return records with policy information and evaluation time.
Forward that configuration intact. Copying an allowed category into a receipt
would invent a grant and lose its original confirmation time.

Valid v2 records can be read without a startup rewrite. The next explicit action
writes the v3 format. The upgrade guides for
[Next.js](/docs/frameworks/next/upgrade-v3#keep-visitors-existing-choices),
[React](/docs/frameworks/react/upgrade-v3#keep-visitors-existing-choices) and
[JavaScript](/docs/frameworks/javascript/upgrade-v3#keep-visitors-existing-choices)
cover how v3 treats v2 records.

## Keep open tabs in step

Tabs and windows on the same origin (scheme, host and port) share the consent
cookie and localStorage. When a visitor rejects in one tab, every other open tab
on that origin applies the rejection without a reload. Scripts and features
gated on `effectivePermissions` lose permission, subscribers are notified once
and `onPermissionsChanged` fires. Clearing records in one tab returns the others
to the active policy's defaults: an opt-in policy denies optional categories and
shows the prompt again.

Tabs on another subdomain that shares the consent cookie do not share
localStorage, so the browser sends them no `storage` event. They pick up the
change on their next focus or visibility change, or when you reconcile
yourself as described in
[Reconcile yourself or turn it off](#reconcile-yourself-or-turn-it-off).

The `storage` event only exists for localStorage. When localStorage is
unavailable (blocked by the browser, a sandboxed frame or a privacy mode) and
c15t stores in the cookie alone, another tab's change arrives only on the next
focus or visibility change, or when you call `runtime.reconcileStorage()` or
`persistence.reconcile()`. c15t does not poll the cookie or use a
`BroadcastChannel` for this.

Browser persistence reads stored records again at these moments:

|Moment|What happens|
|--|--|
|Another tab or window on the same origin changes a c15t localStorage key|Reconciles on the `storage` event|
|The page becomes visible again|Reconciles on `visibilitychange`|
|The window regains focus|Reconciles on `focus`|
|The network reconnects|No storage read|

Several triggers in quick succession run one reconciliation in a later task.
Reconnecting does not read storage, because going online changes nothing in
browser storage. On reconnect the kernel retries saves the backend did not
accept and a failed initialization. Save retries do not write the cookie or
localStorage. A write that follows initialization obeys the rules in
[Ordering with pending writes](#ordering-with-pending-writes).

Every adapter that mounts browser persistence does this: the React, Next.js and
TanStack Start providers, Vue, Svelte, Astro, the script tag and
`createConsentRuntime`. With `persistence: false` nothing is stored or read.

### What a reconciliation applies

Stored records are merged into the ones in memory:

* Category decisions merge per category. Each category keeps the decision with
  the newer confirmation time, so a tab that only changed marketing never
  reverts another tab's newer measurement decision.
* The notice dismissal and the vendor record are single decisions. A stored one
  at least as new as the one in memory replaces it; an older one is ignored.
* When two tabs record decisions in the same millisecond, the one stored first
  wins in both tabs.
* Tabs keep one subject. A stored subject is considered only when the record
  that carries it changed, never on focus alone. It replaces a subject the tab
  generated on its first save or copied from storage, so a tab that opened
  before another tab stored a subject joins it. A subject id the server
  resolved (at init, from a prefetch or in a save response) is replaced only by
  a strictly newer stored choice, and an identity set with `identify()` is
  never replaced.
* Under an IAB policy, the TC string follows the reconciled choice. See
  [How the TC string is reconciled](#how-the-tc-string-is-reconciled).
* A record removed from readable storage since this tab last saw it present is
  cleared, and the active policy decides again. A record this tab never saw in
  storage, such as a receipt merged from the server after `identify()` or a
  choice seeded while storage was blocked, stays.
* Blocked storage, or bytes that do not decode, change nothing. A failed read
  never grants a category.

Expiry is not decided here. The applied records are evaluated at the time of the
read, the same way as at startup.

### How the TC string is reconciled

Under an IAB policy, a tab adopts the TC string another tab stored, unless that
TC string conflicts with the reconciled choice. A conflicting TC string is
withdrawn, and `__tcfapi` reports no consent until the next save. Vendors never
receive a stale TC string: c15t withdraws it, or holds it back, before
`__tcfapi` publishes.

1. The `@c15t/iab` module loads the TC string the other tab stored, with its
   purpose, vendor and special-feature selections, so `__tcfapi` and the
   preference controls show the choice now in force. Selections the visitor
   changed in this tab without saving are kept.
2. A missing or older stored TC string leaves the current one in place, unless
   the current one conflicts with the reconciled choice. Then it is withdrawn.
3. A category denied after the TC string was saved conflicts if the TC string
   grants any of its purposes. A partial selection saved through IAB, which
   records its category as denied because not every purpose is granted, keeps
   its TC string.
4. A TC string confirmed before the choice's newest decision no longer
   describes it and is withdrawn, unless a newer receipt replaces it. That
   receipt is adopted even when its TC string is identical, because TC strings
   round their time to the day and custom-vendor selections live only in the
   receipt. The receipt's expiry then applies.
5. The TC string and its receipt (`euconsent-v2`, `c15t-iab-authority-v1`)
   belong to one origin. After a save on a sibling subdomain that shares the
   consent cookie, this subdomain reports no consent through `__tcfapi` until
   it saves again.
6. A tab reloads the TC string when another tab on the same origin stores a
   new one. This covers a save in the same millisecond, or one that changed
   only vendors.
7. When two tabs save in the same millisecond with different selections, the
   more restrictive TC string wins in both, so a revoked vendor is never
   advertised again. If each grants something the other denies, neither is
   published until the next save, and the stored receipt is removed so a page
   opened later does not restore it.
8. When another tab removes the receipt or clears localStorage, this tab
   withdraws its TC string too, because a page opened now would find none. A
   receipt this tab was still decoding is not installed.
9. The removal after a tie checks that the stored receipt is the one it read.
   localStorage has no conditional removal, so a receipt another tab stored a
   moment earlier can still be removed. Every tab then withdraws its TC string
   until the next save, so the race only ever withholds consent.

### Clearing records across tabs

`clearRecords()` also drops every save queued for replay, with or without
browser persistence, so nothing the visitor decided before the clear reaches
the backend afterwards.

`clearRecords()` removes every record and then stores the time of the clear,
the clear epoch, under its own key: `c15t-epoch` in localStorage and a cookie
of the same name (`<storageKey>-epoch` with a custom `storageKey`). Clearing
never removes it. Every consent record written afterwards also records the
epoch it was written under.

A decision confirmed before the epoch was made before the clear, so it is void
wherever it turns up. A decision stamped in the very millisecond of the clear
counts only if it comes from a tab that had already seen that clear, so a tab's
own choice right after its own clear stands while another tab's decision in the
same millisecond does not. A stored record left with no decisions after the
clear is void too, subject included.

* A tab that reconciles only after another tab cleared and saved again drops
  its pre-clear decisions instead of merging them back. Its subject from before
  the clear is dropped too.
* A tab that missed the clear writes only decisions it made after it. Its queued
  write of an earlier decision is discarded, so it cannot bring back a cleared
  record.
* Browser hydration and server reads (`readStoredRecordsFromCookieHeader`, used
  by the Next.js, TanStack Start, Nuxt, SvelteKit and Astro helpers) apply the
  same rule, so a server render agrees with the browser.

Records from before any clear, including v2 and legacy records, read as epoch 0
and are unaffected. A corrupt epoch, or one that cannot be read, also reads as
0: it voids nothing, so a failed read never grants a category. A consent record
whose own epoch field is corrupt is kept, and only its epoch is ignored.

Each clear moves the epoch forward, even when the device clock went back, so a
later clear never lets earlier decisions back in. Two clears in the same
millisecond therefore leave the epoch a millisecond ahead, and a decision saved
in that millisecond is void. An epoch up to one hour ahead
of the clock is kept, as it is when the clock was set back after a clear. Until
the clock catches up, decisions saved in that window are void too. An epoch more
than an hour ahead is treated as corrupt and reads as 0, so a clear never writes
one: after the clock went back more than an hour, the new epoch is capped at an
hour ahead of the clock.

That cap is a known limit. A cleared record carries times from before the clock
went back, and a runtime that missed the clear can write those times back. The
capped epoch is lower than them, so once the clock has recovered, such a
decision counts again. Leaving the epoch uncapped does not help: every tab
whose clock is still behind reads it as corrupt, which voids nothing. Times
alone cannot order a clear against decisions stamped by a clock that went back
more than an hour.

This changes the stored format. After a clear, the consent cookie carries
`&e=<time>` (16 bytes) and the localStorage record an `epoch` field (22 bytes),
and the epoch cookie itself holds a 13-digit time. Visitors who never cleared
their records store exactly what they did before. An older c15t build rejects
both the cookie and the localStorage record once they carry the epoch, so a page
still running one treats the visitor as undecided. Under an opt-out policy that
page grants optional categories by default until a new choice is saved, and the
configured prompt may appear again. Deploy the new build to every page of the
site before visitors can clear their records.

### When the cookie and localStorage disagree

When both copies hold a decision for a category from the same millisecond and
the two conflict, the denial wins.

The subject and IAB metadata come from the cookie. A server response, such as
server-side consent restoration, and a sibling subdomain sharing the cookie
with `crossSubdomain` can both rewrite it without touching this origin's
localStorage, so the local copy can be the older one. The local copy's subject
is used only when this browser's last consent write reached localStorage but
not the cookie, for example because the cookie grew past the size limit, and
the cookie has not changed since. Such a write stores the cookie as it stood
under `<storageKey>-cookie-miss` in localStorage; the next write that reaches
the cookie, or a clear, removes it. When localStorage rejects a write that the
cookie takes, for example because storage is full, the older localStorage copy
is removed.

When a server render seeded the page from the consent cookie
(`skipHydration`), that seed stays authoritative. A denial that reached only
localStorage is still applied on top of it when the page mounts, since it can
only restrict, if it is newer than the seeded decision or from the same
millisecond as a seeded grant. A stored grant is not.

The notice dismissal and vendor denials are stored twice as well. A vendor
list in localStorage at least as new as the cookie's adds its denials but never
lifts one the cookie holds; a copy confirmed before the last clear is ignored, so its
denials never come back. The newer notice dismissal applies; it still only hides a
notice with the fingerprint it names. The consent record follows the rules
below.

The consent record is stored twice: as a cookie, which a server render reads,
and in localStorage. The cookie is authoritative. A well-formed cookie wins
even when it has expired, so a local copy can never bring back a grant the
cookie no longer carries.

A browser can still drop a cookie write, for example when the record grows past
the cookie size limit, while localStorage takes it. A denial in the local copy
that is newer than the cookie's decision for that category is therefore applied
on top of the cookie. A newer local grant is not, so a dropped cookie write only
ever leaves the visitor with less permission. A server render sees only the
cookie; after a dropped write that carried a denial, the browser is the stricter
of the two.

When the two copies were written under different clear epochs, each loses its
decisions from before the later epoch first, and the same rule applies to what
remains. A later epoch in the local copy never lets its grant replace a cookie
denial. The subject and IAB metadata come from the copy written under the later
epoch; a record written before the clear in force keeps its later decisions but
no subject.

A server render cannot know about a clear that never reached a cookie. If the
page could write localStorage but its cookie writes failed during
`clearRecords()` (cookies blocked for the page, or a cookie setter that
throws), the removal of the consent cookie failed too, and so did the epoch
cookie. The browser then applies the clear from localStorage, while a server
render still reads the old consent cookie until the next successful cookie
write. The same applies to a consent cookie set with a different `domain` than
the current `storageConfig` uses, which the clear cannot remove.

### Ordering with pending writes

A tab writes its own choices in a later task, not during the click. Before it
reads storage, it lands its own queued writes, so a reconciliation never undoes
the visitor's latest action in that tab. A queued write follows the same rules
as a read: it stores the per-category merge of its choice and the stored one,
and never replaces a newer notice or vendor record. It keeps the stored subject
unless this tab identified a different user.
When a slow save response returns a server subject id, the tab adds it only to
the record it wrote; it does not recreate records another tab cleared or
overwrite another tab's newer choice.

Two tabs that write at the same moment can both read storage before either
writes, and the later write can then drop the other tab's category decision.
The tab whose decision was dropped still holds it, and on its next
reconciliation it writes it back, merged with what storage holds. It does so
only for decisions it actually stored itself, never for one a clear voided or
another tab replaced with a newer one.

If another tab's change reaches this tab while one of its saves is pending, the
save depends on how far it got. A save not yet sent is dropped. A request
already sent still reaches the backend, which may record it; this tab ignores
the response, so it queues no retry and applies no subject id from it. A save
already queued for retry keeps its original decision time.

### Reconcile yourself or turn it off

Browsers send no event for a change made in the same document, or for a cookie
rewritten without a localStorage change, such as a `Set-Cookie` response header
or another subdomain sharing the cookie. The next focus or visibility change
picks it up. To apply it at once, call the method yourself:

```ts
// Runtime owners: returns true when any record changed.
runtime.reconcileStorage();

// Kernel owners with createPersistence from c15t/modules/persistence:
persistence.reconcile();
```

To keep storage but stop automatic reconciliation, pass `sync: false` in the
persistence options, for example `createConsentRuntime({ persistence: { sync: false } })` or `createPersistence({ kernel, sync: false })`. The manual methods
still work.

`dispose()` removes the listeners and cancels a scheduled reconciliation.

# Customize the interface
URL: https://c15t.com/docs/customization/overview
Change c15t's consent banner and dialog one step at a time, from a prop to your own markup, and find where each step lives in your framework.

## Climb the ladder one step at a time

Each step keeps everything the step below it gives you. Stop at the first one
that makes the change you need:

1. **Props and presentation.** Pick a shape, a position, button order or
   blocking. c15t keeps its markup, styles and behavior.
2. **Theme tokens.** Change colors, type, radius, spacing, shadows and motion
   everywhere at once. Dark mode is a second set of tokens.
3. **Parts and classes.** Add a class or inline style to one part of one
   component, such as the banner card. Tailwind, CSS Modules and CSS-in-JS
   classes go here.
4. **Compose.** Rebuild a component from c15t's parts, in your own layout, while
   c15t still renders the actions the policy requires.
5. **Headless.** Render your own markup from c15t's state and actions. You own
   the layout, focus handling and labels.

Most brand work needs tokens and a few part classes. See
[banner designs](/docs/customization/recipes) for five banners built at
different steps, with screenshots and tested code.

## Where each step lives in your framework

|Framework|Props and presentation|Tokens|Parts and classes|Compose|Headless|
|--|--|--|--|--|--|
|Next.js|`ConsentBanner` props, `options.presentation`|`ConsentTheme` in a Server Component|`options.components`, `className`|[Compose](/docs/frameworks/next/compose)|[Headless](/docs/frameworks/next/headless)|
|TanStack Start|`ConsentBanner` props, `options.presentation`|`ConsentTheme` in the root route|`options.components`, `className`|[Compose](/docs/frameworks/tanstack-start/compose)|[Headless](/docs/frameworks/tanstack-start/headless)|
|React|`ConsentBanner` props, `presentation`|`ConsentTheme`, or CSS variables|`components`, `className`|[Compose](/docs/frameworks/react/compose)|[Headless](/docs/frameworks/react/headless)|
|Nuxt|`presentation` in `nuxt.config.ts`|`tokens` or `theme` in the module options|`components`, `class`|None|[Headless](/docs/frameworks/nuxt/headless)|
|Vue|`presentation` in the `c15tVue` options|`tokens` or `theme` in the plugin options|`components`, `class`|None|[Headless](/docs/frameworks/vue/headless)|
|Astro|`presentation` in the integration options|`theme` in the integration options|`theme.slots`, `class` on `ConsentBanner`|None|None|
|Svelte|`ConsentBanner` props, `presentation`|CSS variables, or `generateThemeCSS()`|`theme.slots`, `class` on `ConsentBanner`|[Primitives](/docs/frameworks/svelte/components/primitives)|[Headless](/docs/frameworks/svelte/headless)|
|SvelteKit|`ConsentBanner` props, `presentation`|`generateThemeCSS()` in a server load|`theme.slots`, `class` on `ConsentBanner`|[Primitives](/docs/frameworks/sveltekit/components/primitives)|[Headless](/docs/frameworks/sveltekit/headless)|
|HTML|`presentation.prompt` in `config`|`ui.theme`|`ui.theme.slots`, `::part()`, `ui.css`|None|[Headless](/docs/frameworks/html/headless)|
|JavaScript|`presentation.prompt` in `init()`|`ui.theme`|`ui.theme.slots`, `::part()`, `ui.css`|None|[Headless](/docs/frameworks/javascript/headless)|

Configuration shapes differ between frameworks. React's
`components.banner.card`, Vue's `components.banner.card` with `class`, and the
`consentBannerCard` key in `theme.slots` target the same part through
different APIs. Check your framework's customize page before you move a
configuration from one framework to another.

## Keep behavior and appearance separate

Presentation controls the prompt's shape, position and blocking. The policy
controls which actions and rights the visitor gets. Changing colors or button
order does not change a saved choice or the policy's scope.

A choice wall always blocks. A notice never blocks and does not become a wall
because you asked for `variant: 'wall'`. The preference dialog stays centered,
whatever position the banner has. If a custom layout leaves out an action the
policy requires, c15t puts it back.

## Read the rest of this section

* [Banner designs](/docs/customization/recipes): five designs with tested code.
* [Theme tokens](/docs/customization/tokens): every `--c15t-*` variable and
  its theme key.
* [Dark mode](/docs/customization/dark-mode): `colorScheme`, dark tokens and a
  dark first paint.
* [Motion and animation](/docs/customization/motion): duration and easing
  tokens, `disableAnimation` and reduced motion.
* [Stylesheets and CSS layers](/docs/customization/stylesheets): how c15t
  loads its rules, when to import `styles.css` yourself, when the dialog's CSS
  loads, and how to run without c15t's styles.
* [Component parts](/docs/customization/slots): every part, its keys in each
  framework, and the `data-*` attributes to select on.
* [Class names and CSS-in-JS](/docs/customization/class-names): CSS Modules,
  vanilla-extract, StyleX and Emotion on c15t's parts.
* [Tailwind CSS](/docs/customization/tailwind): Tailwind 4 and 3 in every
  framework.
* [Copy and translations](/docs/customization/translations): labels,
  languages and right-to-left text.

# Banner designs
URL: https://c15t.com/docs/customization/recipes
Five consent banner designs built with c15t, from one prop to your own markup, with tested code for React, Vue, Svelte, Astro and plain HTML.

## Pick a design

Each design below is a real c15t banner. The screenshots and the code come from
the same Storybook stories, which CI runs to check that each design renders and
that Accept and Reject record a choice.

|Design|Customization level|Frameworks|
|--|--|--|
|[Bottom bar](#bottom-bar)|Props|React, Vue, Astro, Svelte|
|[Branded card](#branded-card)|Theme tokens|React|
|[Choice wall](#choice-wall)|Props|React|
|[Slim bar](#slim-bar)|Compound parts or slots|React, Vue, Svelte|
|[Headless bar](#headless-bar)|Headless|React, Vue, Svelte, HTML|

Next.js and TanStack Start apps use the React code, with the same components
imported from `c15t/next` or `c15t/tanstack-start`. Nuxt uses the Vue code and
SvelteKit uses the Svelte code. [Customization](/docs/customization/overview)
explains when to use each level.

Every design keeps the policy in charge. The policy decides which buttons a
visitor gets, and none of these designs records consent until the visitor
clicks a button.

## Bottom bar

![A white bar across the bottom of a coffee shop page, with the heading "We value your privacy", one line of copy, and Reject All, Accept All and Customize buttons on the right](../assets/v3/bottom-bar.png)

The stock banner becomes a full-width bar along the bottom edge with one prop,
`variant="bar"`. The title and copy sit on the left and the buttons on the
right.

**React**

Render `CookieBanner` in place of `ConsentBanner`, inside your
`ConsentProvider` and next to `ConsentDialog`.

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

/** The stock banner, drawn as a full-width bar along the bottom edge. */
export const CookieBanner = () => (
	<ConsentBanner variant="bar" position="bottom" />
);
```

**Vue**

Render `CookieBanner` and `ConsentManager` from
`c15t/vue/runtime/components/consent-manager.vue` in place of
`ConsentRoot`. To keep `ConsentRoot`, set `presentation.prompt` in the
`c15tVue` options instead, as in [customize](/docs/frameworks/vue/customize).

```vue title="src/CookieBanner.vue"
<script setup lang="ts">
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
</script>

<template>
	<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
	<ConsentBanner variant="bar" position="bottom" />
</template>
```

**Astro**

Add `presentation` to the `c15t()` options in `astro.config.mjs`. The
server renders the banner as a bar.

```ts title="astro.config.mjs (partial)"
presentation: {
	prompt: { position: 'bottom', variant: 'bar' },
},
```

**Svelte**

Render `CookieBanner` in place of `ConsentBanner`, inside
`ConsentProvider` and next to `ConsentDialog`.

```svelte title="src/lib/cookie-banner.svelte"
<script lang="ts">
	import { ConsentBanner } from '@c15t/svelte';
</script>

<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
<ConsentBanner variant="bar" position="bottom" />
```

The HTML script tag takes the same shape through `presentation.prompt`. See
[customize the script tag](/docs/frameworks/html/customize#change-the-banners-shape-and-position).

## Branded card

![A floating card in the bottom-left corner with a warm off-white surface, serif type, small corners, and green Reject All and Accept All buttons next to an outlined Customize button](../assets/v3/brand-card.png)

Theme tokens change the colors, type and radius of the stock card without
touching its markup. This theme sets a green primary color, an off-white
surface, a serif font and four-pixel corners, and fills the actions the policy
marks as primary. Here the policy marks both Reject All and Accept All as
primary, so neither choice stands out.

```ts title="src/consent-theme.ts"
import { defineTheme } from 'c15t/react';

export const brandTheme = defineTheme({
	colors: {
		border: '#e4dccf',
		primary: '#2f6f4e',
		primaryHover: '#24563c',
		surface: '#fbf8f3',
		textOnPrimary: '#ffffff',
	},
	consentActions: { primary: { mode: 'filled', variant: 'primary' } },
	radius: { lg: '4px', md: '4px' },
	typography: { fontFamily: 'Georgia, "Times New Roman", serif' },
});
```

```tsx title="src/consent-ui.tsx"
import { ConsentBanner, ConsentDialog, ConsentTheme } from 'c15t/react';

import { brandTheme } from './consent-theme';

/**
 * Render inside your ConsentProvider, and pass `theme: brandTheme` in the
 * provider options so the action styles apply too.
 */
export const ConsentUI = () => (
	<>
		<ConsentTheme theme={brandTheme} />
		<ConsentBanner />
		<ConsentDialog />
	</>
);
```

`ConsentTheme` renders the tokens as a `<style>` element. In a server-rendered
app, render it from a Server Component or the root layout so the tokens arrive
with the HTML. The provider's `theme` option reads only `consentActions` and
slot styles, so pass the same object there for the filled buttons:

```tsx
<ConsentProvider options={{ mode, theme: brandTheme }}>
```

The preferences dialog reads the same tokens:

![The Privacy Settings dialog over the dimmed coffee shop page, with the same off-white surface, serif type and green Reject All and Accept All buttons](../assets/v3/brand-preferences.png)

Vue, Svelte, Astro and the script tag set the same tokens their own way. See
customize for [Vue](/docs/frameworks/vue/customize),
[Svelte](/docs/frameworks/svelte/customize),
[Astro](/docs/frameworks/astro/customize) or
[HTML](/docs/frameworks/html/customize), and
[theme tokens](/docs/customization/tokens) for every token.

## Choice wall

![A centered consent card over a dimmed coffee shop page, with Reject All, Accept All and Customize buttons](../assets/v3/choice-wall.png)

`variant="wall"` centers the stock banner over a backdrop, locks scrolling and
traps focus until the visitor chooses. Use it only where a policy requires a
choice before the page is usable.

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

/** A centered prompt with a backdrop. The page waits for a choice. */
export const CookieBanner = () => <ConsentBanner variant="wall" />;
```

A choice wall always blocks. A notice never blocks, so a wall requested for a
notice falls back to the floating card.

## Slim bar

![A thin white bar along the bottom of the page with the heading and one line of copy on the left, and Reject All, Accept All and Customize buttons on the same row](../assets/v3/slim-bar.png)

The slim bar puts the title, the copy and the buttons on one row, so it is
shorter than the stock bar. React builds it from the
`ConsentBanner` compound parts. Vue and Svelte have no compound banner parts,
so they add classes to the stock bar's card and header through slots. All
three use the same stylesheet, and all three keep the buttons the policy
requires.

**React**

`ConsentBanner.PolicyActions` renders the policy's buttons, so a required
Reject button stays. Render `CookieBanner` inside your `ConsentProvider`,
next to `ConsentDialog`.

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

import './slim-bar.css';

/**
 * The title, copy and the policy's buttons in a single row. The compound
 * parts keep the policy's actions, so a required Reject button stays.
 */
export const CookieBanner = () => (
	<ConsentBanner.Root variant="bar">
		<ConsentBanner.Card className="slim-bar">
			<ConsentBanner.Header className="slim-bar__text">
				<ConsentBanner.Title />
				<ConsentBanner.Description />
			</ConsentBanner.Header>
			<ConsentBanner.PolicyActions />
		</ConsentBanner.Card>
	</ConsentBanner.Root>
);
```

**Vue**

Spread `slimBar` into the options you pass to `app.use(c15tVue, ...)`.
`ConsentRoot` then renders the slim bar.

```ts title="src/consent-options.ts"
import type { C15tVuePluginOptions } from 'c15t/vue/vue-plugin';

import './slim-bar.css';

/**
 * Spread into the options you pass to `app.use(c15tVue, ...)`. The bar keeps
 * the stock markup and actions; the slot classes put it on one row.
 */
export const slimBar = {
	components: {
		banner: {
			card: { class: 'slim-bar' },
			header: { class: 'slim-bar__text' },
		},
	},
	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
} satisfies C15tVuePluginOptions;
```

**Svelte**

Spread `slimBar` into the props you pass to `ConsentProvider`.
Svelte scopes component styles, so the classes live in a global
stylesheet.

```ts title="src/lib/consent-options.ts"
import type { ConsentManagerOptions } from '@c15t/svelte';

import './slim-bar.css';

/**
 * Spread into the options you pass to `ConsentProvider`. The bar
 * keeps the stock markup and actions; the slot classes put it on one row.
 */
export const slimBar = {
	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
	theme: {
		slots: {
			consentBannerCard: 'slim-bar',
			consentBannerHeader: 'slim-bar__text',
		},
	},
} satisfies Partial<ConsentManagerOptions>;
```

```css title="src/slim-bar.css"
.slim-bar {
	box-sizing: border-box;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.5rem 1.5rem;
	padding: 0.5rem 1.5rem;
}

/* Title and description share one line. */
.slim-bar__text {
	display: flex;
	flex: 1 1 20rem;
	flex-direction: row;
	flex-wrap: wrap;
	align-items: baseline;
	gap: 0 0.5rem;
	padding: 0;
}

/* The actions share the text's row, so drop the footer's own box. */
.slim-bar > [data-testid='consent-banner-footer'] {
	padding: 0;
	border: 0;
	background: none;
}
```

## Headless bar

![A dark navy bar across the bottom of the page with one line of white copy, an underlined Preferences link, and white pill-shaped Reject all and Accept all buttons](../assets/v3/headless-bar.png)

The headless bar is your own markup and CSS, driven by c15t's headless API. It
shows the same design in every framework. The policy still decides which
buttons appear and in what order, the Preferences button is always there, and
a choice is recorded only when the visitor clicks.

**React**

`useHeadlessConsentUI()` from `c15t/react/headless` returns the banner
state and `performAction`. Render `CookieBar` in place of
`ConsentBanner`, and keep `ConsentDialog`, which Preferences opens.

```tsx title="src/cookie-bar.tsx"
import { useHeadlessConsentUI } from 'c15t/react/headless';
import type { HeadlessConsentBannerAction } from 'c15t/react/headless';

import './cookie-bar.css';

const labels: Record<HeadlessConsentBannerAction, string> = {
	accept: 'Accept all',
	customize: 'Preferences',
	dismiss: 'Got it',
	reject: 'Reject all',
	save: 'Save',
};

export const CookieBar = () => {
	const { banner, openDialog, performAction } = useHeadlessConsentUI();

	if (!banner.isVisible) {
		return null;
	}

	// The policy decides which actions this visitor gets, and in what order.
	// Preferences has its own button, so it is always there.
	const actions = banner.orderedActions.filter(
		(action) => action !== 'customize'
	);

	return (
		<section className="cookie-bar" aria-label="Cookie consent">
			<p className="cookie-bar__text">
				We use cookies to measure traffic and improve this site. Choose which
				ones can run.
			</p>
			<div className="cookie-bar__actions">
				<button type="button" className="cookie-bar__link" onClick={openDialog}>
					Preferences
				</button>
				{actions.map((action) => (
					<button
						key={action}
						type="button"
						className="cookie-bar__button"
						onClick={() => performAction(action)}
					>
						{labels[action]}
					</button>
				))}
			</div>
		</section>
	);
};
```

**Vue**

The composables from `c15t/vue/vue-plugin` give the policy's actions and
the active surface. Render `CookieBar` and `ConsentManager` in place of
`ConsentRoot`. Preferences sets `activeUI` to `'manager'`, which opens
`ConsentManager`.

```vue title="src/CookieBar.vue"
<script setup lang="ts">
import {
	useConsentActiveUI,
	useConsentPolicyActions,
	useConsentSave,
	useDismissNotice,
	usePromptRequirement,
} from 'c15t/vue/vue-plugin';
import { computed } from 'vue';

import './cookie-bar.css';

const labels: Record<string, string> = {
	accept: 'Accept all',
	dismiss: 'Got it',
	reject: 'Reject all',
};

const activeUI = useConsentActiveUI();
const prompt = usePromptRequirement();
const { actionGroups } = useConsentPolicyActions('prompt');
const saveConsent = useConsentSave();
const dismissNotice = useDismissNotice();

const isVisible = computed(
	() => activeUI.value === 'banner' && prompt.value.kind !== 'none'
);

// The policy decides which actions this visitor gets, and in what order.
// Preferences has its own button, so it is always there.
const actions = computed(() =>
	actionGroups.value.flat().filter((action) => action in labels)
);

const run = (action: string) => {
	if (action === 'accept') {
		void saveConsent('all');
	} else if (action === 'reject') {
		void saveConsent('none');
	} else if (action === 'dismiss') {
		void dismissNotice();
	}
};
</script>

<template>
	<section v-if="isVisible" class="cookie-bar" aria-label="Cookie consent">
		<p class="cookie-bar__text">
			We use cookies to measure traffic and improve this site. Choose which ones
			can run.
		</p>
		<div class="cookie-bar__actions">
			<button
				type="button"
				class="cookie-bar__link"
				@click="activeUI = 'manager'"
			>
				Preferences
			</button>
			<button
				v-for="action in actions"
				:key="action"
				type="button"
				class="cookie-bar__button"
				@click="run(action)"
			>
				{{ labels[action] }}
			</button>
		</div>
	</section>
</template>
```

**Svelte**

`getHeadlessConsent()` returns the banner state and `performAction`.
Render `CookieBar` in place of `ConsentBanner`, inside
`ConsentProvider`, and keep `ConsentDialog`, which Preferences
opens.

```svelte title="src/lib/cookie-bar.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	import './cookie-bar.css';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Preferences',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};

	// The policy decides which actions this visitor gets, and in what order.
	// Preferences has its own button, so it is always there.
	const actions = $derived(
		consent.banner.orderedActions.filter((action) => action !== 'customize')
	);
</script>

{#if consent.banner.isVisible}
	<section class="cookie-bar" aria-label="Cookie consent">
		<p class="cookie-bar__text">
			We use cookies to measure traffic and improve this site. Choose which ones
			can run.
		</p>
		<div class="cookie-bar__actions">
			<button
				type="button"
				class="cookie-bar__link"
				onclick={() => consent.openDialog()}
			>
				Preferences
			</button>
			{#each actions as action (action)}
				<button
					type="button"
					class="cookie-bar__button"
					onclick={() => consent.performAction(action)}
				>
					{labels[action]}
				</button>
			{/each}
		</div>
	</section>
{/if}
```

**HTML**

The headless build, `c15t.headless.js`, keeps script gating and
`window.c15t` and ships no banner, dialog or CSS. Buttons with
`data-c15t-action` need no code. Because there is no stock dialog,
Preferences opens category switches inside the bar and a Save button
records them. Replace `https://your-project.inth.app` with the backend URL
from your Inth project, and put the block before `</body>`.

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.headless.js"
	defer
></script>

<style>
	.cookie-bar {
		position: fixed;
		inset: auto 0 0;
		z-index: 50;
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		gap: 0.75rem 1.5rem;
		padding: 0.875rem 1.5rem;
		background: #14213d;
		color: #f8f9fb;
		font:
			0.9375rem/1.5 system-ui,
			sans-serif;
		box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
	}

	.cookie-bar__text {
		flex: 1 1 20rem;
		margin: 0;
	}

	.cookie-bar__actions {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem;
	}

	.cookie-bar button {
		padding: 0.5rem 1rem;
		border: 1px solid #f8f9fb;
		border-radius: 999px;
		background: transparent;
		color: inherit;
		font: inherit;
		cursor: pointer;
	}

	.cookie-bar .cookie-bar__button {
		background: #f8f9fb;
		color: #14213d;
		font-weight: 600;
	}

	.cookie-bar .cookie-bar__link {
		border-color: transparent;
		text-decoration: underline;
		text-underline-offset: 3px;
	}

	.cookie-bar button:focus-visible {
		outline: 2px solid #fca311;
		outline-offset: 2px;
	}
	/* On narrow screens, Reject and Accept share a row at equal width. */
	@media (max-width: 30rem) {
		.cookie-bar__actions {
			width: 100%;
		}

		.cookie-bar__actions button {
			flex: 1 1 40%;
		}

		.cookie-bar__actions .cookie-bar__link {
			flex-basis: 100%;
		}
	}

	/* The headless build has no dialog, so preferences open inside the bar. */
	.cookie-bar[hidden],
	.cookie-bar__prefs[hidden] {
		display: none;
	}

	.cookie-bar__prefs {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem 1.25rem;
		flex-basis: 100%;
		margin: 0;
		padding: 0;
		border: 0;
	}

	.cookie-bar__prefs label {
		display: flex;
		align-items: center;
		gap: 0.375rem;
	}
</style>

<section
	id="cookie-bar"
	class="cookie-bar"
	aria-label="Cookie consent"
	hidden
>
	<p class="cookie-bar__text">
		We use cookies to measure traffic and improve this site. Choose which
		ones can run.
	</p>
	<fieldset
		class="cookie-bar__prefs"
		hidden
	>
		<legend class="cookie-bar__text">Allow these cookies:</legend>
		<label
			><input
				type="checkbox"
				name="functionality"
			/>
			Functionality</label
		>
		<label
			><input
				type="checkbox"
				name="measurement"
			/>
			Measurement</label
		>
		<label
			><input
				type="checkbox"
				name="experience"
			/>
			Experience</label
		>
		<label
			><input
				type="checkbox"
				name="marketing"
			/>
			Marketing</label
		>
	</fieldset>
	<div class="cookie-bar__actions">
		<!-- c15t wires data-c15t-action buttons itself; they need no code. -->
		<button
			type="button"
			class="cookie-bar__link"
			data-c15t-action="customize"
		>
			Preferences
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="dismiss"
			data-notice-only
			hidden
		>
			Got it
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="reject"
			data-choice-only
		>
			Reject all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="accept"
			data-choice-only
		>
			Accept all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-save
			hidden
		>
			Save
		</button>
	</div>
</section>

<script>
	const bar = document.getElementById('cookie-bar');
	const prefs = bar.querySelector('.cookie-bar__prefs');
	const saveButton = bar.querySelector('[data-save]');
	const switches = prefs.querySelectorAll('input');
	const choiceButtons = bar.querySelectorAll('[data-choice-only]');
	const noticeButtons = bar.querySelectorAll('[data-notice-only]');

	// The tag is deferred, so queue calls until window.c15t is the real API.
	window.c15t = window.c15t || [];
	const queue = (call) => {
		if (Array.isArray(window.c15t)) {
			window.c15t.push(call);
		} else {
			window.c15t[call[0]](...call.slice(1));
		}
	};

	// c15t says which surface is due; the page decides what it looks like.
	// 'banner' shows the bar, 'dialog' opens the switches, 'none' hides it.
	queue([
		'on',
		'ui',
		(surface) => {
			const { kind } = c15t.getSnapshot().promptRequirement;
			const editing = surface === 'dialog';
			// A notice gets one acknowledgement button instead of Accept and Reject.
			for (const button of choiceButtons) {
				button.hidden = kind === 'notice' && !editing;
			}
			for (const button of noticeButtons) {
				button.hidden = kind !== 'notice' || editing;
			}
			for (const input of switches) {
				input.checked = c15t.has(input.name);
			}
			prefs.hidden = !editing;
			saveButton.hidden = !editing;
			bar.hidden =
				surface === 'none' || (surface === 'banner' && kind === 'none');
		},
	]);

	// Save records exactly what the switches show.
	saveButton.addEventListener('click', () => {
		const choice = {};
		for (const input of switches) {
			choice[input.name] = input.checked;
		}
		c15t.save(choice);
	});
</script>
```

React, Vue and Svelte import the same stylesheet, `cookie-bar.css`. The HTML
block contains it inline.

```css title="src/cookie-bar.css"
.cookie-bar {
	position: fixed;
	inset: auto 0 0;
	z-index: 50;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.75rem 1.5rem;
	padding: 0.875rem 1.5rem;
	background: #14213d;
	color: #f8f9fb;
	font:
		0.9375rem/1.5 system-ui,
		sans-serif;
	box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
}

.cookie-bar__text {
	flex: 1 1 20rem;
	margin: 0;
}

.cookie-bar__actions {
	display: flex;
	flex-wrap: wrap;
	gap: 0.5rem;
}

.cookie-bar button {
	padding: 0.5rem 1rem;
	border: 1px solid #f8f9fb;
	border-radius: 999px;
	background: transparent;
	color: inherit;
	font: inherit;
	cursor: pointer;
}

.cookie-bar .cookie-bar__button {
	background: #f8f9fb;
	color: #14213d;
	font-weight: 600;
}

.cookie-bar .cookie-bar__link {
	border-color: transparent;
	text-decoration: underline;
	text-underline-offset: 3px;
}

.cookie-bar button:focus-visible {
	outline: 2px solid #fca311;
	outline-offset: 2px;
}
/* On narrow screens, Reject and Accept share a row at equal width. */
@media (max-width: 30rem) {
	.cookie-bar__actions {
		width: 100%;
	}

	.cookie-bar__actions button {
		flex: 1 1 40%;
	}

	.cookie-bar__actions .cookie-bar__link {
		flex-basis: 100%;
	}
}
```

On a 375-pixel screen the copy takes the full width, Preferences sits on its
own line, and Reject all and Accept all share a row at equal width:

![The dark headless bar on a narrow phone screen, with the copy on two lines, a centered Preferences link, and Reject all and Accept all buttons side by side](../assets/v3/headless-bar-mobile.png)

In the HTML version, Preferences opens the switches inside the bar:

![The dark bar grown taller, with checkboxes for Functionality, Measurement, Experience and Marketing above Preferences, Reject all, Accept all and Save buttons](../assets/v3/headless-bar-html.png)

A headless UI owns its focus handling and labels. Test it with a keyboard and
a screen reader. The headless pages for [React](/docs/frameworks/react/headless),
[Vue](/docs/frameworks/vue/headless) and [Svelte](/docs/frameworks/svelte/headless)
cover notices and custom preference forms.

## Check a design

Run these checks after you adopt a design:

1. Clear site data and reload. The banner appears and no optional vendor
   request appears in DevTools Network.
2. Click Reject all, reload, and confirm the banner stays closed and the
   vendors stay blocked.
3. Open preferences from your footer link, allow one category, save, and
   confirm only that category's vendors load.
4. Test a 375-pixel viewport with your longest translation, and tab through
   every button.

[Verify consent](/docs/guides/verify-consent) has the full list.

## Run the designs

The source repository renders each design in its Storybook under
`Docs / Banner designs`: `apps/storybook-react`, `apps/storybook-vue`,
`apps/storybook-svelte` and `apps/storybook-astro`. Each story uses an
in-memory policy and loads no analytics. The HTML headless bar runs at
`/consent-example/headless` in `internals/fixtures/script-tag`, which the example
acceptance tests cover.

# Theme tokens
URL: https://c15t.com/docs/customization/tokens
Change c15t's colors, type, radius, spacing, shadows and motion with theme tokens, and see every --c15t-* variable with its default.

## Where tokens come from

c15t's components take their colors from `--c15t-*` CSS variables, and most
of their fonts, radii, spacing, shadows and motion too. c15t's rules set the
defaults. You change them with a theme object or with CSS, and every part
that reads a token changes with it. Some values are still fixed for one
component, such as button padding, the radius of the "Secured by" tag and
several font sizes and weights, so a token change does not move them. Restyle
those parts through [slots](/docs/customization/slots) or your own CSS.
[Stylesheets and CSS layers](/docs/customization/stylesheets)
covers how c15t loads its rules, and [dark mode](/docs/customization/dark-mode)
covers the dark set of tokens.

## Set semantic values together

This React theme changes the brand color and large corner radius. Include
hover and foreground colors when overriding raw variables so the button remains
readable in each state.

```ts
import { defineTheme } from '@c15t/ui/theme';

export const theme = defineTheme({
	colors: { primary: '#2f6f4e' },
	radius: { lg: '4px' },
	consentActions: {
		primary: { variant: 'primary', mode: 'filled' },
		dismiss: { variant: 'neutral', mode: 'stroke' },
	},
});
```

Install `@c15t/ui` if importing its theme helper directly. Where the theme
goes depends on the framework:

|Framework|Tokens|`consentActions`|
|--|--|--|
|Next.js, TanStack Start, React|`<ConsentTheme theme={theme} />`, rendered on the server where the app has one|`theme` in the provider options|
|Nuxt, Vue|`theme` or `tokens` in the module or plugin options|Not available|
|Astro|`theme` in the integration options|The same `theme`|
|Svelte, SvelteKit|`generateThemeCSS(theme)` from `@c15t/ui/theme` on the server, in a `<style>` element, or `--c15t-*` variables in your stylesheet|`theme` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)|
|HTML, JavaScript|`ui.theme`|Not available|

React and Svelte providers do not turn tokens in their `theme` option into
CSS, and warn in development when a theme holds tokens but the page has no
`<style id="c15t-theme">`. Your framework's customize page shows the full
setup.

`consentActions` selects styling by action role. A per-action entry overrides
`primary`, which overrides `default`.

## Combine a generated theme with your own CSS

`generateThemeCSS` writes its variables on `:root:root` and
`.c15t-theme-root.c15t-theme-root`, more specific than c15t's defaults. The
theme therefore overrides the defaults whether its
`<style>` element comes before or after c15t's rules. The same output backs
`ConsentTheme` in React, Next.js and TanStack Start, Astro's `theme` option and
the script tag's `ui.theme`.

A `--c15t-*` variable you set on plain `:root` in your own CSS loses to a
generated theme that sets the same variable, even when your rule loads later.
Put the value in the theme, or raise your selector:

```css
:root:root {
  --c15t-primary: #2f6f4e;
}
```

Scoped rules such as `[data-prompt] { --c15t-primary: ... }` set the variable
on the banner element itself, so they still apply inside it.

## Every token

Every framework uses the same tokens. A theme object, such as `ConsentTheme`'s
`theme`, Astro's and Vue's `theme` or the script tag's `ui.theme`, takes the
theme key, such as `radius.lg`. Vue and Nuxt `tokens` take the CSS variable
name without the leading `--`, such as `c15t-radius-lg`. A stylesheet sets the
CSS variable itself. Your framework's customize page shows where each one goes.
[Motion and animation](/docs/customization/motion) explains the duration and
easing tokens.

|CSS variable|Theme key|Default|
|--|--|--|
|`--c15t-primary`|`colors.primary`|`hsl(228, 100%, 60%)`|
|`--c15t-primary-hover`|`colors.primaryHover`|`hsl(228, 100%, 55%)`|
|`--c15t-surface`|`colors.surface`|`hsl(0, 0%, 100%)`|
|`--c15t-surface-hover`|`colors.surfaceHover`|`hsl(0, 0%, 98%)`|
|`--c15t-border`|`colors.border`|`hsl(0, 0%, 90%)`|
|`--c15t-border-hover`|`colors.borderHover`|`hsl(0, 0%, 85%)`|
|`--c15t-text`|`colors.text`|`hsl(0, 0%, 10%)`|
|`--c15t-text-muted`|`colors.textMuted`|`hsl(0, 0%, 40%)`|
|`--c15t-text-on-primary`|`colors.textOnPrimary`|auto-derived from `colors.primary` when omitted|
|`--c15t-overlay`|`colors.overlay`|`hsla(0, 0%, 0%, 0.5)`|
|`--c15t-switch-track`|`colors.switchTrack`|`hsl(0, 0%, 85%)`|
|`--c15t-switch-track-active`|`colors.switchTrackActive`|`colors.primary`|
|`--c15t-switch-thumb`|`colors.switchThumb`|`hsl(0, 0%, 100%)`|
|`--c15t-font-family`|`typography.fontFamily`|`system-ui, -apple-system, sans-serif`|
|`--c15t-font-size-sm`|`typography.fontSize.sm`|`0.875rem`|
|`--c15t-font-size-base`|`typography.fontSize.base`|`1rem`|
|`--c15t-font-size-lg`|`typography.fontSize.lg`|`1.125rem`|
|`--c15t-font-weight-normal`|`typography.fontWeight.normal`|`400`|
|`--c15t-font-weight-medium`|`typography.fontWeight.medium`|`500`|
|`--c15t-font-weight-semibold`|`typography.fontWeight.semibold`|`600`|
|`--c15t-line-height-tight`|`typography.lineHeight.tight`|`1.25`|
|`--c15t-line-height-normal`|`typography.lineHeight.normal`|`1.5`|
|`--c15t-line-height-relaxed`|`typography.lineHeight.relaxed`|`1.75`|
|`--c15t-space-xs`|`spacing.xs`|`0.25rem`|
|`--c15t-space-sm`|`spacing.sm`|`0.5rem`|
|`--c15t-space-md`|`spacing.md`|`1rem`|
|`--c15t-space-lg`|`spacing.lg`|`1.5rem`|
|`--c15t-space-xl`|`spacing.xl`|`2rem`|
|`--c15t-radius-sm`|`radius.sm`|`0.25rem`|
|`--c15t-radius-md`|`radius.md`|`0.5rem`|
|`--c15t-radius-lg`|`radius.lg`|`0.75rem`|
|`--c15t-radius-full`|`radius.full`|`9999px`|
|`--c15t-shadow-sm`|`shadows.sm`|`0 1px 2px hsla(0, 0%, 0%, 0.05)`|
|`--c15t-shadow-md`|`shadows.md`|`0 4px 12px hsla(0, 0%, 0%, 0.08)`|
|`--c15t-shadow-lg`|`shadows.lg`|`0 8px 24px hsla(0, 0%, 0%, 0.12)`|
|`--c15t-duration-fast`|`motion.duration.fast`|`80ms`|
|`--c15t-duration-normal`|`motion.duration.normal`|`150ms`|
|`--c15t-duration-slow`|`motion.duration.slow`|`200ms`|
|`--c15t-easing`|`motion.easing`|`cubic-bezier(0.4, 0, 0.2, 1)`|
|`--c15t-easing-out`|`motion.easingOut`|`cubic-bezier(0.215, 0.61, 0.355, 1)`|
|`--c15t-easing-in`|`motion.easingIn`|`cubic-bezier(0.55, 0.055, 0.675, 0.19)`|
|`--c15t-easing-in-out`|`motion.easingInOut`|`cubic-bezier(0.645, 0.045, 0.355, 1)`|
|`--c15t-easing-spring`|`motion.easingSpring`|`cubic-bezier(0.34, 1.56, 0.64, 1)`|

The radius tokens round different parts. `radius.lg` rounds the banner card,
the preference dialog, `ConsentGate` placeholders and the floating trigger.
`radius.md` rounds buttons, accordions, tabs and the vendor list.
`radius.sm` rounds small parts inside the banner and dialog. To give the banner
and its buttons the same 4px corners, set both `lg` and `md`.

## Target a prompt with CSS

```css
[data-prompt][data-model='opt-in'] {
  --c15t-primary: #2f6f4e;
  --c15t-primary-hover: #24563c;
  --c15t-text-on-primary: #fff;
}
```

Use attributes exposed by the rendered component, not guessed class names.
The script tag's banner has no `data-prompt` or `data-model`. Test the prompt
and the preferences dialog separately because tokens scoped to one prompt do
not automatically reach a portaled dialog.

|Size variable|Default|Target|
|--|--|--|
|`--consent-banner-max-width`|`440px`|Floating card|
|`--consent-banner-widget-max-width`|`20rem`|Widget|
|`--consent-banner-wall-max-width`|`30rem`|Choice wall|

The banner footer lays out its actions by the card's width, not the
viewport's. With the default `compact` profile, a card narrower than 22rem
puts Reject and Accept on one row and Customize on a full-width row below
them, on any screen size.

Test long translations and small screens after changing width or typography.
A compact banner must still fit the required actions.

## Restyle the "Secured by" tag

The tag sits on the edge of the banner and dialog cards and uses the primary
color by default. Set these variables on `:root`, or on an element that
contains the tag. The dialog renders in a portal, so a variable set on the
banner does not reach the dialog's tag.

|Variable|Default|Target|
|--|--|--|
|`--consent-branding-tag-background-color`|`var(--c15t-primary)`|Tag background|
|`--consent-branding-tag-border-color`|`--c15t-primary` mixed 14% toward black|Tag border|
|`--consent-branding-tag-text-color`|`var(--c15t-text-on-primary, #fff)`|"Secured by" and the wordmark|
|`--consent-branding-tag-mark-color`|The text color|c15t mark or inth logo|
|`--consent-branding-tag-shadow`|Inset highlight and a 1px drop shadow|Tag shadow|
|`--consent-branding-tag-attached-edge-width`|`0px`|Border on the edge that meets the card|

The stylesheet does not declare these variables. Each default resolves on the
tag, so a `--c15t-primary` you scope to a banner still colors the tag.

This makes the tag look like a tab of the card:

```css
:root {
  --consent-branding-tag-background-color: var(--c15t-surface);
  --consent-branding-tag-border-color: var(--c15t-border);
  --consent-branding-tag-text-color: var(--c15t-text-muted);
  --consent-branding-tag-mark-color: var(--c15t-primary);
  --consent-branding-tag-shadow: none;
}
```

The edge that meets the card has no border by default. Above the banner the
tag overlaps the card's top border by 1px and covers it. Below the dialog the
tag starts under the card's bottom border. Set
`--consent-branding-tag-attached-edge-width: 1px` to draw that edge. It is
drawn over the card's border, so the two borders do not stack.

# Dark mode
URL: https://c15t.com/docs/customization/dark-mode
Switch c15t's banner and dialog to dark colors with colorScheme, set your own dark tokens, follow your site's theme switch, and paint dark on the first frame in every framework.

## How c15t turns dark

c15t's stylesheet switches every `--c15t-*` color token to its dark value when
`<html>` has a `dark` or a `c15t-dark` class. The `colorScheme` option decides
whether c15t sets `c15t-dark` itself:

|`colorScheme`|What c15t does with `c15t-dark`|
|--|--|
|`'light'`|Removes it once|
|`'dark'`|Adds it once|
|`'system'`|Follows `prefers-color-scheme`, including changes while the page is open|
|Unset|Copies your `dark` class into `c15t-dark` and follows it as it changes|
|`null`|Leaves it alone. Your site sets it|

Astro also accepts `'none'`, which means the same as `null`.

`'light'` only removes `c15t-dark`. If your site puts `dark` on `<html>`, the
stylesheet still switches the tokens to dark. Pick one class convention for
your site and let c15t follow it.

## Defaults in each framework

|Framework|Where to set it|Default|
|--|--|--|
|Next.js, TanStack Start|`options.colorScheme` on `ConsentRoot`, and `colorScheme` on `ConsentTheme`|Unset: copies `dark`|
|React|`colorScheme` in the `ConsentProvider` options, and on `ConsentTheme`|Unset: copies `dark`|
|Nuxt|`colorScheme` under the `c15t` key in `nuxt.config.ts`, or in `app/app.config.ts`|Unset: copies `dark`|
|Vue|`colorScheme` in the `c15tVue` options|Unset: copies `dark`|
|Astro|`colorScheme` in the `c15t()` integration options|`'system'`|
|Svelte, SvelteKit|`colorScheme` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)|Unset: copies `dark`|
|HTML|`data-color-scheme` on the script tag: `light`, `dark`, `system` or `none`|`system`|
|JavaScript|`ui.colorScheme` in `init()`|`'system'`|

React, Vue and Svelte apps usually already have a theme switch that toggles a
`dark` class, such as next-themes. Copying that class keeps c15t in step with
the site without extra code.

Astro and the script tag default to `'system'` because neither can rely on a
site convention. Astro paints the banner from server HTML before any site
script runs, and Astro sites share no `dark` class convention, so following the
operating system is the one choice its inline script can make correctly. A plain
HTML page has no convention either. A site that has one opts in with `null`.

### Set colorScheme null in Nuxt

In Nuxt, set `colorScheme: null` under the `c15t` key in `nuxt.config.ts` or
in `app/app.config.ts`. Nuxt drops a `null` in inline module options, such as
`modules: [['@c15t/vue', { colorScheme: null }]]`, before the module reads it,
so c15t would copy your `dark` class as if `colorScheme` were unset.

## Follow your site's theme switch

In React, Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit, leave
`colorScheme` unset and toggle `dark` on `<html>`. c15t watches the class and switches with
it. Include the class in the server HTML when your site renders dark, so the
first paint matches.

In Astro, set `colorScheme: 'none'` and toggle `c15t-dark` together with your
own class. A `ClientRouter` navigation replaces the attributes of `<html>`, so
set the class again on `astro:after-swap` if your theme script does not.

With the script tag, add `data-color-scheme="none"`. With `init()`, pass
`ui: { colorScheme: null }`. The UI is then dark while `<html>` has `dark` or
`c15t-dark`, and follows the class as it changes. The UI renders in a shadow
root that the page's class cannot reach, so c15t copies the class onto the
shadow host.

If your site sets `c15t-dark` itself in React, Next.js, TanStack Start, Vue,
Nuxt, Svelte or SvelteKit, pass `colorScheme: null` so c15t leaves it alone.

## Set your own dark colors

Theme tokens take a `dark` object with the same color keys as `colors`. Every
color you set in `colors` also applies in dark mode, unless `dark` sets it too,
so give a dark value for each brand color:

```ts title="consent-theme.ts"
export const theme = {
	colors: { primary: '#2f6f4e', primaryHover: '#24563c', surface: '#fbf8f3' },
	dark: { primary: '#7fd1a8', primaryHover: '#9fdcbd', surface: '#1b1f1d' },
};
```

Where the theme goes depends on the framework:

* **React, Next.js, TanStack Start.** Pass it to `ConsentTheme`. To write the
  CSS outside a component, call `generateThemeCSS(theme, colorScheme)` from
  `c15t/react/utils`, or `@c15t/react/utils` if you installed the scoped
  package. It writes the same CSS as `ConsentTheme`.
* **Vue, Nuxt.** Pass it as `theme` in the plugin or module options. It goes
  into the `<style id="c15t-css-vars">` element with `tokens`.
* **Astro.** Pass it as `theme` in the integration options.
* **SvelteKit, Svelte.** Pass it to `generateThemeCSS(theme, colorScheme)` from
  `@c15t/ui/theme` on the server.
* **HTML, JavaScript.** Pass it as `ui.theme`.

This Nuxt example follows the system setting and uses its own dark primary
color. Every other dark token keeps c15t's default:

```ts title="nuxt.config.ts (c15t options)"
// Follow the visitor's system setting, with a dark primary of our own.
colorScheme: 'system',
theme: { dark: { primary: '#7fd1a8' } },
```

To set dark values in plain CSS instead, write them for both classes:

```css
:root.dark,
:root.c15t-dark {
  --c15t-primary: #7fd1a8;
  --c15t-surface: #1b1f1d;
}
```

A generated theme, such as the output of `ConsentTheme` or
`generateThemeCSS`, writes its dark values on `:root:root.dark` and
`:root:root.c15t-dark`. Those selectors outrank the rule above. If you use both,
put dark values in the theme, or repeat `:root` in your own selectors.

## Paint dark on the first frame

A banner that renders light and then turns dark flashes. How to avoid that
depends on where the banner first renders:

|Framework|What to do|
|--|--|
|Next.js, TanStack Start|Render `<ConsentTheme theme={theme} colorScheme="system" />` on the server, with the same value as `options.colorScheme`. `'dark'` writes dark tokens as the default and `'system'` adds a `prefers-color-scheme` media query, so the server HTML is dark before hydration. With `colorScheme` unset, put your `dark` class in the server HTML.|
|React|Render `<ConsentTheme colorScheme="system" />` next to the provider, with the same value as the provider's `colorScheme`. Its CSS makes the tokens dark from the first frame, before the provider sets the class. In a server-rendered React app, render it on the server.|
|Nuxt|For `'dark'` and `'system'`, the module adds an inline script to `<head>` that sets `c15t-dark` before the server-rendered banner paints. It carries the module's `nonce`. With `colorScheme` unset, put your `dark` class in the server HTML.|
|Vue|The plugin applies `colorScheme` and writes the tokens when you install it, before the first render.|
|Astro|`ConsentScript` in `<head>` sets the class from an inline script before the banner paints, and c15t sets it again after each `ClientRouter` navigation. Keep `ConsentScript` in your layout's `<head>`.|
|Svelte|The provider sets the class as it mounts. With `colorScheme` unset, the stylesheet reads your `dark` class directly, so the tokens are dark from the first frame.|
|SvelteKit|Pass the scheme to `generateThemeCSS(theme, 'system')` in your server load, so the CSS in `<svelte:head>` already has the media query. With `colorScheme` unset, put your `dark` class in the server HTML.|
|HTML, JavaScript|c15t applies the scheme when it mounts the UI, before any surface renders.|

[Theme tokens](/docs/customization/tokens) lists every color token, and your
framework's customize page shows where its theme goes.

## Check the result

1. Open the page in a private window with your operating system in dark mode,
   or add your `dark` class to `<html>`.
2. The banner is dark on its first frame. Reload with the Network panel
   throttled to see the first paint.
3. Open the preference dialog. It uses the same dark tokens as the banner.
4. Switch the scheme while the page is open. With `'system'` or an unset
   `colorScheme`, the banner and dialog follow without a reload.
5. Check the contrast of the primary button text in both schemes.

# Motion and animation
URL: https://c15t.com/docs/customization/motion
Change how fast c15t's banner and dialog animate with duration and easing tokens, turn animations off per surface with disableAnimation, and check reduced-motion behavior in each framework.

## Change the speed with motion tokens

c15t animates its surfaces with three durations and five easing curves. Set
them in the theme's `motion` object, or as CSS variables:

|CSS variable|Theme key|Default|Used by|
|--|--|--|--|
|`--c15t-duration-fast`|`motion.duration.fast`|`80ms`|Banner fade out, buttons, tabs|
|`--c15t-duration-normal`|`motion.duration.normal`|`150ms`|Preference dialog, late banner fade in, switches, accordions|
|`--c15t-duration-slow`|`motion.duration.slow`|`200ms`|Legal links, floating trigger|
|`--c15t-easing`|`motion.easing`|`cubic-bezier(0.4, 0, 0.2, 1)`|Switches, accordions|
|`--c15t-easing-out`|`motion.easingOut`|`cubic-bezier(0.215, 0.61, 0.355, 1)`|Preference dialog, late banner fade in, floating trigger hover|
|`--c15t-easing-in`|`motion.easingIn`|`cubic-bezier(0.55, 0.055, 0.675, 0.19)`|Banner fade out|
|`--c15t-easing-in-out`|`motion.easingInOut`|`cubic-bezier(0.645, 0.045, 0.355, 1)`|Floating trigger snapping to a corner|
|`--c15t-easing-spring`|`motion.easingSpring`|`cubic-bezier(0.34, 1.56, 0.64, 1)`|The dialog's scale in|

This theme slows the dialog down and removes its overshoot:

```ts title="consent-theme.ts"
export const theme = {
	motion: {
		duration: { fast: '120ms', normal: '220ms' },
		easingSpring: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
	},
};
```

The banner never slides in. When it shows with the page, it is part of the
first paint and appears on its first frame. When it arrives more than 100ms
after the page first painted, such as after a slow script or a client-side
init, it fades in over `--c15t-duration-normal` instead, and its root and
backdrop carry `data-entry="late"`. A banner rendered on the server always
shows at once. When it hides, Vue, Svelte and the script tag fade it out over
`--c15t-duration-fast`.

The theme goes where your framework's other tokens go. See
[theme tokens](/docs/customization/tokens) and your framework's customize page.
In Vue and Nuxt, set `tokens` with the variable name without the leading
`--`, such as `'c15t-duration-normal': '220ms'`.

## Turn animations off

`disableAnimation` removes the banner's fades, the enter and exit
transitions of the dialogs, and the hover and snap transitions of the floating
`ConsentDialogTrigger`. Set it once for every surface, then override it for one
surface where your framework allows:

|Framework|For every surface|For one surface|
|--|--|--|
|Next.js, TanStack Start|`options.disableAnimation` in Next.js `c15t.config.ts`, or on `ConsentRoot`|`disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`|
|React|`disableAnimation` in the `ConsentProvider` options|The same component props|
|Nuxt|`disableAnimation` in the `c15t` module options|`disableAnimation` prop on `consent-banner.vue`, `consent-manager.vue` and the IAB banner and dialog, when you render them yourself|
|Vue|`disableAnimation` in the `c15tVue` options|The same component props|
|Astro|`disableAnimation` in the `c15t()` integration options|`disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`|
|Svelte, SvelteKit|`disableAnimation` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)|`disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`|
|HTML|`data-disable-animation` on the script tag, or `ui.disableAnimation` in `config`|`ui.banner.disableAnimation`, `ui.dialog.disableAnimation`|
|JavaScript|`ui.disableAnimation` in `init()`|`ui.banner.disableAnimation`, `ui.dialog.disableAnimation`|

A value on one surface wins over the value for every surface.

Vue's `ConsentRoot` renders the banner and dialog without props, so in Vue and
Nuxt a per-surface value only applies when you render the surface components
yourself.

## Follow the visitor's reduced motion setting

c15t's stylesheet stops the banner, dialog, floating trigger, switches, tabs
and accordions from animating while the visitor asks for reduced motion. The
rules sit in a `prefers-reduced-motion: reduce` media query, so they apply in
every framework and follow the setting as it changes, with no option to set.

`disableAnimation: false` does not bring the animations back for these
visitors, because the stylesheet rule applies whatever the option says.

## Animate your own rules on dialog state

The preference dialog marks its open state with `data-state`, `open` or
`closed`, so a rule can animate your own additions to it. Which element
carries the attribute depends on the framework:

|Framework|Elements with `data-state`|
|--|--|
|HTML, JavaScript|Dialog overlay, positioner and content|
|Svelte, SvelteKit|Dialog backdrop, positioner and content|
|Vue, Nuxt|Dialog content and overlay. The dialog unmounts when it closes, so you only see `open`|
|React, Next.js, TanStack Start|Not on `ConsentDialog`. The `Dialog` primitive's trigger, overlay, content and close parts carry it|

Banners do not carry `data-state`. Read `data-prompt`, `data-variant` and the
other attributes in [component parts](/docs/customization/slots) instead.

## Stop transitions while you switch themes

Every c15t stylesheet has a `c15t-no-transitions` class that sets
`transition` and `animation` to `none` on an element and its children. Add it
to `<html>` while your app swaps themes, so colors change in one frame. Force
a style and layout pass before you remove it. Otherwise the browser computes
the new theme only after the class is gone, and the change animates:

```ts
const root = document.documentElement;
root.classList.add('c15t-no-transitions');
applyYourTheme();
// Reading layout applies the new theme while transitions are off.
root.getBoundingClientRect();
root.classList.remove('c15t-no-transitions');
```

This assumes `applyYourTheme` changes classes or custom properties
synchronously. If your framework applies the theme in a later render, run the
last two lines after that render commits.

## Check the result

1. In DevTools, open the Rendering panel and emulate
   `prefers-reduced-motion: reduce`. Reload with site data cleared.
2. The banner appears without sliding in.
3. Open the preference dialog and toggle a switch. The switch changes without
   animating.
4. Turn the emulation off, set a slower `motion.duration.normal`, and open the
   dialog again. It fades in at the new speed.

# Stylesheets and CSS layers
URL: https://c15t.com/docs/customization/stylesheets
See how c15t delivers its styles in each framework without a render-blocking stylesheet, when to import styles.css yourself with styles false, which file holds the dialog's rules, and how c15t's cascade layer meets your own.

## What each framework loads

|Framework|What you import|How the styles arrive|
|--|--|--|
|Next.js, TanStack Start, React|Nothing|Each stock surface renders the rules it uses as `<style>` elements|
|Nuxt, Vue|Nothing|Each Vue component imports its own stylesheet|
|Astro|Nothing|`<ConsentScript />` inlines the banner's rules into the HTML. The client links the dialog's rules when a dialog first opens. On a Tailwind CSS 3 site, the integration adds `c15t/astro/styles.css` to every page instead|
|Svelte|Nothing|Each stock surface inserts the rules it uses into `<head>`|
|SvelteKit|Nothing|`c15tHandle` writes a server-rendered banner's rules into the HTML. The other surfaces insert theirs in the browser|
|HTML|Nothing|`c15t.js` carries its stylesheet into the UI's shadow root|
|JavaScript|Nothing|`init()` carries its stylesheet into the UI's shadow root|

Inline c15t styles avoid a stylesheet request before the page's first paint.
A linked stylesheet in `<head>` used to delay it by a round trip. With 4x
CPU throttling, 1.6 Mbps download and 150 ms RTT, a Next.js page first painted
at about 370 ms instead of 650 ms once the link was gone.

Inline rules add bytes to each server-rendered HTML response. Enable HTTP
compression on the production host to reduce their transfer cost. On repeat
document visits, a cached external stylesheet can paint sooner than sending
the inline rules again. To use that cache, keep the stylesheet imports and
set `styles: false` as described below.

Load `styles.css` yourself with Tailwind CSS 3 or a named cascade layer.
[Import the stylesheet yourself](#import-the-stylesheet-yourself)
covers those cases.

## How the surfaces deliver their rules

c15t splits its rules into two sheets. The first-paint sheet holds the
default tokens, every c15t CSS variable, and the rules for the banner, the
floating trigger and the `ConsentGate` placeholder. The dialog sheet holds the
preference dialog's and the preference widget's rules.

In React, Next.js and TanStack Start, `ConsentBanner`, `ConsentDialogTrigger`
and the default `ConsentGate` placeholder render the first-paint sheet.
`ConsentDialog` and `ConsentWidget` render it plus the dialog sheet. The
dialog sheet ships with the dialog's lazily loaded code, so it is not part of
the first page load. A server-rendered banner puts its rules in the HTML.

`IABConsentBanner` also delivers the IAB variables and banner rules.
`IABConsentDialog` adds the IAB dialog rules when it opens, including the
shared rules it needs when rendered without a banner. IAB setups need no
stylesheet imports with automatic styling enabled.

Streamed React IAB banners become visible once their complete card markup
arrives. This prevents the centered card from moving as the browser parses
its remaining content, without waiting for hydration.

* In React 19, React moves the elements into `<head>` and renders each sheet
  once per page, as `<style data-precedence="c15t" data-href="c15t-first-paint">`.
* In React 18, the elements render in place, next to the surface.
* In React 19 with the provider's `nonce` option set, they also render in
  place and carry the nonce. React drops the nonce of a style it moves to
  `<head>` unless the app passed that nonce to React's server renderer.

In Svelte, each stock surface inserts the sheets it uses into `<head>` as
`<style data-c15t-styles="…">`, once per page, before its own elements
render. The elements stay after the surface unmounts. The Svelte dialog's
sheets, its rules and the primitives, load with the dialog's code.

On a server-rendered SvelteKit page, the banner leaves a
`<meta name="c15t-styles">` marker, and `c15tHandle` from `@c15t/svelte/kit`
writes the sheets into the HTML `<head>` as `<style>` elements. The banner is
styled before hydration with no stylesheet request. Without `c15tHandle` in
`src/hooks.server.ts`, a server-rendered banner shows unstyled until
hydration. The [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart)
adds the handle.

In Astro, `<ConsentScript />`, or the banner on a layout without it, inlines
the first-paint sheet into the HTML as
`<style data-c15t-styles="c15t-first-paint">` with the page nonce. When
`tailwindcss` resolves to version 3 from the Astro root, the integration
inlines nothing and adds `c15t/astro/styles.css` to every page through
Astro's CSS pipeline, so the site's `c15t/postcss-tailwind3` plugin processes
it. That stylesheet still holds back the first paint.

The surfaces render no stylesheet with `noStyle`, or when the provider sets
`styles: false`.

## Import the stylesheet yourself

Set `styles: false` in the provider options and import `styles.css` when you
need control over the file:

* **Tailwind CSS 3.** c15t's `<style>` rules sit in a native
  `@layer components`, and Tailwind 3's unlayered preflight beats them. Import
  `styles.css` through the `postcss-tailwind3` plugin instead, as
  [Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3) shows.
  Astro sites skip this: the integration detects Tailwind 3 and links the
  stylesheet itself.
* **A named cascade layer.** Import the stylesheet into your own layer, as in
  [order c15t's layer against your CSS](#order-c15ts-layer-against-your-css).
* **Cached styles across document visits.** Keep external CSS when its HTTP
  cache performs better for your site's repeat visits. Compare cold and warm
  visits on your production host before choosing this option.

|Framework|Option|Files to import|
|--|--|--|
|Next.js|`options.styles` in `c15t.config.ts` or on `ConsentRoot`|`c15t/next/styles.css`, and `c15t/next/iab/styles.css` for IAB TCF|
|TanStack Start|`options.styles` on `ConsentRoot`|`c15t/tanstack-start/styles.css`, and `c15t/tanstack-start/iab/styles.css` for IAB TCF|
|React|`options.styles` on `ConsentProvider`|`c15t/react/styles.css`, and `c15t/react/iab/styles.css` for IAB TCF|
|Svelte, SvelteKit|`options.styles` on `ConsentProvider` or `ConsentRoot`|`@c15t/svelte/styles.css`, and `@c15t/svelte/iab/styles.css` for IAB TCF|
|Astro|`styles` in the `c15t()` integration options|See [load Astro's stylesheets yourself](#load-astros-stylesheets-yourself)|

```ts title="c15t.config.ts (Next.js)"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({ options: { styles: false } });
```

`styles: false` turns off only the stylesheets. Tokens from `ConsentTheme`
and slot classes still apply.

If you keep a `styles.css` import without `styles: false`, the surfaces still
look right, but the rules ship twice and the stylesheet link still holds back
the first paint. Remove the import, or add `styles: false` if you need it.

## Where the dialog's rules come from

|Framework|The preference dialog's rules|
|--|--|
|Next.js, TanStack Start, React|In the dialog sheet that `ConsentDialog` and `ConsentWidget` render. It ships with the dialog's lazily loaded code. With `styles: false`, in `styles.css`. No `@c15t/react` or `@c15t/ui` module imports CSS, so a Next.js app that uses only the Pages Router builds without `transpilePackages`|
|Nuxt, Vue|The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's|
|Astro|In `@c15t/ui/styles/sheets/dialog.css`. The Svelte dialog, the default `ui`, also needs the primitives stylesheet. c15t links both when a visitor first points at, focuses or opens a control that opens the dialog, waits for them before it shows the dialog, and keeps them across `ClientRouter` navigation. On a Tailwind CSS 3 site, the dialog's rules are in `c15t/astro/styles.css`, and c15t links only the primitives stylesheet|
|Svelte, SvelteKit|In the dialog's sheets, which load with the dialog's code. With `styles: false`, in `@c15t/svelte/styles.css`|
|HTML, JavaScript|Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use|

`styles.css` still holds every stock surface's rules for apps that set
`styles: false`. In that manual mode, IAB TCF also needs `iab/styles.css`
after the base stylesheet.

Earlier 3.0 alphas shipped the dialog's rules in `@c15t/ui/styles/dialog.css`,
which the dialog's code imported. That file, the `@c15t/ui/styles/dialog`
module and `c15t/astro/dialog.css` are now empty and stay only so existing
imports keep resolving. Remove those imports.

## Order c15t's layer against your CSS

c15t puts its component rules in the cascade layer `components`. Tokens,
variables and keyframes stay unlayered. Each stylesheet, and each `<style>`
element the surfaces render, opens with Tailwind CSS 4's layer order:

```css
@layer properties, theme, base, components, utilities;
```

Cascade layers rank by the order they are first named, so `components` stays
above Tailwind's preflight in `base` and below `utilities`, whichever
stylesheet loads first. Without Tailwind the other layers stay empty. Vue's
per-component stylesheets open with the same statement.

What this means for your overrides:

* Any unlayered rule of yours outranks every c15t component rule, whatever its
  specificity or load order. You do not need `!important`.
* A rule in one of your own layers wins only if that layer comes after
  `components` in the layer order.
* Tokens are not layered. Set them as described in
  [theme tokens](/docs/customization/tokens).

If your CSS declares its own layer order, load that statement before c15t's
rules. To put c15t's rules in a named layer, set `styles: false` and import
the stylesheet into that layer, such as
`@import 'c15t/react/styles.css' layer(c15t)`. Its component rules then sit
in `c15t.components`, so order `c15t` against your own layers.

## Load Astro's stylesheets yourself

By default the Astro integration inlines the banner's rules into each page,
including the IAB banner rules when it sets `iab`, and links the dialog's
rules when a dialog opens. On a Tailwind CSS 3 site it adds
`c15t/astro/styles.css` and, with IAB, `c15t/astro/iab/styles.css` to every
page instead of inlining the banner's rules. To load the
files yourself, for example from a global stylesheet that names its own
layers, set `styles: false` in the `c15t()` options and import them after
your layer order statement. With `styles: false`, c15t inlines no rules and
links no stylesheet when the dialog opens. The Svelte dialog, the default
`ui`, needs the primitives stylesheet next to `styles.css`:

```css title="src/styles/global.css"
@import 'c15t/astro/styles.css';
/* Only with ui: 'svelte'. */
@import 'c15t/astro/primitives.css';
/* Only when the integration sets iab. */
@import 'c15t/astro/iab/styles.css';
```

Keep c15t's rules when you restyle the surfaces. The browser hides the Astro
banner with the `hidden` attribute, and c15t's rules make that attribute beat
the banner's own `display` rule.

## Style the script tag's shadow root

The script tag and `init()` from `@c15t/browser` render into a shadow root with
their own copy of the stylesheet. Your page's CSS does not reach the UI, and
the UI's CSS does not reach your page. To style it:

|Option|What it does|
|--|--|
|`ui.theme`|Tokens, written after the stylesheet inside the shadow root|
|`ui.css`|A string of CSS added after the stylesheet and the theme|
|`ui.stylesheetURLs`|Stylesheets linked inside the shadow root, after c15t's, with the client's `nonce`. They load asynchronously, so the first frame can render without them|
|`::part()`|Page CSS that reaches a part by its slot key, as in `[data-c15t-ui]::part(consentBannerCard)`|
|`ui.shadow: false`, or `data-shadow="false"`|Renders into the page, so your stylesheets apply. c15t still injects its stylesheet next to the UI|
|`ui.styles: false`|Drops the injected stylesheet. With `shadow: false`, load `@c15t/browser/styles.css` from your bundle, or link `dist/c15t.css` from the same package version as the script|

A stylesheet in `ui.stylesheetURLs` should also load on the page. Some CSS,
such as Tailwind 4's `@property` rules, only takes effect in the page's
stylesheets. Of these options, the script tag has an attribute for `shadow`
only. Set the others with `c15t.push(['config', { ui: { ... } }])`.

## Run without c15t's styles

`noStyle` removes c15t's stock classes from the markup, and in the script tag
also the injected stylesheet. Your part classes, `data-testid` and the `data-*`
attributes stay. [Component parts](/docs/customization/slots#remove-c15ts-classes-with-nostyle)
lists where each framework takes it.

`noStyle` does not supply layout, spacing, focus indicators or responsive
behavior. If a token seems to do nothing, check the layer order and your
selector before you reach for `noStyle`.

## Check the result

1. Open DevTools Network, clear site data and reload. No c15t stylesheet
   request appears before the first paint. In the HTML or the Elements panel,
   `<head>` holds c15t's rules: `<style data-href="c15t-first-paint">` in
   React 19, or a `<style data-c15t-styles>` element in Svelte, SvelteKit
   and Astro. In React 18, or with a `nonce`, the `<style>` sits next to the
   banner instead.
2. Open the preference dialog. It is styled on its first frame. Opening it
   adds the dialog's rules: a second `<style>` element in React, Next.js,
   TanStack Start, Svelte and SvelteKit, or a linked
   `@c15t/ui/styles/sheets/dialog.css` in Astro.
3. With `styles: false`, your imported `styles.css` loads once, and no c15t
   `<style>` element appears.
4. Select a banner part and read the Styles panel. c15t's rules appear under
   `@layer components`, and your unlayered rules for the same property win.

# Component parts
URL: https://c15t.com/docs/customization/slots
Find every part of c15t's banner, dialog, widget, trigger and ConsentGate placeholder, its key in your framework's part API, and the data attributes to select on.

## Which part API your framework uses

Each framework has one way to add classes, inline styles or attributes to a
single part of a stock component. The keys differ between the two
vocabularies, so a configuration from one does not work in the other.

|Framework|Part API|Keys look like|Class key|
|--|--|--|--|
|Next.js, TanStack Start|`options.components` in Next.js `c15t.config.ts`, or on `ConsentRoot`|`components.banner.card`|`className`|
|React|`components` in the `ConsentProvider` options|`components.banner.card`|`className`|
|Nuxt|`components` in the `c15t` options, or in `app/app.config.ts`|`components.banner.card`|`class`|
|Vue|`components` in the `c15tVue` options|`components.banner.card`|`class`|
|Astro|`theme.slots` in the `c15t()` integration options|`slots.consentBannerCard`|A string, or `className`|
|Svelte, SvelteKit|`theme.slots` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)|`slots.consentBannerCard`|A string, or `className`|
|HTML, JavaScript|`ui.theme.slots`|`slots.consentBannerCard`|A string, or `className`|

React and Vue also read `theme.slots` from the theme in their options, and
apply each slot to the matching `components` part, such as
`consentDialogCard` to `dialog.card` and `toggle` to `switch.root`. Where both
set the same part, classes from both apply, inline styles merge with
`components` winning per property, and any other attribute in `components`
replaces the theme's. In Vue and Nuxt, each part object is bound with
`v-bind`, so write `class` and `style` rather than React's `className`.

Svelte's stock components, and Astro's `ConsentBanner`, `IABConsentBanner`
and `ConsentDialogTrigger`, also take a `class` prop. On `ConsentBanner` it
goes on the banner root.

This React fragment belongs in the provider options:

```tsx
components: {
  banner: {
    card: { className: 'brand-card' },
    title: { style: { fontWeight: 600 } },
  },
},
```

The same parts with `theme.slots`, which every framework reads:

```ts
theme: {
  slots: {
    consentBannerCard: 'brand-card',
    consentBannerTitle: 'brand-title',
  },
},
```

A slot can also be `{ className, style }`. Svelte applies both on every part,
including the IAB banner and dialog.

[Class names and CSS-in-JS](/docs/customization/class-names) covers CSS
Modules, vanilla-extract, StyleX and Emotion, and
[Tailwind CSS](/docs/customization/tailwind) covers utilities on parts.

## Banner parts

|Part|`components` key|`theme.slots` key|`data-testid`|
|--|--|--|--|
|Positioning root, with the state attributes|`banner.root`|`consentBanner`|`consent-banner-root`|
|Card sizing and branding container|`banner.cardShell`|None||
|Visible card|`banner.card`|`consentBannerCard`|`consent-banner-card`|
|Title and description container|`banner.header`|`consentBannerHeader`||
|Title|`banner.title`|`consentBannerTitle`||
|Description|`description.banner`|`consentBannerDescription`||
|Action area|`banner.footer`|`consentBannerFooter`||
|Group of action groups|`banner.actions`|None||
|One group of equally prominent actions|`banner.actionGroup`|`consentBannerFooterSubGroup`||
|Group of right links|`banner.rights`|`consentBannerRights`||
|One right link|`banner.rightLink`|`consentBannerRightLink`||
|Backdrop of a blocking banner|`banner.overlay`|`consentBannerOverlay`||
|"Secured by" tag|`tag.banner`|`consentBannerTag`||
|Filled and outlined buttons|`button.primary`, `button.secondary`|`buttonPrimary`, `buttonSecondary`||

The button parts apply to every c15t button of that style, in the banner and
the dialog. The script tag's banner has no rights group, so
`consentBannerRights` does not apply there.

## Preference dialog parts

|Part|`components` key|`theme.slots` key|`data-testid`|
|--|--|--|--|
|Positioner|`dialog.root`|None||
|Dialog container|`dialog.container`|`consentDialog`|`consent-dialog-root`|
|Card|`dialog.card`|`consentDialogCard`||
|Header|`dialog.header`|`consentDialogHeader`||
|Title|`dialog.title`|`consentDialogTitle`||
|Description|`description.dialog`|`consentDialogDescription`||
|Content|`dialog.content`|`consentDialogContent`||
|Backdrop|`dialog.overlay`|`consentDialogOverlay`||
|"Secured by" tag|`tag.dialog`|`consentDialogTag`||

The stock dialog's footer is the preference widget's footer. Style it with
`consentWidgetFooter`. There is no `consentDialogFooter` slot.

## Preference widget parts

The widget is the list of categories inside the dialog. React and Vue call it
`manager`.

|Part|`components` key|`theme.slots` key|
|--|--|--|
|Widget root|`manager.root`|`consentWidget`|
|Footer|`manager.footer`|`consentWidgetFooter`|
|Group of action groups|`manager.actions`|None|
|One action group|`manager.actionGroup`|`consentWidgetFooterSubGroup`|
|Category accordion|`accordion.root`, `accordion.triggerRow`, `accordion.arrow`, `accordion.header`, `accordion.title`, `accordion.control`, `accordion.contentViewport`, `accordion.contentInner`|`consentWidgetAccordion`|
|One accordion item|`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`|None|
|Category switch|`switch.root`, `switch.track`, `switch.thumb`|`toggle`|
|Vendor list|`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`, `vendor-list.item`, `vendor-list.header`, `vendor-list.name`, `vendor-list.description`, `vendor-list.link`, `vendor-list.control`|None|
|"Secured by" tag|`tag.manager` in React, `tag.dialog` in Vue|`consentWidgetTag`|

## Floating trigger parts

|Part|`components` key|`theme.slots` key|
|--|--|--|
|Button|`trigger.root`|`consentDialogTrigger`|
|Icon|`trigger.icon`|`consentDialogTriggerIcon`|
|Label|`trigger.text`|None|
|Toolbar, its items and icons|`trigger.toolbar`, `trigger.toolbarItem`, `trigger.toolbarIcon`|`consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, `consentDialogTriggerToolbarIcon`|

React renders the toolbar from `ConsentDialogTriggerToolbar`, and while
`ConsentDevTools` is mounted. Vue renders it only while `ConsentDevTools` is
mounted. In Astro, the toolbar slots reach the React dialog.

## Legal links and IAB TCF parts

|Component|`components` keys|`theme.slots` keys|
|--|--|--|
|Legal links|`legal-links.root`, and `link.banner`, `link.dialog`, `link.manager` for one link|None|
|IAB banner|`iab-banner.root`, `cardShell`, `card`, `header`, `title`, `description`, `partnersLink`, `purposeList`, `purposeMore`, `legitimateInterestNotice`, `footer`, `actions`, `actionGroup`, `overlay`|`iabConsentBanner`, `iabConsentBannerCard`, `iabConsentBannerHeader`, `iabConsentBannerFooter`, `iabConsentBannerTag`, `iabConsentBannerOverlay`|
|IAB dialog|`iab-dialog.root`, `card`, `header`, `headerContent`, `title`, `description`, `closeButton`, `body`, `content`, `loading`, `footer`, `tabs`, `tabsList`, `tabTrigger`, `tabIndicator`, `tabPanel`, `specialPurposes`, `consentNotice`, `actions`, `actionGroup`, `overlay`|`iabConsentDialog`, `iabConsentDialogCard`, `iabConsentDialogHeader`, `iabConsentDialogFooter`, `iabConsentDialogTag`, `iabConsentDialogOverlay`|
|IAB purpose, stack and vendor rows|`iab-purpose-item.*`, `iab-stack-item.*`, `iab-vendor-list.*`|None|

Legal links take no `theme.slots` key. They keep their stock link class, and
a description slot's classes stay on the description around them.

## ConsentGate placeholder parts

`ConsentGate` shows a placeholder card while its category is denied. React,
Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit render the same
three parts:

|Part|`components` key|`theme.slots` key|`data-testid`|
|--|--|--|--|
|Placeholder card|`consent-gate.root`|`consentGate`|`consent-gate-placeholder`|
|Title|`consent-gate.title`|`consentGateTitle`|`consent-gate-title`|
|Button that opens preferences|`consent-gate.button`|`consentGateButton`|`consent-gate-button`|

The button part applies on top of `button.primary`, or `buttonPrimary`. The
parts only reach the built-in placeholder. A placeholder you pass yourself
takes your own classes, and the wrapper around the gate takes `className` in
React or `class` in Svelte. Astro, HTML and JavaScript have no `ConsentGate`.

## Style parts from outside the script tag's shadow root

The script tag and `init()` render into a shadow root. Every part that has a
`theme.slots` key carries it in a `part` attribute, so page CSS can reach it
with `::part()`:

```css
[data-c15t-ui]::part(consentBannerCard) {
  border: 3px solid #6943a3;
}
```

## Select on state attributes

Parts carry `data-*` attributes that describe their state. Select on these
instead of guessing at markup:

|Element|Attributes|
|--|--|
|Banner root|`data-prompt`, `data-model`, `data-variant`, `data-position`, `data-blocking`|
|Action buttons|`data-action` (`accept`, `reject`, `customize`, `dismiss` or `save`), `data-variant`, `data-mode`|
|Footer and action groups|`data-direction`, `data-fill`, `data-split`|
|Right links|`data-action="right"`, `data-right`|
|Preference dialog|`data-state` (`open` or `closed`), on the elements listed in [motion](/docs/customization/motion#animate-your-own-rules-on-dialog-state)|
|Category switch|`data-state`, `data-disabled`|

The script tag's banner root has `data-variant`, `data-position` and
`data-blocking` only, with `data-blocking` set to `"true"` or `"false"`. Its
right links carry `data-action="customize"`.

The banner card does not inherit the root's attributes. With Tailwind, give
the root `group` and read the root's attribute from a child part:

```tsx
components: {
  banner: {
    root: { className: 'group' },
    card: { className: 'group-data-[variant=bar]:rounded-none' },
  },
},
```

Test notices as well as choice prompts. A notice has an acknowledge action,
`data-action="dismiss"`, instead of accept and reject.

## Do not target c15t's class names

c15t's stock class names are generated from CSS Modules and end in a hash, such
as `c15t-ui-card-lgjVq`. The hash changes whenever the source CSS changes, and
the classes disappear under `noStyle`. A rule that targets one breaks on an
upgrade without warning. Target a part API, `data-testid`, a `data-*`
attribute or `::part()` instead.

## Remove c15t's classes with noStyle

`noStyle` renders the same markup and behavior without c15t's stock classes. It
keeps your part classes and styles, `data-testid` and the `data-*` attributes.
It does not replace layout, spacing, focus indicators or responsive behavior,
so use it when you intend to write all of that yourself.

|Framework|Where|
|--|--|
|Next.js, TanStack Start, React|`noStyle` in the provider options for every component, or the `noStyle` prop on `ConsentBanner`, `ConsentDialog`, `ConsentWidget`, `ConsentDialogTrigger` and the IAB components|
|Svelte, SvelteKit|`noStyle` in the provider options, or the prop on a stock component|
|Astro|`noStyle` prop on `ConsentBanner` and `IABConsentBanner`|
|HTML, JavaScript|`ui.noStyle`, which also drops the bundled stylesheet|
|Vue, Nuxt|The `noStyle` prop on `ConsentWidget`, and on the `PreferenceItemRoot` and `PreferenceItemContent` primitives, whose other parts follow the root. The banner, dialog and trigger have no `noStyle`|

In `theme.slots`, `{ noStyle: true }` on one slot replaces that part's stock
classes in Svelte, Astro's banner and the script tag. React and Vue, including
Astro's React and Vue dialog islands, ignore a slot's `noStyle`, so its classes
apply on top of the stock ones. If the markup itself must change, use your framework's compound
components or headless API.

# Class names and CSS-in-JS
URL: https://c15t.com/docs/customization/class-names
Style c15t's component parts with CSS Modules, vanilla-extract, StyleX, Emotion or plain class names, and see which approach works in each framework.

## Pass a class to a part

CSS Modules, vanilla-extract, StyleX, Emotion and Tailwind all end up as a class
on an element and a rule in a stylesheet. Give c15t the class through your
framework's part API, and the rule wins over c15t's own rule for that part:
c15t's rules sit in the `components` cascade layer, and an unlayered rule from
your stylesheet outranks any layered one.

Each example below adds a 3px colored border and 4px corners to the banner card.
The React examples run as Storybook stories in CI, which check that each class
lands on the card and that the computed border comes from the class, not from
c15t's own card rule. The script tag examples run in the example app's browser
tests.

|Framework|Part API|Class key|Inline `style`|Where the class's CSS must load|
|--|--|--|--|--|
|Next.js, TanStack Start, React|`components.<component>.<part>`, or `theme.slots`|`className`|Yes|Anywhere on the page|
|Nuxt, Vue|`components.<component>.<part>`, or `theme.slots`|`class` (`className` in `theme.slots`)|Yes|Anywhere on the page|
|Svelte, SvelteKit|`theme.slots`, or `class` on a component|A string, or `className` in a slot object|Yes|A global stylesheet, or `:global()`|
|Astro|`theme.slots` in the integration options, or `class` on `ConsentBanner`|A string, or `className` in a slot object|Yes|A global stylesheet|
|HTML, JavaScript|`ui.theme.slots`|A string, or `className` in a slot object|Yes|Inside the shadow root through `ui.stylesheetURLs`, or anywhere with `shadow: false`|

[Component parts](/docs/customization/slots) lists the parts and their keys in
each framework.

## CSS Modules

Import the module and pass its class. This works wherever your bundler compiles
CSS Modules:

```css title="src/banner.module.css"
.card {
	border: 3px solid rgb(219 39 119);
	border-radius: 4px;
}
```

```ts title="src/consent-components.ts"
import type { ConsentProviderOptions } from 'c15t/react';

import styles from './banner.module.css';

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: styles.card } },
};
```

Pass `components` in your `ConsentProvider` options, or in `options` on
`ConsentRoot` in Next.js and TanStack Start.

## vanilla-extract

vanilla-extract compiles `style()` calls in `.css.ts` files to static CSS at
build time. Add its plugin for your bundler, such as
`@vanilla-extract/vite-plugin`, then pass the class:

```ts title="src/consent-components.css.ts"
import { style } from '@vanilla-extract/css';
import type { ConsentProviderOptions } from 'c15t/react';

const card = style({ border: '3px solid rgb(37 99 235)', borderRadius: 4 });

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: card } },
};
```

## StyleX

`stylex.props()` returns `className` and, for dynamic values, `style`. A React
part accepts both, so spread the result into the part. Add the StyleX compiler
plugin for your bundler, such as `@stylexjs/unplugin`:

```ts title="src/consent-components.ts"
import * as stylex from '@stylexjs/stylex';
import type { ConsentProviderOptions } from 'c15t/react';

const styles = stylex.create({
	card: {
		borderColor: 'rgb(22 163 74)',
		borderRadius: 4,
		borderStyle: 'solid',
		borderWidth: 3,
	},
});

/**
 * Pass as `components` in your ConsentProvider options. `stylex.props()`
 * returns `className` and, for dynamic styles, `style`; the slot takes both.
 */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: stylex.props(styles.card) },
};
```

StyleX writes atomic classes into an unlayered stylesheet, so they outrank
c15t's layered rules without extra specificity.

## Emotion

`css()` from `@emotion/css` returns a class name and inserts its rule into a
`<style>` element in the document `<head>` when your code runs:

```ts title="src/consent-components.ts"
import { css } from '@emotion/css';
import type { ConsentProviderOptions } from 'c15t/react';

const card = css({ border: '3px solid rgb(234 88 12)', borderRadius: 4 });

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: card } },
};
```

Emotion inserts its rules into the page, not into a shadow root. With the HTML
script tag or `@c15t/browser`, set `ui: { shadow: false }` so the UI renders
in the page where those rules reach it. `ui.stylesheetURLs` cannot carry them,
because they have no URL.

## Use other frameworks' part APIs

Vue and Nuxt bind a part's object to the element with `v-bind`, so write
`class` rather than `className`. A class string from CSS Modules,
vanilla-extract or Emotion works the same way. To use StyleX, map its
`className` to `class`.

Svelte scopes component styles, so a class defined in a component's `<style>`
block does not reach a c15t part. Define it in a global stylesheet or with
`:global(.your-class)`. `theme.slots` accepts a string or
`{ className, style }`, and `class` on `ConsentBanner` goes on the banner root.

Astro serializes its integration options, so `theme.slots` in
`astro.config.mjs` takes plain strings and objects. Use class names from a
global stylesheet or Tailwind there. Build-time tools that export class names
from a module, such as CSS Modules, cannot reach `astro.config.mjs`.

## Style the script tag's shadow root

The script tag and `init()` from `@c15t/browser` render into a shadow root. A
class from your page's stylesheet reaches a part only if the stylesheet reaches
the shadow root. Pick one:

* **`ui.stylesheetURLs`.** c15t links each URL inside the shadow root, after
  its own stylesheet. Link the stylesheet that holds your classes, such as your
  CSS Modules or Tailwind build.
* **`::part()`.** Every part with a slot key carries it in a `part` attribute.
  Page CSS can style it with `[data-c15t-ui]::part(consentBannerCard)`,
  without any class.
* **`ui.css`.** A string of CSS that c15t adds inside the shadow root.
* **`shadow: false`.** c15t renders into the page and every page stylesheet
  applies, including Emotion's.

This example links a Tailwind build into the shadow root and puts utilities on
two parts:

```html title="index.html"
<link
	rel="stylesheet"
	href="/tailwind.css"
/>
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			ui: {
				// The banner renders in a shadow root, where the page's
				// stylesheets do not reach. Link your Tailwind build into it
				// too, and keep the page's own link: Tailwind 4 registers
				// variables with @property, which only works in the page.
				stylesheetURLs: ['/tailwind.css'],
				theme: {
					slots: {
						consentBannerCard: 'rounded-none border-4 border-sky-600',
						consentBannerTitle: 'uppercase tracking-wide',
					},
				},
			},
		},
	]);
</script>
```

## Check the result

1. Open the page in a private window so the banner shows.
2. Select the banner card in the Elements panel. It carries your class.
3. In the Styles panel, your rule applies and c15t's rule for the same
   property is struck out. If your class is on the element but its rule is
   missing, the stylesheet does not reach the part. Check the "Where the class's CSS
   must load" column in [Pass a class to a part](#pass-a-class-to-a-part).

# Tailwind CSS
URL: https://c15t.com/docs/customization/tailwind
Use c15t's styles with Tailwind CSS 4 or 3 in every framework, put utilities on c15t component parts, and use Tailwind's dark variant with c15t.

## How c15t's styles meet Tailwind

c15t's component rules live in the CSS cascade layer `components`. Each c15t
stylesheet starts with Tailwind CSS 4's layer order,
`@layer properties, theme, base, components, utilities;`, and cascade layers
rank by the order they are first named. On Tailwind 4, c15t's rules stay above
Tailwind's preflight in `base` and below your utilities in `utilities`,
whichever stylesheet loads first. A plain utility such as `p-2` on a c15t part
wins without `!important`.

Tailwind CSS 3 has no cascade layers. It treats `@layer components` as its own
directive and fails the build on a stylesheet that uses it without a matching
`@tailwind components`. c15t's Tailwind 3 PostCSS plugin removes the layer
wrappers from c15t's stylesheets before Tailwind 3 runs. c15t's rules then
win by specificity, as they did in c15t v2, so a utility on a c15t part needs
Tailwind's important modifier, such as `!p-2`. The plugin cannot reach the
`<style>` elements c15t renders itself, so on Tailwind 3 you turn those off
with `styles: false` and import the stylesheet instead. The Astro integration
does this for you when it finds Tailwind 3.

The setups below come from fixtures that CI builds for each framework and
checks in Chromium. The Next.js snippets come from the Next.js 16 Turbopack
fixture. The Next.js 15 and webpack fixtures use the same files. The check
confirms that c15t's banner and dialog keep their styles under Tailwind's
preflight, that a padding utility on the banner root
beats c15t's own padding, and that the `dark:` variant applies. The fixtures run
without a backend, so they use `offline()` mode or a local `backendURL`. Keep the
`mode` or `backendURL` from your quickstart.

## Set up Tailwind CSS 4

Install Tailwind's plugin for your build tool and add it to the build. c15t
loads its own styles in every framework, so your CSS entry holds only
Tailwind. Do not import c15t's stylesheet next to Tailwind 4: the stock
components already render the same rules, and the import would hold back the
first paint.

**Next.js**

Next.js runs Tailwind 4 through `@tailwindcss/postcss`:

```js title="postcss.config.mjs"
export default { plugins: { '@tailwindcss/postcss': {} } };
```

Import Tailwind in the global stylesheet that `app/layout.tsx` or
`pages/_app.tsx` loads:

```css title="app/globals.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**TanStack Start**

Add `@tailwindcss/vite` before the TanStack Start plugin:

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		tailwindcss(),
		tanstackStart({ prerender: { enabled: true } }),
		react(),
	],
});
```

Import Tailwind from the stylesheet your root route links:

```css title="src/styles.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**React**

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [react(), tailwindcss()] });
```

Import this stylesheet from your entry module:

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**Nuxt**

Add `@tailwindcss/vite` under `vite.plugins` and list your CSS entry in
`css`. The Vue components load c15t's styles themselves:

```ts title="nuxt.config.ts"
import tailwindcss from '@tailwindcss/vite';
import { hosted } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { backendURL: '/api/c15t', mode: hosted() },
	compatibilityDate: '2026-07-04',
	css: ['~/assets/css/main.css'],
	modules: ['c15t/vue'],
	ssr: false,
	vite: { plugins: [tailwindcss()] },
});
```

Your CSS entry imports Tailwind and declares the dark variant:

```css title="app/assets/css/main.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**Vue**

The Vue components load their own stylesheets, so the CSS entry holds only
Tailwind:

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [vue(), consentManifest({ backendURL: '/api/c15t' }), tailwindcss()],
});
```

Import this stylesheet from `src/main.ts`:

```css title="src/style.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**Astro**

c15t inlines the banner's rules into each page and links the dialog's
when it opens, so the CSS entry holds only Tailwind. Add
`@tailwindcss/vite` under `vite.plugins`:

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'astro/config';
import c15t, { offline } from 'c15t/astro';

export default defineConfig({
	integrations: [
		svelte(),
		c15t({
			mode: offline({
				policyRules: [
					{
						id: 'tailwind-matrix',
						match: { isDefault: true },
						model: 'opt-in',
						prompt: 'choice',
					},
				],
			}),
		}),
	],
	vite: { plugins: [tailwindcss()] },
});
```

Import this stylesheet from your layout:

```css title="src/styles/global.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**Svelte**

```ts title="vite.config.ts"
import { svelte } from '@sveltejs/vite-plugin-svelte';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [svelte(), tailwindcss()] });
```

Import this stylesheet from `src/main.ts`:

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**SvelteKit**

```ts title="vite.config.ts"
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [tailwindcss(), sveltekit()] });
```

Import this stylesheet from your root `+layout.svelte`:

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

**HTML**

The script tag renders its UI in a shadow root with its own copy of c15t's
stylesheet. Build your Tailwind CSS as usual and link it from the page:

```css title="style.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

To put utilities on c15t's parts, link the same build into the shadow root
with `ui.stylesheetURLs`, as in
[put utilities on c15t parts](#put-utilities-on-c15t-parts).

**JavaScript**

`init()` from `@c15t/browser` renders into a shadow root, the same way as
the script tag. Build Tailwind as usual for your page. To put utilities on
c15t's parts, pass the URL of your built stylesheet in
`ui.stylesheetURLs`, as in
[put utilities on c15t parts](#put-utilities-on-c15t-parts).

## Set up Tailwind CSS 3

Tailwind 3's preflight is unlayered, so it beats the layered rules c15t
renders itself and strips the banner's padding and borders. On Tailwind 3,
turn those rules off with `styles: false` and import c15t's `styles.css`
through a PostCSS plugin. The Astro integration needs only the plugin: it
detects Tailwind 3 and links `c15t/astro/styles.css` itself. Every c15t
package that ships a stylesheet exports the plugin as
`<package>/postcss-tailwind3`, so use the one from the package you installed:

|You installed|Plugin name|
|--|--|
|`c15t` (React, Next.js, TanStack Start, Vue, Nuxt, Astro)|`c15t/postcss-tailwind3`|
|`@c15t/svelte` (Svelte, SvelteKit)|`@c15t/svelte/postcss-tailwind3`|
|`@c15t/browser` (script tag in the light DOM)|`@c15t/browser/postcss-tailwind3`|

They are the same plugin. A config that already lists
`@c15t/ui/postcss-tailwind3` keeps working.

Make four changes:

1. Set `styles: false` where you configure c15t: `options` in Next.js
   `c15t.config.ts`, `options` on `ConsentRoot` in TanStack Start, `options`
   on `ConsentProvider` in React, and `styles={false}` on `ConsentProvider` in
   Svelte or `ConsentRoot` in SvelteKit.
   Vue, Nuxt and Astro need no change.
2. Add the plugin to your PostCSS plugins, before `tailwindcss`. Write the plugins as an object, as the examples below do.
   PostCSS runs them in the order of the keys. Next.js also accepts an array
   of plugin names, but Vite's PostCSS loader rejects that form.
3. Import c15t's stylesheet above the `@tailwind` directives, whatever your
   build tool. Vue, Nuxt and Astro skip this step. Vite drops an `@import`
   that follows another rule, with the warning
   `@import must precede all other statements`, and the banner renders
   unstyled. Next.js 16 with Turbopack fails the build.
4. Set `darkMode: 'class'` so Tailwind's `dark:` variant follows the same
   `dark` class c15t reads.

The plugin also processes the stylesheets the Vue and Nuxt components import,
and the one the Astro integration adds on a Tailwind 3 site. Without it,
Tailwind 3 stops
the build with "`@layer components` is used but no matching
`@tailwind components` directive is present", or purges c15t's rules, because
c15t's class names never appear in your source.

Tailwind 3 has no cascade layers, so c15t's selectors outrank a single utility
class. Add the important modifier to utilities you pass to c15t parts:
`!bg-red-500`, `hover:!bg-red-500`. A bare `bg-red-500` has no effect. Theme
tokens work the same on Tailwind 3 and 4.

In React and Next.js apps, `c15t setup` adds the plugin and the stylesheet
import when it finds Tailwind 3, but does not set `styles: false`. Add that
yourself. It replaces an existing
`styles.tw3.css` import from an earlier setup with `styles.css`. When it
cannot edit your PostCSS config, it prints the step to do by hand. See
[setup](/docs/cli/commands/setup#set-up-styles-and-tailwind-css).

Create React App ignores PostCSS config files, so Tailwind 3 cannot run the
plugin and the build fails on c15t's stylesheet. `c15t setup` warns
about this. Add the plugin before `tailwindcss` through CRACO, eject, or move
the app to Vite.

**Next.js**

Next.js loads `postcss.config.mjs` itself:

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

Scan `app/` and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

Import `c15t/next/styles.css` above the directives. Turbopack fails the
build when the import sits below them. The same order works with
webpack. Set `styles: false` in `ConsentRoot`'s `options` as well:

```css title="app/globals.css"
/* Turbopack rejects an @import below other rules, so it goes first. */
@import 'c15t/next/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

**TanStack Start**

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

Import `c15t/tanstack-start/styles.css` above the directives, in the
stylesheet your root route links, and set `styles: false` in
`ConsentRoot`'s `options`:

```css title="src/styles.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import 'c15t/tanstack-start/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

**React**

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

Import `c15t/react/styles.css` above the directives, import this
stylesheet from your entry module, and set `styles: false` in the
`ConsentProvider` options:

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import 'c15t/react/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

**Nuxt**

Nuxt reads PostCSS plugins from `postcss.plugins` in `nuxt.config.ts`, in
the order listed:

```ts title="nuxt.config.ts"
import { hosted } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { backendURL: '/api/c15t', mode: hosted() },
	compatibilityDate: '2026-07-04',
	css: ['~/assets/css/main.css'],
	modules: ['c15t/vue'],
	postcss: {
		plugins: {
			'c15t/postcss-tailwind3': {},
			tailwindcss: {},
			autoprefixer: {},
		},
	},
	ssr: false,
});
```

Scan `app/` and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{vue,ts}'],
	darkMode: 'class',
} satisfies Config;
```

The Vue components load c15t's styles themselves, and the plugin processes
them too, so the CSS entry holds only the directives:

```css title="app/assets/css/main.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

**Vue**

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{vue,ts}'],
	darkMode: 'class',
} satisfies Config;
```

The Vue components load their own stylesheets, and the plugin processes
them too, so the CSS entry holds only the directives:

```css title="src/style.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

**Astro**

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{astro,html,ts}'],
	darkMode: 'class',
} satisfies Config;
```

When the integration finds Tailwind 3 in the project, it adds
`c15t/astro/styles.css` to every page through Astro's CSS pipeline
instead of inlining the banner's rules, so the plugin processes it. You
do not set `styles: false` or import c15t's stylesheet, and the CSS
entry holds only the directives. The first paint still waits for that
stylesheet:

```css title="src/styles/global.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

**Svelte**

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/svelte/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{svelte,ts}'],
	darkMode: 'class',
} satisfies Config;
```

Import `@c15t/svelte/styles.css` above the directives, import this
stylesheet from `src/main.ts`, and pass `styles={false}` to
`ConsentProvider`:

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import '@c15t/svelte/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

**SvelteKit**

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/svelte/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

Scan your source and turn on the class-based dark variant:

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{html,svelte,ts}'],
	darkMode: 'class',
} satisfies Config;
```

Import `@c15t/svelte/styles.css` above the directives, import this
stylesheet from your root `+layout.svelte`, and pass `styles={false}` to
`ConsentRoot`:

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import '@c15t/svelte/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

**HTML**

In the default shadow root, c15t's stylesheet never meets Tailwind, so the
page's Tailwind 3 setup needs nothing from c15t:

```css title="style.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

To render the UI in the page instead, see
[render the UI in the light DOM](#render-the-ui-in-the-light-dom).

**JavaScript**

`init()` renders into a shadow root by default, where c15t's stylesheet
never meets Tailwind. To render the UI in the page and build c15t's rules
into your Tailwind CSS, see
[render the UI in the light DOM](#render-the-ui-in-the-light-dom).

## Put utilities on c15t parts

Pass utilities to a component part through your framework's part API. The
fixtures put padding on the banner root, which c15t also pads, with a different
value in dark mode. On Tailwind 4 a plain utility wins. On Tailwind 3, add `!`,
as in `!p-[7px] dark:!p-[11px]`, because c15t's unlayered rules outrank a plain
utility. [Component parts](/docs/customization/slots) lists the parts each
framework exposes.

Tailwind only generates classes it finds in the files its `content` globs or
`@source` rules scan. Keep part classes in a scanned file.

**Next.js**

Add the classes to `options.components` on `ConsentRoot`, in the
`'use client'` wrapper from your quickstart:

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

**TanStack Start**

```tsx title="src/routes/__root.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

**React**

```tsx title="src/main.tsx"
const options = {
	components: { banner: { root: { className: 'p-[7px] dark:p-[11px]' } } },
	mode,
};
```

**Nuxt**

Tailwind scans `app/`, not `nuxt.config.ts`, so put part classes in
`app/app.config.ts` under the `c15t` key. The module merges it with the
`c15t` options in `nuxt.config.ts`. Vue takes `class`, not `className`:

```ts title="app/app.config.ts"
// Tailwind scans `app/`, so keep slot classes here rather than in
// nuxt.config.ts.
export default defineAppConfig({
	c15t: {
		components: { banner: { root: { class: 'p-[7px] dark:p-[11px]' } } },
	},
});
```

**Vue**

Add the classes to `components` in the `c15tVue` options. Vue takes
`class`, not `className`:

```ts title="src/main.ts"
.use(c15tVue, {
	components: {
		banner: {
			root: { class: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode: hosted(),
})
```

**Astro**

`class` on `ConsentBanner` goes on the banner root:

```astro title="src/pages/index.astro"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

**Svelte**

`class` on `ConsentBanner` goes on the banner root:

```svelte title="src/App.svelte"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

**SvelteKit**

```svelte title="src/routes/+layout.svelte"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

**HTML**

Put the classes on parts with `ui.theme.slots`, and link your Tailwind
build into the shadow root with `ui.stylesheetURLs`. Keep the page's own
link too. Tailwind 4 registers some of its variables with `@property`,
which only takes effect in the page's stylesheets, not a shadow root's:

```html title="index.html"
<link
	rel="stylesheet"
	href="/tailwind.css"
/>
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			ui: {
				// The banner renders in a shadow root, where the page's
				// stylesheets do not reach. Link your Tailwind build into it
				// too, and keep the page's own link: Tailwind 4 registers
				// variables with @property, which only works in the page.
				stylesheetURLs: ['/tailwind.css'],
				theme: {
					slots: {
						consentBannerCard: 'rounded-none border-4 border-sky-600',
						consentBannerTitle: 'uppercase tracking-wide',
					},
				},
			},
		},
	]);
</script>
```

Tailwind must scan the file that holds the slot classes.

**JavaScript**

Pass `ui.stylesheetURLs` and `ui.theme.slots` to `init()`. Keep a link to
the same stylesheet on the page, because Tailwind 4's `@property` rules
only take effect there:

```ts title="src/consent.ts (partial)"
ui: {
  stylesheetURLs: ['/tailwind.css'],
  theme: {
    slots: {
      consentBannerCard: 'rounded-none border-4 border-sky-600',
    },
  },
},
```

## Use the dark variant

The fixtures make Tailwind's `dark:` variant follow a `dark` class on `<html>`:
`@custom-variant dark (&:where(.dark, .dark *));` on Tailwind 4 and
`darkMode: 'class'` on Tailwind 3. c15t's stylesheet reads the same class, and
in React, Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit an unset
`colorScheme` also copies it into `c15t-dark`. One toggle then switches your
utilities and c15t's dark tokens together.

Astro and the script tag follow the system setting by default. [Dark mode](/docs/customization/dark-mode) covers each
case.

## Render the UI in the light DOM

The script tag and `init()` render into a shadow root, so your page's CSS does
not reach c15t and c15t's CSS does not reach your page. To style the UI with
your page's Tailwind build directly, render it in the page with
`data-shadow="false"` or `ui: { shadow: false }`.

On Tailwind 4, that is the whole change. c15t still injects its layered
stylesheet, and the layer order keeps it above preflight:

```html title="light-dom.html"
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	data-shadow="false"
	defer
></script>
```

On Tailwind 3, keep the default shadow root. Tailwind 3's preflight is
unlayered, so in the page it beats c15t's layered rules whatever their
specificity and removes the button padding and card borders. Linking
`c15t.css` from the page does not help, because nothing removes its layers.

To render in the light DOM anyway, turn the injected sheet off with
`styles: false`, and build c15t's rules into your Tailwind CSS with the plugin
instead:

```html title="light-dom.html"
<script>
	window.c15t = [['config', { ui: { shadow: false, styles: false } }]];
</script>
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	defer
></script>
```

Import `@c15t/browser/styles.css` above the directives in your Tailwind entry.
Install `@c15t/browser@alpha`, which provides both the stylesheet and
`@c15t/browser/postcss-tailwind3`:

```css title="style.css"
/*
 * With `shadow: false`, c15t's injected stylesheet is layered and Tailwind
 * 3's preflight is not, so preflight wins. Turn the injected sheet off and
 * build c15t's rules into your Tailwind CSS instead.
 */
@import '@c15t/browser/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/browser/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

In the light DOM your page's global rules reach the banner too, so check
buttons and headings after the switch.

## Check the result

1. Build the app and open it in a private window. The banner has its card
   background, border and button padding, so preflight did not reset it.
2. Inspect the part you gave a utility. In the Styles panel, your utility is
   applied and c15t's rule for the same property is struck out.
3. Add the `dark` class to `<html>`. Your `dark:` utility applies and, where
   c15t follows the class, the banner switches to dark colors.
4. Open the preference dialog. Its rules come from a separate stylesheet in
   most frameworks, so check that it is styled too.

# Copy and translations
URL: https://c15t.com/docs/customization/translations
Change consent wording through i18n and test the complete prompt and preferences flow.

## Configure shared messages

Use provider `i18n` for wording that should stay consistent across components.
For React, this fragment belongs in `ConsentProvider` options:

```tsx
i18n: {
  messages: {
    en: {
      common: {
        acceptAll: 'Accept all',
        rejectAll: 'Reject optional',
        customize: 'Choose cookies',
        acknowledge: 'Got it',
      },
    },
  },
}
```

Supply the same message keys in each supported locale. A one-off component prop
such as `dismissButtonText` is useful for one banner; use translations for a
site-wide change. Astro's serializable integration options have their own
types, so verify that shape before copying a React object. The Vue plugin and
Nuxt module have no `i18n` option; their copy comes from the backend.

## Load only the languages you use

c15t bundles English. Every other language it ships is a separate entry point
in `@c15t/translations`, named by its language code. Importing one registers
c15t's built-in copy for that language. Offline mode can then switch to it,
and your messages that repeat its wording don't hide backend edits. Import
them in the file that configures the provider, so they load in the browser:

```ts
import '@c15t/translations/de';
import '@c15t/translations/fr';
```

Each entry also exports that copy as `translations`, if you want to read a
string or build your messages from it:

```ts
import { translations as de } from '@c15t/translations/de';
```

The entries are `bg`, `cs`, `cy`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`,
`ga`, `gu`, `he`, `hi`, `hr`, `hu`, `id`, `is`, `it`, `lb`, `lt`, `lv`, `mt`,
`nb`, `nl`, `nn`, `pl`, `pt`, `rm`, `ro`, `sk`, `sl`, `sv` and `zh`.
`@c15t/translations/all` still loads every language at once. The `c15t`
package doesn't re-export these entries, so add `@c15t/translations` to your
dependencies.

## Combine messages with backend copy

With a backend or a manifest, the copy it sends for the visitor's language is
the base. Your `i18n.messages` for that language replace it key by key, and
keys you leave out keep the backend's wording, including copy edited in your
Inth project. c15t looks up messages for the exact language first, then for
its primary language, so `de-AT` uses your `de` messages when there is no
`de-AT` entry. Messages for other languages are not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing a stock bundle to enable a language
keeps backend edits visible, while a key you actually reworded stays pinned
in code. c15t only recognizes the built-in wording of English and of the
languages you [import](#load-only-the-languages-you-use), such as
`@c15t/translations/de` or `@c15t/translations/all`.

## Write labels that describe the action

Accept and Reject record a choice. Customize opens preferences. Acknowledge
dismisses a notice and does not record a grant. Do not label a notice dismissal
"Accept all" or make a preferences link sound like it submits an opt-out.

The notice acknowledgement uses `common.acknowledge`, with `common.dismiss` as
a fallback for older translation bundles. Keep the displayed label and the
command's effect aligned.

## Translate the ConsentGate placeholder

The `ConsentGate` placeholder reads the `consentGate` section:

|Key|Where it shows|
|--|--|
|`consentGate.title`|The placeholder text. `{category}` is replaced by the category's translated title.|
|`consentGate.actionButton`|The button that opens preferences, with the same `{category}` replacement.|
|`consentGate.policyBlocked`|React and Vue show it in place of the title, with no button, when a strict policy leaves the category out of scope.|

Earlier versions called this section `frame`. Copy under `frame` in
`i18n.messages` or custom translations still applies. c15t reads it as `consentGate`, a key set under `consentGate`
wins over the same key under `frame`, and c15t logs a warning once outside
production. Rename the section to `consentGate` to remove the warning.

## Show right-to-left languages

c15t sets `dir="rtl"` on its surfaces when the resolved language is Arabic,
Hebrew, Persian, Urdu, Pashto, Sindhi, Kurdish or Dhivehi. It matches the
primary language, so `ar-EG` counts as Arabic. Hebrew is the only
right-to-left translation c15t ships. For the others, supply your own
messages or the copy from your Inth project.

What follows the direction:

* Text, headings and the button row in the banner, the preference dialog and
  the preference widget flow right to left.
* A floating or widget banner in its default corner moves to the mirrored
  corner, so `bottom-left` becomes `bottom-right`. A `position` you set
  yourself stays where you put it.
* The HTML script tag, `@c15t/browser` and Astro's banner also set `lang` on
  their surfaces. React, Vue and Svelte set `dir` only, so set `lang` on
  `<html>` yourself.

What does not follow yet:

* The IAB TCF dialog aligns several labels, indents and borders to the left.
* The floating `ConsentDialogTrigger` keeps the corner you give it.

Test right-to-left pages with a real translation before you ship them.

## Test more than English

Try the longest labels you support at a narrow width, with browser zoom and
right-to-left text where relevant. Check banner actions, category descriptions,
legal links and the preferences save action. Translate explanations as well as
buttons so a visitor can make an informed choice.

# Banner experiments
URL: https://c15t.com/docs/guides/banner-experiments
Run A/B tests on consent banner presentation with any feature-flag provider or built-in weighted assignment, and attribute every impression and choice to its arm.

## Vary presentation, not policy

An experiment changes only how the prompt and the preference center look:
variant, position, layout, primary actions, blocking. The policy rule, its
categories and its copy stay the same for every arm, so every arm records a
choice under the same policy fingerprint.

Your normal `presentation` is the `control` arm; without one, `control` is
the stock banner. Every other arm lists only what it changes. Add the
experiment to the provider you already have and pass the arm your feature flag
resolved. In the React example, the `Consent` wrapper takes the arm as a prop:

```tsx title="src/consent.tsx"
import { defineExperiment } from 'c15t';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	hosted,
} from 'c15t/react';
import type { ConsentProviderCallbacks } from 'c15t/react';
import type { ReactNode } from 'react';

import { scripts } from './scripts';

const mode = hosted({ backendURL: 'https://your-project.inth.app' });

// `control` is the stock banner. `wall` blocks the page until the visitor
// chooses.
const bannerExperiment = defineExperiment({
	arms: { wall: { prompt: { variant: 'wall' } } },
	id: 'banner-shape',
});

const pushToDataLayer = (event: Record<string, unknown>) => {
	const page = window as Window & { dataLayer?: unknown[] };
	page.dataLayer ??= [];
	page.dataLayer.push(event);
};

// Forward each impression and choice made under an arm to your analytics.
const callbacks = {
	onChoiceRecorded: ({ consentAction, experiment }) => {
		if (experiment) {
			pushToDataLayer({
				arm: experiment.arm,
				consent_action: consentAction,
				event: 'c15t_choice_recorded',
				experiment_id: experiment.id,
			});
		}
	},
	onSurfaceShown: ({ experiment, surface }) => {
		if (experiment) {
			pushToDataLayer({
				arm: experiment.arm,
				event: 'c15t_surface_shown',
				experiment_id: experiment.id,
				surface,
			});
		}
	},
} satisfies ConsentProviderCallbacks;

export const Consent = ({
	arm,
	children,
}: {
	/**
	 * The arm your flag provider resolved. Omit it to let c15t pick, or pass
	 * `off` to leave this visitor out of the experiment.
	 */
	arm?: 'control' | 'wall' | 'off';
	children: ReactNode;
}) => (
	<ConsentProvider
		options={{
			callbacks,
			experiment: arm === 'off' ? undefined : { ...bannerExperiment, arm },
			mode,
			scripts,
		}}
	>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

`defineExperiment()` from `c15t` returns its argument and has TypeScript check
the arm names in `arm` and `split`. The callbacks forward each impression and
choice to `window.dataLayer`; see
[send the events to your own analytics](#send-the-events-to-your-own-analytics-too).

Your flag provider returns a plain string. To check it before passing it as
`arm`, type it with `ExperimentArmName` from `c15t`, which is `control` plus
the experiment's arm names:

```ts
import type { ExperimentArmName } from 'c15t';

// 'control' | 'wall'
type BannerArm = ExperimentArmName<typeof bannerExperiment>;

const armFromFlag = (value: string | undefined): BannerArm | undefined =>
	value === 'control' || value === 'wall' ? value : undefined;
```

Omit `arm` to let c15t pick, and set `split` to weight the arms:

```ts
experiment: { ...bannerExperiment, split: { control: 60, wall: 40 } }
```

|Field|Purpose|
|--|--|
|`id`|Stable experiment name, recorded with every choice|
|`arms`|What each arm changes, merged over `presentation`. `control` is your `presentation` and is not listed|
|`arm`|The arm your flag resolved: `control` or a key of `arms`|
|`split`|Relative weights when c15t picks the arm; default equal. Keys are `control` and the arms|
|`acknowledgeDiagnostics`|Run an arm that trips a presentation diagnostic and record that you reviewed it|

c15t merges the arm over `presentation`, exposes it as `snapshot.experiment`,
sends it with `/init`, and records it on the choices of visitors the banner
showed it to, so you can compare opt-in rate and time to decision per arm.

The same option exists in `c15t/next` (`ConsentRoot` `options`), `c15t/vue`,
`@c15t/svelte`, the `c15t()` Astro integration from `c15t/astro`, and
`@c15t/browser`. On a server-rendered page in Next.js, TanStack Start or
SvelteKit, pass it to `resolveConsent` instead, which counts the arm and hands
it to the client; see [Vercel Flags SDK](#vercel-flags-sdk).

`experiment` is read once, when the provider mounts. Changing it later has
no effect; remount the provider (a `key` in React) to switch experiments.

Assignment and arm validation load as a separate chunk, only on pages that
set `experiment`. A site without an experiment does not download them.

An experiment compares choices, so the banner has to ask about at least one
category. Under a rule with `scopeMode: 'permissive'`, the banner asks only
about the categories your site declares through `consentCategories`,
`scripts` or `vendors`. With none declared, it asks about none: accepting or rejecting records a notice
acknowledgement instead of a choice, `onChoiceRecorded` never fires, and the
experiment counts impressions without choices. Outside production, c15t logs
a warning the first time the banner shows an arm in that state.

### Astro

The Astro banner is server-rendered HTML that the browser only shows or
hides, so the arm is resolved on the server. To pick it per request, set
`middleware: false` in `c15t()` and compose the consent middleware yourself
with `experimentArm`, where `bannerExperimentFlag` stands for your flag lookup:

```ts title="src/middleware.ts"
import { consentMiddleware } from 'c15t/astro/middleware';

export const onRequest = consentMiddleware({
	experimentArm: async (context) => await bannerExperimentFlag(context),
});
```

Return `undefined` to run no experiment for that request. A fixed
`experiment.arm` in `c15t()` puts every visitor in one arm, which only
suits a staged rollout. Prerendered routes render once for every visitor, so
they get no per-request arm. `c15t()` throws at config time when
`experiment` has neither.

### Vary the theme

An arm can carry `theme` overrides next to its presentation fragment. They
merge over the host `theme` one token group deep, so an arm can change one
colour or radius and keep the rest of your palette. Arrays and scalars are
replaced.

```tsx
experiment: {
	id: 'button-style',
	arms: {
		bold: {
			theme: {
				colors: { primary: '#0a0a0a' },
				radius: { lg: '4px' },
			},
		},
	},
}
```

Read the merged theme with `useResolvedTheme()` in React,
`useResolvedTheme(theme)` in Vue, `getConsentManager().theme` in Svelte and
`client.theme` in `@c15t/browser`. Astro renders the arm's tokens with the
banner. In React, `consentActions` and slot overrides apply through the
provider, but colour, radius and other tokens reach the page through
`ConsentTheme`. Render it from the resolved theme in a client component inside
the provider, with both imported from `c15t/react`:

```tsx
<ConsentTheme theme={useResolvedTheme()} />;
```

Rendered from a client component, `ConsentTheme` ships the theme generator.
With an arm from your flag, you can instead render
`<ConsentTheme theme={resolveExperimentTheme(theme, experiment, { arm })} />`
from a Server Component. Per-action styling through
`theme.consentActions` runs through the same prominence check as
presentation: an arm that fills accept and outlines reject trips
`equivalent-prominence-overridden` and needs `acknowledgeDiagnostics: true`.

## Resolve the arm with a flag provider

Resolve the arm wherever your flags live and pass its name as `arm`. c15t
records `assignedBy: 'host'` and never re-assigns a visitor you assigned.

### Vercel Flags SDK

Give the flag three values. `off` keeps a visitor out of the test; `control`
and `wall` split the rest. Set the weights in the Vercel dashboard, so
you can roll out and widen the test without a deploy: start at 90% `off`,
check that both arms arrive, then move to 0% `off` for the real run.

```ts title="src/flags.ts"
import { vercelAdapter } from '@flags-sdk/vercel';
import { flag } from 'flags/next';

export const bannerExperimentFlag = flag<'off' | 'control' | 'wall'>({
	key: 'banner-shape',
	adapter: vercelAdapter(),
	identify, // your existing identify
	defaultValue: 'off',
});
```

Keep `identify` returning a stable id. Vercel splits on it, so a visitor
keeps their arm when you change the weights.

Resolve the flag where consent resolves and pass the experiment to
`resolveConsent`. The server reports the arm with `/init`, and the returned
state carries the experiment to `ConsentRoot`, so the client needs no
`experiment` option of its own. In Next.js, do this in the root layout:

```tsx title="app/layout.tsx"
import { resolveConsent } from 'c15t/next/server';
import { Suspense } from 'react';
import type { ReactNode } from 'react';

import { ExperimentConsent } from '@/components/experiment-consent';
import { bannerExperiment } from '@/lib/experiment';
import { bannerExperimentFlag } from '@/lib/flags';

import '@/styles/globals.css';

const ResolvedConsent = async ({ children }: { children: ReactNode }) => {
	const arm = await bannerExperimentFlag();
	const state = await resolveConsent({
		// `off` keeps this visitor out of the experiment.
		experiment: arm === 'off' ? undefined : { ...bannerExperiment, arm },
	});

	return <ExperimentConsent state={state}>{children}</ExperimentConsent>;
};

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<Suspense fallback={null}>
				<ResolvedConsent>{children}</ResolvedConsent>
			</Suspense>
		</body>
	</html>
);

export default RootLayout;
```

`@/lib/flags` exports the flag above. `ExperimentConsent` is the `Consent`
wrapper from the
[App Router guide](/docs/frameworks/next/app-router) with the event callbacks
from [send the events to your own analytics](#send-the-events-to-your-own-analytics-too)
in `options`. The layout awaits consent inside `<Suspense>`, as in
[render the banner in the server HTML](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
so the banner is in the server HTML already showing the visitor's arm.
`resolveConsent` in `c15t/tanstack-start/server` and `@c15t/svelte/server`
takes the same `experiment`.

If you pass `resolveConsent()` to `ConsentRoot` without awaiting it (the
streaming layout), the client mounts before the state arrives. Pass the
same experiment to the client options as well; c15t warns in development
when the streamed state carries an experiment the client did not get.

### PostHog

PostHog resolves flags asynchronously in the browser. Because `experiment`
is read once at mount, wait for the flags, then mount the provider with the
resolved arm. Do not wait forever: a blocked or slow flags request would
leave the visitor with no banner and you with no consent. After a second,
mount without the experiment. Those visitors see `presentation` and are not
counted in either arm. This component wraps the `Consent` component from
[the first example](#vary-presentation-not-policy):

```tsx title="src/flagged-consent.tsx"
import posthog from 'posthog-js';
import { useEffect, useState } from 'react';
import type { ReactNode } from 'react';

import { Consent } from './consent';

export const FlaggedConsent = ({ children }: { children: ReactNode }) => {
	const [arm, setArm] = useState<'control' | 'wall' | 'off' | null>(null);
	useEffect(() => {
		// The first answer wins: the provider reads the arm once.
		const fallback = setTimeout(
			() => setArm((current) => current ?? 'off'),
			1000
		);
		const unsubscribe = posthog.onFeatureFlags(() => {
			const flag = posthog.getFeatureFlag('banner-shape');
			setArm((current) => current ?? (flag === 'wall' ? 'wall' : 'control'));
		});
		return () => {
			clearTimeout(fallback);
			unsubscribe();
		};
	}, []);
	if (arm === null) {
		// Flags not loaded yet: no provider, no banner.
		return children;
	}
	return <Consent arm={arm}>{children}</Consent>;
};
```

### LaunchDarkly, GrowthBook, Statsig

```ts
const arm = ldClient.stringVariation('banner-shape', 'control');
const arm = growthbook.getFeatureValue('banner-shape', 'control');
const arm = StatsigClient.instance()
	.getExperiment('banner-shape')
	.get('arm', 'control');
```

An `arm` that is not `control` or a key of `arms` logs an error and runs no
experiment for that visitor; the page still renders. Treat that as a flag
misconfiguration.

## Let c15t assign the arm

Omit `arm` and c15t picks one by `split` (equal by default) when the page
starts, before `/init`, and records `assignedBy: 'c15t'`. A visitor who
already saw an arm keeps it.

The banner waits until the arm is picked, so the visitor never sees the base
banner swap for their arm. On a server-rendered page that means the banner is
not in the server HTML; it appears once the browser has loaded the
assignment chunk. If the chunk fails to load, the base banner shows and no
experiment runs. To keep the banner in the server HTML, resolve the arm on
the server and pass it as `arm`.

Once the banner has shown the arm, c15t stores `{ id, arm }` under
`c15t-experiment-v1` in localStorage (a cookie when localStorage is
unavailable), so the visitor keeps seeing the banner they saw. Nothing is
stored for a visitor who is never prompted, and nothing is stored for a
host-resolved arm: your flag provider decides that one on every visit. The
record holds no identifier. It exists only to keep the consent banner
consistent, so treat it like the consent record itself when you describe
your storage.

A `split` that gives no arm a positive weight, or that names an arm that does
not exist, logs an error and runs no experiment. An arm missing from the
split gets no visitors.

```ts
experiment: {
	id: 'banner-shape',
	arms: { wall: { prompt: { variant: 'wall' } } },
	split: { control: 60, wall: 40 },
}
```

Changing `id` starts a new experiment and re-assigns everyone. Removing an
arm re-assigns only the visitors who were in it. For a clean analysis, change
`id` rather than editing the arms of a running experiment.

Built-in assignment is not available in Astro; see
[Astro](#astro).

## Acknowledge presentation diagnostics

Each arm is resolved under the visitor's policy the same way `presentation`
is. An arm that trips a diagnostic, for example
`equivalent-prominence-overridden` because it makes accept primary while
reject stays neutral, is not shown under that policy: those visitors see the
base presentation, are not counted in the experiment, and c15t logs the
diagnostics. Set `acknowledgeDiagnostics: true` to run the arm anyway. c15t
then logs the diagnostics as a warning once per policy and records
`acknowledgedDiagnostics: true` with the arm on every choice. You own the
legal review of that arm; c15t records that you made it.

The check runs in the browser once the policy is known, so catch a rejected
arm before you deploy with `validateExperiment` in a test. `euPolicy` and
`presentation` stand for the policy and presentation your site uses:

```ts
import { validateExperiment } from 'c15t/experiment';

test('banner-shape arms pass under the EU policy', () => {
	validateExperiment(bannerExperiment, euPolicy, { presentation });
});
```

It throws for an invalid definition and for arms with unacknowledged
diagnostics.

## Read the assignment

```tsx
import {
	useExperiment,
	useResolvedPresentation,
	useResolvedTheme,
} from 'c15t/react';

const { id, arm, assignedBy } = useExperiment() ?? {};
const presentation = useResolvedPresentation();
const theme = useResolvedTheme();
```

React exposes three hooks:

* `useExperiment()` returns the assigned arm (`id`, `arm`, `assignedBy`,
  `acknowledgedDiagnostics`), or `null` while no experiment is configured
  or no arm is assigned yet.
* `useResolvedPresentation()` returns `presentation` with the assigned
  arm merged over it per surface. While no arm is assigned it returns
  `presentation` itself. The stock banner, dialog and widget render from it,
  as do `usePromptPresentation()` and `usePreferencesPresentation()`.
* `useResolvedTheme()` returns `theme` with the arm's `theme` merged one
  token group deep over it. While no arm is assigned, or the arm has no
  `theme`, it returns `theme` itself. The provider injects this merged theme.

Built-in assignment lands after mount, so `useExperiment()` is `null` on the
server render and during hydration and the resolved hooks return the base
values. The banner is held until then, and a clean preferences draft reseeds
from the arm's `preferences.defaults` when it lands. An
arm from your flag is known from the first render, on the server too.

Vue exposes `useExperiment()`, `useResolvedPresentation()` and
`useResolvedTheme(theme)`, Svelte `getConsentManager().experiment`,
`.presentation` and `.theme`, and `@c15t/browser` `client.presentation` and
`client.theme`. Every adapter also reports the arm on `snapshot.experiment`.

## What is recorded

An impression or a choice carries the arm only once the banner has shown it
in the current page. A returning visitor who reopens the preference center
from a footer link, or saves from an inline widget, never saw the arm's
banner, so their choice is recorded without it and does not count toward any
arm.

Each choice saved through `POST /subjects` carries in `metadata`:

|Key|Value|
|--|--|
|`experiment`|`{ id, arm, assignedBy, acknowledgedDiagnostics }`|
|`timeToDecisionMs`|Milliseconds from the surface's first impression to the action|

`uiSource` on the same record names the surface (`banner`, `dialog`,
`widget`). The `surface:shown` and `choice:recorded` kernel events and the
`onSurfaceShown` and `onChoiceRecorded` callbacks carry the same
`experiment` object, so impressions and decisions can be joined per arm in
your analytics without a backend query.

## Measure the results

An opt-in rate needs two counts per arm: how many visitors the banner was
owed to, and how many of them accepted. c15t sends both to the backend on
its own; you do not wire anything up.

* **Visitors owed the banner.** While a visitor has no stored choice, every
  `/init` carries their arm as `<id>=<arm>` in the `experiment` query
  parameter, and the backend puts it on that request's session report as
  `experiment: { id, arm }`. In manifest mode, the server render or the
  init route puts it on the report it sends to `POST /sessions`. A visitor
  who already chose is not shown the banner, so is not counted. A
  server-to-server caller can send the `x-c15t-experiment` header instead.
* **Choices.** Every choice saved through `POST /subjects` carries the arm
  in `metadata.experiment`, as above.

On a server-rendered page the server calls `/init`, not the browser, so the
server has to know the arm. Pass the experiment to `resolveConsent`, as in
[Vercel Flags SDK](#vercel-flags-sdk): it sends only `{ id, arm }` to the
backend and hands the full experiment to the client in its state.
`resolveConsent` takes `experiment` in `c15t/next/server`,
`c15t/tanstack-start/server` and `@c15t/svelte/server`; Astro and Nuxt pass
the arm they rendered on their own. When c15t picks the arm in the browser,
the browser's own `/init` carries it, so a server-rendered page that skips
the client `/init` has no count for built-in assignment. Resolve the arm with
a flag on those pages.

### Where the counts go

On Inth, the dashboard reads both counts for you. A self-hosted backend
hands each session report to `sessions.onReport`, which is where you log or
count it; `experiment` is on the report. Choices are in the `consent` table,
and [`GET /experiments/:id/summary`](#read-the-summary-from-your-backend)
groups them per arm.

The opt-in rate of an arm is visitors with an `accept_all` choice under that
arm, divided by visitors whose session reports carry the arm. Count
visitors, not requests: an undecided visitor sends a report on every page
until they choose. Deduplicate the reports per visitor the way you count
sessions.

### Send the events to your own analytics too

The `onSurfaceShown` and `onChoiceRecorded` callbacks carry the same
`experiment` object, so a few lines forward them to any tool. The
[React example](#vary-presentation-not-policy) pushes both to
`window.dataLayer` for Google Tag Manager, as `c15t_surface_shown` with the
surface and `c15t_choice_recorded` with the consent action. To send them to
PostHog instead, call `posthog.capture()` with the same fields in the
callbacks. The callbacks run for every impression and choice; check
`experiment` first, because it is `undefined` for visitors outside the test.

An impression fires before any consent exists. If your analytics tool loads
only after consent, it never sees a decliner's impression, and its opt-in
rate trends towards 100%. The backend counts above do not have that gap.

### Read the results

Consent rates move by a few points, not by half. At a 30% base rate you need
roughly 2,500 visitors per arm to detect a 5-point change with 80% power,
and about 10,000 per arm to detect 2 points. Run a sample-size calculator
against your own base rate before you start, decide the stop date up front,
and do not stop early on a good-looking day.

Under an `opt-out` policy with `prompt: 'notice'`, dismissing the notice
records no choice, so compare arms on opt-outs instead: `opt_out` choices
per visitor owed the banner.

Time to decision is the median `timeToDecisionMs` per arm over the choices.
Use the median, not the mean: a visitor who leaves the tab open skews the
mean without saying anything about the arm.

## Read the summary from your backend

The self-hosted backend copies `experiment.id`, `experiment.arm` and
`timeToDecisionMs` out of `metadata` onto their own columns (migration
`6-experiment-attribution`), so `GET /experiments/:id/summary` can group
choices per arm without a JSON query. It needs an API key.

```bash
curl 'https://app.example.com/api/c15t/experiments/banner-shape/summary?from=2026-09-01&to=2026-09-30' \
  -H "Authorization: Bearer $C15T_API_KEY"
```

```json
{
	"experimentId": "banner-shape",
	"from": "2026-09-01T00:00:00.000Z",
	"to": "2026-09-30T23:59:59.999Z",
	"arms": [
		{
			"arm": "wall",
			"choices": 120,
			"byAction": {
				"accept_all": 80,
				"custom": 10,
				"opt_out": 0,
				"reject_all": 30,
				"unknown": 0
			},
			"bySurface": { "banner": 100, "dialog": 20 },
			"medianTimeToDecisionMs": 4200
		},
		{
			"arm": "control",
			"choices": 95,
			"byAction": {
				"accept_all": 50,
				"custom": 5,
				"opt_out": 0,
				"reject_all": 40,
				"unknown": 0
			},
			"bySurface": { "banner": 90, "dialog": 5 },
			"medianTimeToDecisionMs": 5100
		}
	]
}
```

`byAction` always has all five keys. They are the action the backend
stored, not the client's `consent_action`: `accept_all` for accept,
`reject_all` for reject, `opt_out` for a reject under an opt-out policy,
`custom` for a saved selection, and `unknown` for a record without one.
`choices` counts consent records, so a visitor who changes their mind under
the same arm counts twice.

`from` and `to` accept an ISO 8601 date or timestamp and filter on the
consent's `givenAt`, both ends inclusive. A date without a time is the whole
of that day in UTC: `from=2026-09-01` starts at midnight and `to=2026-09-30`
runs to the end of the 30th, so the example above covers all of September. A
`from` later than `to` is a 400. `domain` narrows to one domain name. An
experiment id no consent carries returns `arms: []`.

From server code, the [Node.js SDK](/docs/self-host/api/node-sdk#read-an-experiment-summary)
makes the same call. Create the client with an API key; `from` and `to` also
take a `Date`:

```ts
const c15t = createC15tClient({
	baseUrl: 'https://app.example.com/api/c15t',
	apiKey,
});

const result = await c15t.experiments.summary('banner-shape', {
	from: '2026-09-01',
	to: '2026-09-30',
});
```

The summary counts choices. The other half of an opt-in rate, the visitors
each arm's banner was owed to, is on the session reports `/init` produces
(see [Measure the results](#measure-the-results)). Divide `accept_all` per
arm by the visitors whose reports carry that arm.

## Try it

Every example app under `internals/fixtures/` runs this experiment outside the pages
the docs publish. Each page shows the assigned arm and the events the
callbacks sent. Adding `arm=wall` sets the arm the way a flag would, so the
page shows `assignedBy: host`. Run each command in the example's directory.

|Example|Start|Open|
|--|--|--|
|Next.js|`bun run dev`|`/experiment`, with the arm from a stand-in flag: `?arm=wall`, `?arm=off` to leave the test, `control` otherwise|
|TanStack Start|`C15T_EXPERIMENT=1 bun run dev`|`/consent-example?experiment=1`, then add `&arm=wall`|
|React|`bun run dev`|`/experiment.html`, then add `?arm=wall`|
|Nuxt|`C15T_NUXT_EXPERIMENT=1 bun run dev`; add `C15T_NUXT_EXPERIMENT_ARM=wall` for the wall arm|`/consent-example`|
|Vue|`bun run dev`|`/?experiment=1`, then add `&arm=wall`|
|Astro|`C15T_EXPERIMENT=1 bun run dev`|`/consent-example?experiment=1` runs `control`, as Astro has no built-in assignment; add `&arm=wall`|
|Svelte|`bun run dev`|`/?experiment=1`, then add `&arm=wall`|
|SvelteKit|`bun run dev`|`/experiment-example?experiment=1`, then add `&arm=wall`|
|HTML script tag|`bun run dev`|`/?experiment=1`, then add `&arm=wall`|
|JavaScript|`bun run dev`|`/experiment/`, then add `?arm=wall`|

## End an experiment

Move the winning arm's fragment into `presentation` (and its `theme` into
`theme`), then remove `experiment`. Visitors keep their consent; the stored
arm is ignored once no experiment reads it.

## Copy is out of scope

Arms change presentation and theme tokens only. Copy is not a variant dimension because
`copyRevision` is hashed into the prompt fingerprint: a copy change re-prompts
every returning visitor, so a copy experiment would re-prompt them on each
arm switch. Vary layout, shape, position and action prominence instead.

# Verify consent
URL: https://c15t.com/docs/guides/verify-consent
Check in a production build that vendor requests wait for consent, rejection survives a reload, preferences reopen and privacy signals apply.

## What you are checking

A banner on screen proves only that the banner renders. Before shipping,
confirm four things in a production build:

1. Optional vendors make no requests before the visitor allows them.
2. A rejection survives a reload and a new tab.
3. The visitor can reopen preferences and change their mind.
4. The policy is right for each location you serve.

Run the checks against `next build && next start`, `vite preview`, or your
framework's equivalent. Dev servers load code differently and hide problems.

## Set up the browser

1. Open a private window, so no earlier choice is stored.
2. Open DevTools, select Network, and turn on **Disable cache** and
   **Preserve log**.
3. List the vendors you expect, such as `posthog.com`, `googletagmanager.com`,
   `connect.facebook.net` or `youtube-nocookie.com`. You will filter by each.

Before testing, list every place a vendor could load: `<script>` tags,
framework analytics plugins, tag manager tags and embeds. c15t cannot hold
back code it does not load. Remove duplicates first, or the results mean
nothing.

## Run the visitor flow

|Step|What to check|
|--|--|
|Load the page|The banner appears under an opt-in policy. Filter Network by each vendor domain; opt-in vendors show no requests.|
|Click Reject|The banner closes. Vendor domains still show no requests.|
|Reload|No banner. Still no vendor requests. DevTools Application shows a `c15t` cookie.|
|Open a new tab on the same site|Same result as the reload.|
|Open preferences from your footer link|The dialog opens with the categories you rejected turned off.|
|Allow one category and save|Only vendors in that category start loading. The others stay silent.|
|Turn that category off again|The page reloads, and the vendor does not load after the reload.|
|Navigate between pages without a full reload|Each vendor loads once, not once per navigation.|

By default, Google Tag and Google Tag Manager load before consent on purpose
and send Consent Mode signals. For them, check that the consent state in the
request parameters changes when the visitor chooses, not that requests are
absent. With `loadMode: 'after-consent'`, they follow the table above. See
[Google Tag Manager](/docs/integrations/google-tag-manager).

## Check each location

Policies usually differ by region. Test at least:

* A location that needs a choice, such as Germany or the United Kingdom.
* A location without a prompt, such as a US state without a privacy law in
  your rules.
* A request with no location headers at all. c15t applies your policy's
  fallback for unknown locations; make sure that fallback is what you want.

Use a VPN, your host's geolocation preview, or the `country` option on your
framework's server helper while testing. Remove test overrides before you
deploy.

## Check privacy signals

Turn on Global Privacy Control in the browser. Brave and DuckDuckGo send it by
default; in Firefox, enable it in Privacy settings. Reload and confirm the
categories your policy restricts for GPC are denied, without the visitor
having clicked anything. Turn GPC off and confirm the restriction ends.

## Check failure behavior

Make the request that initializes consent fail, then reload. Depending on your
setup, that is the backend `/init`, a same-origin init route, a manifest fetch,
or the `/init` a bundled manifest falls back to when a regional policy needs a
location the browser does not know.

* For a request the browser makes, block it in DevTools (right-click the
  request, then **Block request URL**).
* When the server resolves consent before the page loads, the browser never
  sees that request. Make it fail on the server instead, for example by
  pointing the backend URL at an unreachable address for one run.
* With a custom transport, make its `init` fail.

No banner appears, and vendors that wait for consent send no requests. Skip this
check only if the page makes no initialization request at all, such as a
build-time manifest with no regional fallback. A helper that always loads, such
as `gtag` with its default `loadMode`, still loads; check that it reports denied
consent. A missing banner must never mean "allowed". Then undo the change and
confirm the page recovers.

## Check the interface

* Tab through the banner and dialog with the keyboard only. Focus stays inside
  a modal dialog and returns to the button that opened it when it closes.
* Set the viewport to 375 pixels wide and switch to a language with long
  labels, such as German.
* After applying your theme, check text contrast and that focus rings are
  visible.

## Record the result

Write down the framework, the rendering mode, the policy you tested, and the
requests you saw before and after consent. "The banner appears" is not a test
result. If something fails, [troubleshooting](/docs/guides/troubleshooting)
starts with three checks that locate most problems.

# Troubleshooting
URL: https://c15t.com/docs/guides/troubleshooting
Fix a missing banner, analytics that load before consent, choices lost on reload, CORS errors, hydration differences, failed manifest downloads, mode errors and failed static builds in c15t v3.

## Start with three checks

Most problems show up in one of these places. Run them before changing code.

1. **Which c15t is running.** In the browser console, run `window.c15t`. v3
   prints `{ version, pkg, mode, hosting }`, for example `mode: 'manifest'`
   from `@c15t/nextjs`. `hosting` is `'inth'` or `'self-hosted'` once the
   backend has answered `/init`, and `null` before then or without a backend. `undefined` means no c15t provider has mounted on this
   page. A `window.c15tStore` object means the page runs v2. With the script
   tag, `window.c15t` is the full browser API instead.
2. **The backend request.** In DevTools Network, filter by your backend URL.
   Look for `/init` or `/manifest` and check its status. A CORS error means
   the backend does not trust your site's origin.
3. **Consent state.** Add the c15t DevTools panel from your framework's guide.
   It shows the resolved policy, whether a prompt is needed, each category's
   permission and the scripts c15t manages.

Your framework's troubleshooting page covers adapter-specific failures, such
as Next.js prerendering errors or SvelteKit hydration.

## "Can't resolve 'c15t/next'" or a missing export

npm's `latest` tag still points to c15t v2, which has no framework entry
points. A plain `npm install c15t` therefore installs v2, and imports such as
`c15t/next`, `c15t/react` or `ConsentRoot` fail with "Package subpath is not
defined by exports" or "Module not found".

Install the v3 release and check the lockfile:

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha`|
|pnpm|`pnpm add c15t@alpha`|
|yarn|`yarn add c15t@alpha`|
|bun|`bun add c15t@alpha`|

Keep every c15t package, including `@c15t/integrations`, on the same release.
Mixing v2 and v3 packages is not supported.

## Why is there no banner?

No banner is sometimes correct. Find out which case you have:

|What DevTools shows|Cause|Fix|
|--|--|--|
|The backend request failed or has a CORS error|Wrong backend URL, or your origin is not trusted|Copy the URL from your Inth project exactly, including any path. Add the site's origin, such as `https://www.example.com` or `http://localhost:3000`, to the project's trusted origins.|
|Requests go to `your-project.inth.app` and fail|The placeholder backend URL from the guides is still in your code|Replace `https://your-project.inth.app` with the URL from your Inth project, including any path prefix.|
|No backend request at all|No provider mounted, the provider runs in offline mode, or the page resolved from a bundled manifest|Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](/docs/concepts/modes#set-the-backend-url) lists.|
|The policy resolved and no prompt is needed|The visitor's location maps to a policy without a prompt, such as a US state without a privacy law in the recommended rules|Expected. Test from a location that needs a prompt. Server helpers such as Next.js `resolveConsent` accept a `country` override for testing; remove it before you deploy.|
|The policy resolved and a choice is stored|A returning visitor|Expected. Clear site data or use a private window.|
|The banner is in the DOM but invisible or unstyled|c15t's rules are missing: `styles: false` without an imported stylesheet, a Content Security Policy that blocks c15t's `<style>` elements, Tailwind CSS 3's preflight, or a SvelteKit app without `c15tHandle`|See [stylesheets and CSS layers](/docs/customization/stylesheets) for how your framework loads c15t's rules.|

Do not "fix" a missing banner by granting every category or turning c15t off.
While the policy is unresolved, every optional category stays denied. Turning
the runtime off lets optional scripts load.

## Why does analytics load before the visitor chooses?

c15t only controls scripts you register with it. Find every other loader:

* A `<script>` tag in your HTML, layout or `_document`.
* A framework package or plugin, such as `@next/third-parties`,
  `@nuxt/scripts`, `nuxt-gtag` or a Vercel or Netlify analytics toggle.
* A tag in Google Tag Manager that fires on page view.
* An embed, such as a YouTube iframe, rendered without `ConsentGate`.

Remove the extra loader and register the vendor through
[integrations](/docs/integrations/overview). To replace a framework package,
follow [migrate from `@next/third-parties`](/docs/frameworks/next/scripts#migrate-from-nextthird-parties),
[migrate from `@nuxt/scripts`](/docs/frameworks/nuxt/scripts#migrate-from-nuxtscripts)
or [migrate from `nuxt-gtag`](/docs/frameworks/nuxt/scripts#migrate-from-nuxt-gtag).
Then reload with the Network panel open and cache disabled. The vendor's
domain should be absent until you allow its category.

Also check the policy. Under an opt-out policy, optional categories are allowed
before a choice, so the request is expected.

Google Tag and Google Tag Manager are an exception by design. By default
their helpers load before a choice and send Google Consent Mode signals, so a
request to Google before consent is expected. If you need no request at all
before consent, set `loadMode: 'after-consent'`; see
[Google Tag Manager](/docs/integrations/google-tag-manager#choose-when-the-container-loads).

## Why does the choice disappear on reload?

|Check|Fix|
|--|--|
|After saving, does DevTools Application show a `c15t` cookie and a `c15t` localStorage entry?|If not, look for `persistence: false` in your config. Examples use it on purpose; production apps should not.|
|Does the browser block storage, for example in a sandboxed iframe or a strict privacy mode?|The choice works for the current page only. Nothing to fix in your app.|
|Did the domain, subdomain or protocol change between visits?|Cookies and localStorage are per origin. Serve the site from one origin, or share the cookie across subdomains.|
|Did the policy change since the visitor chose?|A changed policy, a new required category or an expired choice prompts again. This is intended.|

Never save a choice automatically on page load to make persistence "stick".
That records consent the visitor did not give.

## Why does the page reload after saving preferences?

A visitor turned off a category or vendor they had allowed. Scripts that
already ran cannot be unloaded, so c15t reloads the page to start clean with
only permitted code. Set `reloadOnConsentRevoked: false` if you clean up
revoked vendors yourself; [clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup)
covers the options.

## Why does the server HTML differ from the browser?

Pass the value your framework's server helper returns to the provider
unchanged. Do not merge it with defaults or rebuild it from permissions. Make
sure the server and browser use the same backend URL, because two backends can
resolve different policies.

Never keep consent state in a module-level variable on the server. One
visitor's state can leak into another request. Create it per request, as the
framework guides do.

## Why does the build fail to download the manifest?

`manifest()` resolves from a policy snapshot that the build downloads from
`${backendURL}/manifest`. A production build stops when the download fails,
and dev logs the same message as a warning. Every framework uses the same
messages, prefixed with the integration's name, such as
`@c15t/nextjs/build`, `@c15t/core/build` (for `c15t/build`),
`@c15t/tanstack-start/build`, `@c15t/vue/vite`, `@c15t/svelte/vite`,
`@c15t/vue` (Nuxt) or `@c15t/astro`:

|Message|Cause|Fix|
|--|--|--|
|`could not fetch the consent manifest from <url> during the build (fetch failed: ...)`, with `ENOTFOUND`, `ECONNREFUSED` or another network error|The build cannot reach the backend|Build where the backend is reachable, or deploy with `C15T_ON_BUILD_ERROR=runtime`|
|`... (no response within 10 seconds)`|The backend did not answer in time|Check the backend, or build where it is reachable|
|`... (/manifest responded 404 Not Found)`, or another status|The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix|Copy the backend URL exactly as Inth shows it|
|`... (/manifest returned an invalid consent manifest.)`|The URL answered with something other than a consent manifest, such as an HTML page|Point the backend URL at the backend itself, not your site or a dashboard page|
|`no backend URL is set, so the build cannot fetch the consent manifest. Pass backendURL or set ...`|No `backendURL` option and no backend URL variable|Set the variable your framework reads; see [consent modes](/docs/concepts/modes#set-the-backend-url)|
|`skipped the consent manifest fetch because "/api/c15t" is not an absolute http(s) URL, so the server fetches the policy at runtime.`|A relative backend URL. A notice, not an error.|Pass the absolute backend URL. With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL.`|
|`C15T_ON_BUILD_ERROR must be 'runtime' or 'fail', received "..."`|The variable has another value|Set it to `runtime` or `fail`, or unset it|
|`onBuildError must be 'runtime' or 'fail', received "..."`|The option has another value|Pass `'runtime'` or `'fail'`|

Each failure message ends with what to do next. In a production build:
`` Set `C15T_ON_BUILD_ERROR=runtime` (or `onBuildError: 'runtime'`) to deploy with runtime fetching. ``
The Vite plugins add one more fix. The plugin can't see a mode set in app
code, so an app that uses `manifest({ manifestURL })` or
`manifest({ source: 'runtime' })` should pass `source: 'runtime'` to
`consentManifest()`, and the build skips the download.
A failed download never reuses an older snapshot. With
`C15T_ON_BUILD_ERROR=runtime`, the build finishes without a snapshot, and the
manifest is fetched at runtime. Dev warnings end with
`The server fetches it at runtime instead. A production build stops on this error.`

[Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
describes the policy and when the build skips the download.

### A single-page app warns that the policy depends on location

`consentManifest()` from `c15t/build` logs this warning when it downloads a
policy with location rules:

```txt
@c15t/core/build: the consent policy depends on the visitor's location, which the browser doesn't know. Unless you pass `inputs` or `geoURL` to `manifest()`, every first visit still calls the backend's /init, so the bundled policy adds bytes without saving a request. Consider `mode: hosted()` instead.
```

Pass the visitor's `{ country, region }` as `manifest({ inputs })` when your
edge knows it, or a `geoURL` that answers with it. Otherwise switch the mode
to `hosted()`, which asks `/init` without bundling the policy.

## Why does the provider say a mode is required?

The browser throws when a provider or `init()` gets no mode, or a mode name
instead of a factory:

|Message|Fix|
|--|--|
|`` @c15t/react ConsentProvider: `mode` is required. Use manifest() or hosted(). ``|Pass `mode`, such as `manifest()` from the same package. The start of the message names the package and the API that got no mode, such as `@c15t/svelte ConsentProvider` or `@c15t/core createConsentRuntime()`. Production builds name the package only: `` @c15t/react: `mode` is required. ``|
|`` @c15t/browser: `mode` must be a factory, such as manifest(), hosted() or offline() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds. ``|Import the factory and call it: `init({ mode: hosted() })`.|
|`` c15t: hosted() needs `backendURL`. Pass it, or add consentManifest() from c15t/build to your Vite config and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL). ``|The React `hosted()` found no backend URL. `@c15t/browser` throws the same message prefixed `@c15t/browser:`. A production build prints only the first sentence.|
|`` c15t: `mode` is the hosted() transport itself, so its code ships in the client bundle. Pass the hosted() your framework package exports instead: it is plain data, and the root loads the code only when it runs. ``|A warning outside production. A server-rendered root got a transport from `c15t/react`. Import the mode from your framework package. Next.js has its own wording; see [Next.js troubleshooting](/docs/frameworks/next/troubleshooting).|

## Why does the static build fail when development works?

A static host serves files only. Route handlers, server functions, rewrites
and proxies that worked under the dev server do not exist after deployment.
Point the browser at the absolute backend URL from Inth instead of a
same-origin `/api/c15t` path, then test the built output with a static file
server, not the dev server. [Choose your setup](/docs/concepts/choose-your-setup)
lists the static path for each framework.

## Why does the UI disappear with an ad blocker?

Check the Network panel for `ERR_BLOCKED_BY_CLIENT`. Some filter lists block
the consent backend's domain or old c15t chunk names such as
`consent-dialog-*.js`. Current releases use neutral chunk names; update and
rebuild. If the backend domain is blocked, the banner cannot load policy and
every optional category stays denied.

## Why does my theme do nothing?

Check that c15t's rules load, that you set a token or slot the
component actually reads, and that the state attribute you target is on the
element you style. A `data-variant` on the banner root is not on its card.
Check the Tailwind version and CSS layer order before adding specificity. See
[customization](/docs/customization/overview).

# Frameworks
URL: https://c15t.com/docs/frameworks
c15t setup guides for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, plain HTML and JavaScript.

## Pick your framework

|Framework|Package|Guide|
|--|--|--|
|Next.js|`c15t` (`c15t/next`)|[Next.js quickstart](/docs/frameworks/next/quickstart)|
|TanStack Start|`c15t` (`c15t/tanstack-start`)|[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart)|
|React|`c15t` (`c15t/react`)|[React quickstart](/docs/frameworks/react/quickstart)|
|Nuxt|`c15t` (`c15t/vue` Nuxt module)|[Nuxt quickstart](/docs/frameworks/nuxt/quickstart)|
|Vue|`c15t` (`c15t/vue/vue-plugin`)|[Vue quickstart](/docs/frameworks/vue/quickstart)|
|Astro|`c15t` (`c15t/astro`)|[Astro quickstart](/docs/frameworks/astro/quickstart)|
|Svelte|`@c15t/svelte`|[Svelte quickstart](/docs/frameworks/svelte/quickstart)|
|SvelteKit|`@c15t/svelte`|[SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart)|
|HTML, a CMS, a page builder or a static site generator|`@c15t/browser` from a script tag|[HTML quickstart](/docs/frameworks/html/quickstart)|
|JavaScript with a bundler, or your own UI|`@c15t/browser`, or `c15t` (`c15t/runtime`)|[JavaScript quickstart](/docs/frameworks/javascript/quickstart)|

Not sure which setup your rendering mode needs? [Choose your setup](/docs/concepts/choose-your-setup)
maps each app shape, such as a Next.js static export or a prerendered SvelteKit
site, to a guide.

## Install the right package

Most frameworks use one package, `c15t`, and import the framework entry point:
`c15t/next`, `c15t/react`, `c15t/vue` (the Nuxt module), `c15t/vue/vue-plugin`
(plain Vue), `c15t/astro` or `c15t/tanstack-start`.
You do not need `@c15t/nextjs` or `@c15t/react` as well; `c15t` depends on
them.

Svelte and SvelteKit use their own package, `@c15t/svelte`. HTML pages and the
stock UI in JavaScript use `@c15t/browser`. Vendor script helpers are a separate
install, `@c15t/integrations`, in every framework.

v3 is published under the `alpha` tag. Install `c15t@alpha`; a plain
`c15t` install still gets v2.

## After the quickstart

A banner on screen does not mean analytics wait for consent. Move existing
scripts into c15t, replace embeds that load on their own, and keep a link to
reopen preferences. Then [verify the integration](/docs/guides/verify-consent).

# Quickstart
URL: https://c15t.com/docs/frameworks/next/quickstart
Add c15t consent management to a Next.js App Router app with Inth, a build-time policy manifest and consent-gated scripts, then check it works. Links to the Pages Router and static export guides.

## Before you start

This quickstart sets up the App Router with a Next.js server, which is what
most Next.js apps use. Your build bundles the Inth project's public policy
manifest and your server resolves consent for each visitor, so the browser gets the answer
with the page and makes no `/init` request. Consent choices go to Inth.

Using the Pages Router, `output: 'export'` or cached pages? Find your app in
[Use another router or deployment](#use-another-router-or-deployment) first.

You need an [Inth](https://inth.com) project. Set its policy rules, add your
site's origin to its trusted origins, and copy its backend URL. The URL is
public configuration, not a secret. A
[self-hosted backend](/docs/self-host/quickstart) uses the same files with its
own URL.

The setup bundles your policy into the server at build time, the
recommended production setup. Rebuild after changing policies, translations
or vendors.

## Install c15t

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

There is no stylesheet to import. c15t's components render their own rules
as `<style>` elements. With Tailwind CSS 3, import the stylesheet
yourself and set `styles: false`, as
[Customize](/docs/frameworks/next/customize#load-the-stylesheet-yourself)
shows.

## Set the backend URL

Set your project's backend URL, including any path prefix, in `.env.local` and
in your host's build settings:

```sh title=".env.local"
NEXT_PUBLIC_C15T_BACKEND_URL=https://example-inth.inth.app
```

If your app already sets `NEXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

`https://example-inth.inth.app` is a demo project you can use to try the
setup. Next.js inlines `NEXT_PUBLIC_` variables at build time, so the build,
the server and the browser use the same URL, and changing the variable on a
built app has no effect until you rebuild.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

export default withConsentManifest(nextConfig);
```

`next build` and `next dev` fetch `${NEXT_PUBLIC_C15T_BACKEND_URL}/manifest`
and write the policy to `node_modules/.cache/c15t/`, outside your source tree.
`resolveConsent` reads it on its own, so you don't import it. `next start`
serves the built snapshot and fetches no policy. There is nothing to keep out
of Git.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

## Add the consent config

Create `c15t.config.ts` at the project root:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`withConsentManifest` finds this file, so `ConsentRoot` and `resolveConsent`
read it without an import. Export the config as the file's default export.
The file is bundled into the browser as well as the server, so it can hold
`scripts` but must hold no secrets.

The config sets no `mode`, so it uses `manifest()`: the server resolves each
visitor from the bundled policy. [Consent modes](/docs/concepts/modes) lists
the alternatives.

PostHog waits for measurement consent here. Replace `phc_your_project_key`
with your project key, or use the [integration](/docs/integrations/overview)
your application needs. `cookieless_mode: 'never'` disables cookieless capture
after rejection. Remove any existing PostHog loader, including `next/script`
and tag-manager entries, so the integration loads once.

## Resolve consent in the root layout

Render `ConsentRoot` in the root layout and pass it `resolveConsent()` without
awaiting it:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

The layout is a Server Component. `c15t/next` gives it `ConsentRoot`,
`ConsentBanner`, `ConsentDialog` and `ConsentDialogLink` as client components,
so you write no `'use client'` wrapper. `ConsentRoot` already wraps
`ConsentProvider`, so don't mount both.

Next.js renders the page without waiting for consent and sends the result
later in the same response. Until the browser applies it, the banner stays
hidden and optional categories stay denied. To send the banner in the first
HTML instead, see
[render the banner in the server HTML](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html).

## Check it works

Start the production build with `next build` and `next start`, then open the
site in a fresh browser session with DevTools open.

1. Under an opt-in policy, the banner appears and the Network panel shows no
   PostHog request.
2. Click **Reject All**, then reload. The banner stays closed and PostHog does
   not load.
3. Open **Privacy settings** in the footer and turn on **Analytics** (the
   `measurement` category). PostHog loads.
4. Open **Privacy settings** again and turn **Analytics** off. The page
   reloads and PostHog does not load again.
5. The browser makes no `/init` request, and choices post to
   `${backendURL}/subjects`.

If the banner does not appear, see
[why is there no banner](/docs/guides/troubleshooting#why-is-there-no-banner)
and [Next.js troubleshooting](/docs/frameworks/next/troubleshooting).
[Verify consent](/docs/guides/verify-consent) has the release checklist. A
visible banner alone does not prove that analytics wait for consent.

## Use another router or deployment

|Your app|Guide|
|--|--|
|App Router with a Next.js server|[App Router](/docs/frameworks/next/app-router), the full version of this quickstart|
|Pages Router with a Next.js server|[Pages Router](/docs/frameworks/next/pages-router)|
|`output: 'export'`, with either router|[Static export](/docs/frameworks/next/static-export)|
|Static, ISR or `'use cache'` pages, Cache Components, `ensureStatic`, or the banner in the first HTML|[Rendering and deployment](/docs/frameworks/next/rendering)|
|The fewest files, with consent resolved in the browser|[Client-side initialization](/docs/frameworks/next/client-side)|

`offline()` keeps policy in your code and choices in the browser, with no
consent records. Not recommended for production environments. See
[offline configuration](/docs/frameworks/next/data-fetching-reference#offline-configuration).

## Next steps

* [App Router](/docs/frameworks/next/app-router): the awaited layout, the
  consent route for static pages, and backend `/init` instead of the manifest.
* [Scripts](/docs/frameworks/next/scripts): more vendors and how each loads
  and revokes.
* [Customize](/docs/frameworks/next/customize): theme, layout and copy.
* [Runnable Next.js example](/docs/examples): this quickstart as an app you
  can run.

# App Router
URL: https://c15t.com/docs/frameworks/next/app-router
Set up c15t in the Next.js App Router with Inth, a build-time policy manifest, consent-gated scripts and a streamed or awaited root layout.

## Before you start

This guide uses [Inth](https://inth.com) for policies and consent records. Your
Next.js build bundles the project's public policy manifest. The server resolves consent
for each visitor. The browser sends consent choices to Inth.

A [self-hosted backend](/docs/self-host/quickstart) uses the same files with
its own URL. [Offline mode](/docs/frameworks/next/data-fetching-reference#offline-configuration)
keeps policy in your code and choices in the browser, with no consent records.
Not recommended for production environments.

This setup needs a Next.js server. For `output: 'export'`, follow
[static export](/docs/frameworks/next/static-export). For static, ISR or
`'use cache'` pages, Cache Components, or other rendering choices, start at
[rendering and deployment](/docs/frameworks/next/rendering).

Location-based policies need trusted location headers from your host. Without
them, c15t applies your unknown-location rule. See
[Forward geography headers](/docs/frameworks/next/geography-headers) before
you deploy.

## Install c15t and configure your backend

[Create an Inth project](https://inth.com), set its policy rules and add your
site's origin to its trusted origins. Copy the project's backend URL.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

There is no c15t stylesheet to import. The components render their own rules
as `<style>` elements, so no stylesheet request holds back the first paint.
With Tailwind CSS 3, import `c15t/next/styles.css` yourself and set
`styles: false` in `ConsentRoot`'s `options`, as
[Customize](/docs/frameworks/next/customize#load-the-stylesheet-yourself)
shows.

## Set the backend URL

Set `NEXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env.local` and in your host's build settings:

```sh title=".env.local"
NEXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `NEXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

Next.js inlines `NEXT_PUBLIC_` variables at build time, so the build, the
server and the browser use the same URL, and changing the variable on a built
app has no effect until you rebuild. To set the URL in code instead, pass
`backendURL` to `defineConsentConfig` and to `withConsentManifest`.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

## Add the consent config

Create `c15t.config.ts` at the project root, next to `next.config.ts`:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`withConsentManifest` finds the file, so `ConsentRoot`, `resolveConsent` and
the consent route read it without an import. Export the config as the file's
default export. The file is bundled into the browser as well as the server,
so it can hold `scripts` but must hold no secrets.

|Option|Default|Behavior|
|--|--|--|
|`backendURL`|`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`|Backend base URL. Choices post to `${backendURL}/subjects`.|
|`mode`|`manifest()`|`manifest()`, `hosted()` or `offline()` from `c15t/next`. See [consent modes](/docs/concepts/modes).|
|`routePrefix`|none|Where you mount the [consent route](#initialize-in-the-browser). Set it only when some pages resolve consent in the browser.|
|`proxy`|`false`|Send browser saves through the consent route too. See [optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).|
|`journey`|`'page'`|The consent journey scope.|
|`scripts`, `vendors`, `clearOnRevocation`, `networkBlocker`, `persistence`, `scriptLoader`, `options`|none|Browser options. `ConsentRoot` props of the same name win over them.|

PostHog waits for measurement consent here. Replace `phc_your_project_key`
with your project key, or use the [integration](/docs/integrations/overview)
your application needs. `cookieless_mode: 'never'` disables cookieless capture
after rejection. Remove any existing PostHog loader, including `next/script`
and tag-manager entries, so the integration loads once.

## Start consent resolution in the root layout

Render `ConsentRoot` in the root layout and pass it `resolveConsent()` without
awaiting it:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

The layout is a Server Component. `c15t/next` gives it `ConsentRoot`,
`ConsentBanner`, `ConsentDialog` and `ConsentDialogLink` as client components,
so you write no `'use client'` wrapper. `ConsentRoot` already wraps
`ConsentProvider`, so don't mount both.

`resolveConsent` reads the visitor's cookies and location headers and resolves
the policy from the bundled manifest. Next.js renders the page without waiting
and sends the result later in the same response. When the resolved policy
shows a banner, `ConsentBanner` renders on the server and arrives in that later
chunk, so it is visible before the page hydrates. Until the browser applies the
result after hydration, the dialog stays hidden, optional categories stay
denied, `ConsentGate` shows its placeholder and gated scripts do not load. The
browser makes no `/init` request.

To mount the banner after hydration instead, pass `streamBanner: false` in
`ConsentRoot`'s `options`.

A new visitor then sees the banner. A returning visitor with a valid stored
choice sees none, and the scripts that choice allows load. A choice that has
expired, was recorded under a different policy, or does not cover every
required category prompts again.

If the snapshot is missing and the runtime manifest request fails or takes
longer than `timeoutMs`, 500 ms by default, `resolveConsent` returns a
baseline state without a policy. The page has already rendered. The browser
retries after hydration, and gated scripts and embeds stay blocked until a
policy resolves. Pass `onError` to report these failures; see
[troubleshooting](/docs/frameworks/next/troubleshooting).

The layout calls `next/headers`, so routes under it render per request. With
`cacheComponents: true` the layout stays synchronous, and Next.js keeps the
page in the prerendered static shell. See
[Cache Components](/docs/frameworks/next/rendering#use-cache-components).

## Render the banner in the server HTML

To send the banner with the HTML, await `resolveConsent` in an async Server
Component and mount it inside `Suspense`:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import { Suspense } from 'react';
import type { ReactNode } from 'react';

import './globals.css';

const ResolvedConsent = async ({ children }: { children: ReactNode }) => {
	const state = await resolveConsent();

	return (
		<ConsentRoot state={state}>
			{children}
			<ConsentBanner />
			<ConsentDialog />
			<footer>
				<ConsentDialogLink>Privacy settings</ConsentDialogLink>
			</footer>
		</ConsentRoot>
	);
};

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<Suspense fallback={null}>
				<ResolvedConsent>{children}</ResolvedConsent>
			</Suspense>
		</body>
	</html>
);

export default RootLayout;
```

The server renders the consent subtree after the policy resolves, so the
banner arrives already decided and does not change after hydration. The page
content waits with it. Next.js streams an empty shell first and the page in a
later chunk of the same response. With runtime fetching, a slow manifest response keeps the page
blank for up to `timeoutMs`. If the request fails, the page renders without a
banner, optional categories stay denied, and the browser resolves the policy
after hydration.

The `Suspense` boundary is required with `cacheComponents: true`. Awaiting
request data in the root layout without it fails the build.
[Stream or await consent](/docs/frameworks/next/rendering#stream-or-await-consent-in-the-app-router)
compares the two layouts.

The banner renders its rules into the server HTML. `ConsentDialog` adds the
dialog's rules with its lazily loaded code, so they are not part of the first
page load.

## Initialize in the browser

Static, ISR and `'use cache'` pages are shared between visitors, so the server
cannot resolve consent into them. Render `ConsentRoot` without `state` in their
root layout:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ReactNode } from 'react';

import './globals.css';

// No resolveConsent: the browser resolves consent, so pages can be static.
const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<ConsentRoot>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

Without `state`, the browser resolves consent after hydration. Give it a
route on your origin that resolves the bundled policy with the browser
request's location headers. Set `routePrefix` in `c15t.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

// The backend URL comes from NEXT_PUBLIC_C15T_BACKEND_URL.
export default defineConsentConfig({ routePrefix: '/api/c15t' });
```

Then mount one catch-all route under it:

```ts title="app/api/c15t/[...c15t]/route.ts"
import { createConsentRoute } from 'c15t/next/api';

export const { GET } = createConsentRoute();
```

`createConsentRoute()` answers `GET /api/c15t/init` and
`GET /api/c15t/manifest` from the bundled snapshot. Any other path under
`/api/c15t` returns 404. To keep saves on your origin too, set `proxy: true`
in `c15t.config.ts` and pass `createConsentRoute({ proxy: true })`, which
forwards the remaining consent paths, such as `/subjects`, to the backend; see
[optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).

Without `routePrefix`, a page without `state` calls `${backendURL}/init`. The
HTML is the same for every visitor either way. To mix these pages with
server-rendered ones, see
[static, ISR and cached pages](/docs/frameworks/next/rendering#render-static-isr-and-cached-pages).

## Use backend init instead of the manifest

Set `mode: hosted()` in `c15t.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig, hosted } from 'c15t/next';

export default defineConsentConfig({ mode: hosted() });
```

Keep `withConsentManifest` in `next.config.ts`: it is what finds
`c15t.config.ts`. With `hosted()` it downloads no manifest, so `next build`
does not contact the backend. The layouts stay the same. `resolveConsent`
and the browser now call `${backendURL}/init`, and consent choices still go to
`${backendURL}/subjects`. Every visit makes a backend request, which the
manifest avoids. For a browser-only setup with no server work, follow
[client-side initialization](/docs/frameworks/next/client-side).

To keep `manifest()` but apply policy edits without a rebuild, use
`manifest({ source: 'runtime' })`. The server then fetches and caches the
policy, as
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data)
describes.

Keeping browser saves on your origin with
[`proxy: true`](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin) is optional with
either source. [Optimization](/docs/frameworks/next/optimization) also covers
manifest cache refresh and measured performance.

## Verify the setup

Start the production build with `next build` and `next start`, then open the
site in a fresh browser session with DevTools open.

1. Under an opt-in policy, the banner appears and the Network panel shows no
   PostHog request.
2. Click **Reject All**, then reload. The banner stays closed and PostHog does
   not load.
3. Open **Privacy settings** in the footer and turn on **Analytics** (the
   `measurement` category). PostHog loads.
4. Open **Privacy settings** again and turn **Analytics** off. The page reloads
   and PostHog does not load again.
5. The browser makes no `/init` request, and choices post to
   `${backendURL}/subjects`.

Test a new visitor and two locations. Requests without location headers
follow your unknown-location rule. [Script loading](/docs/frameworks/next/scripts)
explains each vendor's loading and revocation behavior, and
[the consent checks](/docs/guides/verify-consent) cover the release checklist.

# Pages Router
URL: https://c15t.com/docs/frameworks/next/pages-router
Set up c15t in the Next.js Pages Router with Inth, a build-time policy manifest, getServerSideProps and consent-gated scripts.

## Before you start

This guide uses [Inth](https://inth.com) for policies and consent records. Your
Next.js build bundles the project's public policy manifest. The server resolves consent
for each visitor in `getServerSideProps`, through `withConsentProps`. The browser sends consent choices to
Inth.

A [self-hosted backend](/docs/self-host/quickstart) uses the same files with
its own URL. [Offline mode](/docs/frameworks/next/data-fetching-reference#offline-configuration)
keeps policy in your code and choices in the browser, with no consent records.
Not recommended for production environments.

This setup needs a Next.js server. For `output: 'export'`, follow
[static export](/docs/frameworks/next/static-export).
[Rendering and deployment](/docs/frameworks/next/rendering) compares every
path.

Location-based policies need trusted location headers from your host. Without
them, c15t applies your unknown-location rule. See
[Forward geography headers](/docs/frameworks/next/geography-headers) before
you deploy.

## Install c15t and configure your backend

[Create an Inth project](https://inth.com), set its policy rules and add your
site's origin to its trusted origins. Copy the project's backend URL.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

## Set the backend URL

Set `NEXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env.local` and in your host's build settings:

```sh title=".env.local"
NEXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `NEXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

Next.js inlines `NEXT_PUBLIC_` variables at build time, so the build, the
server and the browser use the same URL, and changing the variable on a built
app has no effect until you rebuild.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

`withConsentProps()` and `createPagesConsentRoute()` read the snapshot
through the same alias. The wrapper adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages` for this: the Pages Router leaves
dependencies external on the server otherwise, and an external package does
not see the alias.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

## Add the consent config

Create `c15t.config.ts` at the project root, next to `next.config.ts`:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	routePrefix: '/api/c15t',
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`withConsentManifest` finds the file, so `ConsentRoot`, `withConsentProps` and
the consent route read it without an import. The file is bundled into the
browser as well as the server, so it can hold `scripts` but must hold no
secrets. The config sets no `mode`, so it uses `manifest()`; see
[consent modes](/docs/concepts/modes).

`routePrefix` names the consent route below. Pages without
`getServerSideProps` resolve consent in the browser through it.

PostHog waits for measurement consent here. Replace `phc_your_project_key`
with your project key, or use the [integration](/docs/integrations/overview)
your application needs.

## Add the consent API route

Create one catch-all API route under `routePrefix`:

```ts title="pages/api/c15t/[...c15t].ts"
import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute();
```

It answers `GET /api/c15t/init` and `GET /api/c15t/manifest` from the bundled
snapshot. With runtime fetching, it fetches `${backendURL}/manifest` and
caches the public policy. Any other path under `/api/c15t` returns 404, and
methods other than `GET` and `HEAD` get `405`. The file must be named
`[...c15t].ts`; for another name, pass the parameter as the second argument,
such as `createPagesConsentRoute({}, 'path')` for `[...path].ts`.

## Mount one root for every page

There is no c15t stylesheet to import. The components render their own rules
as `<style>` elements, so no stylesheet request holds back the first paint.
With Tailwind CSS 3, import `c15t/next/styles.css` yourself and set
`styles: false` in `ConsentRoot`'s `options`, as
[Customize](/docs/frameworks/next/customize#load-the-stylesheet-yourself)
shows.

Render `ConsentRoot` in `_app.tsx`. It reads the state a page resolved on the
server from `pageProps.consent`:

```tsx title="pages/_app.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ConsentPageProps } from 'c15t/next/pages';
import type { AppProps } from 'next/app';

import '@/styles/globals.css';

const App = ({ Component, pageProps }: AppProps<ConsentPageProps>) => (
	// Pages without getServerSideProps resolve consent in the browser.
	<ConsentRoot state={pageProps.consent}>
		<Component {...pageProps} />
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentRoot>
);

export default App;
```

A page with `withConsentProps` supplies `consent`. On any other page,
including static and `getStaticProps` pages, `consent` is undefined, and the
browser asks `/api/c15t/init` after hydration. That route resolves the
bundled policy with the browser request's location headers.

## Resolve consent in getServerSideProps

Export `withConsentProps()` from `c15t/next/pages` as the page's
`getServerSideProps`:

```tsx title="pages/index.tsx (partial)"
import { withConsentProps } from 'c15t/next/pages';

export const getServerSideProps = withConsentProps();
```

It resolves the visitor's consent from `c15t.config.ts` and adds it to the
page's props as `consent`, with `undefined` fields removed, as Next.js
requires. The page renders the banner in the server HTML, and the browser
applies the same state without an `/init` request.

A page with its own `getServerSideProps` passes it in:

```ts title="pages/posts/[slug].tsx (partial)"
export const getServerSideProps = withConsentProps(async ({ params }) => ({
	props: { post: await loadPost(params?.slug) },
}));
```

Consent resolves while the page's function runs, and its `redirect` and
`notFound` results pass through unchanged. `resolveConsent` options, such as
`timeoutMs`, go in the second argument.

Add `withConsentProps` to every page that should render consent on the
server. Do not resolve consent in `getStaticProps`. It runs without the
visitor's request, so it cannot read their cookies or location. If the
snapshot is missing and the runtime manifest request fails or takes longer
than `timeoutMs`, 500 ms by default, the page renders without a policy and the
browser retries after hydration.

## Use backend init instead of the manifest

Set `mode: hosted()` in `c15t.config.ts` and remove `routePrefix` and
`pages/api/c15t/[...c15t].ts`. Keep `withConsentManifest`, which finds the
config. With `hosted()` it downloads no manifest, so `next build` does not
contact the backend. `_app.tsx` and the pages stay the same. `withConsentProps` and the browser now call
`${backendURL}/init`, and consent choices still go to
`${backendURL}/subjects`. For a browser-only setup with no server work, follow
[client-side initialization](/docs/frameworks/next/client-side).

Keeping browser saves on your origin with
[`proxy: true`](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin) is optional with
either source.

## Verify the setup

Start the production build with `next build` and `next start`, then open a
page that exports `withConsentProps` in a fresh browser session with DevTools
open.

1. View the page source. It contains `data-testid="consent-banner-root"`.
2. Under an opt-in policy, the Network panel shows no PostHog request. Click
   **Reject All** and reload. The banner stays closed and PostHog does not
   load.
3. Open **Privacy settings** and turn on **Analytics** (the `measurement`
   category). PostHog loads.
4. Navigate to another page with a Next.js `Link` and reopen
   **Privacy settings**. The choice is still selected.
5. Open a static page directly. It shows the same choice, resolved in the
   browser through `/api/c15t/init`.

Pages with `withConsentProps` make no `/init` request, and choices post to
`${backendURL}/subjects`. [Script loading](/docs/frameworks/next/scripts)
explains each vendor's loading and revocation behavior, and
[the consent checks](/docs/guides/verify-consent) cover the release checklist.

# Static export
URL: https://c15t.com/docs/frameworks/next/static-export
Add c15t to a Next.js site built with output export, where the browser resolves consent through Inth without request helpers or API routes.

## Resolve consent in the browser

A site built with `output: 'export'` has no Next.js server at runtime. There is
no `/api/c15t` route, no rewrite, and no request for `resolveConsent` to read.
The browser calls your Inth backend directly and resolves consent after the
page loads. Static hosting still gets hosted policies and consent records.

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = { output: 'export' } satisfies NextConfig;

// Finds c15t.config.ts. A static export skips the manifest download.
export default withConsentManifest(nextConfig);
```

`withConsentManifest` finds your `c15t.config.ts`. With `output: 'export'` it
skips the manifest download, because no server would read the snapshot.

[Create an Inth project](https://inth.com), set its policy rules and add your
exported site's origin to its trusted origins. Copy the project's backend URL.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

## Share the backend URL

Set `NEXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env.local` and in your host's build settings. Keep it
absolute. A path such as `/api/c15t` would point at your static host, which
has nothing to answer it. `NEXT_PUBLIC_INTH_PROJECT_URL` works too; when both
are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

Create `c15t.config.ts` at the project root with `mode: hosted()`. Without a
server there is no consent route, so the browser calls `${backendURL}/init`.

```ts title="c15t.config.ts"
import { defineConsentConfig, hosted } from 'c15t/next';

// The browser asks the backend's /init. The backend URL comes from
// NEXT_PUBLIC_C15T_BACKEND_URL.
export default defineConsentConfig({ mode: hosted() });
```

Add your `scripts` to the same config, as the
[quickstart](/docs/frameworks/next/quickstart#add-the-consent-config) shows.

## Mount the root

There is no c15t stylesheet to import. The components render their own rules
as `<style>` elements, so no stylesheet request holds back the first paint.
With Tailwind CSS 3, import `c15t/next/styles.css` yourself and set
`styles: false` in `ConsentRoot`'s `options`, as
[Customize](/docs/frameworks/next/customize#load-the-stylesheet-yourself)
shows.

In the App Router, render `ConsentRoot` without `state` in the root layout:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ReactNode } from 'react';

import './globals.css';

// No resolveConsent: the browser resolves consent, so pages can be static.
const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<ConsentRoot>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

In the Pages Router, use the same `_app.tsx` as a server app. Exported pages
have no `getServerSideProps`, so `pageProps.consent` is undefined:

```tsx title="pages/_app.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ConsentPageProps } from 'c15t/next/pages';
import type { AppProps } from 'next/app';

import '@/styles/globals.css';

const App = ({ Component, pageProps }: AppProps<ConsentPageProps>) => (
	// Pages without getServerSideProps resolve consent in the browser.
	<ConsentRoot state={pageProps.consent}>
		<Component {...pageProps} />
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentRoot>
);

export default App;
```

Without server state, `ConsentRoot` initializes in the browser. Backend
`/init` reads the visitor's location from its own request, so location-based
policies depend on the backend host's geography headers, not on your static
host.

## What happens before initialization

The exported HTML is the same for every visitor and cannot contain one
visitor's consent. After the page loads, the browser restores the stored choice
and requests the policy from `/init`. Until the policy resolves, optional
categories stay denied and the banner stays hidden. Do not add an unconditional
analytics script to the exported HTML to work around that wait.

## Test the exported files

Run `next build` and serve the generated `out/` directory with a static file
server. `next dev` can hide a dependency on an API route that the export does
not have. Then open the site in a fresh browser session with DevTools open.

1. The Network panel shows `/init` and `/subjects` requests to your backend's
   origin, and no failed same-origin `/api/c15t` request.
2. Under an opt-in policy, the banner appears and no PostHog request runs.
   Click **Reject All** and reload. The banner stays closed and PostHog does
   not load.
3. Open **Privacy settings** and turn on **Analytics** (the `measurement`
   category). PostHog loads.
4. Block the backend's domain in DevTools and reload in a fresh session. No
   banner appears and no vendor loads.

A browser error about CORS means the backend does not trust the exported
site's origin. Add it to your Inth project's trusted origins. See
[the consent checks](/docs/guides/verify-consent) for the release checklist.

## Other static options

A same-origin `/api/c15t` URL needs a proxy at your host, because Next.js
rewrites need a server. Without one, keep the absolute backend URL.

To resolve a manifest in the browser instead, set
`mode: manifest({ resolve: 'browser', manifestURL })` with an absolute
`manifestURL` the browser can fetch, such as
`https://your-project.inth.app/manifest`. Browser resolution has no location
input of its own, so location-based policies call the backend's `/init`
unless you pass `geoURL`. `c15t/next/static` has lower-level helpers that
resolve a bundled manifest; see
[static manifest helpers](/docs/frameworks/next/data-fetching-reference#static-manifest-helpers).

Offline mode stores choices only in the browser and records nothing. Not
recommended for production environments. Static hosting alone is not a reason
to use it; see
[offline configuration](/docs/frameworks/next/data-fetching-reference#offline-configuration).

# Client-side initialization
URL: https://c15t.com/docs/frameworks/next/client-side
Initialize c15t in the browser in a Next.js app with hosted() mode, without server prefetch, a consent route or API handlers.

## When to initialize in the browser

This setup has the fewest files. The browser calls your Inth backend's `/init`
after the page loads, so the server does no consent work and every page can be
static. The HTML is the same for every visitor, and the banner appears after
hydration.

Use it when you do not need the banner in the server HTML and do not want a
consent route. For a server app, the [App Router](/docs/frameworks/next/app-router)
and [Pages Router](/docs/frameworks/next/pages-router) guides resolve consent
on the server and make no `/init` request per visit. For `output: 'export'`,
follow [static export](/docs/frameworks/next/static-export).
[Rendering and deployment](/docs/frameworks/next/rendering) compares every
path.

Until the policy resolves, optional categories stay denied and the banner
stays hidden.

## Configure the backend and the mode

[Create an Inth project](https://inth.com), set its policy rules and add your
site's origin to its trusted origins. A self-hosted backend works the same way
with its own URL.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

Set `NEXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env.local` and in your host's build settings:

```sh title=".env.local"
NEXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `NEXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NEXT_PUBLIC_C15T_BACKEND_URL` wins.

Create `c15t.config.ts` at the project root with `mode: hosted()`:

```ts title="c15t.config.ts"
import { defineConsentConfig, hosted } from 'c15t/next';

// The browser asks the backend's /init. The backend URL comes from
// NEXT_PUBLIC_C15T_BACKEND_URL.
export default defineConsentConfig({ mode: hosted() });
```

`hosted()` initializes through `${backendURL}/init` and posts choices to
`${backendURL}/subjects`. Add your `scripts` to the same config, as the
[quickstart](/docs/frameworks/next/quickstart#add-the-consent-config) shows.
The file is bundled into the browser, so it must hold no secrets.

Wrap `next.config.ts` in `withConsentManifest`, which finds `c15t.config.ts`:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

With `hosted()` it downloads no manifest, so `next build` does not contact the
backend.

## Mount the root without state

The components render their own styles. With Tailwind CSS 3,
[load the stylesheet yourself](/docs/frameworks/next/customize#load-the-stylesheet-yourself).
In the App Router, render `ConsentRoot` in the root layout without `state`:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ReactNode } from 'react';

import './globals.css';

// No resolveConsent: the browser resolves consent, so pages can be static.
const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<ConsentRoot>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

In the Pages Router, render it in `_app.tsx`. Without `withConsentProps`,
`pageProps.consent` is undefined on every page:

```tsx title="pages/_app.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ConsentPageProps } from 'c15t/next/pages';
import type { AppProps } from 'next/app';

import '@/styles/globals.css';

const App = ({ Component, pageProps }: AppProps<ConsentPageProps>) => (
	// Pages without getServerSideProps resolve consent in the browser.
	<ConsentRoot state={pageProps.consent}>
		<Component {...pageProps} />
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentRoot>
);

export default App;
```

Without server state, `ConsentRoot` initializes in the browser. Keep it
mounted across client navigation.

## Optional same-origin requests

With `routePrefix` and `proxy: true` in `c15t.config.ts` and a consent route
that forwards saves, the browser sends every consent request to your own
origin, which saves it a separate connection to the backend's domain. It
needs a Next.js server. See
[optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).

## Verify browser initialization

Open the production build in a fresh browser session with DevTools open.

1. The browser calls `${backendURL}/init` once, then shows the banner. No
   PostHog request runs.
2. Click **Reject All** and reload. The banner stays closed and PostHog does
   not load.
3. Open **Privacy settings**. The rejection is still selected. Turn on
   **Analytics** (the `measurement` category); PostHog loads.
4. Block the backend's domain in DevTools and reload in a fresh session. No
   banner appears and no vendor loads. A hidden banner is not permission.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/next/rendering
Choose how Next.js resolves consent for your router, rendering mode and hosting, from streamed App Router layouts to static export, ISR, Cache Components and ensureStatic.

## Pick your rendering path

Find the row that matches your app. Most App Router apps with a Next.js server
use the first row.

For server deployments, use the recommended
[build-time manifest](/docs/frameworks/next/optimization#bundle-the-manifest-during-builds)
with either router. A fresh server resolves from the deployment's snapshot;
policy changes require a rebuild.

|Your app|Where consent resolves|Banner in the server HTML|Recipe|
|--|--|--|--|
|App Router with a Next.js server|Root layout starts `resolveConsent` and streams the result|Yes, in a later chunk, before hydration. The page renders without waiting.|[Stream consent](/docs/frameworks/next/app-router#start-consent-resolution-in-the-root-layout)|
|App Router, the page must arrive with its banner|Root layout awaits `resolveConsent` inside `Suspense`|Yes. The page waits for consent.|[Await consent](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html)|
|App Router with `cacheComponents: true`|Either layout above. Never await in the layout itself.|Yes, with either layout|[Cache Components](#use-cache-components)|
|Static, ISR or `'use cache'` pages|Browser, `ConsentRoot` without `state`|No|[Static, ISR and cached pages](#render-static-isr-and-cached-pages)|
|Routes that set `ensureStatic`|`'shell'` or `'prefetch'`: either App Router layout. `'navigation'`: browser, without `state`|Same as the layout you use|[Keep pages static with `ensureStatic`](#keep-pages-static-with-ensurestatic)|
|Pages Router with `getServerSideProps`|`withConsentProps` from `c15t/next/pages`|Yes|[Pages Router](/docs/frameworks/next/pages-router#resolve-consent-in-getserversideprops)|
|Pages Router pages without `getServerSideProps`|Browser, through the same `_app.tsx` and the consent API route|No|[Pages Router](/docs/frameworks/next/pages-router#mount-one-root-for-every-page)|
|`output: 'export'`|Browser, calling the backend directly|No|[Static export](/docs/frameworks/next/static-export)|
|A server app that should skip server work and local routes|Browser, calling backend `/init` with `mode: hosted()`|No|[Client-side initialization](/docs/frameworks/next/client-side)|
|Edge runtime|Not covered by an example or test|Not covered|[Edge runtime](#edge-runtime)|

Server rendering puts the visitor's answer in the first response. The browser
then applies it without another request, so gated scripts can load as soon as
the page hydrates. Browser rendering sends the same HTML to every visitor and
resolves consent after the page loads. In both cases optional categories stay
denied, and the banner stays hidden, until a policy has resolved.
[Choose your setup](/docs/concepts/choose-your-setup) explains this across
frameworks.

## Stream or await consent in the App Router

Both App Router layouts call `resolveConsent` from `c15t/next/server` in the
root layout. They differ in what waits for it.

|Layout|What the visitor gets|Cost|
|--|--|--|
|Streamed, the default|The page renders at once. The banner follows in a later chunk of the same response and shows before hydration. The dialog, gated scripts and embeds wait for the browser to apply the result.|The banner is a separate streamed reveal, which React can hold for up to 300 ms after an earlier one.|
|Awaited inside `Suspense`|The banner is in the server HTML and does not change after hydration.|The page content streams after consent resolves, in a later chunk of the same response.|

The streamed layout passes the pending promise to `ConsentRoot`, so a slow or
failed manifest request never holds the page. Start with it.

The awaited layout moves the page inside the consent boundary. With runtime
fetching, a slow manifest response keeps the page blank for up to `timeoutMs`,
500 ms by default. React
can also hold a streamed boundary's reveal for up to 300 ms after the browser's
first paint or an earlier boundary's reveal, even with a warm manifest cache.
`<SpeedInsights />` from `@vercel/speed-insights` is one such boundary, because
it wraps itself in `Suspense`. Choose the awaited layout only when the page
and its banner must arrive together, and measure the page.

Without `cacheComponents`, you can also make the root layout itself async and
await `resolveConsent` there. The page and the banner then arrive together, but
the response starts only after consent resolves.

## Use Cache Components

With `cacheComponents: true`, Next.js prerenders a static shell and fills
request-time parts per request. Both App Router layouts work:

* The streamed layout stays synchronous. The page content stays in the static
  shell and consent resolves per request.
* The awaited layout needs its `Suspense` boundary. Awaiting request data in
  the root layout without one fails the build with a
  `blocking-prerender-dynamic` error. The page content moves into the
  per-request part.

Next.js suggests `export const instant = false` to fix that error. Don't use it
for consent. It only turns the check off. The layout still waits for consent
before it sends anything, so every route under it renders per request with no
static shell. Add the `Suspense` boundary instead.

With `partialPrefetching: true`, prefetches never resolve consent.
`resolveConsent` calls `connection()` before it reads the request, and
`connection()` never finishes during a prefetch. A `<Link prefetch={true}>`
that renders the layout on the server stops there. Consent resolves once, for
the page load. Client navigation keeps the same root layout, so it does not
resolve again.

`ConsentGate` does not read the clock while rendering, so a page that renders
it can stay in the static shell without its own `Suspense` boundary.

Cache Components rejects `export const revalidate`. Cache page content with
`'use cache'` and `cacheLife` instead, and resolve consent for those pages in
the browser as described in the next section.

Two Cache Components issues have their own pages. A per-request CSP nonce does
not work with a prerendered shell; see
[Content Security Policy](/docs/frameworks/next/content-security-policy). If
`next dev` reports an unstable `Date.now()` at the `resolveConsent` call, see
[troubleshooting](/docs/frameworks/next/troubleshooting#why-does-nextjs-report-an-unstable-datenow-during-prerendering).

## Render static, ISR and cached pages

`resolveConsent` reads the request's cookies and headers. A layout that calls
it makes every route under it dynamic. A static, ISR or `'use cache'` page is
shared between visitors, so it cannot contain one visitor's consent. Resolve
consent for those pages in the browser:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ReactNode } from 'react';

import './globals.css';

// No resolveConsent: the browser resolves consent, so pages can be static.
const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<ConsentRoot>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

Without `state`, `ConsentRoot` resolves the visitor's consent after
hydration. The page can be static, use `export const revalidate` for ISR, or
use `'use cache'`. Set `routePrefix: '/api/c15t'` in `c15t.config.ts` and
mount the consent route from the
[App Router guide](/docs/frameworks/next/app-router#initialize-in-the-browser).
The browser then asks `/api/c15t/init`, which resolves the bundled policy on
your server with the browser request's location headers. Without
`routePrefix`, the browser asks `${backendURL}/init`.

For a whole app of static pages, use this as the only root layout. To mix
static pages with server-rendered ones, give each kind its own root layout in
a route group, such as `app/(site)/layout.tsx` with the streamed layout and
`app/(static)/layout.tsx` with this one. Moving between two root layouts loads
the whole page. The visitor's choice survives because c15t stores it in a cookie and
localStorage.

To resolve the policy in the browser itself, set
`mode: manifest({ resolve: 'browser' })`. The browser then loads the resolver
and fetches `${routePrefix}/manifest`. It has no location input of its own,
so a location-based policy still asks `/init` unless you pass `geoURL`. See
[consent modes](/docs/concepts/modes#manifest).

## Keep pages static with `ensureStatic`

Next.js 16.4 adds the
[`ensureStatic`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic)
route segment config. It tells Next.js which parts of a route must stay
static, so the server does no per-request work for them. Which level you can
use depends on your consent layout:

|`ensureStatic`|Streamed layout|Awaited layout|Browser layout|
|--|--|--|--|
|`'shell'`|Works|Works, but links show only the `Suspense` fallback before the click|Works|
|`'prefetch'`|Works|Works, but links show only the `Suspense` fallback before the click|Works|
|`'navigation'`|Build fails|Build fails|Works|

Every level needs `cacheComponents: true`. `'shell'` and `'prefetch'` also
need `partialPrefetching: true`. At both levels, prefetches never resolve
consent, including a `<Link prefetch={true}>` under `'shell'`, as
[Use Cache Components](#use-cache-components) explains. One visitor's consent
never ends up in a prefetch or in static output. Use the streamed layout if
prefetched pages should show their content before the click.

`'navigation'` requires the whole route to be static, including the root layout
above the page. A layout that calls `resolveConsent` reads the request, so the
build fails. Give those pages the browser layout in their own route group, as
[Static, ISR and cached pages](#render-static-isr-and-cached-pages) shows.

Don't wrap `resolveConsent` in `'use cache'` to get past the error. It reads
the visitor's cookies, and a cached result would show one visitor's consent to
everyone.

## Choose how the server gets the policy

The rendering path decides when consent resolves. The `mode` in
`c15t.config.ts` decides where the policy comes from.

|Source|Config|Use it when|
|--|--|--|
|Build-time manifest, recommended|`manifest()`, the default, with `withConsentManifest`|Your app has a Next.js server and policy changes ship with a rebuild.|
|Cached manifest|`manifest({ source: 'runtime' })`|Policy changes must apply without a rebuild.|
|Backend `/init`|`hosted()`|You want the fewest moving parts, or you export a static site.|
|Offline|`offline()`|Local development and tests. Not recommended for production environments.|

With a build-time manifest, your Next.js server resolves each visitor locally
without fetching policy. With runtime caching, warm requests make no policy
request to the backend, but an empty cache fetches upstream.
With backend `/init`, every server render or browser initialization
asks the backend to resolve the visitor. Consent saves go to
`${backendURL}/subjects` either way.

Offline mode keeps policy in your code and choices in the browser, with no
consent records. It runs only with `mode: offline()`; without a backend URL,
`manifest()` and `hosted()` throw. See
[offline configuration](/docs/frameworks/next/data-fetching-reference#offline-configuration).

The [fetching reference](/docs/frameworks/next/data-fetching-reference#mode-combinations)
lists what each mode does on the server and in the browser, and
[consent modes](/docs/concepts/modes) compares them across frameworks.

## Get the visitor's location

Location-based policies need trusted location headers from your host, such as
`x-vercel-ip-country` or `cf-ipcountry`. Without them, c15t applies your
unknown-location rule. Some hosts pass those headers to `proxy.ts` but strip
them before Server Components run. Add `c15tProxy` from `c15t/next/proxy` in
that case, as [Forward geography headers](/docs/frameworks/next/geography-headers)
shows. A static export has no server and cannot read location headers.

## Keep browser requests on your origin

`proxy: true` in `c15t.config.ts`, with a consent route that forwards saves,
sends the browser's saves through `/api/c15t` instead of the backend's domain.
It is optional, saves the browser a separate connection, and changes nothing
about when consent resolves. It needs a Next.js server. See
[Optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).

## Use a src directory

With `src/`, keep `c15t.config.ts` at the project root, next to
`next.config.ts`: `withConsentManifest` looks for it there and nowhere else.
Put `proxy.ts` under `src/` next to `src/app` or `src/pages`, as Next.js
requires.

## Edge runtime

No c15t example or compatibility test runs on the Edge runtime. What is known:

* `c15t/next/pages` takes the Node.js `req` and `res` from `getServerSideProps`
  and `pages/api` routes, so it needs the Node.js runtime.
* The App Router examples and tests run `resolveConsent` and the route handlers
  from `c15t/next/api` on the default Node.js runtime.

Keep the default runtime for layouts, pages and route handlers that use c15t.
If you set `export const runtime = 'edge'` on them, test the result yourself.

## Keep server and browser state aligned

Pass the `resolveConsent` result to `ConsentRoot` unchanged. Both read the
same `c15t.config.ts`, so they agree on the mode and the journey. The result
carries the
resolved policy, the stored records and the evaluation time. Replacing it with a
browser preset, or turning allowed categories into saved choices during
hydration, can change the first render's permissions or prompt. Keep one
`ConsentRoot` mounted across client navigation.

With server state, `ConsentGate` renders the placeholder for a denied category
in the server HTML. A granted category gets an empty wrapper, and the embed
mounts after hydration, so an iframe loads once even when the page streams
inside `Suspense`. See [ConsentGate](/docs/frameworks/next/components/consent-gate).

If the server request fails or runs past `timeoutMs`, `resolveConsent` returns
a baseline state without a policy. The page still renders, optional categories
stay denied, and the browser retries after hydration. See
[troubleshooting](/docs/frameworks/next/troubleshooting).

With `mode: offline()`, or with no backend URL at all, `resolveConsent()`
makes no backend request. It returns the visitor's stored records, location,
language and privacy signals, with no resolved policy.

## Taps before hydration

A banner in the server HTML shows before the page's JavaScript runs. On a slow
phone that gap can last seconds. The stock `ConsentBanner` puts a small inline
script in front of its buttons that holds an Accept all, Reject all, notice
dismiss or Customize tap made in that gap. Accept, reject and dismiss hide the
banner at once. When the banner hydrates and the runtime has started, c15t
records the choice with the time of the tap, saves it and loads the scripts it
allows; Customize opens the dialog.

A tap made on a banner for one model or prompt is dropped when the browser
resolves another, and the banner shows again. A banner you build from hooks
has no inline script, so a tap before hydration does nothing there, and a
page with two stock banners holds no early taps at all. Neither
does a button in a composed `ConsentBanner` that has its own `onClick`,
`asChild`, `type="submit"` or `performDefaultAction={false}`, so your handler,
link or form still decides that tap. A tap on a banner with its own `uiSource`
is recorded with that source. Under a
Content Security Policy the script needs `options.nonce`; see
[Content Security Policy](/docs/frameworks/next/content-security-policy).

## Cache policy, never visitor state

A manifest is public policy configuration, so your server and CDN can cache it.
A resolved state, a stored record and HTML rendered with them belong to one
visitor. Keep them out of shared caches. Do not cache a route whose layout
awaits `resolveConsent`, and do not store `resolveConsent` results under a
shared key. The prerendered static shell under Cache Components holds no
visitor state, so Next.js can cache it.

## Verify your rendering path

1. Run `next build` and read the route table. Routes under a layout that calls
   `resolveConsent` show as dynamic, or partial with Cache Components. Static
   and ISR pages under the browser layout stay static.
2. View the page source in a fresh session. The awaited layout and Pages Router
   `getServerSideProps` pages contain `data-testid="consent-banner-root"`. The
   streamed and browser layouts do not.
3. In DevTools Network, confirm no vendor request runs before you choose.
   With a manifest, server-rendered pages make no `/init` request.
4. Reject, reload, and confirm the banner stays closed and vendors stay blocked.
   Reopen Privacy settings and confirm the rejection is still selected.
5. Test two locations if your policies differ by region.

The [consent checks](/docs/guides/verify-consent) cover the rest.

# Upgrade from v2
URL: https://c15t.com/docs/frameworks/next/upgrade-v3
Upgrade a Next.js app from c15t v2 (@c15t/nextjs) to v3. Covers packages, ConsentRoot or ConsentProvider, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.

**Upgrade this Next.js app to c15t v3**

Paste into Claude Code, Codex, Cursor or another coding agent at the root of your app.

```prompt
Upgrade this Next.js app from c15t v2 to c15t v3.

Read [https://v3.c15t.com/docs/frameworks/next/upgrade-v3.md](https://v3.c15t.com/docs/frameworks/next/upgrade-v3.md) first and follow it in order. Do not guess v3 APIs from memory.

1. List every c15t dependency and import: `@c15t/nextjs`, `@c15t/react`, `@c15t/scripts`, `@c15t/dev-tools` and `c15t`. Note whether the app uses the App Router, the Pages Router or both.
2. Check that React is 18 or later and Next.js is 15 or later. Stop and tell me if either needs a major upgrade.
3. Replace the packages with `c15t@alpha`, plus `@c15t/integrations@alpha` if the app uses vendor helpers.
4. Run `npx @c15t/cli@alpha codemods packages-to-c15t consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks scripts-to-integrations dev-tools-to-c15t policy-packs-to-policy-rules callbacks-to-v3 theme-to-consent-theme iab-option-to-iab-provider css-variables-to-v3 postcss-tailwind3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
5. If the app used `fetchInitialData()`, `C15tPrefetch` or `ssrData`, move it to `ConsentRoot` with `resolveConsent()`. Otherwise keep browser initialization with the `ConsentProvider` and `hosted()` the codemod wrote.
6. Update callbacks, policy presets, renamed options and components, theme CSS, CSS variables and IAB setup as the guide describes.
7. Keep the existing backend URL. If the app runs its own c15t backend, stop and tell me, because it has to be upgraded in the same release with [https://v3.c15t.com/docs/self-host/upgrade-v3.md](https://v3.c15t.com/docs/self-host/upgrade-v3.md).
8. Run the typecheck and build, and resolve every `TODO(c15t v3)` comment.

When you finish, list the files you changed, anything you could not migrate, and how you checked that vendor requests still wait for consent.
```

## Before you start

* Upgrade React and React DOM to 18 or later, and Next.js to 15 or 16.
* If you run your own c15t backend, upgrade it in the same release. A v3
  client can't read a v2 backend. See
  [Upgrade a self-hosted backend](/docs/self-host/upgrade-v3).
  Inth-hosted backends need no change.

## Replace the packages

Remove `@c15t/nextjs`, `@c15t/react` and `@c15t/scripts`, then install `c15t`
from the `alpha` dist-tag. npm's default tag still resolves v2.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

Drop `@c15t/integrations@alpha` if you don't use its vendor helpers.

|v2 import|v3 import|
|--|--|
|`@c15t/nextjs`|`c15t/next`. Server helpers are in `c15t/next/server`, `c15t/next/pages` and `c15t/next/api`.|
|`@c15t/react`|`c15t/next`, which re-exports the React components and hooks|
|`@c15t/nextjs/styles.css`|Nothing: remove the import. Keep `c15t/next/styles.css` only with `styles: false`|
|`DevTools` from `@c15t/dev-tools/react`|`DevTools` from `c15t/next/devtools`|
|`@c15t/scripts/*`|`@c15t/integrations/*`|

The `packages-to-c15t` codemod rewrites the `@c15t/nextjs` and `@c15t/react`
imports and removes the stylesheet imports. It doesn't edit `package.json`.

`@c15t/nextjs` is still published at v3, so its imports keep working if you
pin it to `@alpha`. These docs use `c15t/next`.

Every v3 package ships ESM only. If a CommonJS file in your app calls
`require()` on a c15t package, convert it to ESM.

## Rename the integrations dependency

v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts`
from your dependencies and install `@c15t/integrations` from the `alpha`
dist-tag:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

Replace the package name in each import. Vendor subpaths and helper names stay
the same.

Before, in v2:

```ts
import { googleTagManager } from '@c15t/scripts/google-tag-manager';
import { posthog } from '@c15t/scripts/posthog';
```

After:

```ts
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { posthog } from '@c15t/integrations/posthog';
```

The `scripts` configuration option and the `Script` type keep their names.

Two helper behaviors change. A helper that needs an ID, such as `metaPixel`,
`googleTagManager` or `posthog`, now logs an error and skips its script when
the ID is empty or only whitespace, where v2 loaded a broken script. And if
your code reads `@c15t/integrations/registry`, an entry's `consentCategory` can
now be a compound condition such as `{ and: ['marketing', 'measurement'] }`,
not only a category name.

`@c15t/scripts` stays available as a deprecated compatibility package for all
of v3. It re-exports the implementation and types of `@c15t/integrations`, so
you can migrate imports separately from the rest of the upgrade. Compatibility
ends in v4; versions already published stay on npm.

To preview the import changes in JavaScript and TypeScript files:

```bash
npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
```

Review the output, then run it again without `--dry-run`. The codemod runs
only when you name it. It does not change `package.json`, lockfiles, or
imports inside `.vue`, `.svelte` or `.astro` files; update those by hand, then
reinstall dependencies and build the app.

## Replace `useConsentManager()`

`useConsentManager()` returned the whole consent state, so every component
that called it re-rendered on every change. v3 has one hook per field. Run the
codemod first:

```bash
npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
```

Review the proposed files, then run it again without `--dry-run`. For this v2
component:

```tsx title="Before (v2): components/accept-button.tsx"
import { useConsentManager } from '@c15t/react';

export function AcceptButton() {
	const { activeUI, has, saveConsents } = useConsentManager();
	if (activeUI !== 'banner' || has('marketing')) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

the codemod writes:

```tsx title="After (v3): components/accept-button.tsx"
import { useActiveUI, useConsent } from '@c15t/react';
import { useHeadlessConsentUI } from '@c15t/react/headless';

export function AcceptButton() {
	const activeUI = useActiveUI() ?? 'none';
	const hasMarketing = useConsent('marketing');
	const { saveCustomPreferences: saveConsents } = useHeadlessConsentUI();
	if (activeUI !== 'banner' || hasMarketing) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

The codemod keeps the entry you imported from. Change `@c15t/react` to
`c15t/react` afterwards if you moved to the umbrella package. Fields it cannot
rewrite stay on a `useConsentManager()` call under a `TODO(c15t v3)` comment,
which fails the build until you replace them. The table lists the v2 fields
components read. The other fields held provider configuration, such as
`legalLinks`, `scripts` and `storageConfig`, or store internals; set
configuration through `ConsentProvider` props.
Import hooks from `c15t/react`, `c15t/next` or `c15t/tanstack-start`, and
`useHeadlessConsentUI` from the matching `/headless` entry.

|v2 field|v3 replacement|
|--|--|
|`activeUI`|`useActiveUI()`. It returns `null` until c15t picks a surface, where v2 returned `'none'`.|
|`setActiveUI(ui)`|`useSetActiveUI()`|
|`has(category)`|`useConsent(category)`, one call per category at the top of the component|
|`consents`|`useConsents()`|
|`saveConsents('all')`|`useHeadlessConsentUI().saveCustomPreferences('all')`|
|`saveConsents('necessary')`|`useHeadlessConsentUI().saveCustomPreferences('none')`|
|`saveConsents('custom')`|`useConsentDraft().save()`, or `useHeadlessConsentUI().saveCustomPreferences()` inside a `ConsentDraftProvider`|
|`selectedConsents`|`useConsentDraft().values`|
|`setSelectedConsent(name, value)`|`useConsentDraft().set(name, value)`|
|`setConsent(name, value)`|`useSaveConsents()`, called with `{ [name]: value }`|
|`consentInfo`|`useExplicitChoice()`|
|`hasConsented()`|`useExplicitChoice() !== null`|
|`consentCategories`, `consentTypes`, `getDisplayedConsents()`|`useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`|
|`policyCategories`|`usePolicyCategories()`. The v2 list started with `'necessary'`; this one does not.|
|`policyScopeMode`|`usePolicyScopeMode()`|
|`policyBanner`|`usePromptPresentation()`|
|`policyDialog`|`usePreferencesPresentation()`|
|`model`|`useModel()`. It returns `null` while no policy matches, where v2 returned `'opt-in'`.|
|`branding`|`useBranding()`. It returns `null` when unset, where v2 returned `'c15t'`.|
|`iab`|`useIABSnapshot()`|
|`locationInfo`|`useLocation()`|
|`overrides`, `setOverrides()`|`useOverrides()`, `useSetOverrides()`|
|`setLanguage()`|`useSetLanguage()`|
|`user`, `identifyUser()`|`useUser()`, `useIdentify()`|
|`translationConfig`|`useTranslations()` for the active strings|
|`subscribeToConsentChanges(listener)`|`useSubscribeToConsentChanges()`, or the `onPermissionsChanged` callback|
|`updateConsentCategories(categories)`|`useRegisterConsentCategories()`|
|`manager`|Nothing. Use the hooks above.|

`saveCustomPreferences()` saves the way the stock buttons do. It closes the
banner or dialog after a successful save. `useSaveConsents()` calls the engine
directly and does not close anything.

In v2, `useConsentManager()` kept one draft per component. In v3,
`useConsentDraft()` and `useHeadlessConsentUI()` share a draft only inside a
`ConsentDraftProvider`. Without one, `saveCustomPreferences()` saves a fresh
draft and ignores what `useConsentDraft().set()` staged, even in the same
component. Save with `useConsentDraft().save()`, or render the code that stages
and the code that saves inside one `ConsentDraftProvider`. `ConsentWidget`
already includes one. The codemod
adds a `TODO(c15t v3)` comment where this applies.

## Replace `ConsentManagerProvider`

A typical v2 App Router app wrapped the layout in a client component:

```tsx title="Before (v2): components/consent-manager/provider.tsx"
'use client';

import {
	ConsentBanner,
	ConsentDialog,
	ConsentManagerProvider,
} from '@c15t/nextjs';

export default function ConsentManagerClient({ children }) {
	return (
		<ConsentManagerProvider
			options={{ mode: 'hosted', backendURL: 'https://your-project.c15t.dev' }}
		>
			<ConsentBanner />
			<ConsentDialog />
			{children}
		</ConsentManagerProvider>
	);
}
```

v3 gives you two ways forward.

**Resolve consent on the server.** This is the recommended path. The server
reads the visitor's policy and stored choice, so gated scripts can start right
after hydration and the banner can be in the first HTML. Replace the client
component with `ConsentRoot`. Pass it `resolveConsent()` from
`c15t/next/server` as `state` and your `defineConsentConfig()` result as
`config`, then add the manifest route. `ConsentRoot` already wraps
`ConsentProvider`, so don't mount both. If v2 set `storageConfig.storageKey`,
pass the same name to `resolveConsent()` as `cookieName`, or the server won't
find the stored choice. Follow the
[App Router guide](/docs/frameworks/next/app-router) or the
[Pages Router guide](/docs/frameworks/next/pages-router). This replaces v2's
`fetchInitialData()`, `ssrData` and `C15tPrefetch`, which are gone.

**Keep browser initialization**, as v2 did without `fetchInitialData()`. Keep
your client component, import from `c15t/next`, and change the provider:

```tsx title="After (v3): components/consent-manager/provider.tsx, changed lines"
import { ConsentBanner, ConsentDialog, ConsentProvider } from 'c15t/next';
// c15t/next's hosted() is data for c15t.config.ts; the provider takes the transport.
import { hosted } from 'c15t/react';

// In the component, replace ConsentManagerProvider:
<ConsentProvider
  options={{ mode: hosted({ backendURL: 'https://your-project.c15t.dev' }) }}
>
```

The `consent-provider-options` codemod makes this change, including the
`hosted` import:

```bash
npx @c15t/cli@alpha codemods consent-provider-options --dry-run --json
```

Static exports use browser initialization too. See
[static export](/docs/frameworks/next/static-export) and
[client-side setup](/docs/frameworks/next/client-side).

Either way, remove the `@c15t/nextjs/styles.css` import, as
[stylesheets](#stylesheets) explains, and keep your backend URL. An existing hosted URL such as
`https://your-project.c15t.dev` keeps working with v3 clients. New Inth
projects use URLs such as `https://your-project.inth.app`.

The other v2 modes map to transports:

|v2 option|v3 option|
|--|--|
|`mode: 'offline'` with `offlinePolicy`|`mode: offline({ policyRules })`|
|`mode: 'custom'` with `endpointHandlers`|`mode: custom(transport)`, where `transport` implements the v3 transport interface. `endpointHandlers` throws.|

The codemod rewrites the offline mode too. It can't translate
`endpointHandlers`, so it leaves a `TODO(c15t v3)` comment on a custom mode.

Offline mode keeps choices in the browser and records nothing on a server. Not
recommended for production environments.

## Replace callbacks

Callbacks stay under `callbacks` in your options, with new names:

|v2 callback|v3 callback|
|--|--|
|`onConsentSet`|`onPermissionsChanged` to react to what may run now. `onChoiceRecorded` to react to the visitor's accept, reject or save.|
|`onConsentChanged`|`onChoiceRecorded`. See the note below the table.|
|`onBannerFetched`|No callback. In React and Next.js, read `usePolicyResolution()` to know when the policy has resolved. In JavaScript, read `resolution` from the kernel snapshot.|
|`onError`, `onBeforeConsentRevocationReload`|Unchanged|

The `callbacks-to-v3` codemod renames `onConsentChanged` to
`onChoiceRecorded`. It leaves a `TODO(c15t v3)` comment there about the new
payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
replacement for:

```bash
npx @c15t/cli@alpha codemods callbacks-to-v3 --dry-run --json
```

v2's `onConsentChanged` fired only when a save changed at least one category's
value, and passed `preferences` and `previousPreferences`. v3's
`onChoiceRecorded` fires for every accept, reject or save that confirms a
category, including one that saves the same values again, because each save
renews the choice's confirmation time. Its payload carries `snapshot`,
`confirmed` and `actionAt`. v3 has no callback that fires only when a save
changes a value. If you need the before and after values, use
`onPermissionsChanged`: it passes `previous` and the new `snapshot` whenever
effective permissions change, whether a save or something else changed them.

v2's `onConsentSet` also fired on initialization and hydration. In v3,
`onChoiceRecorded` runs only when the visitor acts, and `onPermissionsChanged`
runs when effective permissions change for any reason, including expiry, a
policy update or a privacy signal. Neither runs at startup if the resolved
permissions match the defaults, such as an opt-in policy that leaves every
category denied. If an external API needs the starting state, read it once at
startup as well: in React and Next.js from `useEffectivePermissions()` in an
effect, which also runs on later changes, and in JavaScript from
`kernel.events.on('init:applied', ({ snapshot }) => ...)`.

```ts title="After (v3): callbacks in your options"
callbacks: {
  onChoiceRecorded(event) {
    console.log('Visitor recorded a choice', event);
  },
  onPermissionsChanged(event) {
    console.log('Effective permissions changed', event);
  },
},
```

## Move policy packs to policy rules

v2 policy packs become policy rules, and `policyPackPresets` becomes
`policyRulePresets`, exported from `c15t`. Where the rules live depends on your
backend:

* **Inth**: set the rules in your Inth project. Rules in client code do not
  change a hosted policy.
* **Self-hosted**: move the backend's `policyPacks` to `manifest.policyRules`.
  See [policy configuration](/docs/self-host/guides/policy-packs).
* **Offline**: move `offlinePolicy.policyPacks` to `offline({ policyRules })`.

```tsx title="After (v3): offline policy rules"
import { offline, policyRulePresets } from 'c15t';

const mode = offline({
	policyRules: [
		policyRulePresets.europeOptIn(),
		policyRulePresets.worldOptOutNoPrompt(),
	],
});
```

In Next.js, import `offline` from `c15t/next` instead and set the result as
`mode` in `c15t.config.ts`. Both take the same `policyRules`.

|v2 preset|v3 preset|
|--|--|
|`europeOptIn()`, `europeIab()`|Same names|
|`californiaOptIn()`, `californiaOptOut()`|Same names|
|`quebecOptIn()`|Same name|
|`worldNoBanner()`|`worldOptOutNoPrompt()`|

`worldNone()` is a separate, new preset: it shows nothing and grants no
rights, while `worldOptOutNoPrompt()` keeps v2's opt-out and preference rights.

The `policy-packs-to-policy-rules` codemod renames `policyPackPresets` and
`worldNoBanner()`, and moves the import to `c15t` where it came from
`c15t/react` or `c15t/next`. `consent-provider-options` moves
`offlinePolicy.policyPacks` into `offline({ policyRules })`. Preset calls need
no other change, but a hand-written v2 pack uses `consent` and `ui` keys,
which v3 rules replace with flat keys such as `model` and `prompt`; the
codemods mark those with a `TODO(c15t v3)` comment.

v3 adds presets for more regions. `offline()` without `policyRules` uses
`recommendedPolicyRules()`. Read [policies](/docs/concepts/policies) before you
change a rule's model or prompt, and
[how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice.

## Rename options and components

|v2|v3|
|--|--|
|`translations`|`i18n`|
|`backendURL`, `mode: 'hosted'`|`mode: hosted({ backendURL })` from `c15t/react` on `ConsentProvider`. Next.js `ConsentRoot`: `NEXT_PUBLIC_C15T_BACKEND_URL` and `c15t.config.ts`.|
|`ssrData` (Next.js)|`ConsentRoot` with `state` from `resolveConsent()`|
|`iframeBlockerConfig`|`iframeBlocker`, or `false` to turn it off|
|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, `FrameProps`|`ConsentGate` and its parts. The `Frame` names still work as deprecated aliases and log a one-time warning outside production.|
|`frame` translations, such as `frame.title`|`consentGate`, such as `consentGate.title`. Copy under `frame` still applies and logs a warning outside production.|
|`FrameTranslations`|`ConsentGateTranslations`. `FrameTranslations` still works as a deprecated alias.|
|`--frame-*` CSS variables|`--consent-gate-*`, with the same suffixes, such as `--consent-gate-placeholder-background-color`. The old names no longer apply.|
|`YouTubeEmbed`, `GoogleMap`|Removed. Wrap your own embed in `ConsentGate`.|
|`useConsentScript()`|Removed. Register the script in `scripts` with a `@c15t/integrations` helper.|
|`useSSRStatus()`|Removed|
|`ConsentButton`|Removed. Use the `ConsentBanner` and `ConsentWidget` buttons, or call `useHeadlessConsentUI()` from your own button.|
|`@c15t/react/cookie-banner`|`c15t/react/consent-banner`|
|`retryConfig`|Removed|
|`store`, including `namespace`, `debug`, `initialConsentCategories` and `initialTranslationConfig`|Removed. Use the top-level `consentCategories` and `i18n` options. Debug information is on `window.c15t`.|
|`window.c15tStore`|`window.c15t`|
|`iab: iab({ ... })`|`IABProvider`. See [Move IAB setup](#move-iab-setup-to-iabprovider).|

The `consent-provider-options` codemod renames `ConsentManagerProvider` and
its option and prop types, turns `mode` and `backendURL` into `hosted()` or
`offline()`, and renames `iframeBlockerConfig`. v2 still accepted the
deprecated `translations` option; the `translations-to-i18n` codemod moves it
to `i18n`.

```bash
npx @c15t/cli@alpha codemods consent-provider-options translations-to-i18n --dry-run --json
```

`ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
and `ConsentWidget` keep their names. The `scripts`, `networkBlocker`,
`legalLinks`, `overrides`, `theme` and `colorScheme` options keep theirs too,
but `theme` tokens no longer produce CSS on their own. See
[Update styles and themes](#update-styles-and-themes).

`persistence` and `storageConfig` are read once, when the provider mounts. v2
moved a stored choice when the storage key changed. Remount the provider to
change storage. Reading a vendor that nothing declares, through `vendors`, a
script or the backend, returns `false`.

Some names left the root `c15t/react` entry:

|v2 import from the root|v3 import|
|--|--|
|`useHeadlessConsentUI`, `useConsentDialogTrigger`, `useColorScheme`, `useFocusTrap` and the translation helpers|`c15t/react/headless`|
|Flat banner parts such as `ConsentBannerCard` and `ConsentBannerAcceptButton`|`ConsentBanner.Card`, `ConsentBanner.AcceptButton` and the other compound parts, or the same names from `c15t/react/components/consent-banner`|
|`TriggerRoot`, `TriggerButton`, `TriggerIcon`, `TriggerText`, `useTriggerContext`, `useDraggable`|`c15t/react/consent-dialog-trigger`|
|Token types such as `ColorTokens` and `TypographyTokens`|`c15t/react/types`. `Theme` stays on the root.|
|`configureConsentManager`, `policyPackPresets`, `ConsentStoreState`, `ConsentManagerInterface`|Removed. Use `policyRulePresets` from `c15t`.|

The `root-exports-to-subpaths` codemod moves these imports to their new
entries and marks removed names with a `TODO(c15t v3)` comment:

```bash
npx @c15t/cli@alpha codemods root-exports-to-subpaths --dry-run --json
```

`ConsentGate` changes one behavior from `Frame`. When its category is granted,
the embed now mounts after hydration instead of in the server HTML, so an
iframe loads once instead of twice. Size the wrapper with `className` or
`style` to hold its space. Test ids change from `frame-placeholder` and
`frame-open-dialog` to `consent-gate-placeholder` and `consent-gate-button`.

## Update styles and themes

### Render theme CSS

In v2 the provider built CSS from `options.theme` in the browser. In v3 it
doesn't. Without a change, custom colors, fonts and radii fall back to the
defaults, and you only see a development warning.

Render `ConsentTheme` with the same theme object, or put the output of
`generateThemeCSS(theme)` in your own stylesheet. Keep `options.theme` for
`consentActions` and `slots`. See
[customization](/docs/customization/overview) and
[tokens](/docs/customization/tokens).

The `theme-to-consent-theme` codemod marks a provider `theme` that sets
tokens with a `TODO(c15t v3)` comment.

A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
`:root` lose to it. Put them in the theme instead, or raise your selector.

### Stylesheets

* Remove the c15t stylesheet import, such as `@c15t/react/styles.css` or
  `@c15t/nextjs/styles.css`. The stock components in `c15t/react`,
  `c15t/next` and `c15t/tanstack-start` render the rules they use as
  `<style>` elements, so no stylesheet request holds back the first paint. An
  import you keep still styles the components, but the rules ship twice and
  the stylesheet still delays the first paint.
* Keep an import of the v3 stylesheet, such as `c15t/react/styles.css`, only
  with Tailwind CSS 3 or a named cascade layer, and set
  `styles: false` in the provider options so the components add no second
  copy. See
  [stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself).
  The `packages-to-c15t` codemod removes `@c15t/react` and `@c15t/nextjs`
  stylesheet imports. With Tailwind CSS 3 or a cascade layer it keeps them,
  pointed at `c15t`, with a `TODO(c15t v3)` comment.
* With manual styles, `iab/styles.css` no longer repeats the default tokens.
  Import it after `styles.css`. Automatic IAB styling needs neither import.
* Tailwind CSS 3 needs a PostCSS plugin for c15t's `styles.css`. Add
  `'c15t/postcss-tailwind3': {}` before `tailwindcss` in `postcss.config`,
  and set `styles: false`. See [Tailwind CSS 3](/docs/customization/tailwind#set-up-tailwind-css-3).
  Create React App can't run the plugin. The `postcss-tailwind3` codemod adds
  it to an object-form `postcss.config` and warns about configs it can't
  edit.

### CSS variables and slots

|v2|v3|
|--|--|
|`--consent-widget-*`|`--consent-manager-*`, used by `ConsentDialog` and `ConsentWidget`|
|`--consent-widget-accordion-*`|Removed. Set `--accordion-*` instead.|
|`--frame-*`|`--consent-gate-*`|
|`--consent-banner-entry-animation`, `--consent-banner-exit-animation`|Removed|
|`theme.slots.frame`|`consentGate`, `consentGateTitle` and `consentGateButton`|
|`theme.slots.consentDialogFooter`|`consentWidgetFooter`|

The `css-variables-to-v3` codemod renames `--consent-widget-*` and
`--frame-*` in stylesheets and inline styles, and marks
`--consent-widget-accordion-*` with a comment instead of renaming it, because
`--accordion-*` styles every accordion. `theme-to-consent-theme` renames
`theme.slots.consentDialogFooter` and marks `theme.slots.frame`.

```bash
npx @c15t/cli@alpha codemods theme-to-consent-theme css-variables-to-v3 postcss-tailwind3 --dry-run --json
```

`theme.slots` now applies in React. v2 accepted it in types and ignored it, so
check slots you set before the upgrade.

In the App Router, render `ConsentTheme` from a Server Component such as the
root layout. In the Pages Router, render it in `pages/_document.tsx`.

## Move IAB setup to `IABProvider`

React, Next.js and TanStack Start no longer take an `iab` provider option.
Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or
`ConsentRoot`, around the IAB components. Its props are the options you passed
to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new
`publisherRestrictions`.

The `iab-option-to-iab-provider` codemod marks the `iab` option with a
`TODO(c15t v3)` comment; move it by hand.

A `cmpId` that isn't an integer from 2 to 4095 now throws. Without a `cmpId`,
the CMP doesn't mount, so there is no `__tcfapi` and no TC string.

`@c15t/iab` no longer exports `createIABManager`, `decodeTCString`,
`generateTCString` or `c15tToIabPurposes`. Use `createIAB({ kernel, cmpId })`,
which returns a handle with `generateTCString()`, `acceptAll()`, `rejectAll()`
and `save()`. If your app depends on `@c15t/iab` directly, upgrade it to
`@c15t/iab@alpha` too, or your import resolves to the v2 package. Remove it if
`IABProvider` now covers everything you used it for.

Server integrations now send a reference to the Global Vendor List instead of
the list, and the browser fetches it when the IAB module mounts. If you set a
Content Security Policy, allow the list's origin in `connect-src`, or `'self'`
for same-origin routes.

See the [IAB guide](/docs/frameworks/next/iab) for a complete setup.

## Update headless UI code

`useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`.
The `root-exports-to-subpaths` codemod moves the import.
Some of its methods take different arguments:

|v2|v3|
|--|--|
|`performAction(action, { surface })`|`performAction(action)`. It also accepts `'dismiss'` and `'customize'`.|
|`openBanner({ force })`|`openBanner()`|
|`saveCustomPreferences({ uiSource })`|`saveCustomPreferences()`, `saveCustomPreferences('all')` or `saveCustomPreferences('none')`|
|`banner.layout`, `dialog.layout`, `hasPolicyHints`|`banner` and `dialog` carry `variant`, `position`, `rights`, `requiredActions` and `diagnostics`|

The `UseHeadlessConsentUIResult` type is no longer exported. Use
`ReturnType<typeof useHeadlessConsentUI>` if you need it.

## Update complete translation objects

Partial overrides through `i18n.messages` and objects typed as `Translations`
need no change. A complete translation object typed as `CompleteTranslations`
fails type-checking until you add the new sections and keys: `consentGate`, which
replaces `frame`, `rights`, the notice and dismiss strings such as
`common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy
under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves
`frame` copy to `consentGate`.

`i18n.messages` for the visitor's language now merge over the backend's copy
instead of being replaced by it.

## Keep visitors' existing choices

v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It
does not rewrite them on page load; the next accept, reject or save writes a
v3 record.

A v2 denial keeps restricting its category. A v2 grant keeps applying until
the policy's validity period runs out, and then c15t asks again. If the rule
comes from a preset and the v2 record noted the policy it was made under, c15t
also asks again when that policy has changed. Under custom rules, a v2 grant
applies until it expires. Do not copy permissions into new
records yourself; c15t decides which v2 choices still count.

## Update dev tools

`@c15t/dev-tools/react` and `@c15t/dev-tools/tanstack` are gone. Import
`DevTools`, `C15tTanStackDevtoolsPanel` and `c15tDevtools()` from
`c15t/next/devtools`. Dev tools read the consent engine, so `namespace`,
`createStoreConnector()` and `getC15tStore()` are gone too. See
[dev tools](/docs/frameworks/next/components/dev-tools).

The `dev-tools-to-c15t` codemod points the imports at `c15t/next/devtools` and
removes the `namespace` prop:

```bash
npx @c15t/cli@alpha codemods dev-tools-to-c15t --dry-run --json
```

## Upgrade from an earlier v3 alpha

The v3 alphas renamed and removed APIs that never shipped in a stable release.
Names that were in stable v2 keep a deprecated alias. Every other renamed name
is removed with no alias, so a build that still uses one fails to type-check
or throws at runtime.

### Deprecated, still working

Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside
production, log a one-time warning such as
`` c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead. ``

|Package|Deprecated|Use instead|
|--|--|--|
|`c15t/react`, `c15t/next`, `c15t/tanstack-start`|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, and the `FrameProps` type|`ConsentGate` and its parts, and `ConsentGateProps`|

v2's `ConsentManagerProvider` and string modes such as `mode: 'hosted'` are
handled by the `consent-provider-options` codemod, not by aliases.

### Removed

Modes and build integrations, in every framework:

|Removed|Use instead|
|--|--|
|`hosted({ url })`|`hosted({ backendURL })`, or the framework's backend URL variable|
|`createManifestTransport({ manifest })`|`createManifestTransport({ snapshot })`|
|`assertDecisionInputs` defaulting to `false` on `hosted()`|It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.|
|`hostedModes` from `c15t/runtime/provider`|`readHostedMode(mode)`|
|`buildManifest: true` in Astro and Nuxt|`onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`.|
|A generated `c15t-manifest.ts` and its `.gitignore` entry|`import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.|
|The build options `outputFile`, `exportName`, `importSource` and `rootDir`|Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.|

Next.js:

|Removed|Use instead|
|--|--|
|`defineConsentConfig({ manifestURL, initURL })`|`routePrefix`, or `mode: manifest({ resolve: 'browser', manifestURL })`|
|A named `consentConfig` export, passed to `ConsentRoot` as `config`|`export default defineConsentConfig(...)` in `c15t.config.ts`. `withConsentManifest` finds the file. `config` stays as an optional override.|
|`ConsentRoot`'s `backendURL` prop|`backendURL` in the config, or `NEXT_PUBLIC_C15T_BACKEND_URL`|
|The `'use client'` wrapper that passed `config` and `scripts`|`scripts` and other browser options in `c15t.config.ts`. A Server Component renders `ConsentRoot` directly.|
|`createNextConsentRouteHandlers()`, its `GET` and `manifestGET`|`createConsentRoute()` in one catch-all route, `app/api/c15t/[...c15t]/route.ts`|
|`createPagesApiHandlers()` and its `init` and `manifest`|`createPagesConsentRoute()` in `pages/api/c15t/[...c15t].ts`|
|`resolveConsent(...)` with a JSON round trip in `getServerSideProps`|`export const getServerSideProps = withConsentProps()`, and `AppProps<ConsentPageProps>` in `_app.tsx`|
|`resolveConsent({ manifest })`, and `manifest` on the route helpers|`snapshot`, which defaults to the build's|
|`ConsentManifestOptions` and the `c15t.server.ts` module|`ResolveConsentOptions` or `NextConsentRouteOptions`. The helpers read the config and snapshot themselves.|
|`resolveStrictestDefaultInit` from `c15t/next/static`|`resolveUnknownLocationInit`|
|`ConsentRoot` falling back to offline mode when no config or `NEXT_PUBLIC_C15T_BACKEND_URL` gives it a backend URL|`ConsentRoot` throws. Set `mode: offline()` to run without a backend.|
|`onBuildError: 'runtime'` to build a `hosted()` or `offline()` app while the backend is unreachable|Nothing. `withConsentManifest` reads the mode from `c15t.config.ts` and skips the download for modes that don't use it.|
|`hosted`, `offline` and `manifest` from `c15t/next` as transports|They are data for `c15t.config.ts` now. A `ConsentProvider` imports them from `c15t/react`.|

## Update the CLI

* Run `c15t login` again. The CLI signs in through Inth now and no longer
  reads sessions saved by v2.
* `c15t setup` no longer writes `.env.local` or `.env.example` and no longer
  accepts `--env`. It writes the backend URL into the files it generates.
* `c15t setup` no longer detects Remix or Gatsby. Pick a guide from
  [Choose your setup](/docs/concepts/choose-your-setup) for those apps.

## Check the migration

1. Run your typecheck and build. Remaining `TODO(c15t v3)` comments from the
   codemod fail the build until you resolve them.
2. Load the app with a v2 consent cookie from before the upgrade. The banner
   stays closed if that choice still applies, and a rejected category stays
   blocked.
3. In a private window, check in DevTools Network that vendor requests wait for
   consent, start after you accept, and stay absent after you reject and
   reload.
4. Reopen preferences from your privacy settings link and change a category.

The [verification guide](/docs/guides/verify-consent) has the full release
checklist.

# Scripts
URL: https://c15t.com/docs/frameworks/next/scripts
Register vendor scripts in a Next.js ConsentRoot, check how each vendor loads, let visitors turn off one vendor, clear stored data after revocation and replace @next/third-parties.

## Install the script helpers

The [App Router](/docs/frameworks/next/app-router),
[Pages Router](/docs/frameworks/next/pages-router) and
[static export](/docs/frameworks/next/static-export) guides already register
scripts. Use this page to add vendors to an existing setup or to change how
they load. Install the helpers if you have not:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

Keep `next.config.ts` and the layout from your router guide. Adding a vendor
needs no server change. Server-rendered state, a streamed promise and
browser initialization without `state` all reach the same `ConsentRoot`, and
no script loads until the browser has a resolved policy and the visitor's
choice allows it.

## Register scripts in c15t.config.ts

The [runnable Next.js example](/docs/examples) loads PostHog under the
measurement category. Replace the placeholder `phc_your_project_key` with your
project key, or replace the helper with the
[integration](/docs/integrations/overview) your application uses. Include the
measurement category in your policy.

Put the scripts in `c15t.config.ts`, next to `next.config.ts`:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
cookieless capture after rejection. Remove any existing PostHog loader,
including `next/script` and tag-manager entries, so the integration loads once.

`withConsentManifest` in `next.config.ts` finds the file, and `ConsentRoot`
reads its `scripts` in the browser, so a Server Component layout renders
`ConsentRoot` without passing them. The file is bundled into the browser as
well as the server, so it must hold no secrets.

`scripts`, `vendors`, `clearOnRevocation`, `networkBlocker`, `persistence`,
`scriptLoader` and `options` can also be passed to `ConsentRoot` as props,
which win over the config. Functions can't cross from a Server Component to a
Client Component, so pass them as props only from a `'use client'` file.

## Register several vendors

Every helper goes in the same `scripts` array in `c15t.config.ts`, in the App
Router and the Pages Router alike. This config loads Google Tag Manager and
Meta Pixel together:

```ts title="c15t.config.ts"
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { metaPixel } from '@c15t/integrations/meta-pixel';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		googleTagManager({ id: 'GTM-XXXXXXX' }),
		metaPixel({ pixelId: 'YOUR_PIXEL_ID' }),
	],
});
```

Each helper keeps its own consent rules. Meta Pixel waits for marketing, and
Google Tag Manager follows the
[Consent Mode contract](/docs/integrations/google-tag-manager). Remove the
container and pixel snippets from `pages/_document.tsx` or your layout, so each
vendor loads once. If they come from `@next/third-parties`, follow
[migrate from `@next/third-parties`](#migrate-from-nextthird-parties). With an
empty ID, a helper logs an error and its script does not load, so leave a
helper out of the array until you have its ID.

## Check each vendor's loading behavior

The example configures PostHog to load after consent and turns off cookieless
capture. Its default helper can load before consent and use the SDK's own
consent controls. Read the [PostHog guide](/docs/integrations/posthog) before
you change those settings.

Ordinary scripts wait for their category's permission. Give each script a
stable, unique `id`, and remove any other loader for the same vendor. Helpers
with `alwaysLoad` can load an SDK before permission is granted, so a category
alone does not guarantee that no request happens. See the
[vendor guides](/docs/integrations/overview) for each helper's contract.

Removing a script element cannot undo JavaScript that already ran or requests
already sent. When a visitor turns off a category they had granted,
`ConsentRoot` reloads the page, so the next page runs only permitted code. See
[reload after revocation](/docs/frameworks/next/components/consent-root#reload-after-revocation).

Use [custom integrations](/docs/integrations/building-integrations) for a
vendor without a helper. Google helpers follow the
[Consent Mode contract](/docs/integrations/google-tag-manager).

## Embeds and other requests

Scripts cover vendor code c15t loads for you. For the rest:

* [Embeds](/docs/frameworks/next/embeds) keeps iframes out of the page with
  `ConsentGate` or the iframe blocker.
* [Network blocker](/docs/frameworks/next/network-blocker) holds `fetch` and
  XHR calls that match a rule until their category is allowed.

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Declare
the vendors and pass them to `ConsentRoot` as `vendors`; helpers from
`@c15t/integrations` already carry their vendor slug. See
[vendor consent](/docs/frameworks/next/vendor-consent).

## Clear stored tracking data

Script gating does not remove cookies or Web Storage entries a script already
wrote. Pass `clearOnRevocation` to `ConsentRoot` to remove declared data when
its category is denied. See
[clear on revocation](/docs/frameworks/next/clear-on-revocation) for
configuration and browser limits.

To send your own events only to allowed integrations, see
[send events only to allowed integrations](/docs/integrations/overview#send-events-only-to-allowed-integrations).

## Migrate from `@next/third-parties`

The components in `@next/third-parties/google` add `next/script` tags and
embeds when the page renders. c15t never sees them, so the banner
cannot hold them back, and `GoogleAnalytics` and `GoogleTagManager` send no
Consent Mode signals. Replace each export, keep your IDs, then remove the
package.

|`@next/third-parties/google`|c15t replacement|
|--|--|
|`<GoogleAnalytics gaId="G-XXXXXXXXXX" />`|`gtag({ id: 'G-XXXXXXXXXX', category: 'measurement' })` from `@c15t/integrations/google-tag`|
|`<GoogleTagManager gtmId="GTM-XXXXXXX" />`|`googleTagManager({ id: 'GTM-XXXXXXX' })` from `@c15t/integrations/google-tag-manager`|
|`sendGAEvent(...args)`|`window.gtag?.(...args)`|
|`sendGTMEvent(data)`|`window.dataLayer?.push(data)`|
|`<YouTubeEmbed videoid="VIDEO_ID" />`|`ConsentGate` around a `youtube-nocookie.com` iframe. See [YouTube](/docs/integrations/youtube).|
|`<GoogleMapsEmbed apiKey="API_KEY" mode="place" />`|`ConsentGate` around a Maps Embed API iframe. See [Google Maps](/docs/integrations/google-maps).|

### Replace GoogleAnalytics and GoogleTagManager

Delete the components from `app/layout.tsx`, `pages/_app.tsx` or
`pages/_document.tsx`. Add a helper for each one to the `scripts` array your
`ConsentRoot` receives, with the same measurement ID and container ID:

```ts title="lib/scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import type { Script } from 'c15t';

export const scripts: Script[] = [
	// Replaces <GoogleAnalytics gaId="G-XXXXXXXXXX" />
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
	// Replaces <GoogleTagManager gtmId="GTM-XXXXXXX" />
	googleTagManager({ id: 'GTM-XXXXXXX' }),
];
```

Keep only the helpers for the tags you used. If GA4 already runs inside your
Tag Manager container, register `googleTagManager` alone, or each page view
counts twice.

The component props map to helper options:

|Prop|c15t|
|--|--|
|`gaId`|`id` on `gtag`|
|`debugMode`|`config: { debug_mode: true }` on `gtag`|
|`dataLayerName` on `GoogleAnalytics`|No equivalent. `gtag` always queues on `window.dataLayer`.|
|`gtmId`|`id` on `googleTagManager`|
|`dataLayerName` on `GoogleTagManager`|`dataLayer` on `googleTagManager`. Keep the same name.|
|`dataLayer`|No option. Seed the data layer before the container loads. See [keep initial data layer values](#keep-initial-data-layer-values).|
|`auth`, `preview`, `gtmScriptUrl`|No option. Use a [custom integration](/docs/integrations/building-integrations) for GTM environments or a server-side tagging URL.|
|`nonce`|`options={{ nonce }}` on `ConsentRoot`. See [Content Security Policy](/docs/frameworks/next/content-security-policy).|

### Keep initial data layer values

`GoogleTagManager` pushes its `dataLayer` object in the same inline snippet
that pushes the `gtm.js` start event, before the container script runs, so the
container's startup triggers can read those values. Pushing the object later,
like an event, can arrive after those triggers have run.

Seed the queue in the initial HTML instead, before c15t loads the container.
Add a `beforeInteractive` script to the root `app/layout.tsx`, or to
`pages/_document.tsx` with the Pages Router. Keep `ConsentRoot` and the rest
of your layout as they are:

```tsx title="app/layout.tsx (partial)"
import Script from 'next/script';
import type { ReactNode } from 'react';

const initialDataLayer = { pageType: 'product' };

export default function RootLayout({ children }: { children: ReactNode }) {
	return (
		<html lang="en">
			<body>
				<Script id="gtm-initial-data-layer" strategy="beforeInteractive">
					{`window.dataLayer = window.dataLayer || [];
window.dataLayer.push(${JSON.stringify(initialDataLayer)});`}
				</Script>
				{children}
			</body>
		</html>
	);
}
```

`googleTagManager` keeps an array that already exists, so the queue holds your
object, then Consent Mode `default`, then the `gtm.js` start event. The script
sends nothing to Google, so it also works with `loadMode: 'after-consent'`.
Use the name you pass as `dataLayer` on `googleTagManager`, and pass your
Content Security Policy nonce to `Script` as `nonce`.

### Choose when Google loads

The `gtag` and `googleTagManager` helpers take a `loadMode` option. It
decides whether the page contacts Google before the helper's category is
allowed:

|`loadMode`|Until the category is allowed|Use it when|
|--|--|--|
|`'always'` (default)|c15t loads Google's script, sends Consent Mode `default` with the current permissions, then sends `update` as they change. Google receives requests with the optional consent types denied.|You want Consent Mode signals from visitors who have not allowed the category.|
|`'after-consent'`|c15t sends no request to Google.|Your site must make no request to Google before opt-in. You give up Consent Mode's cookieless pings and conversion modeling for visitors who haven't allowed the category.|

With `'after-consent'`, `gtag` waits for its `category`, and
`googleTagManager` waits for `measurement` or `marketing` because a container
usually holds both kinds of tag. Pass `category` to `googleTagManager` to
change that, for example `category: 'measurement'` for an analytics-only
container. Until the helper loads, `window.gtag` doesn't exist, and neither
does `window.dataLayer` unless you seeded it, so event calls written as
`window.gtag?.(...)` do nothing.

`'after-consent'` waits for the category to be allowed, not for a recorded
choice. Under an `opt-in` policy, that happens when the visitor allows it.
Under an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

In either mode, the container runs every tag in it once it starts. Google
tags inside follow Consent Mode, but Custom HTML tags and third-party pixels
fire on their own triggers. With the default `category`, a visitor who
allowed only measurement starts the container, and a marketing pixel in it
loads too. With `'always'`, both load before any choice. Add a
consent check to each of those tags in GTM, or move the vendor out of the
container to its own c15t helper. See
[configure consent inside the container](/docs/integrations/google-tag-manager#configure-consent-inside-the-container).

Set it on each Google helper in your `scripts` array:

```ts
gtag({
	id: 'G-XXXXXXXXXX',
	category: 'measurement',
	loadMode: 'after-consent',
}),
googleTagManager({ id: 'GTM-XXXXXXX', loadMode: 'after-consent' }),
```

The [Google Tag](/docs/integrations/google-tag) and
[Google Tag Manager](/docs/integrations/google-tag-manager) guides list what
each mode sends and how to check it in DevTools.

### Move sendGAEvent and sendGTMEvent calls

`sendGAEvent` only works after the `GoogleAnalytics` component has rendered.
In `@next/third-parties` 16.x, once you remove the component, every call logs
`@next/third-parties: GA has not been initialized` and drops the event.
`sendGTMEvent` still pushes to `window.dataLayer` without its component, but
importing it keeps the package installed.

Call the `gtag` function and data layer that c15t sets up instead. The
arguments do not change:

```ts
// Before
sendGAEvent('event', 'sign_up', { method: 'email' });
sendGTMEvent({ event: 'sign_up', method: 'email' });

// After: no import needed
window.gtag?.('event', 'sign_up', { method: 'email' });
window.dataLayer?.push({ event: 'sign_up', method: 'email' });
```

Call them from browser code, such as an event handler. `window.gtag` and
`window.dataLayer` exist once c15t has set up the Google helper. Until then the
optional call does nothing and the event is lost, as with `sendGAEvent`. With a
custom `dataLayer` name on `googleTagManager`, push to `window[name]`
instead.

To send one event to every allowed integration rather than to Google alone,
use [`createEventDispatcher`](/docs/integrations/overview#send-events-only-to-allowed-integrations).
It drops the event while measurement is denied.

### Replace YouTubeEmbed and GoogleMapsEmbed

`YouTubeEmbed` loads `lite-youtube-embed` from `cdn.jsdelivr.net` and the
video thumbnail from YouTube before the visitor chooses. `GoogleMapsEmbed`
renders its Google iframe straight away. Render your own iframe inside
`ConsentGate` instead:

```tsx title="components/video-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';

export const VideoEmbed = () => (
	<ConsentGate category="measurement">
		<iframe
			className="video-frame"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
			allowFullScreen
		/>
	</ConsentGate>
);
```

Put the `videoid` in the URL path and the `params` string in its query, and use
the `playlabel` text as the iframe `title`. For a map, keep the URL
`GoogleMapsEmbed` built. In `place` mode that is
`https://www.google.com/maps/embed/v1/place?key=<apiKey>&q=<q>`, with
`center`, `zoom`, `maptype`, `language` and `region` as further query
parameters. Other modes need their own parameters, such as `center` and
`zoom` for `view`, so copy every parameter your component set. The
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover categories, sizing
and placeholders.

### Remove the package

Search the project for `@next/third-parties`. When nothing imports it,
uninstall it, for example with `npm uninstall @next/third-parties`. Then open
the production build in a private window under an opt-in policy. With
`loadMode: 'after-consent'`, nothing requests `googletagmanager.com` before you
choose. With the default, Google Tag Assistant shows a `consent` `default`
command before any tag fires. No request goes to `cdn.jsdelivr.net`, YouTube
or Google Maps until you allow the embed's category.

## Verify the integration

Open the production build in a fresh browser session with DevTools open.

1. Under an opt-in policy, no vendor requests anything before you choose.
2. Open **Privacy settings** and turn on **Analytics** (the `measurement`
   category) only. PostHog loads, and marketing vendors such as Meta Pixel stay
   blocked.
3. Reject, reload, and reopen **Privacy settings**. The rejection is still
   selected and no vendor loads.
4. Turn a granted category off. The page reloads and that vendor does not load
   again.

The [runnable example](/docs/examples) registers PostHog, and
[the consent checks](/docs/guides/verify-consent) cover the release checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/next/embeds
Keep YouTube videos, maps and other iframes out of a Next.js page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.

## Pick a method

|Method|Use it when|
|--|--|
|`ConsentGate`|You render the iframe in a React component and want a placeholder until the visitor allows its category.|
|The iframe blocker|The iframe comes from markup you do not render with a component, such as CMS or Markdown content.|

Both keep the iframe's `src` out of the page until the category is allowed, so
the embed's host receives no request before consent.

## Gate an embed with ConsentGate

Wrap the iframe in `ConsentGate` in a Client Component:

```tsx title="components/video-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';

export const VideoEmbed = () => (
	<ConsentGate category="measurement">
		<iframe
			className="video-frame"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
			allowFullScreen
		/>
	</ConsentGate>
);
```

Import `VideoEmbed` into any page or Server Component under the layout that
mounts `ConsentRoot`; only this file needs `'use client'`. The iframe stays out
of the page until the visitor allows measurement, and a placeholder with a
button that opens the preference dialog takes its place.

Pick the category that matches what the embed does. The example uses
measurement for YouTube because its player measures views. A map or chat
widget usually belongs under functionality or experience.

What the server HTML contains depends on how your layout passes consent state.
[ConsentGate](/docs/frameworks/next/components/consent-gate) covers the
default, awaited and Pages Router layouts, the placeholder and its props.

## Gate an iframe with the iframe blocker

`ConsentRoot` runs the iframe blocker in the browser by default. Give an
iframe `data-src` instead of `src`, and a `data-category`:

```html title="Markup from your CMS"
<iframe
  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
  data-category="functionality"
  title="Store map"
></iframe>
```

The server HTML has no `src`, so nothing loads before hydration. After
hydration, c15t sets `src` from `data-src` when the category is allowed and
removes `src` when the category is withdrawn. It watches the page, so iframes
added by client-side navigation are handled too. Add `data-vendor` with a
vendor ID to also block the iframe while the visitor has turned that vendor
off.

To turn the blocker off, pass `options={{ iframeBlocker: false }}` to
`ConsentRoot`.

## Verify the embeds

Open the production build in a private window with DevTools open, under a
policy that asks for consent.

1. View the page source. No iframe has a `src` pointing at
   `youtube-nocookie.com` or `google.com/maps`, and the Network panel shows no
   request to them.
2. Allow the embed's category and save. The iframe loads.
3. Withdraw the category and save. The page reloads without the embed.

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover sizing and titles.

# Network blocker
URL: https://c15t.com/docs/frameworks/next/network-blocker
Hold fetch and XMLHttpRequest calls in a Next.js app until their consent category is allowed, with networkBlocker rules in c15t.config.ts.

## Add rules

The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
list until the visitor grants their category. Use it for beacons and API calls
that bypass script loading, such as a pixel fired by an SDK already on the
page. Load vendor SDKs through [`scripts`](/docs/frameworks/next/scripts)
first, so they do not run at all before consent.

Define the rules in `c15t.config.ts`. `onRequestBlocked` is a function, so the
rules cannot be passed as a prop from a Server Component, but the config is
bundled into the browser and can hold them.

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	networkBlocker: {
		rules: [
			{
				id: 'google-analytics',
				domain: 'google-analytics.com',
				category: 'measurement',
			},
			{
				id: 'meta-pixel',
				domain: 'facebook.com',
				pathIncludes: '/tr',
				category: 'marketing',
			},
		],
	},
});
```

Keep your `scripts` in the same call. Keep the page content inside
`ConsentRoot`. Blocking starts when it renders, so
components outside it that send requests while rendering, and modules evaluated
before it, are not covered. Requests your server makes, in Server Components,
route handlers or `getServerSideProps`, are not blocked either.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The provider holds matching requests from its first render in the browser,
before any of its children render or run effects. That covers requests from
child components, including their mount effects, and from effects in
components rendered next to the provider. The blocker module itself loads
after mount and decides each held request. Apps without `networkBlocker` do
not download it.

The standalone `useNetworkBlocker` hook works the same way from the first
render of the component that calls it. That render patches `fetch` and
`XMLHttpRequest`. If React throws the render away and never commits it, the
hold ends after 10 seconds. Nothing checked consent for the requests it held,
so they fail the way the blocker fails a blocked request: a 451 response for
`fetch`, a failed XHR. The same happens when the component unmounts before
the blocker loads.

While consent is unknown, a matching request that would be blocked waits
instead of failing. Consent is unknown until the policy has loaded, which is
also when a returning visitor's stored choice takes effect. The request is
then sent if the choice allows it and blocked otherwise. If the policy fails
to load, optional categories stay denied and waiting requests are blocked.
If the policy request never finishes, they keep waiting and are never sent.

A synchronous XHR cannot wait. Before the blocker module has loaded, a
matching one throws a `NetworkError` from `send()`. After that, one that
consent does not allow yet is blocked.

## What the network blocker cannot stop

The blocker only sees requests made after the provider starts rendering in
the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:

* Code that runs before the provider renders: inline scripts in the HTML,
  third-party tags in `<head>`, scripts loaded before hydration (such as
  `next/script` with `beforeInteractive`), and client modules that evaluate
  earlier. Webpack builds evaluate a route's client component modules when
  its chunk loads, so their top-level code runs first. Turbopack evaluates a
  client component module when its first element renders, which inside the
  provider is after blocking starts.
* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
  provider rendered.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` or `<iframe>` elements, web workers and service
  workers.
* With the standalone `useNetworkBlocker` hook instead of the provider
  option, requests sent before the component that calls it renders.
  Blocking starts in that component's first render, not the provider's.

Keep tracking calls out of that window:

* Send them from an effect or an event handler, never at module top level.
* Load vendor SDKs through `scripts` instead of a `<script>` tag or
  `next/script`, so they wait for consent before they run at all.
* Check `useConsent('measurement')` (or the category you need) before you
  call a vendor from your own code, and treat the blocker as a backstop.

## Verify the blocked requests

Open the production build in a private window with the DevTools Network panel
open, under a policy that asks for consent.

1. Before a choice, requests matching a rule are absent from the Network panel,
   and the console logs each blocked request.
2. Allow the rule's category and save. Matching requests go out.
3. Reject, reload, and check that they stay absent.

# Vendor consent
URL: https://c15t.com/docs/frameworks/next/vendor-consent
Let visitors allow a category such as marketing in a Next.js app and still turn off one vendor in it, with vendors in c15t.config.ts and useVendorAllowed.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in `c15t.config.ts`, using the
`vendor` slug each script already carries:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	vendors: [
		{
			id: 'x-pixel',
			name: 'X Pixel',
			category: 'marketing',
			privacyPolicyUrl: 'https://x.com/privacy',
		},
	],
});
```

`vendors` is a top-level option, not inside `options`. Keep your `scripts` in
the same call. A `vendors` prop on `ConsentRoot` wins over the config's.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. To render a component only while one
vendor is allowed, read `useVendorAllowed('youtube')` and render it when the
hook returns `true`. [Embeds](/docs/frameworks/next/embeds) covers the iframe
blocker's `data-vendor` attribute.

## What the preference dialog shows

`ConsentDialog` and `ConsentWidget` list each declared vendor under its
category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`useVendorDraft()` from `c15t/next` reads and stages vendor switches on the
same draft the category switches use, so one save records both.
`useVendorAllowed(id)` returns whether a vendor may run now: it is declared,
its category is allowed and the visitor has not switched it off.

```tsx title="components/x-pixel-switch.tsx (partial)"
'use client';

import { useVendorAllowed, useVendorDraft } from 'c15t/next';

const { vendors, setVendor, save } = useVendorDraft();
const xPixelAllowed = useVendorAllowed('x-pixel');

<input
  type="checkbox"
  checked={vendors['x-pixel'] ?? true}
  onChange={(event) => setVendor('x-pixel', event.target.checked)}
/>
<button type="button" onClick={() => save()}>Save</button>
```

`save()` resolves `{ ok: false }` without recording anything when the policy
or the vendor list changed under the edit. Call `reset()` to start again.
`useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
returns the recorded vendor decision, or `null` before the visitor made one.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/next/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a Next.js app when that category is denied, with clearOnRevocation in c15t.config.ts.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns in
`c15t.config.ts`. When that category is denied, c15t deletes them:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	clearOnRevocation: {
		measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
		marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
	},
});
```

`clearOnRevocation` is a top-level option, not inside `options`. Keep your
`scripts` in the same call. A `clearOnRevocation` prop on `ConsentRoot` wins
over the config's. It is read once, when `ConsentRoot` mounts; remount it to
change the list.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/next/customize
Load the c15t stylesheet yourself in Next.js when you need to, and change colors, radius, button roles, component parts, dark mode and banner shape with ConsentTheme and ConsentRoot options.

## See the designs

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one. Its React code works in Next.js with
the same components imported from `c15t/next`.

## Load the stylesheet yourself

A Next.js app imports no c15t stylesheet. `ConsentBanner`, `ConsentDialog`
and the other stock components render the rules they use as `<style>`
elements, in the server HTML for a server-rendered banner.

Import the stylesheet yourself with Tailwind CSS 3, to put c15t's rules in a
named cascade layer. Set `styles: false` under `options` in
`c15t.config.ts`, so the components add no second copy:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({ options: { styles: false } });
```

Then import c15t once from the global stylesheet that `app/layout.tsx` or
`pages/_app.tsx` loads:

```css title="styles/globals.css"
@import 'c15t/next/styles.css';
```

c15t's rules live in the cascade layer `components`, and each `<style>`
element the components render opens with Tailwind CSS 4's layer order,
`@layer properties, theme, base, components, utilities;`. Unlayered CSS,
Tailwind 4 utilities and StyleX's atomic classes override c15t's rules
without specificity tricks, whichever stylesheet loads first.
[Stylesheets and CSS layers](/docs/customization/stylesheets) explains the
order and which file holds the dialog's rules.

Tailwind CSS 3 has no cascade layers, and its unlayered preflight beats
c15t's layered rules. Set `styles: false` in the provider options, import
`styles.css` above the `@tailwind` directives, and add the
`c15t/postcss-tailwind3` PostCSS plugin before `tailwindcss`. Utilities
you pass to c15t parts then need the important modifier, such as
`!bg-red-500`. [Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3)
shows the tested setup for each framework.

## Change colors and radius with tokens

Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
properties. The rules the components render set the default values, as
does `styles.css` when you import it with `styles: false`. To change them,
render `ConsentTheme` with your theme where your app renders on the server,
or override the variables directly in your CSS.

`ConsentTheme` renders a `<style id="c15t-theme">` element with the
variables for `theme`. It is not a client component: rendered from a Server
Component or another server-only file, the theme generator stays out of the
browser bundle. Rendered from a client component it still works, but the
browser downloads the generator (about 1.7 KB gzip). The provider no longer
turns `theme` tokens into CSS. It still reads `consentActions` and slot
styles from its `theme` option, and warns in development when `theme` holds
tokens but the page has no `c15t-theme` stylesheet.

|`ConsentTheme` prop|Purpose|
|--|--|
|`theme`|Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.|
|`colorScheme`|`'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`.|
|`nonce`|Content Security Policy nonce for the `<style>` element.|

Pass the same `colorScheme` to `ConsentTheme` and to the provider. If your
app manages dark mode through a root class, such as next-themes' `dark`
class, omit `colorScheme` and include that class in the server HTML.
[Dark mode](/docs/customization/dark-mode) covers `theme.dark`, `null` and
a dark first paint.

To switch between different token sets at runtime, render `ConsentTheme`
from a client component and change its props, which ships the generator.

Outside a component, call `generateThemeCSS(theme, colorScheme)` from
`c15t/react/utils`, or `@c15t/react/utils` with the scoped package. It
writes the same CSS as `ConsentTheme`. Outside React, import it from
`@c15t/ui/theme`. Call it on the server or at build time and put the result in a
`<style>` element or your stylesheet. It escapes `<`, so the result is safe
inside `<style>`.

Define the theme in a module without `'use client'`, so Server and Client
Components can both import it:

```ts title="lib/theme.ts"
import { defineTheme } from 'c15t/next';

export const brandTheme = defineTheme({
	colors: { primary: '#315c47', primaryHover: '#24473a' },
	radius: { lg: '16px' },
});
```

Render `ConsentTheme` from a Server Component layout. This layout themes the
routes under `app/branded`:

```tsx title="app/branded/layout.tsx"
import { ConsentTheme } from 'c15t/next';
import type { ReactNode } from 'react';

import { brandTheme } from '@/lib/theme';

const BrandedLayout = ({ children }: { children: ReactNode }) => (
	<>
		<ConsentTheme theme={brandTheme} />
		{children}
	</>
);

export default BrandedLayout;
```

To theme the whole site, render `<ConsentTheme theme={brandTheme} />` in your
root layout, before `ConsentRoot`. View the page source to check that
the `<style id="c15t-theme">` element is in the server HTML. In the Pages
Router, render `ConsentTheme` in `pages/_document.tsx`, which runs only on the
server.

Earlier v3 alphas generated theme CSS in the browser from the provider's
`theme` option. To migrate:

1. Move the theme into a module without `'use client'`, so server and
   client files can both import it.
2. Render `<ConsentTheme theme={theme} />` next to the consent root, from a
   Server Component or another server-rendered file. Pass `colorScheme` and
   `nonce` if you set them on the provider.
3. Keep passing `theme` to the provider only for `consentActions` and slot
   styles. A theme with tokens only can be removed from the provider.
4. The default tokens the provider used to inject now come with the rules
   the components render. If you import `styles.css` with `styles: false`,
   keep that import.

## Style the action buttons

`consentActions` decides how each action role looks: `default` applies to
every button, `primary` to whichever actions the policy or your props mark
primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
Per-action keys win over `primary`, which wins over `default`.

Banner sizing has its own variables. Override them in CSS when a variant
needs a different footprint:

|Variable|Default|Applies to|
|--|--|--|
|`--consent-banner-max-width`|`440px`|`floating` cards|
|`--consent-banner-widget-max-width`|`20rem`|`widget` chips|
|`--consent-banner-wall-max-width`|`30rem`|`wall` cards|

The footer lays out its actions by the card's width, not the viewport's.
With the default `compact` profile, a card narrower than 22rem puts Reject
and Accept on one row and Customize on a full-width row below them.

## Colors by consent model

The primary action can change while the brand color stays the same. Set
`consentActions.primary` once, then select `primaryButton` per policy as
shown in [ConsentBanner](../components/consent-banner#per-policy-buttons).

To give opt-in and opt-out banners different colors, scope the tokens to
the root's attributes. Include hover and foreground colors when overriding
CSS tokens directly:

```css
[data-prompt][data-model='opt-in'] {
	--c15t-primary: #2f6f4e;
	--c15t-primary-hover: #24563c;
	--c15t-text-on-primary: #fff;
}

[data-prompt][data-model='opt-out'] {
	--c15t-primary: #6b3fa0;
	--c15t-primary-hover: #55327f;
	--c15t-text-on-primary: #fff;
}
```

These colors apply to the action marked primary. Button layout and color
changes do not change the policy or expire a saved choice.

## Slots

Each component part is a slot. A slot accepts any attributes the element
takes, so the contract is the same whether you write class strings or pass an
object with `className` and `style`. Set slots on the provider under
`components`, keyed by component and part.

`ConsentTheme` renders tokens only. Components read `consentActions` in the
browser, so pass a theme that contains them through `options` in
`c15t.config.ts`:

```ts title="lib/theme.ts (partial)"
export const actionTheme = defineTheme({
	consentActions: {
		primary: { variant: 'primary', mode: 'filled' },
		dismiss: { variant: 'neutral', mode: 'stroke' },
	},
});
```

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

import { actionTheme } from './lib/theme';

export default defineConsentConfig({ options: { theme: actionTheme } });
```

Keep your `scripts` and other options in the same call.

## Change the banner's shape

For a full-width notice, use the `bar` variant. In a Client Component inside
the existing root, replace the stock banner with:

```tsx title="components/regional-banner.tsx"
'use client';

import { ConsentBanner, usePolicyRule } from 'c15t/next';

export function RegionalBanner() {
	const policy = usePolicyRule();
	return (
		<ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />
	);
}
```

[ConsentBanner](/docs/frameworks/next/components/consent-banner#variants)
lists every variant and position.

To remove the notice card's radius, add these values to the existing
`options.components.banner` slots. The root owns `data-prompt`, so the card
uses Tailwind's `group` selector to read it:

```ts
const bannerSlots = {
	root: { className: 'group' },
	card: { className: 'group-data-[prompt=notice]:rounded-none' },
	rightLink: {
		className: 'underline-offset-4 data-[right=opt-out]:text-red-700',
	},
};

// In the existing options.components object:
// banner: bannerSlots
```

The root also carries `data-variant`, so you can restyle one shape without
touching the others. Tailwind, giving a `bar` a brand-colored top edge and
tighter text:

```tsx
<ConsentProvider
	options={{
		mode,
		presentation: { prompt: { variant: 'bar' } },
		components: {
			banner: {
				root: { className: 'group' },
				card: {
					className:
						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
				},
			},
			description: {
				banner: { className: 'group-data-[variant=bar]:text-xs' },
			},
		},
	}}
/>
```

`data-variant` sits on the root, so child slots use Tailwind's `group`
prefix to read it.

[Class names and CSS-in-JS](/docs/customization/class-names) shows CSS
Modules, vanilla-extract, StyleX and Emotion classes on a part.

Set `noStyle` on a component to drop the built-in classes from every part and
keep only what your slots pass. Set `noStyle` in the provider options to do it
for every component.

[Component parts](/docs/customization/slots) lists every part key under
`components` and the `data-*` attributes each part carries. Action buttons
carry `data-action`, so a single rule such as `[data-action='dismiss']`
styles one role across every surface. Right links are underlined text by
default, so the only button on a notice is the primary action.

[Component parts](/docs/customization/slots) lists every component's part keys,
including the `ConsentGate` placeholder's `components['consent-gate'].root`,
`.title` and `.button`, and [class names and CSS-in-JS](/docs/customization/class-names) covers CSS
Modules, vanilla-extract, StyleX and Emotion.

## Turn on dark mode and change motion

Pass `colorScheme` to `ConsentTheme` in your layout and the same value in
`options` on `ConsentRoot`. Leave it unset to follow a `dark` class on
`<html>`, such as the one next-themes sets, and add dark colors with
`theme.dark`. [Dark mode](/docs/customization/dark-mode) covers each value
and a dark first paint.

`options.disableAnimation` on `ConsentRoot` turns off the banner and dialog
animations, and the same prop on `ConsentBanner` or `ConsentDialog` overrides
it for one surface. [Motion and animation](/docs/customization/motion) covers
the duration and easing tokens and reduced motion.

## Check the result

Open the page in a fresh session. The banner uses your colors and radius, and
the primary action has the style you set. Choices, policy and actions are the
same as with the default design; customizing never records a choice. The
[customization overview](/docs/customization/overview) covers tokens, parts,
copy and headless UI across frameworks.

# Translations
URL: https://c15t.com/docs/frameworks/next/translations
Where c15t banner and dialog copy comes from in Next.js, how the server and browser pick the visitor's language, and how to override copy and switch languages from a Client Component.

## Where the copy comes from

The banner, dialog, widget and gate placeholder read their text from the
translations in your Inth project, or your self-hosted backend's
configuration. The policy carries the copy for the visitor's language. Edit
wording there first, so it changes without a deploy.

Code can override that copy in two places:

* `options.i18n` on `ConsentRoot` changes a message everywhere it appears.
* Text props on `ConsentBanner` change one banner.

[Copy and translations](/docs/customization/translations) lists the message
keys and explains how code messages combine with the project's copy.

## How c15t picks the language

In the [App Router](/docs/frameworks/next/app-router) and
[Pages Router](/docs/frameworks/next/pages-router) setups, `resolveConsent`
reads the first entry of the request's `Accept-Language` header. It resolves
the policy and its copy on the server, so the banner in the first HTML is
already in the visitor's language. Pass `language` to `resolveConsent` to use
your own value instead, such as the locale from a `[lang]` route segment.

When the browser resolves consent, as in
[client-side rendering](/docs/frameworks/next/client-side) and
[static export](/docs/frameworks/next/static-export), the browser's `/init`
request carries its own `Accept-Language` header.

When your project has no copy for the requested language, the backend
returns its fallback language.

The banner, dialog and widget set `dir` from the active language. Right-to-left
languages such as Arabic and Hebrew render with `dir="rtl"`, and a floating
banner you did not position yourself moves to the opposite side.

## Change the copy in code

Keep the messages in their own module:

```ts title="lib/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/next';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

Import it in `c15t.config.ts` and pass it under `options`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

import { i18n } from './lib/consent-i18n';

export default defineConsentConfig({ options: { i18n } });
```

`ConsentRoot` reads the config in the browser and on the server, so the
layout keeps passing only `state`. Keep your `scripts` and other options in
the same call.

`ConsentRoot` renders on the server too, so your messages are already in the
server HTML.

For the visitor's language, your messages replace the project's copy key by
key. Keys you leave out keep the project's wording, and messages for other
languages are not applied. `ConsentRoot` reads `i18n` once, when it mounts. In
development it logs a warning if `i18n` changes later.

`i18n.locale` sets the language of the copy when no backend or server state
supplies one, as in offline mode. It defaults to `en`.

## Change one banner's copy

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. The props
replace the text in every language, so pass values in the page's language:

```tsx
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>;
```

## Switch the language at runtime

`useSetLanguage()` stores the new language, and `useInit()` resolves the policy
again, which fetches the copy for that language. Call both from your language
switcher:

```tsx title="components/language-switcher.tsx"
'use client';

import { useInit, useSetLanguage, useSnapshot } from 'c15t/next';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

Setting the language without calling `init()` changes nothing on screen. Your
`i18n` messages for the new language apply on top of the copy that arrives.

If your site changes language through its own i18n library, run the same two
calls when its locale changes. To make the server HTML match too, pass the
locale to `resolveConsent` as `language`.

## Verify

1. Under a policy that shows a banner, request a dynamic page with
   `curl -H 'Accept-Language: de' <your-url>`. If your project translates
   German, the banner text in the HTML is German.
2. Open the page in the browser and check that a message you set in `i18n`
   shows in the banner.
3. Switch the language with your switcher. DevTools Network shows a new
   request to your consent route or `/init`, and the banner and dialog text
   change without a reload.

# Compose your own banner
URL: https://c15t.com/docs/frameworks/next/compose
Build a Next.js consent banner as a Client Component from the ConsentBanner parts in c15t/next, with your own markup and buttons, rendered inside ConsentRoot.

## When to compose

Compose the banner from its parts when you need its elements in a different
order, an element it does not have, or your design system's button in place
of c15t's. The parts keep the stock
behavior. They read the same policy, record the same choices and render the
same class names, so theme tokens and slots still apply.

Try the lighter tools first:

|Change|Use|
|--|--|
|Colors, type, radius, spacing|[Theme tokens](/docs/customization/tokens)|
|Classes or attributes on one part|[Component parts](/docs/customization/slots)|
|Labels and languages|[Copy and translations](/docs/customization/translations)|
|Shape, position, button order|`ConsentBanner` props such as `variant`, `position`, `layout` and `primaryButton`|
|Different markup or order|Compound parts, on this page|
|Entirely custom UI and behavior|Headless hooks|

For a banner that shares nothing with the stock markup, use the
[headless hooks](/docs/frameworks/next/headless). For one changed class,
token or prop, see [customize](/docs/frameworks/next/customize).

## Compose the banner

`CookieBanner` keeps the stock card, title and copy, and renders each action
the policy asks for as your design system's button. `BrandButton` stands in
for that button:

```tsx title="components/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

```tsx title="components/cookie-banner.tsx"
'use client';

import { ConsentBanner, useTranslations } from 'c15t/next';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

`c15t/next` re-exports every `c15t/react` component, so `ConsentBanner` and
its parts come from the same import as `ConsentRoot`. The file starts with
`'use client'` because a Server Component can neither read a property of a
client component, such as `ConsentBanner.Root`, nor pass a function, such as
`renderAction`.

The parts read the provider inside
[ConsentRoot](/docs/frameworks/next/components/consent-root). Import
`CookieBanner` in the layout that renders `ConsentRoot`, from the
[quickstart](/docs/frameworks/next/quickstart#resolve-consent-in-the-root-layout)
or your router guide, and render it in place of `ConsentBanner`, next to
`ConsentDialog`. `CookieBanner` is a client component, so a Server Component
layout can render it:

```tsx title="app/layout.tsx (partial)"
<ConsentRoot state={resolveConsent()}>
	{children}
	<CookieBanner />
	<ConsentDialog />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</ConsentRoot>;
```

The Pages Router renders the same components in `pages/_app.tsx`, so the
composed banner works in both routers.

`ConsentBanner.Root` renders only while the banner is the active surface,
the same condition the stock `ConsentBanner` uses, so `CookieBanner` needs
no visibility logic. It renders nothing before a policy resolves and closes
once the visitor chooses.

`ConsentBanner.PolicyActions` renders the actions the policy asks for, in
the policy's order and groups, with any rights links, such as "Do not sell
or share my data", before them. For each action it calls `renderAction`
with the action name and the props c15t would give the stock button:
`key`, `consentAction`, `isPrimary`, and a `style` that stretches the
buttons when the layout fills the row. Return an element to replace that
button, or `null` to keep the stock one. The banner never renders `save`,
so the example skips it.

Each action part gets those props plus `asChild` and `noStyle`. `asChild`
renders `BrandButton` in place of c15t's `button`, and `noStyle` drops
c15t's button classes so they do not compete with yours. The part keeps its
behavior. Accept saves every category and Reject saves only necessary, and
both close the banner. Customize opens the preference dialog. Dismiss
records that the visitor saw a notice, without recording a choice.

With `asChild`, the part's default label does not render, because your
element keeps its own children. `useTranslations()` returns the labels the
stock buttons use, in the visitor's language.

Under a notice, the policy asks only for an acknowledgement, so
`PolicyActions` passes `dismiss` and `CookieBanner` renders one button. If
you place `ConsentBanner.AcceptButton` and `ConsentBanner.RejectButton`
yourself instead, they render under every policy, including one that owes
only a notice.

## Banner parts

Every part is a property of `ConsentBanner`. All parts except `Root` and
`PolicyActions` forward their ref, and they accept the attributes of the
element they render plus `noStyle`.

|Part|Renders|Props|
|--|--|--|
|`Root`|The `div` that positions the banner, only while the banner shows. Renders the backdrop itself when blocking.|`variant`, `position`, `blocking`, `models` (default `['opt-in', 'opt-out']`), `uiSource` (default `'banner'`), `noStyle`, `disableAnimation`|
|`Card`|The visible `div`, labelled with the title. `role="region"`, or `role="dialog"` with `aria-modal="true"` and a focus trap when blocking.|`asChild`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`Title`|An `h2` with the translated title, or the notice title under a notice.|children replace the text|
|`Description`|A `div` with the translated copy and the configured legal links.|`legalLinks`, `asChild`|
|`PolicyActions`|`Footer`, the rights links and the policy's action groups.|`renderAction`, children replace the rights links|
|`Footer`|A `div` for the actions.|`asChild`|
|`FooterSubGroup`|A `div` for one group of actions. `Actions` is an alias.|`asChild`|
|`AcceptButton`|A `button` that saves every category and closes the banner.|action button props|
|`RejectButton`|A `button` that saves only necessary and closes the banner.|action button props|
|`CustomizeButton`|A `button` that opens the preference dialog.|action button props|
|`DismissButton`|A `button` that acknowledges a notice.|action button props|
|`Rights`|A `div` with one `RightLink` per right the policy recommends, or nothing.|`rights`, `asChild`|
|`RightLink`|A `button` styled as underlined text that opens the preference dialog.|`right` (`'opt-out'` or `'preferences'`), `asChild`|
|`Overlay`|The backdrop of a blocking banner. `Root` already renders it, so do not add it.|none|

`Content` is an alias of `Card`.

The action buttons take `asChild`, `noStyle`, `consentAction`, `isPrimary`,
`variant` (`'primary'` or `'neutral'`), `mode` (`'filled'`, `'stroke'`,
`'lighter'` or `'ghost'`), `onClick` and any `button` attribute. Your
`onClick` runs before the action, and calling `event.preventDefault()` in
it skips the action. `consentAction` sets `data-action` and selects the
`theme.consentActions` entry. `PolicyActions` passes it for you, and
`DismissButton` sets it itself. A button you place yourself has no
`data-action` and no per-action theme until you pass `consentAction`.

`useConsentBannerSurface()` returns the `variant`, `position`,
`positionSource` and `blocking` that `Root` resolved, for your own elements
that depend on the banner's shape.

[ConsentBanner](/docs/frameworks/next/components/consent-banner) lists the
stock banner's props, variants and data attributes.

## Render a part as your own element

`asChild` swaps the part's element for the one element you pass as its
child. `Card`, `Header`, `Description`, `Footer`, `FooterSubGroup`,
`Rights`, `RightLink` and the action buttons support it. `Root` and
`Overlay` ignore it, and `Title` always renders an `h2`, so a child you pass
to `Title` ends up inside that `h2`. `Description` with `asChild` drops the
inline legal links.

The part merges its props onto your element:

* The part's props apply first, and props you set on the child win.
* `className` keeps both, the part's classes first.
* `style` merges, and your values win per property.
* Event handlers both run, yours first. On an action button, calling
  `event.preventDefault()` in yours skips c15t's action.
* The part's ref and your child's ref both receive the DOM node.
* Your child keeps its own children. The part's default content, such as a
  button label, does not render.

Your component has to pass its ref and every prop it does not use to its
DOM element. Otherwise c15t's click handler, `data-action` and focus
handling never reach the page. The `BrandButton` in the example does both.
Pass exactly one element. Text, a fragment or several children render
nothing.

Action buttons pass no `type` under `asChild`, so give your button a
default of `type="button"`. Without it, the button submits a surrounding
form.

## Compose the preference dialog

`ConsentDialog` has parts too. Compose it when the dialog needs a different
header or footer, and keep `ConsentWidget` inside `Content`. The widget
owns the category switches, the draft and the policy's Save, Accept and
Reject buttons.

|Part|Renders|Props|
|--|--|--|
|`Root`|The dialog in a portal on `document.body`, with its open state, backdrop, focus trap, scroll lock and Escape to close.|`open`, `models` (default `['opt-in', 'opt-out', 'none']`), `overlay` (a node, or `false` for none), `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`, `uiSource` (default `'dialog'`)|
|`Card`|The panel `div`.|`className`, `style`, `noStyle`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`HeaderTitle`|An `h2` with `id="consent-dialog-title"`.|children replace the text|
|`HeaderDescription`|A `div` with `id="consent-dialog-description"` and the legal links.|`legalLinks`, `asChild`|
|`Content`|A `div` for `ConsentWidget`.|`asChild`|
|`Footer`|A `div` with the branding tag, unless you pass children or `hideBranding`.|`hideBranding`, `asChild`|
|`ConsentCustomizationCard`|The stock card with all of the above.|`legalLinks`, `hideBranding`, `noStyle`|
|`Overlay`|The backdrop. `Root` already renders it.|none|

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Render the composed dialog in place of `ConsentDialog`, next to your
banner. The stock `ConsentDialog` downloads its code when the dialog first
opens. The parts load that same code when they first render, and a
composed `ConsentDialog.Root` renders on every page, so the code downloads
with the page. `c15t/react/components/consent-dialog` exports the same
parts without the deferral.

`ConsentWidget` has parts as well, such as `ConsentWidget.Root`,
`ConsentWidget.Accordion`, `ConsentWidget.AccordionItems` and
`ConsentWidget.PolicyActions`, for a preference list with your own layout.

`c15t/next` exports `ConsentDialog` and `ConsentWidget` with their parts.
It has no `components/consent-dialog` subpath, so import the parts without
the deferral from `c15t/react/components/consent-dialog`, in a Client
Component. [ConsentDialog](/docs/frameworks/next/components/consent-dialog)
and [ConsentWidget](/docs/frameworks/next/components/consent-widget) list
every part and its slots.

## Keep the banner accessible

The stock parts carry the roles, labels and focus handling. A composed
banner keeps them as long as you keep the parts that own them:

* `Card` owns the banner's role, label and focus trap. With `asChild`, your
  element receives them, so do not set `role` or `aria-modal` on it.
* `Card` takes its `aria-label` from the translated title, not from text you
  pass to `Title`. If you change the title text, pass the same text as
  `aria-label` on `Card`.
* To attach your own ref to `Card`, pass a ref object from `useRef`. A
  callback ref turns off the focus trap on a blocking banner.
* Render each action as a real `button`. Its text is the accessible name,
  so keep the label inside your button.
* Keep a way to reopen preferences after the banner closes, such as the
  `ConsentDialogLink` in your footer.
* The dialog's `Root` names the panel with the ids on `HeaderTitle` and
  `HeaderDescription`. Keep both parts, or put `id="consent-dialog-title"`
  and `id="consent-dialog-description"` on your own heading and copy.

## Keep theme tokens and slots working

The parts render the stock class names, and the banner's `Root` renders
c15t's rules, so c15t's styles and `--c15t-*` tokens style a composed
banner the way they style the stock one.

Slots in the provider's `options.components` reach each part by key:
`banner.root`, `banner.card`, `banner.header`, `banner.title`,
`description.banner`, `banner.footer` and `banner.actions`,
`banner.actionGroup`, `banner.rights` and `banner.rightLink`. A class you
pass to a part joins its stock and slot classes. The stock `ConsentBanner`
also renders the `banner.cardShell` wrapper and the "Secured by" tag, and a
composed banner renders neither.

Action buttons read the `button.primary` or `button.secondary` slot and the
`theme.consentActions` entry for their `consentAction`. `noStyle` on a
button drops c15t's button classes and keeps slot classes. `noStyle` on
`Root` removes the built-in styling from every part inside it.

[Customize](/docs/frameworks/next/customize) shows where to set tokens with
`ConsentTheme`, and slots and `consentActions` through `ConsentRoot`'s
`options`.

## Check the result

1. Clear site data and reload. The composed banner appears with your
   buttons. In DevTools Elements, each action is your element with a
   `data-action` attribute. In DevTools Network, no optional vendor request
   has fired.
2. Tab through the banner. Every action is reachable in the policy's order
   and shows a focus ring. Press Enter on Customize, and the preference
   dialog opens.
3. Click Reject all. The banner closes. Reload, and it stays closed with
   the vendors still blocked.
4. Reopen preferences from your footer link. The optional categories are
   off. Allow one, save, and only that category's vendors load.
5. If your policies include a notice region, test it too. The banner shows
   your acknowledgement button and no Accept or Reject.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Headless
URL: https://c15t.com/docs/frameworks/next/headless
Build a custom consent banner in Next.js with the c15t/next/headless hooks inside your existing ConsentRoot.

## When to go headless

The pre-built banner and dialog cover most designs through props, slots, and
the stylesheet. Go headless when your markup has to be something else
entirely: a design system component, a native sheet, or a layout the compound
parts cannot express.

Headless code owns the rendered controls, so it also owns the compliance
outcome. The hooks hand you the actions a policy requires, the rights it must
keep reachable, and diagnostics when your presentation drops one. Render from
those lists rather than from a fixed set of buttons, and a site that later adds
a notice region keeps working without a code change.

Check for a policy before rendering your own surfaces. `useModel()` from
`c15t/next` returns `null` while no rule has resolved and `'none'` under a rule
that owes no consent UI, and the pre-built surfaces render nothing in that
state.

## Minimal example

The headless hooks read the runtime from the `ConsentRoot` set up in your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) guide, so they only run in a
Client Component. Render this component inside that existing root in place
of the stock banner. Keep the dialog and persistent preferences control.

```tsx title="components/consent-banner.tsx"
'use client';

import { useHeadlessConsentUI, useTranslations } from 'c15t/next/headless';

const ACTION_LABELS = {
	accept: 'acceptAll',
	reject: 'rejectAll',
	customize: 'customize',
	dismiss: 'acknowledge',
	save: 'save',
} as const;

export function Banner() {
	const { banner, performAction, openDialog } = useHeadlessConsentUI();
	const { common, rights } = useTranslations();

	if (!banner.isVisible) {
		return null;
	}

	return (
		<section role="region" aria-label="Privacy">
			{banner.preferenceControls.map((right) => (
				<button key={right} type="button" onClick={openDialog}>
					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
				</button>
			))}
			{banner.actionGroups.map((group) => (
				<div key={group.join('-')}>
					{group.map((action) => (
						<button
							key={action}
							type="button"
							data-primary={banner.primaryActions.includes(action) || undefined}
							onClick={() => performAction(action)}
						>
							{common[ACTION_LABELS[action]]}
						</button>
					))}
				</div>
			))}
		</section>
	);
}
```

`banner.actionGroups` is the resolved layout: reject and accept share a group
at equal prominence, and the rest follow. `banner.orderedActions` is the same
list flattened. Under a notice the only action is `dismiss`, and
`banner.preferenceControls` recommends additional buttons for opening
preferences. Under a notice it contains `opt-out`, which selects the
"Do not sell or share my data" label. The example renders that button and
an "OK" button. Both controls keep their own command: opening
preferences and dismissing the notice.

The list is a rendering helper. It does not establish that your UI implements
all policy rights. Provide disclosure and persistent preferences access.

`performAction` saves all categories for `accept`, none for `reject`, the
current draft for `save`, records a dismissal for `dismiss`, and opens the
preference center for `customize`. `banner.diagnostics` reports when a host
layout drops a required action or gives equivalent actions different
prominence. Review each diagnostic when configuring custom presentation.

`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
shape from `presentation.prompt`, so a headless surface can follow the same
bar, widget, or wall choice the pre-built banner would make, and can trap
focus and lock scroll exactly when `blocking` is true.

# Components
URL: https://c15t.com/docs/frameworks/next/components
Every c15t component a Next.js app imports from c15t/next, what each renders, which ones are Client Components, and where to start.

## Component reference

`c15t/next` exports `ConsentRoot` and re-exports every component and hook from
`c15t/react`, so a Next.js app needs one import path. Every component except
`ConsentTheme` ships with `'use client'`. You can still render them from a
Server Component, as long as every prop you pass is serializable.

|Component|Renders|Runs as|Reference|
|--|--|--|--|
|`ConsentRoot`|The consent runtime, seeded with the state `resolveConsent` returned|Client Component|[ConsentRoot](/docs/frameworks/next/components/consent-root)|
|`ConsentBanner`|The banner, when the visitor's policy asks for one|Client Component|[ConsentBanner](/docs/frameworks/next/components/consent-banner)|
|`ConsentDialog`|The preference center as a modal|Client Component|[ConsentDialog](/docs/frameworks/next/components/consent-dialog)|
|`ConsentWidget`|The preference center inline in a page, for a privacy route|Client Component|[ConsentWidget](/docs/frameworks/next/components/consent-widget)|
|`ConsentDialogLink`|An unstyled button that opens the dialog, for your footer|Client Component|[ConsentDialogLink](/docs/frameworks/next/components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens the dialog. `ConsentDialogTriggerToolbar` adds your own actions beside it|Client Component|[ConsentDialogTrigger](/docs/frameworks/next/components/consent-dialog-trigger)|
|`ConsentGate`|Its children while a category is allowed, a placeholder otherwise|Client Component|[ConsentGate](/docs/frameworks/next/components/consent-gate)|
|`ConsentTheme`|A `<style>` element with your theme tokens|Server-safe|[Customize](/docs/frameworks/next/customize)|
|`DevTools` from `c15t/next/devtools`|A development panel for consent state, scripts and events|Client Component|[DevTools](/docs/frameworks/next/components/dev-tools)|

Render every component except `ConsentTheme` inside `ConsentRoot`, because
they read the runtime `ConsentRoot` creates. `ConsentRoot` already renders
`ConsentProvider`, so do not mount both.

## Start with ConsentRoot, the banner and the dialog

Most apps start with four components. `ConsentRoot` holds the runtime,
`ConsentBanner` and `ConsentDialog` ask for a choice, and a
`ConsentDialogLink` lets visitors reopen their preferences. The quickstart
renders them in the root layout, a Server Component:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

`ConsentRoot` reads `c15t.config.ts`, so the layout passes it only the
`state` from `resolveConsent`. The
[Pages Router guide](/docs/frameworks/next/pages-router) renders the same
components in `pages/_app.tsx`. Add `ConsentWidget`, `ConsentDialogTrigger` or
`ConsentGate` later, where a page needs them.

## Server and Client Components

In the App Router, the `'use client'` boundary decides what you can pass as a
prop:

* **`ConsentRoot`** reads `c15t.config.ts` in the browser, so a Server
  Component passes it only `state`. The `state` from `resolveConsent`, or its
  promise, is plain data and can cross. Put functions such as callbacks in
  the config, not in props from a Server Component.
* **Banner, dialog, widget, link, trigger and gate** can render straight from
  a Server Component page or layout under `ConsentRoot`. Strings, numbers,
  booleans and JSX children cross the boundary. Function props, such as the
  `onSelect` handler of a `ConsentDialogTriggerToolbar` action, need a
  `'use client'` file.
* **`ConsentTheme`** has no `'use client'` directive. Render it from a Server
  Component layout and the theme generator stays out of the browser bundle.
* **`DevTools`** loads only in development. Import it with `next/dynamic` and
  `ssr: false`, as its page shows.

A component that reads consent state with a hook, such as `useConsent`, is
always a Client Component. See [hooks](/docs/frameworks/next/hooks).

## IAB TCF components

`c15t/next` does not re-export the IAB TCF components. Import
`IABProvider`, `IABConsentBanner` and `IABConsentDialog` from `c15t/react/iab`,
render them inside `ConsentRoot` next to
`ConsentBanner` and `ConsentDialog`, and load `c15t/next/styles.css` and
`c15t/next/iab/styles.css` with `styles: false`. All three are Client
Components. The stock banner and dialog stay closed
under an IAB policy. See [IAB TCF](/docs/frameworks/next/iab).

## Other entry points

|Import|Exports|Use|
|--|--|--|
|`c15t/next/components/consent-dialog-link`|`ConsentDialogLink` only|A module that needs the link without loading the rest of the adapter|
|`c15t/next/headless`|Headless hooks|Your own banner and dialog markup. See [headless](/docs/frameworks/next/headless)|
|`c15t/next/server`|`resolveConsent` and the other server helpers|Server Components and Route Handlers|
|`c15t/next/devtools`|`DevTools`|Development only|

## Check the components

Load the site in a private window under a policy that asks for a choice:

1. The banner shows, and DevTools Network has no requests to your vendors'
   hosts.
2. Click the footer's `ConsentDialogLink`. The dialog opens with every optional
   category off.
3. Allow one category and save. Its vendor requests appear, and a
   `ConsentGate` for that category mounts its children.
4. Reload. The banner stays closed, and the link still reopens the dialog.
5. View the page source. With the
   [awaited layout](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
   a first visit contains an element with
   `data-testid="consent-banner-root"`, and the page after your choice does
   not.

# ConsentRoot
URL: https://c15t.com/docs/frameworks/next/components/consent-root
Render the Next.js ConsentRoot once from a Server Component layout, pass it the server-resolved state, and see how it reads c15t.config.ts and picks the consent mode.

## Mount one root

`ConsentRoot` wraps the React `ConsentProvider` and connects it to
`c15t.config.ts` and the server-resolved state. Mount it once; it already
supplies the provider used by consent components and hooks.

Follow the [quickstart](/docs/frameworks/next/quickstart),
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) for the complete setup.
Keep `ConsentRoot` mounted across navigation.

Render `ConsentRoot` straight from a Server Component layout, or from
`pages/_app.tsx`. `c15t/next` gives Server Components a client reference to
it, and `ConsentRoot` reads `c15t.config.ts` itself, so the layout passes only
`state`. The `state` from `resolveConsent`, or its promise, is plain data and
can cross from the server to the browser. `withConsentManifest` in
`next.config.ts` is what makes the config file reachable; without it,
`ConsentRoot` warns outside production that it found no config.

## Props

|Prop|Purpose|
|--|--|
|`state`|Visitor state or its promise from `resolveConsent`, or `pageProps.consent` from `withConsentProps`. Omit it to resolve consent in the browser|
|`config`|A `defineConsentConfig` result to use instead of `c15t.config.ts`, for a root the file can't reach, such as in a test. A Server Component can't pass it, because it may hold functions|
|`scripts`|Consent-managed script configurations|
|`vendors`|Vendors the preference center lists under their category, each with its own switch. Merged with vendors the backend declares. See [vendor consent](/docs/frameworks/next/vendor-consent)|
|`clearOnRevocation`|Cookies and Web Storage keys to remove when their category is denied. Initial-only; remount `ConsentRoot` to replace it|
|`scriptLoader`|Script-loader options|
|`networkBlocker`|[Network-blocker](/docs/frameworks/next/network-blocker) options, or `false` to disable it|
|`persistence`|Browser persistence options; defaults to `true`|
|`options`|Provider options such as styling, callbacks and an explicit `mode` override|

Every prop except `state` and `config` can also be set in `c15t.config.ts`. A
prop wins over the config's value of the same name. `options` merges one key
at a time, and `options.callbacks` one callback at a time, so
`options={{ nonce }}` keeps the config's callbacks and other options.

### Which mode does ConsentRoot use?

`ConsentRoot` runs the config's `mode`, `manifest()` by default, or
`options.mode` when you pass one. It loads only that mode's code:

* `manifest()`: with `state`, the browser applies it and needs no request.
  Without `state`, or to re-init, it asks `${routePrefix}/init` when the
  config sets `routePrefix`, else `${backendURL}/init`.
* `manifest({ resolve: 'browser' })`: the browser loads the resolver on first
  use and fetches `${routePrefix}/manifest`, else `${backendURL}/manifest`.
* `hosted()`: the browser calls `${backendURL}/init` when it needs a policy.
* `offline()`: the browser resolves bundled rules. Choices stay in the
  browser and nothing is recorded. Not recommended for production
  environments.

Choices post to `${backendURL}/subjects` in every mode but `offline()`. With
no backend URL anywhere, `ConsentRoot` throws
`` @c15t/nextjs: manifest() needs a backend URL. Set NEXT_PUBLIC_C15T_BACKEND_URL (or NEXT_PUBLIC_INTH_PROJECT_URL), or `backendURL` in c15t.config.ts. ``
instead of running a mode you did not choose. See
[offline configuration](/docs/frameworks/next/data-fetching-reference#offline-configuration)
and [consent modes](/docs/concepts/modes).

`options.mode` also takes a transport, such as `custom(transport)`. A
`hosted()` or `offline()` transport from `c15t/react` works there, but
outside production it warns that its code is now in the first-load bundle.
Use the data factories from `c15t/next` instead.

## Provider options

`ConsentRoot` passes `options` to its provider. Keep scripts, vendors,
`clearOnRevocation`, persistence and network-blocker configuration at the top
level of the config or the props; `options` does not accept them.

The provider owns initialization, persistence, script loading and subscriptions.
Changing its initial mode or prefetch configuration is not a supported way to
switch visitors or backends after mounting.

|Option|Purpose|
|--|--|
|`mode`|`manifest()`, `hosted()` or `offline()` from `c15t/next`, or a transport such as `custom(transport)`. Replaces the config's `mode`|
|`callbacks`|Choice, permission and error events|
|`theme`, `components`|Consent-action styles, theme slots and component slot attributes. Tokens render through `ConsentTheme`|
|`presentation`|Prompt and preferences layout behavior|
|`experiment`|A/B test of `presentation`, read once at mount. A `state` from `resolveConsent({ experiment })` already carries it. See [banner experiments](/docs/guides/banner-experiments)|
|`preloadDialog`|When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](/docs/frameworks/next/components/consent-dialog#behavior)|
|`i18n`|Languages and message overrides|
|`storageConfig`|Browser record storage configuration|
|`enabled`|Set false only when intentionally bypassing consent enforcement|
|`reloadOnConsentRevoked`|Reload the page after the visitor turns off a granted category or vendor; defaults to `true`|

`enabled: false` grants categories and allows gated loading while suppressing
consent UI. It is not a way to fix failed initialization or hide a banner in
production.

## Listen for consent changes

`onChoiceRecorded` reports explicit accept, reject and save actions.
`onPermissionsChanged` also covers changes caused by policy, expiry or privacy
signals. Hydration and notice dismissal do not become explicit choices.

## When would I use ConsentProvider directly?

Use `ConsentProvider` from `c15t/next` when you need to manage the runtime and
transport yourself. For example, it accepts an externally owned `runtime`.
Its owner must start and dispose that runtime.

For standard Next.js setups, keep `ConsentRoot`. It supports
[browser initialization](/docs/frameworks/next/client-side) as well as
[server rendering](/docs/frameworks/next/rendering).

## Reload after revocation

Removing a script cannot stop code that already ran. A vendor's listeners,
timers and widgets keep working until the page unloads. When an accept, reject
or save turns off a category or vendor that was granted, `ConsentRoot` reloads
the page once the save request settles, so the next page runs only permitted
code. `onBeforeConsentRevocationReload` runs just before the reload.

Otherwise, expiry, policy changes and privacy signals do not reload the page. Set
`options.reloadOnConsentRevoked` to `false` only when every gated vendor stops
itself on revocation, for example through its own opt-out API.

## Clear data when consent is denied

Set `clearOnRevocation` in `c15t.config.ts`, or pass it to `ConsentRoot`, to
declare cookies and Web Storage keys by optional consent category. Neither
accepts it inside `options`. If you use `ConsentProvider` directly, pass it in that provider's
`options`. Cleanup runs in the browser after policy resolution, and the value
is initial-only. See [clear on revocation](/docs/frameworks/next/clear-on-revocation)
for examples, cookie scopes, and browser limits.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/next/components/consent-banner
Render the pre-built ConsentBanner inside a Next.js ConsentRoot and configure its variants, per-policy buttons and compound parts.

## Render the banner inside `ConsentRoot`

Render one `ConsentBanner` inside `ConsentRoot`, in the root layout from your
[App Router](/docs/frameworks/next/app-router) setup or in `pages/_app.tsx`
from the [Pages Router](/docs/frameworks/next/pages-router) setup:

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

The layout is a Server Component. `c15t/next` gives it client references to
`ConsentRoot` and `ConsentBanner`, and `ConsentRoot` reads `c15t.config.ts`
itself, so the layout passes only `state`. Function props, such as
`renderAction`, need a `'use client'` file.

The banner renders what the resolved policy rule requires. With the default
streamed layout, it arrives in a later chunk of the server response, before
hydration, unless `options.streamBanner` is `false`. With the
[awaited layout](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html)
or Pages Router `getServerSideProps`, it is part of the server HTML with the
page. The server and the browser use the same state:

* A `choice` prompt shows the actions the rule allows: reject and accept at
  equal prominence, plus customize when the rule offers it.
* A `notice` prompt shows an "OK" button and a button styled as
  underlined text, labeled "Do not sell or share my data". The latter opens
  preferences. A notice never traps focus or locks scroll.
* A rule with `prompt: 'none'` renders nothing.

An opt-out rule with `prompt: 'none'` still has rights, so the preference
center and the dialog trigger stay available as the route to preferences. A
rule with `model: 'none'` owes no rights, so nothing renders unless you add
`rights: ['preferences']`. With no resolved rule at all, because resolution
failed, no rule matched and you set no default, or init is still withheld, no
consent surface renders: not the banner, the dialog, the widget, the
preferences link, or the trigger. They appear as soon as a rule resolves,
without a remount. `offline()` without `policyRules` resolves the recommended
pack, so it shows the strict opt-in banner until you pass a country.

Acknowledging a notice records its dismissal. It does not record consent or
change category permissions, including existing denials and privacy-signal
restrictions. Customize the label through `common.acknowledge` in your
translations, or use `dismissButtonText` for one banner.

The additional preferences button uses the opt-out label when appropriate.
A choice prompt without Customize renders a "Manage preferences" button.
Both are button elements that open the preference center; CSS gives them
an underlined text appearance. They do not submit an opt-out by themselves.

`preferenceControls` recommends these extra buttons for the stock UI.
It does not verify disclosure or access to rights. Configure your legal links
and keep preferences reachable after the banner closes.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`title`|`ReactNode`|translation|Overrides the title. Under a notice the default is `cookieBanner.noticeTitle`.|
|`description`|`ReactNode`|translation|Overrides the description. Under a notice the default is `cookieBanner.noticeDescription`.|
|`acceptButtonText`|`ReactNode`|`common.acceptAll`|Accept label.|
|`rejectButtonText`|`ReactNode`|`common.rejectAll`|Reject label.|
|`customizeButtonText`|`ReactNode`|`common.customize`|Customize label.|
|`dismissButtonText`|`ReactNode`|`common.acknowledge`|Label of the notice acknowledgement.|
|`variant`|`PromptVariant`|`floating`|Shape of the prompt. See [Variants](#variants).|
|`position`|`PromptPosition`|per variant|Where the prompt sits. Must be valid for the variant.|
|`blocking`|`boolean`|`true` on `wall`|Backdrop, scroll lock, focus trap, and no outside dismissal, as one value.|
|`layout`|`ConsentBannerLayout`|policy default|Orders and groups actions. Required actions the layout omits are restored.|
|`primaryButton`|`ConsentBannerButton \|ConsentBannerButton[]`|`'customize'`|Which actions get the primary treatment. On a notice, dismiss is primary when it is the only action.|
|`direction`|`'row' \|'column'`|`'row'`|How action groups flow.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which configured legal links render inline.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`scrollLock`|`boolean`|unset|Deprecated. Use `blocking` to control scrolling, focus and backdrop together.|
|`trapFocus`|`boolean`|unset|Deprecated. Use `blocking`.|
|`disableAnimation`|`boolean`|`false`|Skips enter and exit animations.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Per-policy buttons

The default already makes Customize primary on a choice banner and OK
primary on a notice. To set button order and treatment for specific rules,
read the active policy inside the provider:

```tsx
'use client';

import { ConsentBanner, usePolicyRule } from 'c15t/next';
import type { ConsentBannerProps } from 'c15t/next';

const banners: Record<
	string,
	Pick<ConsentBannerProps, 'layout' | 'primaryButton' | 'variant'>
> = {
	europe_opt_in: {
		layout: [['reject', 'accept'], 'customize'],
		primaryButton: 'customize',
	},
	us_privacy_states: {
		layout: ['dismiss'],
		primaryButton: 'dismiss',
		variant: 'bar',
	},
};

export function RegionalBanner() {
	const policy = usePolicyRule();
	return <ConsentBanner {...(policy ? banners[policy.id] : undefined)} />;
}
```

Render `RegionalBanner` inside your existing consent boundary, replacing its
stock banner. The layout controls the
action groups; the opt-out preferences button still appears on a notice.
Required actions omitted from a layout are restored. Accept and Reject
keep equivalent default prominence.

Choose one brand color and make whichever action is primary use a filled
button through the provider's theme:

```ts
const theme = {
	colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
	consentActions: { primary: { variant: 'primary', mode: 'filled' } },
} as const;
```

Pass `theme` through `options` in `c15t.config.ts`.
Per-action theme overrides such as `consentActions.dismiss` take precedence
over this primary style. See [Customize](/docs/frameworks/next/customize) for
tokens and slots, and [Policies](/docs/concepts/policies) for the rule IDs and
coverage.

## Variants

The policy decides which actions the banner offers. The variant decides the
shape those actions take. Both come from the same component, so a bar for a
notice region and a card for an opt-in region need no extra components.

Set the variant on the banner, or on the provider under
`presentation.prompt` when every banner should share it. The prop wins.

```tsx
<ConsentBanner variant="floating" position="bottom-center" />;
```

A floating card in a corner or centered on an edge. This is the default for
every prompt. A notice keeps the same card, with its right link and "OK" in the footer.

```tsx
<ConsentBanner variant="bar" position="top" />;
```

A bar across the full width of the viewport. From 1024px wide the text, the
right links, and the controls share one row. Opt in to it for regions that
expect a classic cookie bar.

```tsx
<ConsentBanner variant="widget" position="bottom-right" />;
```

A compact card with smaller type. The full description and its legal links
remain visible. Pair it with a short notice.

```tsx
<ConsentBanner variant="wall" />;
```

A centered card over a backdrop that blocks the page until the visitor
answers. A wall is always blocking.

Each variant accepts its own positions:

|Variant|Positions|Default|
|--|--|--|
|`floating`|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|`top`, `bottom`|`bottom`|
|`widget`|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|`center`|`center`|

A default corner mirrors left and right for right-to-left languages. A
position you set is never mirrored. A position that is not valid for the
variant falls back to the default and logs an `invalid-position` diagnostic
in development.

`blocking` controls the backdrop, scroll lock, and focus trap together.
An explicit value overrides the deprecated `scrollLock` and `trapFocus`
options. Without `blocking`, either legacy option set to `false` selects
non-blocking behavior; otherwise a legacy `true` selects blocking behavior.

A choice `wall` always blocks. Notices always stay non-blocking, and asking
for a notice `wall` falls back to `floating` with an `invalid-variant`
diagnostic. Blocking banners carry `role="dialog"` and `aria-modal="true"`.
Non-blocking banners leave page controls usable by keyboard and pointer.

`PromptVariant` and `PromptPosition` are exported from `c15t/next`.
Compound parts can read the resolved shape with `useConsentBannerSurface()`,
which returns `variant`, `position`, `positionSource` (`host` or `default`),
and `blocking`.

## Composition

Every part is available as `ConsentBanner.<Part>` for custom layouts. The
parts read the same policy state the pre-built banner does, so a custom layout
still gets the right actions for the active rule. Render this Client Component
inside the existing boundary, replacing its stock banner. Keep the dialog and
persistent preferences control.

```tsx title="components/compact-banner.tsx"
'use client';

import { ConsentBanner } from 'c15t/next';

export function CompactBanner() {
	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions />
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
}
```

`ConsentBanner.PolicyActions` renders the resolved action groups and, before
them, the additional preferences buttons. Pass children to replace those
buttons while retaining the policy action groups. This supports custom labels
and button markup.

Use the individual parts when you need a different order or your own markup:

* `ConsentBanner.AcceptButton`, `ConsentBanner.RejectButton`,
  `ConsentBanner.CustomizeButton`, and `ConsentBanner.DismissButton` render one
  action each. `DismissButton` defaults its label to `common.acknowledge`.
* `ConsentBanner.Rights` renders the additional preferences buttons. It
  renders nothing when the list is empty. Pass `rights` to override the
  list.
* `ConsentBanner.RightLink` renders a single right. `right` is `'opt-out'`
  or `'preferences'`. By default it is a button element styled as an
  underlined text link, carrying `data-action="right"` and `data-right`; it
  opens the preference center on click and accepts `asChild` to render your
  own element, such as an anchor to a dedicated opt-out page.

```tsx
<ConsentBanner.Rights>
	<ConsentBanner.RightLink right="opt-out" asChild>
		<a href="/privacy/do-not-sell">Do not sell or share my data</a>
	</ConsentBanner.RightLink>
</ConsentBanner.Rights>;
```

`useBannerCopy()` returns the title, description, and prompt kind the banner
would use, for custom headers that still follow the notice copy.

## Data attributes

The root element carries attributes you can target from CSS or Tailwind. The
card carries `data-state` (`open` or `closed`) for the enter and exit
animations.

|Attribute|Values|
|--|--|
|`data-prompt`|`choice`, `notice`|
|`data-model`|`opt-in`, `opt-out`, `iab`|
|`data-variant`|`floating`, `bar`, `widget`, `wall`|
|`data-position`|The resolved position for the variant|
|`data-blocking`|`true`, present only while blocking|

Each action button carries `data-action`, and each right link carries
`data-action="right"` plus `data-right`. The built-in stylesheet keys every
variant's geometry on `data-variant` and `data-position`, and uses
`data-prompt="notice"` to lay the footer out as one row with the right
links leading and "OK" trailing.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/next/components/consent-dialog
Mount ConsentDialog as a Client Component inside a Next.js ConsentRoot to open the preference center from the banner, links and triggers.

## Open the preference center

`ConsentDialog` is the modal preference center. It is a Client Component that
a Server Component layout can render, inside the `ConsentRoot` that already
provides the consent runtime, as in the
[App Router](/docs/frameworks/next/app-router) and
[Pages Router](/docs/frameworks/next/pages-router) setups. Mount it once,
next to the banner; it opens whenever something makes `dialog` the active
surface: the banner's Customize button, a `ConsentDialogLink` in your footer,
a `ConsentDialogTrigger`, or your own code.

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

Pass props on that element, for example `<ConsentDialog hideBranding />`.

The dialog renders nothing on the
server. It mounts through a portal after hydration, so it does not change the
server HTML or the streamed shell. If the visitor owes a choice or notice,
routes that await `resolveConsent` can render the banner on the server. Pages Router pages without `getServerSideProps` show it
after browser policy resolution. No banner appears when the policy requires
no prompt or an existing record already satisfies it.

To open it from another Client Component inside the boundary, set the active
surface:

```tsx title="components/privacy-menu-item.tsx"
'use client';

import { useSetActiveUI } from 'c15t/next';

export function PrivacyMenuItem() {
	const setActiveUI = useSetActiveUI();
	return (
		<button type="button" onClick={() => setActiveUI('dialog')}>
			Cookie preferences
		</button>
	);
}
```

`ConsentDialogLink` does the same with the policy's rights exposed for
styling; see [ConsentDialogLink](./consent-dialog-link). For a floating
button, see [ConsentDialogTrigger](./consent-dialog-trigger). Under an IAB
policy, mount `IABConsentDialog` from the [IAB guide](/docs/frameworks/next/iab)
instead; this dialog stays closed for the `iab` model.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`open`|`boolean`|follows the active surface|Controls the open state. When set, Escape and the dialog's own Save Settings, Accept All and Reject All buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed.|
|`showTrigger`|`boolean \|ConsentDialogTriggerProps`|`false`|Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'none']`|Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag in the card.|
|`uiSource`|`string`|`'dialog'`|Source identifier recorded with saves made from this dialog.|
|`scrollLock`, `trapFocus`|`boolean`|from `blocking`|Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.|
|`disableAnimation`|`boolean`|`false`|Skips the enter and exit animation of the backdrop and the card.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The dialog is a modal wrapper around the preference center. Its card has a
header with the title `consentManagerDialog.title` and the description
`consentManagerDialog.description` followed by the legal links, then the
same category accordion and Reject All, Accept All and Save Settings actions that
`ConsentWidget` renders, then the branding tag. It mounts through a portal
into `document.body` after hydration, so it is never part of the server
HTML.

Without an `open` prop, the dialog follows the active surface and opens while
it is `dialog`. These set that surface:

* The Customize button on a `ConsentBanner`, and the "Manage preferences"
  or "Do not sell or share my data" button a notice renders.
* `ConsentDialogLink` and `ConsentDialogTrigger`.
* The button in a `ConsentGate` placeholder.
* `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
  from `useHeadlessConsentUI()` on the headless subpath.

The component code is split into its own chunk, so it is not part of the
first page load. It renders nothing until that chunk is ready, and the
chunk downloads at the first of these:

* The browser's first idle period after the page's `load` event, while the
  banner is shown or a `ConsentDialogLink`, `ConsentDialogTrigger`,
  `ConsentGate` button or other button that opens the dialog is mounted.
  This covers a visitor who taps or presses Enter with no hover or focus
  first. Browsers without `requestIdleCallback`, such as Safari, wait
  200 ms after `load` instead.
* Hover or focus on a button that opens the dialog.
* The dialog opening.

Passing `open={true}` or `showTrigger` loads it on mount. A visit with
saved consent and nothing on the page that opens the dialog never
downloads it.

Idle loading is skipped when the visitor has Save-Data on
(`navigator.connection.saveData`), on a `2g` or `slow-2g` connection, and
while offline; hover and focus still load it. To load the chunk only on
hover, focus or open, set `preloadDialog: 'intent'` in the provider
options. The default is `'idle'`. With Next.js, pass it through
`ConsentRoot`'s `options` prop.

If a preload fails, for example because the visitor is offline, nothing is
cached: the next hover, focus or open tries the download again.

The dialog's CSS travels in the same chunk and is applied before the dialog
renders, so the first page load carries only the banner's rules.

Without an `open` prop, Escape closes the dialog without saving. If the
policy still owes a choice, the banner comes back. Save Settings, Accept All and
Reject All close it as soon as the choice is recorded in the browser, in
the same task as the click; the exit animation still plays. The request to
the backend runs afterwards and never reopens the dialog: a failed request
keeps the choice, reports through `onError` and is retried later. See
[when a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
for the order of events. A draft that went stale because the policy changed keeps the dialog open
for review. With `open={true}`, these actions leave the dialog visible; the
parent must set `open={false}` to close it. Clicking the backdrop does not
close it. Closing discards toggles that were not saved: the next open starts
from the recorded choice again. After a save from an uncontrolled dialog,
every consent surface hides unless the policy still owes a prompt, in which
case the banner returns.

The preference center is blocking by default: a backdrop, body scroll lock
and focus trap, all as one value. Set `presentation.preferences.blocking`
to `false` in the provider options to remove all three; the deprecated
`scrollLock` and `trapFocus` props do the same for one dialog. `variant`
and `position` are prompt options. Setting them under
`presentation.preferences` logs an `invalid-variant` diagnostic in
development and changes nothing; the dialog is always centered.

The dialog never opens without a resolved policy rule, even when the
active surface is already `dialog`; it appears as soon as a rule resolves,
without a remount. A rule with `model: 'none'` and no rights owes no consent
UI, so the dialog stays closed under it. When such a rule lists any right,
for example `rights: ['disclosure']` or `rights: ['preferences']`, the dialog
can open as a settings route and Save completes without writing a consent
record.

Copy comes from these translation keys: `consentManagerDialog.title`,
`consentManagerDialog.description`, `common.acceptAll`, `common.rejectAll`,
`common.save`, and `consentTypes.<category>.title` and `.description` for
each row.

## Accessibility

The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
while it is blocking. Its `dir` attribute follows the active language.

While blocking, focus moves on open to the first tabbable control in the
panel, so a keyboard user sees the focus ring on a control rather than
around the whole panel; the `aria-labelledby` and `aria-describedby`
wiring means a screen reader still announces the title and description as
focus enters. Tab and Shift+Tab wrap inside the panel, and on close focus
returns to the element that opened the dialog. A non-blocking dialog manages no focus: nothing moves focus into the
panel or back to the opener. The backdrop is `aria-hidden` and is not
focusable.

Each category switch has the category title as its accessible name. The
`necessary` switch is disabled and always on. A saved grant that the current
policy or a privacy signal overrides gets a note under its row, linked to
the switch through `aria-describedby`.

## Composition

Every part is available as `ConsentDialog.<Part>`: `Root`, `Overlay`,
`Card`, `Header`, `HeaderTitle`, `HeaderDescription`, `Content`, `Footer`
and `ConsentCustomizationCard`, the stock card. `Root` provides the portal,
open state, focus trap, scroll lock and backdrop, and accepts `open`,
`models`, `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`,
`uiSource` and `overlay`. Pass `overlay={false}` to render no backdrop, or a
node to replace the built-in one.

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription legalLinks={['privacyPolicy']} />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Keep `ConsentWidget` inside `Content`: it owns the draft, the switches and
the policy actions, and inherits the dialog's `uiSource`. `Footer` renders
the branding tag unless you pass children or `hideBranding`.

The positioner carries `data-slot="dialog-positioner"`, and both it and the
panel carry `data-blocking="true"` while blocking. Provider component slots
for the stock structure are `dialog.root`, `dialog.container`,
`dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
`dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.

`ConsentDialog` from the package root and from the
`c15t/react/consent-dialog` subpath is the deferred component described
under Behavior, and each `ConsentDialog.<Part>` loads with the same chunk.
`c15t/react/components/consent-dialog` exports the dialog without the
deferral, plus each part as a named export (`Card`, `Header`, `Overlay`,
`Root` and the rest). Importing from that path puts the dialog's code in
the bundle of every page that imports it, so the first open needs no
download but every visitor downloads the dialog.

The compound parts import from `c15t/next` as properties of `ConsentDialog`,
and `ConsentWidget` from the same module. Server Components cannot render
them: keep the composition in a file with `'use client'`. See
[Customize](/docs/frameworks/next/customize) for slots and tokens.

## Verify

Use the default blocking, uncontrolled dialog and an optional in-scope
category that is not restricted by policy or privacy signals such as GPC.
Open the dialog from the banner's Customize button or a preferences link.
A centered card appears over a dimmed backdrop, the page behind it stops
scrolling, and Tab stays inside the card. Press Escape: the card closes and
focus returns to the button you used. Open it again, turn a category on and
choose Save. The dialog closes and `useConsent('<category>')` reports
`true` in your components; under a choice prompt the banner does not return,
while a `notice` prompt keeps its banner until it is acknowledged. Reload the
page and reopen the dialog: the switch reflects the saved choice.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/next/components/consent-widget
Render ConsentWidget on a Next.js privacy page inside ConsentRoot as an inline preference center, server-rendered when the route resolves consent.

## Embed the preference center inline

`ConsentWidget` renders the preference center in the page flow instead of in
a modal: the category switches and the Reject All, Accept All and Save Settings
actions, without a title, backdrop or portal. Use it on a privacy or
settings route where the visitor expects the controls to be part of the
content. It is a Client Component; render it from any route under the
layout that mounts the `ConsentRoot` from your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) setup. Keep
`ConsentDialog` mounted in that root as well so the banner's Customize
button and preference links still have a dialog to open.

```tsx title="app/privacy/page.tsx"
import { CookiePreferences } from '../../components/cookie-preferences';

export default function PrivacyPage() {
	return (
		<main>
			<h1>Privacy</h1>
			<p>Choose which optional categories this site may use.</p>
			<section aria-labelledby="cookie-preferences">
				<h2 id="cookie-preferences">Cookie preferences</h2>
				<CookiePreferences />
			</section>
		</main>
	);
}
```

```tsx title="components/cookie-preferences.tsx"
'use client';

import { ConsentWidget } from 'c15t/next';

export function CookiePreferences() {
	return <ConsentWidget />;
}
```

The page stays a Server Component; only the widget file needs
`'use client'`. When `ConsentRoot` receives an awaited `resolveConsent`
result, from the
[awaited App Router layout](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html)
or a Pages Router page with `getServerSideProps`, the widget is part of the
server HTML with the visitor's recorded choices applied. `ConsentDialog`, by
contrast, always mounts after hydration. With the default streamed layout,
which passes a pending promise, and on static routes, the widget renders once
the browser has applied the resolved policy. The widget uses the
boundary's policy, translations and transport; it does not need a second
provider, and it does not open or close the banner or dialog by itself.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|A standalone widget hides the "Secured by" tag. Pass `false` to show it.|
|`uiSource`|`string`|`'widget'`|Source identifier recorded with saves made from this widget. Inside `ConsentDialog` it inherits `'dialog'`.|
|`disableAnimation`|`boolean`|`false`|Skips animations in the widget's parts.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The widget is the preference center without the modal around it: an
accordion with one row per category, each with a switch, followed by the
Reject All, Accept All and Save Settings actions. `ConsentDialog` renders this same
widget inside its card. Standalone, the widget renders in place, takes part
in server rendering, and does not touch the active surface, so it suits a
privacy page or an account settings screen.

The rows are `necessary` plus the categories in the active policy's scope,
narrowed to the categories the provider declares: `options.consentCategories`
and the categories of its scripts, network rules, vendors and discovered
frames. When nothing is declared, a permissive policy shows only `necessary`
and a strict one its whole scope.
The `necessary` switch is on and disabled. Row titles and descriptions come
from `consentTypes.<category>.title` and `.description`; the action labels
from `common.rejectAll`, `common.acceptAll` and `common.save`. One row is
expanded at a time.

### Draft and save

Switches edit a draft, not the visitor's permissions. Nothing is recorded
until Save. The draft seeds each category from the recorded choice; without
one it uses `presentation.preferences.defaults` from the provider options,
and without that it is on under an opt-out rule and on only for the rule's
preselected categories under an opt-in rule. Save records the displayed
categories, then reseeds the draft from the new record. Accept All and
Reject All record immediately without a separate Save. A save answers a
choice prompt, so an open choice banner closes; it does not dismiss a
`notice` prompt, which keeps its own acknowledgement record. Unsaved toggles
are lost when the widget unmounts.

When the policy changes in a way that affects the choice while the draft has
unsaved toggles, the widget shows an alert, "The privacy policy changed.
Review the current choices before saving.", with a Review choices button
that resets the draft. Save is refused until then. A draft without unsaved
toggles reseeds silently.

A saved grant that the current policy or a privacy signal such as Global
Privacy Control overrides shows a note under its row: "Your saved choice is
restricted by the current privacy settings." The switch still reflects the
saved value; the effective permission is off.

### Vendors

When the provider declares `vendors`, each category's expanded description
ends with one card per vendor whose category condition names that category,
styled like a category row: the vendor's name and a switch on the header,
and its description and privacy policy link behind the card's own expand
control. Cards start collapsed, so a long list stays one line per vendor,
and the category list scrolls inside the dialog rather than growing it.
A collapsed category or card renders its content element empty and mounts
the content the first time it opens, then keeps it mounted, so a long
vendor list costs nothing until a visitor expands its category.
Vendor switches edit the same draft as the category
switches and record on Save. Saving with one vendor off denies that vendor
only; the category stays granted and its other vendors keep loading. While
the category is off in the draft the vendor switches are disabled, with the
hint "Turn on this category to choose vendors." A vendor declared
`disabled`, or one that only falls under `necessary`, is listed without a
switch. Accept All and Reject All clear every vendor denial, including one
staged but not yet saved. Under an `iab` policy no vendor rows render.
Vendors that are only referenced by a script slug, without a name and
privacy policy URL, still gate loading but are not listed, and so does a
vendor whose condition negates a category, since no category row can
host it. See
[vendor consent](../vendor-consent).

### Actions

The preference center always renders Reject All, Accept All and Save Settings, with
Save Settings as the primary action. `presentation.preferences.layout`,
`primaryActions`, `direction` and `uiProfile` in the provider options
reorder and restyle them; a layout that omits one of the three has it
restored. Customize and dismiss actions never render here.

### When consent is not owed

Without a resolved policy rule the widget renders nothing and appears as
soon as a rule resolves, without a remount. A rule with `model: 'none'` and
an empty `rights` list renders nothing; a `none` rule that lists any right,
such as `['disclosure']`, renders the widget and Save completes without
writing a consent record.

For a fully custom preference center, `useConsentDraft()` returns the same
draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
the declared list, the recorded denials and one vendor's effective result.

The `useConsentDraft` hook and `ConsentDraftProvider` component import from
`c15t/next`. Use them in Client Components.

## Accessibility

Each row is a disclosure: a button that expands the category description
and a switch beside it, so a visitor can read the description without
changing the choice. Each switch has the category title as its accessible
name. A category's vendor cards sit in a `region` named "Vendors" with the
count; each card's expand button carries `aria-expanded`, each vendor
switch is named "Allow" followed by the vendor name, and is described by
the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
an `output` element linked to its switch through `aria-describedby`. The
root's `dir` attribute follows the active language.

## Composition

Every part is available as `ConsentWidget.<Part>`. `Root` provides the
draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
and `AccordionItems` render the stock rows; `AccordionItem`,
`AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
`AccordionArrow` and `Switch` build your own; `VendorList` renders one
category's vendor rows and takes a `category` prop. `PolicyActions` renders the
resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
`CustomizeButton` are the individual buttons.

`Accordion` is controlled: pass `value` and `onValueChange`, or no
category description ever opens. The stock `ConsentWidget` holds that state
for you. In this component, `ConsentWidget` comes from the same import as
the example at the top of the page:

```tsx
import { useState } from 'react';

export function PreferenceCenter() {
  const [open, setOpen] = useState<string[]>([]);

  return (
    <ConsentWidget.Root>
      <ConsentWidget.Accordion
        value={open}
        onValueChange={(next) => setOpen(Array.isArray(next) ? next : [next])}
      >
        <ConsentWidget.AccordionItems />
      </ConsentWidget.Accordion>
      <ConsentWidget.PolicyActions />
    </ConsentWidget.Root>
  );
}
```

Provider component slots for the stock structure are `manager.root`,
`manager.footer`, `manager.actionGroup`, `accordion.root`,
`accordion.triggerRow`, `accordion.title`, `accordion.control`,
`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
`vendor-list.item`, `vendor-list.header`,
`vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
`vendor-list.control` and `tag.manager`.

`ConsentWidget` from the package root and from the
`c15t/react/consent-widget` subpath loads its code in a separate chunk the
first time it renders, so a page that never renders it does not download
it. `c15t/react/components/consent-widget` exports the widget without that
deferral, plus each part as a named export.

The compound parts import from `c15t/next` as properties of `ConsentWidget`.
Server Components cannot render them: keep the composition in a file with
`'use client'`. See [Customize](/docs/frameworks/next/customize) for slots and tokens.

## Verify

Visit the page with the widget. Use a displayed optional category whose permission is
not restricted by policy or privacy signals such as GPC. One row per displayed
category appears, with `necessary` on and disabled. Turn that category on:
`useConsent('<category>')`
elsewhere on the page still reports the old value. Choose Save: it now
reports `true`. An open choice banner closes when the save answers its
prompt; a notice banner stays open until acknowledged. Reload the page: the
switch keeps the saved value. Without a saved choice or configured draft
defaults, optional switches start on under an opt-out rule.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/next/components/consent-dialog-link
Open the preference center from a Next.js footer with ConsentDialogLink, a Client Component that renders an unstyled button inside ConsentRoot.

## Reopen the preference center from your footer

`ConsentDialogLink` is an unstyled button that opens the consent dialog.
Put it where your site already keeps its legal links, so preferences stay
reachable after the banner closes. It is a Client Component and must render
inside the `ConsentRoot` from your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) setup, which also mounts
the `ConsentDialog` it opens.

```tsx title="components/site-footer.tsx"
'use client';

import { ConsentDialogLink } from 'c15t/next';
import Link from 'next/link';

export function SiteFooter() {
	return (
		<footer>
			<nav aria-label="Legal">
				<Link href="/privacy">Privacy policy</Link>
				<Link href="/terms">Terms</Link>
				<ConsentDialogLink className="footer-link">
					Privacy settings
				</ConsentDialogLink>
			</nav>
		</footer>
	);
}
```

Render `SiteFooter` inside `ConsentRoot`, in place of the inline footer the
router guides show. In the App Router, render it from the root layout, which
stays a Server Component; only this file needs `'use client'`. In the Pages
Router, render it from `pages/_app.tsx` inside `ConsentRoot`, next to
`<Component {...pageProps} />`. The link
renders a `button`, so the CSS for `.footer-link` should reset button chrome
if your footer styles target anchors only.

`c15t/next/components/consent-dialog-link` exports `ConsentDialogLink` and
nothing else. Import from that path when a module needs only the link, so it
does not load the rest of the adapter.

To reuse an existing link component, pass `asChild`:

```tsx
<ConsentDialogLink asChild>
	<a href="#cookie-preferences">Manage cookies</a>
</ConsentDialogLink>;
```

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`children`|`ReactNode`|required|The visible label, such as "Privacy settings" or "Manage preferences". It is also the accessible name.|
|`asChild`|`boolean`|`false`|Renders your own element, such as an anchor, instead of a `button`, and attaches the click handler to it.|
|`noStyle`|`boolean`|`true`|Omits c15t button classes. Native browser styles remain unless your CSS resets them. Pass `false` to render it as a consent button with `variant` and `mode`.|
|`onClick`|`(event) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to keep it closed.|

Other `button` attributes such as `className`, `style`, `id` and `aria-*`
pass through to the rendered element.

## Behavior

`ConsentDialogLink` renders a `button` with `type="button"` and no c15t
styling by default. Clicking it makes `dialog` the active surface, which opens a
mounted `ConsentDialog`. It performs no save and does not change any
permission.

The element carries `data-c15t-rights` listing the rights of the active
policy rule, for example `disclosure opt-out preferences` under a US
opt-out rule and `disclosure preferences` under an opt-in rule, so a
stylesheet or a `::after` label can adapt the wording by region.

Without a resolved policy rule the link renders nothing and appears as soon
as a rule resolves, without a remount. A rule with `model: 'none'` and an
empty `rights` list owes no consent UI, so the link hides under it; a `none`
rule that lists any right, such as `['disclosure']`, shows the link and the
dialog opens as a settings route.

Mount exactly one `ConsentDialog` inside the same provider. If none is
mounted, the click still switches the active surface: nothing opens, and a
banner that was showing closes because the surface is no longer `banner`.

With `asChild`, the child's own `onClick` runs first; if it calls
`event.preventDefault()` the dialog stays closed. c15t does not prevent the
child's native behavior, so an anchor still follows its `href`. Use a
fragment or the current page as the destination, or render a `button`.

### ConsentDialogLink or ConsentDialogTrigger

Both open the same dialog and carry `data-c15t-rights`. Use
`ConsentDialogLink` where the control belongs in your own layout: a footer,
a privacy page, a settings menu. It has no position, icon or visibility
rule of its own. Use `ConsentDialogTrigger` when you want a floating,
draggable button that positions itself in a corner and can wait until the
prompt is answered.

`ConsentDialogTrigger` has its own page: [ConsentDialogTrigger](./consent-dialog-trigger).

## Accessibility

The rendered `button` is keyboard-focusable and activates with Enter and
Space; its accessible name is the text you pass as `children`, so give it
words that describe the destination rather than "click here". Because the
dialog it opens is labelled by its own title and, while blocking, returns
focus to the link on close, no additional `aria-haspopup` or
`aria-controls` is added; a non-blocking dialog manages no focus, so the
link does not regain it. With `asChild`,
focusability comes from your element: use a `button` or an anchor with an
`href`.

## Verify

Scroll to the footer. With the footer button reset applied, the link uses
your footer's text styles and has no button chrome. Activate it with a click or with Enter: the preference
center opens as a centered dialog. Close it with Escape: with the default
blocking dialog, focus returns to the link. In your browser's element
inspector the link has
`data-c15t-rights`; change the visitor's region to a US opt-out rule and
the value includes `opt-out`. Under a rule with `model: 'none'` and no
rights, the link is absent.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/next/components/consent-dialog-trigger
Add the floating ConsentDialogTrigger button or toolbar to a Next.js ConsentRoot so visitors can reopen the preference center.

## Add the trigger next to the banner

`ConsentDialogTrigger` is a draggable floating button that opens the preference center. Place it once, next to the banner and dialog, so visitors can revisit their choices without a footer link.

Keep the boundary and transport from your
[router setup](/docs/frameworks/next/quickstart). Add this component as a child
of the existing boundary, alongside its banner and dialog:

```tsx title="components/privacy-trigger.tsx"
'use client';

import { ConsentDialogTrigger } from 'c15t/next';

export function PrivacyTrigger() {
	return <ConsentDialogTrigger showWhen="after-prompt" />;
}
```

`showWhen="after-prompt"` keeps the button out of the way while a choice or notice is still owed and shows it once the visitor has answered, so the banner and the trigger never compete for the same corner. The default, `always`, shows it whenever the preference center is closed.

The button carries `data-c15t-rights` with the rights the active policy guarantees, so a stylesheet can label it differently under an opt-out rule.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`icon`|`'branding' \|'fingerprint' \|'settings' \|ReactNode`|`'branding'`|Icon rendered inside the button.|
|`defaultPosition`|`'bottom-left' \|'bottom-right' \|'top-left' \|'top-right'`|`'bottom-right'`|Corner the button starts in.|
|`persistPosition`|`boolean`|`true`|Remember the corner the visitor dragged it to.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the button is visible. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

## Configurable toolbar

Use `ConsentDialogTriggerToolbar` when you want app-owned controls beside the privacy trigger. It always renders exactly one built-in action that opens the preference center, so `actions` only holds controls your app owns.

This partial example belongs in a Client Component inside the existing boundary.
Define the theme state, icons and callbacks in that component.

```tsx
import { ConsentDialogTriggerToolbar } from 'c15t/next';

<ConsentDialogTriggerToolbar
	ariaLabel="Site controls"
	actions={[
		{
			id: 'theme',
			label: isDark ? 'Switch to light theme' : 'Switch to dark theme',
			icon: isDark ? <SunIcon /> : <MoonIcon />,
			pressed: isDark,
			onSelect: toggleColorScheme,
		},
		{
			id: 'support',
			label: 'Open support chat',
			icon: <ChatIcon />,
			onSelect: openSupportChat,
		},
	]}
	preferences={{ icon: 'fingerprint', label: 'Manage privacy settings' }}
/>;
```

Each custom action needs a stable `id`, an accessible `label`, an `icon`, and an `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable ones. Your app owns the state behind each action. The preferences action moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.

The toolbar does not depend on the consent policy. Your actions always render, so a theme toggle stays available while a banner is up. On the toolbar, `showWhen` applies only to the built-in preferences action: `after-prompt` hides that one item while a choice or notice is owed and shows it once the visitor has answered, and `never` leaves it out. The toolbar renders nothing only when it has no visible item. On the single `ConsentDialogTrigger`, `showWhen` applies to the whole control.

No policy, no UI. When no rule has resolved, because resolution failed, no rule matched and you set no default, or init is still withheld, the built-in preferences action and the single `ConsentDialogTrigger` render nothing; app-owned toolbar actions still do. They appear as soon as a rule resolves, without a remount. A rule with `model: 'none'` owes no rights, so the built-in action and the single trigger hide under it too, unless the rule adds `rights: ['preferences']`. The policy chooses what the control says, you choose where and when it sits, and it disappears only when there is nothing to manage.

The built-in action names the strongest right the active rule guarantees. Under a rule that carries the `opt-out` right, such as a US opt-out notice, its accessible name is the translated "Do not sell or share my data" and the button carries `data-right="opt-out"`. Under any other rule it reads "Manage preferences" with `data-right="preferences"`. Either way it opens the preference center, and a `preferences.label` you pass replaces the default. The button also carries `data-c15t-rights` with every right on the rule.

Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and switch arrow-key navigation to up and down:

```tsx
<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />;
```

### Toolbar props

|Prop|Type|Default|Description|
|--|--|--|--|
|`actions`|`ConsentDialogTriggerToolbarAction[]`|`[]`|App-owned actions rendered beside the preferences action.|
|`preferences`|`ConsentDialogTriggerToolbarPreferences`|`{}`|Overrides for the built-in action: `icon`, `label`, `onSelect`, `className`, `style`. The label defaults to the opt-out or preferences right on the active rule.|
|`orientation`|`'horizontal' \|'vertical'`|`'horizontal'`|Layout direction.|
|`defaultPosition`|`CornerPosition`|`'bottom-right'`|Corner the toolbar starts in.|
|`persistPosition`|`boolean`|`true`|Remember the dragged corner.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the built-in preferences action is visible. App-owned actions always render. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Size of each action.|
|`ariaLabel`|`string`|`'Privacy controls'`|Accessible name for the toolbar group.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

While `<ConsentDevTools>` is mounted, the toolbar adds a DevTools button at
the end farthest from its corner and opens the DevTools panel beside itself.
The ready-made `ConsentDialogTrigger` switches to this toolbar layout for as
long as DevTools is mounted.

### Toolbar styling

The toolbar follows the standard precedence: bundled styles, then provider slots, then direct `className` and `style` on the toolbar or on one action. Use `noStyle` for a fully custom implementation.

Add these slot values to `options.components` on your existing
`ConsentRoot` or `ConsentProvider`. Merge them with any existing component
slots and retain the configured transport:

```ts
const triggerSlots = {
	toolbar: { className: 'my-toolbar' },
	toolbarItem: { className: 'my-toolbar-item' },
	toolbarIcon: { className: 'my-toolbar-icon' },
};

// In the existing options.components object:
// trigger: triggerSlots
```

For one toolbar, pass `className="fixed-toolbar"` directly. Each app-owned
item also accepts `className`, such as `className: 'support-action'` on your
support action. Keep its icon and callback in the Client Component.

The toolbar slot keys are `trigger.toolbar`, `trigger.toolbarItem`, and `trigger.toolbarIcon`. With `noStyle`, style the current position and interaction state through `data-corner`, `data-dragging`, and `data-snapping` on the toolbar element.

# ConsentGate
URL: https://c15t.com/docs/frameworks/next/components/consent-gate
Consent-gate an iframe in Next.js with ConsentGate inside ConsentRoot; with server prefetch the server HTML carries the placeholder for a denied category, and a granted embed mounts after hydration.

## Gate an embed behind consent

`ConsentGate` mounts its children only while the effective permission for one
consent category is granted, and shows a placeholder otherwise. Wrap any
iframe or third-party widget that would set cookies or contact a vendor on
load. It is a Client Component; render it from any route under the layout
that mounts the `ConsentRoot` from your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) setup, which also mounts
the `ConsentDialog` the placeholder button opens.

```tsx title="components/product-video.tsx"
'use client';

import { ConsentGate } from 'c15t/next';

export function ProductVideo() {
	return (
		<ConsentGate category="marketing" className="video-frame">
			<iframe
				src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
				title="Product tour"
				loading="lazy"
				allowFullScreen
				style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
			/>
		</ConsentGate>
	);
}
```

Import `ProductVideo` into any page or Server Component; only this file needs
`'use client'`. `marketing` must be in your policy scope. `ConsentGate`
registers its category when it mounts, so the preference center lists
Marketing even if you set `options.consentCategories` without it.

`ConsentGate` does not read the clock during server rendering, so a page that
renders it can still be prerendered, including with `cacheComponents: true`.
It does not need a `Suspense` boundary of its own. On a static page the
prerendered HTML contains the placeholder, and the embed replaces it after
the browser resolves policy and the category is allowed.

The placeholder names the category using its title from your translations. Set
`className` or `style` on `ConsentGate` to reserve the embed's space, so the page
does not shift when the placeholder is replaced.

With the default App Router layout, which passes the pending
`resolveConsent` result, the server HTML contains the placeholder, and the
browser swaps in the embed after it applies the resolved state if the
category is granted. No request reaches the embed's host before that.

With the
[awaited layout](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
the server decides from the resolved rule and the request cookie whether the
category is allowed. Pages Router works the same way when `getServerSideProps`
awaits `resolveConsent` from `c15t/next/pages` and passes the result
through `state` to `ConsentRoot`, as in the
[Pages Router guide](../pages-router). A denied category gets the placeholder
in the server HTML. A granted category gets an empty wrapper, and the embed
mounts once hydration completes. With the awaited layout the page streams
inside a `Suspense` boundary, and React moves streamed HTML into place after
parsing it; an iframe that was already in that HTML would load twice.
Hydration keeps the server's decision as long as the browser's privacy
signals agree with the request: a `navigator.globalPrivacyControl`
that the request did not carry as `Sec-GPC` is re-detected on hydration and
can withdraw a category. Under an opt-in rule a new
visitor gets the placeholder and a returning visitor who allowed `marketing`
gets the iframe; under an opt-out rule a new visitor already has effective
permission, so the iframe renders until they opt out.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The consent category whose effective permission gates the children, for example `'marketing'` or `'functionality'`.|
|`children`|`ReactNode`|required|The embed. It is not mounted until the category is allowed, so it makes no requests before permission.|
|`placeholder`|`ReactNode`|built-in placeholder|Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content.|

Other `div` attributes such as `className`, `style` and `ref` apply to the
wrapper element that stays in the page in both states. `ConsentGateProps` also
declares `noStyle` and `theme`, but the component does not apply them yet;
style the wrapper with `className`, and style the built-in placeholder
through its parts in the provider options.

## Behavior

`ConsentGate` renders a `div` wrapper. Inside it, when the effective permission for
`category` is granted, it renders the children; otherwise it renders the
placeholder. Permission is the same value `useConsent(category)` returns,
so it can be granted under an opt-out rule before the visitor records a
choice, and a recorded grant can be overridden by a privacy signal.

While effective permission is denied, the children are absent from the DOM,
so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
children unmount and the embed disappears. `ConsentGate` does not depend on the
network blocker or the iframe blocker modules; use those for markup you
cannot wrap in a component.

The built-in placeholder shows the title `consentGate.title`,
`Accept {category} consent to view this content.`, with `{category}`
replaced by `consentTypes.<category>.title`, and a button labelled
`consentGate.actionButton`, `Enable {category} consent`. The button opens the
preference center; it
does not grant the category by itself, because the visitor still has to
save. Mount a `ConsentDialog` in the same provider so the button has
something to open.

Under a policy with `scopeMode: 'strict'`, a category outside the rule's
scope cannot be granted. The built-in placeholder then shows `consentGate.policyBlocked`,
"This content is unavailable under your region's consent policy.", without
the button, and a stored grant for that category stays blocked.

When the provider starts from a snapshot prefetched on the server, the
server renders the placeholder for a denied category. For a granted
category it renders the empty wrapper, and the children mount once
hydration completes, so an iframe loads once even when the page streams
inside a `Suspense` boundary. A grant in the request cookie allows the
embed only when policy and privacy signals permit it. Browser privacy signals detected during hydration can
withdraw that permission. In a browser-only setup the
provider has no permission until it resolves policy on the client, so
`ConsentGate` shows the placeholder first and swaps in the embed after resolution
when the category is already granted.

`ConsentGate` is one component on this page; the per-vendor embed guides for
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) show a complete embed
configuration with sizing, titles and the same `ConsentGate` usage across
frameworks.

To read the same permission in your own Client Components, use `useConsent`
from `c15t/next`; the `useIframeBlocker` and `useNetworkBlocker` module
hooks also import from there.

## Composition

The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
translated text; pass children to either to replace it.

```tsx
<ConsentGate
  category="marketing"
  placeholder={
    <ConsentGate.Root>
      <ConsentGate.Title category="marketing" />
      <p>The video is also available on our channel.</p>
      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
    </ConsentGate.Root>
  }
>
  <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
</ConsentGate>
```

To restyle the built-in placeholder without replacing it, set its parts
under `components['consent-gate']` in the provider options. `root` is the
card, and `title` and `button` are its text and button. The `consentGate`, `consentGateTitle` and
`consentGateButton` theme slots reach the same parts. The button part
applies on top of `button.primary`.

```tsx
components: {
  'consent-gate': {
    root: { className: 'rounded-none' },
    button: { className: 'font-semibold' },
  },
},
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

## Accessibility

The placeholder is plain text and a `button`, so it is readable and
operable without the embed. Give the iframe a descriptive `title`, and keep a
transcript, address or link outside the `ConsentGate` for visitors who decline
the category. A denied category may be fixed by policy, so opening the
preference center does not guarantee that the visitor can grant it.

## Verify

Use an optional in-scope category that is available in the preference
center and is not restricted by policy or privacy signals such as GPC.
Load the page with the category denied. The placeholder text names the
category and the network panel shows no request to the embed's host. With a
prefetched snapshot, the server HTML contains the placeholder for a denied
category and neither placeholder nor embed for a granted category; the
embed appears after hydration and the network panel shows one request for
its document. Browser-only initialization
shows the placeholder before policy resolves, then replaces it with the
embed if the category is granted. After policy resolves, activate the
placeholder button: the preference center opens. Turn the category on and
Save: the placeholder is replaced by the embed and its requests start. Reject the
category again from the preference center: the embed disappears.

# Hooks
URL: https://c15t.com/docs/frameworks/next/hooks
Gate features and save consent choices in Next.js Client Components with the focused hooks exported from c15t/next.

## Read only the state you need

Every hook reads the runtime from the `ConsentRoot` set up in your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) guide, so call them from a
Client Component rendered inside that root and import them from
`c15t/next`.

```tsx title="components/optional-feature.tsx"
'use client';

import { useConsent } from 'c15t/next';

export function OptionalFeature() {
	const allowed = useConsent('marketing');
	return allowed ? <div>Optional marketing content</div> : null;
}
```

Call hooks inside the consent provider. `useConsent` reads effective permission,
which can be true under an opt-out policy without a recorded grant.

|Need|Hook|
|--|--|
|One category's current permission|`useConsent(category)`|
|All current permissions|`useConsents()`|
|Recorded per-category choices|`useExplicitChoice()`|
|Whether one declared vendor may run|`useVendorAllowed(id)`|
|Whether a prompt is required|`usePromptRequirement()`|
|Active policy and resolution|`usePolicyRule()`, `usePolicyResolution()`|
|Save an explicit choice|`useSaveConsents()`|
|Open or close a consent surface|`useSetActiveUI()`|
|Acknowledge a notice|`useDismissNotice()`|

## Save from a visitor action

Place this Client Component inside your existing consent boundary.

```tsx title="components/reject-button.tsx"
'use client';

import { useSaveConsents } from 'c15t/next';

export function RejectButton() {
	const save = useSaveConsents();
	return (
		<button type="button" onClick={() => void save('none')}>
			Reject optional
		</button>
	);
}
```

This is an isolated action example, not a complete policy-aware banner. Use the
stock UI or headless surface actions for a complete prompt. Do not call save on
mount to persist a state derived from permissions.

Use focused hooks for feature gates. For a complete custom prompt or preference
center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
for staged choices, inside one `ConsentDraftProvider` so the save commits the
same draft. v3 has no `useConsentManager()`; the
[`use-consent-manager-to-hooks` codemod](/docs/cli/commands/codemods#migrate-useconsentmanager-to-v3-hooks)
rewrites most of its calls to hooks. Read [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) before
treating a callback as evidence of a choice.

# Callbacks
URL: https://c15t.com/docs/frameworks/next/callbacks
Run code in a Next.js app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, from c15t.config.ts.

## Put callbacks in c15t.config.ts

Callbacks are functions, and a Server Component cannot pass functions to a
Client Component. React serializes every prop a layout passes across that
boundary. `c15t.config.ts` is bundled into the browser, so put the callbacks
there instead, under `options`. Define them in a module:

```ts title="lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/next';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

Then pass them in the config:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

import { callbacks } from './lib/consent-callbacks';

export default defineConsentConfig({ options: { callbacks } });
```

`ConsentRoot` reads the config in the App Router layout and in the
[Pages Router](/docs/frameworks/next/pages-router) `_app.tsx` alike, so the
same file covers both routers. Keep your existing `scripts` and other options
in the same call.

`ConsentRoot` subscribes the callbacks after it mounts in the browser. Server
rendering never calls them. The provider calls the latest `callbacks` object
it received, so a new object on a later render takes effect without a
remount.

## Available callbacks

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useSaveConsents()`.|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time as a millisecond timestamp|
|`onPermissionsChanged`|Any effective permission changes value.|`snapshot`, the state after the change; `previous`, the permissions before it|
|`onError`|A consent command fails in the browser, such as a failed `/init` request or a save the backend rejects.|`error`, a message string|
|`onBeforeConsentRevocationReload`|A save withdrew a granted category or vendor, right before c15t reloads the page.|`preferences`, the permissions after the save|

The type for the whole object is `ConsentProviderCallbacks` from `c15t/next`.
Callbacks run after c15t updates its state, so `snapshot` and hooks such as
`useConsent()` already hold the new values.

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only for a visitor's action. `onPermissionsChanged`
runs whenever effective permissions change, whatever the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|A policy resolves in the browser and allows categories before any choice|No|Yes|
|Global Privacy Control turns off a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent analytics and audit trails, because it
fires only when the visitor chose. Use `onPermissionsChanged` to start or stop
your own code. Never treat it as proof that the visitor agreed to anything,
and never save consent from it.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

Dismissing a notice records no choice and changes no permission. Read it with
`useNoticeDismissal()` instead. For consent inside one component, use the
[hooks](/docs/frameworks/next/hooks), which re-render the component when
consent changes.

## Report server-side failures

The provider's `onError` runs in the browser. `resolveConsent` has its own
`onError` option for the server. It runs when the manifest or `/init` request
fails or runs out of `timeoutMs` during rendering. The page still renders with
the request-only state and the browser resolves consent after hydration.
Without the option, `resolveConsent` logs a warning outside production.

```tsx title="app/layout.tsx"
const state = resolveConsent({ onError: (error) => reportToMonitoring(error) });
```

This option is fine in the layout, because it runs on the server and never
crosses to the browser. `reportToMonitoring` stands for your own error
reporter.

## Before a revocation reload

Removing a script tag cannot stop code that already ran, so c15t reloads the
page after an accept, reject or save turns off a category or vendor that was
granted. The reload waits for the save request to finish. Right before it,
`onBeforeConsentRevocationReload` runs synchronously. Use it to call a
vendor's shutdown API or flush queued events. Keep it short, because the
reload does not wait for promises.

A choice that expires, a new policy and a privacy signal change permissions
without a visitor action, so they do not reload the page.

To handle revocation yourself, set `reloadOnConsentRevoked: false` in
`options` on `ConsentRoot`. Code the visitor turned off then keeps running
until the next full page load, and `onBeforeConsentRevocationReload` never
runs.

## Verify

1. Add the callbacks from this page, open the console and DevTools Network,
   clear site data and reload under a policy that shows a banner.
2. Click **Accept All**. `onChoiceRecorded` and `onPermissionsChanged` both log,
   and the save request to your backend appears in Network.
3. Reload. `onChoiceRecorded` does not log again.
4. Open Privacy settings, turn off a category you allowed and save.
   `onBeforeConsentRevocationReload` logs, then the page reloads. After the
   reload, that category's vendor requests are absent from Network.

# IAB TCF
URL: https://c15t.com/docs/frameworks/next/iab
Mount the IAB TCF banner and dialog inside a Next.js ConsentRoot and configure the CMP ID, policy and vendor data.

## Prepare the IAB configuration

Use the IAB integration when your application needs the Transparency and Consent
Framework. Configure an IAB policy, the correct CMP identity and vendor data for
your deployment. A demo CMP ID is not a production configuration.

A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your users' consent records to someone else. Omitting it leaves the add-on
unmounted: no `__tcfapi`, and no TC String written.

Install `@c15t/iab` alongside your framework adapter, then mount the IAB
components inside an existing consent provider connected to Inth.

Next.js uses the React IAB components. There is no `c15t/next/iab` JavaScript
entry point, so import the components from `c15t/react/iab` and render this
Client Component inside the `ConsentRoot` from your
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) setup.

The IAB banner and dialog render their own styles by default. Leave
`ConsentRoot`'s `styles` option enabled. The banner's styles render in the
server HTML, and the dialog loads its rules when opened.

```tsx title="components/iab-consent.tsx"
'use client';

import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
preferences entry point through the surrounding consent provider.

## Resolve the policy before rendering

IAB components remain hidden until an applicable policy resolves. Forcing a
dialog open does not create a policy or vendor list. Inspect resolution and the
Global Vendor List response before changing rendering conditions.

IAB presentation follows `presentation.prompt.blocking` and
`presentation.preferences.blocking`. A blocking dialog needs focus management,
scroll locking and a backdrop together.

## Mount IABProvider for every IAB policy

IAB is opt-in. The standard `ConsentBanner` and `ConsentDialog` do not
handle the IAB model, so when a visitor's policy uses it, the backend
sends its vendor list and the app has no `IABProvider`, they throw an
`IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`):
`c15t: this visitor's policy uses IAB TCF, but no <IABProvider> is mounted`.
The error happens during render, on the server and in the browser, so
your error boundary or the framework's error overlay shows it. Render `IABProvider` from
`c15t/react/iab` for those visitors, or remove the `iab` model from the
policy.

## Verify vendor and purpose choices

Test category choices alongside vendor, purpose, legitimate-interest and special
feature controls used by your integration. Confirm the TC String and `__tcfapi`
reflect the saved state, and verify the vendor's actual requests. A category-only
banner test does not establish that the IAB flow works.

## Load an external stylesheet

With Tailwind CSS 3, or when you want to put c15t in a named cascade layer,
import `c15t/next/styles.css` and then `c15t/next/iab/styles.css` at your global
stylesheet entry. The IAB stylesheet holds the IAB rules and uses the base
stylesheet's tokens. Set `styles: false` in `ConsentRoot`'s `options` so the
components use those stylesheets:

```css title="styles/globals.css"
@import 'c15t/next/styles.css';
@import 'c15t/next/iab/styles.css';
```

Tailwind CSS 3 also needs the
[PostCSS plugin](/docs/customization/tailwind#set-up-tailwind-css-3).

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Pass
them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
placeholders; use vendors from your list whose declarations allow each
restriction.

```tsx title="components/iab-consent.tsx"
'use client';

import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

const publisherRestrictions = [
	// Vendors 10 and 755 may not use purpose 4.
	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
	// Vendor 755 must use legitimate interest for purpose 7.
	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
];

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

# IAB GPP
URL: https://c15t.com/docs/frameworks/next/gpp
Add the IAB Global Privacy Platform API (__gpp) to a Next.js app with ConsentGPP from c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

`ConsentGPP` from `c15t/react/gpp` installs `window.__gpp`, the GPP 1.1 CMP
API, and keeps its GPP string in step with the visitor's choices. Prebid.js,
Google Ad Manager and other ad tech read US privacy signals from it.

## Turn on GPP

Render `ConsentGPP` inside `ConsentRoot`, in the root layout from the
[App Router](/docs/frameworks/next/app-router) guide or in `pages/_app.tsx`
from the [Pages Router](/docs/frameworks/next/pages-router) guide.

```tsx title="app/layout.tsx (partial)"
import { ConsentGPP } from 'c15t/react/gpp';

<ConsentRoot state={resolveConsent()}>
	<ConsentGPP />
	{children}
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>;
```

`ConsentGPP` renders nothing. `__gpp` exists only in the browser: the
component installs it after it mounts and removes it when it unmounts. Its
props are plain data, so a Server Component can render it too. Apps that do
not import `c15t/react/gpp` bundle none of the GPP code.

The props are the GPP options listed below, for example
`<ConsentGPP usFallback="none" />`.

The GPP string follows the policy and location `resolveConsent()` resolves
for the visitor. A US visitor's state comes from the geo headers your host
sends; see [geography headers](/docs/frameworks/next/geography-headers) if
it is missing.

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/next/iab) as well.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Geography headers
URL: https://c15t.com/docs/frameworks/next/geography-headers
Use c15tProxy in Next.js proxy.ts or middleware.ts so Server Components and Route Handlers receive the visitor's country and region.

## When do I need the proxy?

Add `c15tProxy` when your hosting platform exposes the visitor's location to
Next.js middleware or proxy but strips those headers before Server Components
and Route Handlers run. Without them, `resolveConsent`, the awaited
server helpers and the optional consent route at `/api/c15t/init` see an unknown
location and apply your unknown-location policy rule for every visitor.

c15t reads location from the platform headers listed in
[Which headers are read?](#which-headers-are-read): Cloudflare (`cf-ipcountry`,
`cf-region-code`), Vercel (`x-vercel-ip-country`,
`x-vercel-ip-country-region`), the `x-amz-cf-ipcountry` header some
CloudFront setups add, and generic
proxy headers (`x-country-code`, `x-country`, `x-region-code`). c15t does not
keep a list of which hosts strip them. Check your deployment: log
`(await headers()).get('x-vercel-ip-country')` or the equivalent for your host
inside a Server Component. If the value is present, you do not need the proxy.
If it is missing while the same header is present in `proxy.ts`, add the proxy.

The proxy copies the incoming request headers, resolves country, region and
Global Privacy Control from them, and forwards the result on the request as
`x-c15t-country`, `x-c15t-region` and `sec-gpc`. Those application override
headers have the highest precedence, so Server Components and Route Handlers
read the same values the proxy saw. When no location header is present, the
proxy sets nothing and the location stays unknown.

The proxy runs on Next.js `^15.0.0 || ^16.0.0`. It does not apply to a
[static export](/docs/frameworks/next/static-export), which has no server.

## Add the proxy (Next.js 16)

Create `proxy.ts` at the project root, or in `src/` if your app lives there:

```ts title="proxy.ts"
import { c15tProxy } from 'c15t/next/proxy';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
	return c15tProxy(request);
}

export const config = {
	matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

`c15tProxy` returns `NextResponse.next()` with the forwarded request headers.
If you already have a proxy, call `c15tProxy(request)` where you would
otherwise return `NextResponse.next()`, and set any response headers or
cookies on the returned response.

`config.matcher` must cover every page that renders `ConsentRoot`,
because `resolveConsent` and the awaited helpers run during those page
requests. It must also cover `/api/c15t/:path*` if you serve the optional consent
route and want it to resolve policy with the visitor's location. The
consent route's `/manifest` path serves public policy data and does not need
location.

## Add the middleware (Next.js 15)

On Next.js 15 the file is `middleware.ts` and the export is `middleware`:

```ts title="middleware.ts"
import { c15tMiddleware } from 'c15t/next/middleware';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
	return c15tMiddleware(request);
}

export const config = {
	matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

`c15tMiddleware` is the same function as `c15tProxy` under the Next.js 15
name. Both imports stay supported on both Next.js versions. When you upgrade to
Next.js 16 and rename `middleware.ts` to `proxy.ts`, switch the import to
`c15tProxy` from `c15t/next/proxy` at the same time. The options type is
exported as `C15tMiddlewareOptions` and `C15tProxyOptions` respectively.

## Persist geography in cookies

Pass `cookie: true` to also write the resolved location into cookies. Use this
on runtimes where the forwarded request headers do not reach React Server
Components, so that your own server code can read the location on later
requests. The proxy writes the cookie on the response, and `cookies()` reads
the incoming request, so the first visit still resolves as unknown and the
first request after a location change still sees the previous value:

```ts title="proxy.ts"
import { c15tProxy } from 'c15t/next/proxy';
import type { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
	return c15tProxy(request, { cookie: true });
}
```

The default cookie names are `c15t-country` and `c15t-region`. Both are set
with `httpOnly: true`, `sameSite: 'lax'` and `path: '/'`, so browser scripts
cannot read them. Pass an object to rename them:

```ts title="proxy.ts (partial)"
c15tProxy(request, {
	cookie: { countryName: 'geo-country', regionName: 'geo-region' },
});
```

A cookie is written only when the matching header resolved a value. The
proxy never clears a stale cookie, so a visitor whose location header
disappears keeps the previous cookie until it is cleared or the session cookie
expires.

The c15t server helpers read request headers, not these cookies. To use the
cookie, read it where you call `resolveConsent` and pass it as the
`country` override:

```tsx title="app/layout.tsx (partial)"
import { ConsentRoot } from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import { cookies } from 'next/headers';

async function resolveVisitorConsent() {
	const country = (await cookies()).get('c15t-country')?.value;
	return resolveConsent({ country });
}

// Inside the existing synchronous root layout:
<ConsentRoot state={resolveVisitorConsent()}>{children}</ConsentRoot>;
```

This replaces the `resolveConsent` call in the root layout from the
[App Router guide](/docs/frameworks/next/app-router); the layout still passes
the pending result. With the
[awaited layout](/docs/frameworks/next/app-router#render-the-banner-in-the-server-html),
`await resolveVisitorConsent()` inside `ResolvedConsent` and keep it inside
the `Suspense` boundary shown there.

`resolveConsent` accepts `country` and `language` overrides. It has no
`region` override in the current API, so the region cookie is available only to
your own code.

The cookie comes back in the client-controlled `Cookie` header. `HttpOnly`
stops page scripts from reading it; it does not stop a visitor from sending
`c15t-country=<value>` and, through the `country` override, choosing a less
restrictive rule for themselves. Deleting the incoming cookie is not an
option here, because `cookies()` reads that same request and `c15tProxy` only
sets the cookie on the response. Use this fallback only when the edge that
terminates all traffic overwrites the incoming `c15t-country` and
`c15t-region` cookies with its own trusted geography on every request, or
when your code signs the value and verifies the signature before passing it
as `country`. Where you can do neither, keep the cookie out of policy
resolution and use it only for non-policy code such as display defaults.

## Which headers are read?

`c15tProxy` and the server helpers use the same extraction from
`@c15t/schema`. Within each group, the first header with a value wins:

|Input|Headers, highest precedence first|Source|
|--|--|--|
|Country|`x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country`|c15t override, Cloudflare, Vercel, CloudFront, generic|
|Region|`x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`|c15t override, Cloudflare, Vercel, generic|
|Global Privacy Control|`x-c15t-gpc`, `sec-gpc`|c15t override, browser signal|
|Language|`accept-language`|browser|

CloudFront's own geolocation headers, `CloudFront-Viewer-Country` and
`CloudFront-Viewer-Country-Region`, are not in this list. Forward them to the
origin with an origin request policy, then map them in `proxy.ts` before
calling `c15tProxy`. An origin request policy forwards headers but cannot
rename them. A CloudFront Function can also read geography headers when a
cache policy or origin request policy exposes them to the function, as shown
in [AWS's viewer-request example](https://github.com/aws-samples/amazon-cloudfront-functions/tree/main/redirect-based-on-country).

Clear every country and region input c15t recognizes before mapping the
trusted CloudFront values:

```ts title="proxy.ts"
import { c15tProxy } from 'c15t/next/proxy';
import { NextRequest } from 'next/server';

export function proxy(request: NextRequest) {
	const headers = new Headers(request.headers);
	for (const name of [
		'x-c15t-country',
		'cf-ipcountry',
		'x-vercel-ip-country',
		'x-amz-cf-ipcountry',
		'x-country-code',
		'x-country',
		'x-c15t-region',
		'cf-region-code',
		'x-vercel-ip-country-region',
		'x-region-code',
	]) {
		headers.delete(name);
	}
	const country = headers.get('cloudfront-viewer-country');
	const region = headers.get('cloudfront-viewer-country-region');
	if (country) headers.set('x-c15t-country', country);
	if (region) headers.set('x-c15t-region', region);
	return c15tProxy(new NextRequest(request, { headers }));
}
```

The `delete` calls drop client-supplied overrides and fallback geography
headers. When CloudFront omits a country or region, that value stays unknown
instead of falling through to a header supplied by the visitor.

GPC values are meaningful only as `1` or `0`; any other value is treated as
absent. The proxy writes the normalized result to `sec-gpc`, so an incoming
`x-c15t-gpc: 1` reaches Server Components as `sec-gpc: 1`. Browsers refuse to
let scripts set `Sec-*` request headers, which is why the `x-c15t-gpc` override
exists for the browser's own init request.

Only trusted infrastructure may set `x-c15t-country`, `x-c15t-region` or
`x-c15t-gpc` in production, because they always win. A client that sends them
chooses its own policy rule, and `c15tProxy` forwards a client-supplied value
over the platform header rather than stripping it. The edge that terminates all
traffic must therefore delete incoming `x-c15t-*` headers before anything sets
them, in every deployment. Blocking direct origin access with a firewall or
platform origin protection is an additional control that keeps requests on that
edge; it does not replace the stripping, because a forwarded client header
still passes through the protected path.

The browser's own `/init` request carries the same overrides as the
`country`, `region` and `gpc` query parameters, so that a
cross-origin request needs no CORS preflight. The init route and the backend
treat them like the `x-c15t-*` headers, so strip them from `/init` requests at
the same edge.

## Verify

Deploy with the proxy and load the site from two locations with different
configured policy rules, for example through a VPN or your host's geo testing
tools. After server prefetch resolves, the rendered consent policy must match
each location: an opt-in region shows the banner with optional categories denied, while a region
configured for notice-only or no notice renders accordingly. Confirm the values
by logging `(await headers()).get('x-c15t-country')` in a Server Component;
it should equal the platform header seen in the proxy.

Remove the proxy temporarily and reload. If both locations now resolve the
unknown-location rule, your platform strips location headers before Server
Components and the proxy is required. If they still resolve correctly, your
platform already passes the headers through and the proxy is optional.

With the consent route in the matcher, request `/api/c15t/init` from each
location and confirm its `policyResolution` reflects the location. If you use
`cookie: true`, check the response for `Set-Cookie: c15t-country=...` with
`HttpOnly` and `SameSite=Lax`.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/next/content-security-policy
Pass a per-request CSP nonce to ConsentRoot in Next.js and allow the consent backend in connect-src.

## Pass the request nonce to ConsentRoot

Read the nonce from the `x-nonce` request header in the root layout and pass it
as `options={{ nonce }}` on `ConsentRoot`. This is the standard Next.js
nonce pattern: your `proxy.ts` (Next.js 16) or `middleware.ts` (Next.js 15)
generates a nonce per request, sets the `Content-Security-Policy` response
header with `'nonce-<value>'` in `script-src` and `style-src`, and forwards the
same value on the request as `x-nonce`. See the
[Next.js CSP guide](https://nextjs.org/docs/app/guides/content-security-policy)
for the header-generating proxy.

If you also run [`c15tProxy`](/docs/frameworks/next/geography-headers), set
both `x-nonce` and the generated `Content-Security-Policy` header on
`request.headers` before calling it, and set the policy on the returned
response as well. Next.js reads the nonce for its own bootstrap and page
scripts from the request-side policy header, so forwarding only `x-nonce`
leaves the framework scripts without a nonce and the browser blocks hydration.
`c15tProxy` copies the incoming request headers into the forwarded request, so
both headers travel with the geography headers.

Then read the header in the root layout and pass it to `ConsentRoot` as
`options.nonce`. A string can cross from a Server Component to a Client
Component, so no wrapper is needed:

```tsx title="app/layout.tsx"
import { ConsentBanner, ConsentDialog, ConsentRoot } from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import { headers } from 'next/headers';
import { Suspense } from 'react';
import type { ReactNode } from 'react';

import './globals.css';

async function ResolvedConsent({ children }: { children: ReactNode }) {
	const nonce = (await headers()).get('x-nonce') ?? undefined;
	const state = await resolveConsent();

	return (
		<ConsentRoot state={state} options={{ nonce }}>
			{children}
			<ConsentBanner />
			<ConsentDialog />
		</ConsentRoot>
	);
}

export default function RootLayout({ children }: { children: ReactNode }) {
	return (
		<html lang="en">
			<body>
				<Suspense fallback={null}>
					<ResolvedConsent>{children}</ResolvedConsent>
				</Suspense>
			</body>
		</html>
	);
}
```

Reading `headers()` keeps the route dynamic, which a per-request nonce requires
anyway. Do not combine a nonce-based policy with `cacheComponents: true`
(Partial Prerendering): the static shell is rendered once at build time, so its
scripts cannot carry a per-request nonce and the browser blocks them. Next.js
documents this limitation in its CSP guide. For a prerendered shell use the
hash-based policy that guide describes; a host-only `script-src` such as
`'self'` does not authorize Next.js's inline bootstrap scripts and would need
`'unsafe-inline'`, which defeats the policy. Otherwise keep the route fully
dynamic and use the nonce.

`options.nonce` is read when `ConsentRoot` mounts. The provider keeps the latest
value in a ref, but the script loader is created once per runtime, so a nonce
that changes during client-side navigation is not applied to scripts already
created. Each full page load gets the fresh nonce from its own request.

## What the nonce applies to

c15t stamps a nonce on three kinds of DOM nodes:

* Every `<script>` element the script loader creates for a `scripts` entry,
  both `src` and inline `textContent` scripts, gets `options.nonce`. A `nonce`
  set on an individual `scripts` entry takes precedence for that element.
* The `<style>` elements that the banner, dialog and other stock components
  render with c15t's rules get `options.nonce`. With a nonce set, they render
  next to each component instead of moving into `<head>`, because React drops
  the nonce of a style it moves.
* The inline `<script>` that a server-rendered `ConsentBanner` puts before its
  buttons gets `options.nonce`. It holds a tap the visitor makes before the
  page hydrates. If the policy blocks it, the banner still works after
  hydration, but a tap before then does nothing.
* The `<style id="c15t-theme">` element that `ConsentTheme` renders with the
  theme's `--c15t-*` custom properties gets its `nonce` prop. Pass it the same
  request nonce: `<ConsentTheme theme={theme} nonce={nonce} />`.

It does not apply to anything else:

* Scripts that a vendor script loads itself, such as a tag manager injecting
  its tags, do not receive the nonce. Add `'strict-dynamic'` to `script-src` so
  scripts loaded by a nonced script are allowed, or list those vendor hosts
  explicitly.
* The prebuilt stylesheet `c15t/next/styles.css`, if you import it with
  `styles: false`, is a regular stylesheet from your own origin. It is covered
  by `style-src 'self'`, not by the nonce. Use that setup when a page cannot
  carry a per-request nonce.
* Inline `style` attributes on rendered components. A nonce cannot authorize
  style attributes, and browsers ignore `'unsafe-inline'` in a `style-src` list
  that also contains a nonce or hash. Allow them with a separate
  `style-src-attr 'unsafe-inline'` directive, or with `'unsafe-hashes'` plus
  the matching `'sha256-...'` values; hashes only work for static values, not
  for the animated collapse heights. The IAB TCF dialog, the consent dialog
  trigger toolbar and the animated collapse used inside the dialogs render
  inline `style` attributes. Check the
  browser console with your policy enforced to see whether your setup triggers
  a `style-src` violation.
* Iframes, images or requests made by vendor scripts. Allow those hosts in
  `frame-src`, `img-src` and `connect-src` according to each vendor.

## Allow the consent backend in connect-src

The browser sends consent submissions to `${backendURL}/subjects`, and, when
the browser initializes or retries after a failed server prefetch, requests to
`${backendURL}/init` or the manifest URL. Add the backend origin to
`connect-src`, and the manifest origin too when the mode's `manifestURL` is an
absolute URL on a different host such as a CDN:

```txt title="Content-Security-Policy (partial)"
connect-src 'self' https://<your-backend-host> https://<your-manifest-host>;
```

Use the endpoint host supplied by your Inth project or your self-hosted backend.
With `proxy: true` and `routePrefix: '/api/c15t'`, as
[Optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
shows, the browser sends every consent request to `/api/c15t` and `'self'`
covers them; the Next.js server connects to the backend outside the browser's
CSP.

IAB TCF policies can fetch the Global Vendor List from the URL the policy
provides; allow that host in `connect-src` if you use the
[IAB TCF add-on](/docs/frameworks/next/iab). Server-side prefetch runs
in Next.js and is not subject to the browser's CSP.

## Verify

Load a page with the policy enforced, not in report-only mode, and open the
browser console. The banner should render with its theme colors and no CSP
violation should mention `c15t-theme`. Grant a category that gates one of your
`scripts` entries, then check:

* The injected `<script>` element carries the request's nonce. Browsers hide
  the value from `getAttribute('nonce')`; read the element's `nonce` property
  in the console or inspect it in the Elements panel.
* The `<style id="c15t-theme">` element carries the same nonce and the
  `--c15t-*` variables are applied to the banner.
* No `Refused to load the script` or `Refused to apply inline style` errors
  mention a c15t element. A refused vendor dependency points to a missing
  `'strict-dynamic'` or vendor host.
* The consent submission to `/subjects` succeeds. A `connect-src` violation
  here means the backend origin is missing.

Reload with a different nonce and confirm the elements update. A stale nonce
after a full page load usually means a cached HTML response; nonce-based pages
must not be served from a shared cache.

# Performance
URL: https://c15t.com/docs/frameworks/next/optimization
Bundle policy at build time to avoid manifest fetch latency, use runtime caching when policies must refresh without a rebuild, and optionally keep browser consent requests on your origin.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

## Reuse cached policy data

Use runtime manifest caching when policy changes must reach your app without
a rebuild. Set the mode in `c15t.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig, manifest } from 'c15t/next';

export default defineConsentConfig({ mode: manifest({ source: 'runtime' }) });
```

Keep `withConsentManifest`, which finds the config. A manifest contains public
policy configuration that your app server can reuse across requests. Each
visitor's consent still resolves separately.

A warm cache avoids repeated backend policy resolution. It does not eliminate
all requests. Your app may serve its consent route, cold caches fetch
upstream data, and consent choices still reach Inth. IAB policies can also need
a Global Vendor List fetch.

Server rendering supplies the initial policy to the browser. For browser
initialization that needs request geography, add the
[consent route](/docs/frameworks/next/data-fetching-reference#do-i-need-the-consent-route).

## Compare manifests with backend initialization

A warm manifest cache can reduce initialization latency by avoiding an upstream
backend request. The saving depends on backend latency, cache hits and where
consent resolution sits in rendering. It is not a fixed speedup for the whole
page.

|Fetching path|Work during initialization|
|--|--|
|Build-time manifest, recommended|Resolve consent locally from the deployment's snapshot, including on a fresh server instance.|
|Regular backend `/init`|Wait for the backend to resolve consent and return the result.|
|Cold manifest cache|Fetch public policy from the backend, cache it and resolve consent locally.|
|Warm manifest cache|Reuse cached policy and resolve consent locally; local route requests and rendering still take time.|

### Measured performance

Two benchmark reports measure these setups. Each report lists its machine,
network conditions, samples and reproduction steps.

* [Manifest versus backend init](https://github.com/c15t/c15t/tree/v3/benchmarks/reports/next-manifest-2026-09-10).
  With 150 ms of simulated backend latency, a warm manifest cache cut the
  median server response time for a new visitor from about 158 ms to about
  7 ms. A cold cache still waits for the upstream fetch.
* [Streamed versus awaited layout](https://github.com/c15t/c15t/tree/v3/benchmarks/reports/next-consent-boundary-2026-09-25).
  With a 4× CPU slowdown, the streamed layout painted the page in about
  90 ms and the awaited layout in about 390 ms, because React held the
  awaited page's streamed reveal.

Measure your own deployment before you choose a layout for speed.

## Keep browser consent requests on your origin

By default the browser saves consent to `${backendURL}/subjects`, a separate
origin. Sending those requests through your own app can avoid a separate
browser DNS lookup and TLS connection to the consent backend, and lets a
`connect-src 'self'` policy cover them. Manifests and server rendering work
without it.

The app server still connects to the backend, and each save takes an extra
hop through your server. Measure your deployment to check the effect on
latency. Vendor scripts, pixels and iframes keep their own URLs; only c15t
requests move. The same setup works with a self-hosted c15t backend.

Set `routePrefix` and `proxy: true` in the config, and keep `backendURL`
absolute:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({ proxy: true, routePrefix: '/api/c15t' });
```

Then mount the consent route with `proxy: true`, so it forwards saves to the
backend. In the App Router:

```ts title="app/api/c15t/[...c15t]/route.ts"
import { createConsentRoute } from 'c15t/next/api';

export const { DELETE, GET, OPTIONS, PATCH, POST, PUT } = createConsentRoute({
	proxy: true,
});
```

In the Pages Router:

```ts title="pages/api/c15t/[...c15t].ts"
import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute({ proxy: true });
```

What the route serves:

|Request|Handled by|
|--|--|
|`GET /api/c15t/init`|The route, from the bundled manifest, for this request's location, language and privacy signal|
|`GET /api/c15t/manifest`|The route, serving the bundled manifest|
|`POST /api/c15t/subjects` and other consent paths|Forwarded to your backend because `proxy: true`|
|Any other path|`404`, so the route is never an open proxy|

Keep these details right:

* `proxy: true` in `c15t.config.ts` points the browser at `routePrefix` for
  init and saves. `resolveConsent`, `withConsentProps` and the consent route
  keep the absolute `backendURL` from the config or
  `NEXT_PUBLIC_C15T_BACKEND_URL`, so the server never fetches its own route
  and `withConsentManifest` still downloads the manifest from the backend.
* `proxy` needs `routePrefix`. Without it, `defineConsentConfig` throws
  `` @c15t/nextjs: `proxy` sends saves through the consent route, so it needs `routePrefix`. ``
* Set `proxy: true` in both places. With it only in the config, saves reach a
  route that answers them with 404 or 405. To send only init through the route
  and keep saves going straight to the backend, drop `proxy` from both and keep
  `routePrefix`.
* `options.mode` on `ConsentRoot`, or a `hosted({ backendURL })` with its own
  URL, keeps talking to that URL.
* The proxy forwards the visitor's user agent, language, origin and location
  headers, so the backend's firewall sees a normal visitor. Set
  `trustForwardedHeaders: true` on the route only when your host overwrites
  `x-forwarded-for`, as Vercel and Cloudflare do. Otherwise a visitor could
  send a false IP address to your backend.

TanStack Start has the same option, `createConsentStateHandler({ proxy })`.
A full [static export](/docs/frameworks/next/static-export) has no API routes.
Use a hosting-level proxy or the public backend URL there.

## Configure manifest cache refresh

This section applies to runtime fetching. A build-time snapshot stays fixed
until the next build and does not use cache revalidation.

In the App Router, `resolveConsent` and `createConsentRoute` pass
`next: { revalidate: 300 }` to upstream manifest fetches. Next.js's Data Cache
can reuse that policy across requests and server instances when your host
provides a shared cache. A new function instance can therefore read cached
policy even with an empty SDK cache. A Data Cache miss still waits for the
backend.

The SDK also keeps an in-process manifest cache, which supports ETag
revalidation and respects upstream cache headers, including responses marked
private. Pages Router helpers use this cache; ordinary Pages Router fetches
do not use the App Router Data Cache.

For route handlers, `manifestRevalidateSeconds` changes the Data Cache's
300-second revalidation interval. Set it to `false` or `0` to skip that layer.
The SDK cache still follows the upstream cache headers. Visitor-specific
backend `/init` calls use `cache: 'no-store'`, and resolved consent is never
shared between visitors.

Once the upstream `s-maxage` has passed, the in-process cache keeps serving the
cached manifest for as long as the upstream `stale-while-revalidate` allows
(an explicit `s-maxage` is required for that window to apply),
and refreshes it in the background. Requests do not wait for that refresh, and
a refresh that fails or times out leaves the cached manifest in place, so a
slow or unavailable backend does not delay rendering on a server that has
already loaded the manifest. Inth sends `s-maxage=300` and a 24 hour
`stale-while-revalidate` by default; lower the second value on a self-hosted
backend if a policy change must reach servers sooner after an outage. A server
with both caches empty still waits for the first upstream response.

The background refresh is detached from the request. On runtimes that stop
work once a response is sent, register it with the platform so it can finish.
Pass `onBackgroundRevalidate` to the route; it is called inside the handler
with the refresh promise, which never rejects:

```ts title="app/api/c15t/[...c15t]/route.ts"
import { createConsentRoute } from 'c15t/next/api';
import { after } from 'next/server';

export const { GET } = createConsentRoute({
	onBackgroundRevalidate: (refresh) => after(() => refresh),
});
```

`after` is stable from
Next 15.1; on Next 15.0 import `unstable_after` instead. Other hosts pass the
promise to their equivalent, such as `waitUntil` on Vercel or Cloudflare.
Without it the response still returns at once; only the refresh may be cut
short, in which case the next request starts another.

The same hook receives the route's session report. A host that resolves
init from the manifest never calls `/init`, so after each resolution the route
posts a small report to the backend's `POST /sessions`, server-to-server, and
the backend counts the visitor from that instead. The browser makes no request.
`resolveConsent` reports its renders the same way through its `waitUntil`
option. Pass `reportSessions: false` to either to send none.

Build-time snapshots need no background manifest refresh. On serverless
hosts, `onBackgroundRevalidate` can still keep the optional session report
alive after the response. It is not required for resolving consent from the
snapshot.

## Avoid repeating startup work

Keep one boundary in the App Router root layout or Pages Router `_app.tsx`.
Remounting it during navigation creates another runtime and repeats startup
work. Keep the consent UI in that shared root too.

Choose when to resolve consent according to your page. See
[rendering and deployment](/docs/frameworks/next/rendering) for server
rendering, streaming and browser initialization.

Measure cold entry, warm requests and client navigation separately.
Check server requests as well as the browser Network panel. Confirm that
consent saves reach the backend and policy updates appear after a rebuild, or
the configured refresh window with runtime caching. If you set `proxy: true`,
also confirm browser consent requests use your origin.

## Start returning visitors' scripts sooner

`ConsentRoot` loads the script loader as a separate chunk, and only on pages
whose `scripts` array is not empty. Pages without scripts never download it.
By default the chunk loads once the page has hydrated.

When the visitor's consent already lets one of those scripts run, `ConsentRoot`
starts the download during its first render in the browser instead, so the
chunk loads while React hydrates the rest of the page. It decides as the
provider would once mounted: with the state from `resolveConsent()`, once a
streamed state arrives, the current policy, Global Privacy Control, the
visitor's vendor switches and any newer denial stored in the browser. A grant
any of those restricts does not count. The visitors this covers:

* a returning visitor whose stored choice allows one of the scripts;
* any visitor, when a script has `alwaysLoad`, since it runs whatever they
  chose;
* every visitor, when `options.enabled` is `false`, since a disabled provider
  grants every category;
* a visitor under a policy that allows the scripts without a choice, such as
  an opt-out region.

With `options.consentSource` set, and the provider not disabled, the external
source decides consent after the page mounts, so only `alwaysLoad` scripts
start the download early.

The larger the tree inside `ConsentRoot`, the more of that request hydration
covers. There is nothing to configure. The code that decides ships with
`ConsentRoot` only: a `ConsentProvider` from `@c15t/react` rendered without
`ConsentRoot` loads the chunk when it mounts.

c15t does not add a `<link rel="modulepreload">` for the chunk, as it does in
SvelteKit. Next.js assigns the chunk's file name in the browser build, and the
server rendering `ConsentRoot` cannot read it.

# Data fetching reference
URL: https://c15t.com/docs/frameworks/next/data-fetching-reference
Reference for the Next.js c15t.config.ts options, modes, resolveConsent, withConsentProps, the consent route, manifest resolution, request geography and offline configuration.

## Config reference

`defineConsentConfig` from `c15t/next` declares the app's consent setup in
`c15t.config.ts` at the project root. `withConsentManifest` in
`next.config.ts` finds the file and hands it to `ConsentRoot`,
`resolveConsent`, `withConsentProps`, `createConsentRoute` and
`createPagesConsentRoute`, so the app never imports it. For help choosing a
setup, start with [rendering and deployment](/docs/frameworks/next/rendering).
Requires Next.js 15 or 16 (`next ^15.0.0 || ^16.0.0`).

|Property|Default|Behavior|
|--|--|--|
|`backendURL`|`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`|Backend base URL. Consent submissions go to `/subjects` under it, and the server reads `/manifest` or `/init` from it.|
|`mode`|`manifest()`|`manifest()`, `hosted()` or `offline()` from `c15t/next`. See [consent modes](/docs/concepts/modes).|
|`routePrefix`|none|Where the catch-all consent route is mounted, such as `/api/c15t`. A browser that resolves consent itself asks `${routePrefix}/init` instead of the backend's `/init`. Leave it unset when every page resolves consent on the server.|
|`proxy`|`false`|The route at `routePrefix` forwards saves (`createConsentRoute({ proxy: true })`), so the browser saves there instead of `${backendURL}/subjects`. The server helpers keep `backendURL`. Needs `routePrefix`. See [optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).|
|`journey`|`'page'`|The consent journey scope, read by both `resolveConsent` and `ConsentRoot` so they agree.|
|`scripts`, `vendors`, `clearOnRevocation`, `networkBlocker`, `persistence`, `scriptLoader`, `options`|none|Browser options. `ConsentRoot` props of the same name win over them.|

The file is bundled into the browser as well as the server, so it can hold
functions such as `scripts` but must hold no secrets. Read server-only values,
such as a token for `forwardHeaders`, in server code.

Values can be absolute HTTP or HTTPS URLs or paths beginning with `/`. Server
helpers resolve relative paths against the incoming request's host. If your
server answers requests for any `Host` header, such as a Node server exposed
directly or a proxy that forwards `Host` from its default virtual host, use an
absolute `backendURL`. A relative one resolves against whatever `Host` the
request sent, so the request would choose the origin the server fetches.

`defineConsentConfig` returns a frozen object. On the server, which includes
`withConsentManifest` reading the file at build time, it validates first and
throws a `TypeError` with one of these messages. Browser bundles skip the
checks, so they add no bytes there:

|Message|Cause|
|--|--|
|`@c15t/nextjs: defineConsentConfig expects an object.`|The argument is not an object.|
|`` @c15t/nextjs: defineConsentConfig needs `backendURL`, or NEXT_PUBLIC_C15T_BACKEND_URL (or NEXT_PUBLIC_INTH_PROJECT_URL) set at build time. ``|No backend URL, and the mode is not `offline()` or a `hosted()` with its own `backendURL`.|
|`` @c15t/nextjs: defineConsentConfig `backendURL` must be an absolute http(s) URL or a `/`-relative path, received "...". ``|A URL is protocol-relative, such as `//your-project.inth.app`, or bare, such as `api/c15t`. The same check covers `routePrefix`, `mode.manifestURL`, `mode.geoURL` and `mode.backendURL`.|
|`` @c15t/nextjs: `routePrefix` can't be '/': a consent route at the site root would catch every page. Use a path such as '/api/c15t'. ``|`routePrefix` is `'/'`. A catch-all route at the site root would catch every page.|
|`` @c15t/nextjs: defineConsentConfig `mode` must be manifest(), hosted() or offline() from c15t/next. Pass a custom transport through ConsentRoot `options.mode`. ``|`mode` is not one of the data factories.|
|`` @c15t/nextjs: defineConsentConfig `journey` must be 'page', 'tab' or false. ``|`journey` has another value.|
|`` @c15t/nextjs: `proxy` sends saves through the consent route, so it needs `routePrefix`. ``|`proxy: true` without `routePrefix`.|

Protocol-relative and bare URLs are rejected because the server helpers would
resolve them against the request host and reach an unintended origin.

### Do I need the consent route?

Not when every page resolves consent on the server. The root layout or
`withConsentProps` supplies the initial policy directly to the browser.

Add the route when some pages render without server state: static, ISR or
`'use cache'` pages in the App Router, or Pages Router pages without
`withConsentProps`. Set `routePrefix: '/api/c15t'` in `c15t.config.ts` and
mount the route:

```ts title="app/api/c15t/[...c15t]/route.ts"
import { createConsentRoute } from 'c15t/next/api';

export const { GET } = createConsentRoute();
```

For Pages Router, use this file instead:

```ts title="pages/api/c15t/[...c15t].ts"
import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute();
```

The route answers `GET ${routePrefix}/init` by resolving the bundled manifest
with the browser request's location headers, so those pages get the same
policy a server render would. It also answers `GET ${routePrefix}/manifest`
for `manifest({ resolve: 'browser' })`.

Without `routePrefix`, browser initialization calls the backend's `/init`.
See [geography and privacy signals](#geography-and-privacy-signals).

### Mode combinations

|Config|Server render|Browser initialization|
|--|--|--|
|`manifest()`, the default, with `routePrefix`|Resolves the snapshot with request inputs|Calls `${routePrefix}/init`, whose route resolves the snapshot with request inputs|
|`manifest()` without `routePrefix`|Resolves the snapshot with request inputs|Calls `${backendURL}/init`|
|`manifest({ resolve: 'browser' })`|Resolves the snapshot with request inputs|Loads the resolver lazily and fetches `${routePrefix}/manifest`, else `${backendURL}/manifest`|
|`manifest({ source: 'runtime' })`|Fetches and caches `${backendURL}/manifest`|As `manifest()`|
|`hosted()`|Calls `${backendURL}/init`|Calls `${backendURL}/init`|
|`offline()`|No policy request|Resolves bundled local rules|

Hosted and manifest modes submit choices to `${backendURL}/subjects`.
Offline mode uses browser persistence only. A prepared server result
satisfies the first browser initialization; the browser column describes
what happens when initialization is needed, including recovery after the
server render failed.

The browser loads only the code of the mode it runs. With `manifest()`
resolved on the server, the snapshot, the resolver and other languages stay
out of the browser bundle; see
[what each mode adds to first-load JavaScript](/docs/concepts/modes#what-each-mode-adds-to-first-load-javascript).

### Switch to regular backend init

Set `mode: hosted()` in `c15t.config.ts`. The
[client-side guide](/docs/frameworks/next/client-side#configure-the-backend-and-the-mode)
has the complete config. For server rendering, keep the layout from your
router guide. `resolveConsent` will call backend `/init` per request.

Remove the consent route if no page needs it, unless `proxy: true` sends
browser saves through it. See
[optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).

## Server helper options

`resolveConsent` is the one server helper. `c15t/next/server` exports it for
the App Router, where the default request context reads `next/headers` and
calls `await connection()` from `next/server` before reading the clock.
`c15t/next/pages` exports the same function for the Pages Router, taking the
Node `req` instead, and `withConsentProps` wraps it as a `getServerSideProps`.
All of them accept the options in this section; the Pages Router entry
replaces only the `request` adapter.

`resolveConsent()` needs no options: it reads `c15t.config.ts` and the
snapshot `withConsentManifest` downloaded. What it does depends on the mode.
`manifest()` resolves policy from the snapshot, or from
`${backendURL}/manifest` through the in-process cache without one. `hosted()`
calls `${backendURL}/init`. `offline()`, or no backend URL at all, makes no
network request and returns cookie- and header-only state; see
[cookie-only state](#cookie-only-state).

### resolveConsent options

|Option|Default|Behavior|
|--|--|--|
|`config`|`c15t.config.ts`|The config to use instead of the file. Explicit options on this bag win over its fields. In manifest mode, its `routePrefix` names the same-origin route the browser loads a deferred IAB Global Vendor List from.|
|`backendURL`|the mode's, then the config's, then `NEXT_PUBLIC_C15T_BACKEND_URL` or `NEXT_PUBLIC_INTH_PROJECT_URL`|Backend base URL. With `hosted()`, `resolveConsent` calls `${backendURL}/init`.|
|`manifestURL`|the mode's absolute `manifestURL`, then `${backendURL}/manifest`|Absolute `GET /manifest` URL. Setting it resolves from the manifest whatever the mode, through the in-process manifest cache. A `/`-relative `manifestURL` on the mode is the browser's, so the server ignores it.|
|`snapshot`|the snapshot `withConsentManifest` downloaded|A manifest to resolve from instead. Setting it resolves from the manifest whatever the mode.|
|`fetch`|`globalThis.fetch`|Fetch implementation for the backend `/init` or manifest request. Manifest requests already pass `next: { revalidate: 300 }` for the App Router Data Cache. The `/init` call can carry the consent cookie and returns per-visitor state, so it uses `cache: 'no-store'`. A custom fetch must preserve these options. It also keeps the IAB Global Vendor List inline, since the browser cannot replay it.|
|`forwardHeaders`|`[]`|Extra request header names copied onto the outgoing call, such as a token a private backend needs. They travel only over `https` or to a loopback host. `cookie` and `forwarded`/`x-forwarded-*` cannot be named here. Headers absent from the request are skipped.|
|`trustForwardedHeaders`|`false`|Resolve a `/`-relative `backendURL` or `manifestURL` against the request's `forwarded`, `x-forwarded-host` and `x-forwarded-proto` headers instead of `host`, and forward the visitor IP to backend `/init` as `x-forwarded-for`. Set it only behind a proxy that sets those headers and drops the ones a client sends.|
|`onError`|none|Receives the failure from the backend or manifest request, including a `ManifestUnavailableError` when `timeoutMs` runs out or the manifest is backing off after a failure. When omitted, failures are logged with `console.warn` only when `NODE_ENV` is not `production`.|
|`timeoutMs`|`500`|Longest the render waits for policy, in milliseconds, counted from the start of the resolution. When it runs out, the helper returns the baseline state described below. `false` or `Infinity` waits for the manifest cache's 5 second request timeout, or for the `fetch` implementation on backend `/init`. Any other value that is not a finite, non-negative number uses the default.|
|`reportSessions`|`true`|In manifest mode, report the resolved init to the backend's `POST /sessions` after the render, server-to-server, so the backend still counts the visitor. Forwards the visitor's user agent and client IP on `x-c15t-client-ip`, never cookies. `false` sends none.|
|`journey`|the config's `journey`|The consent journey scope this render reports. `ConsentRoot` must use the same value.|
|`experiment`|none|The banner experiment with the arm this request runs. See [banner experiments](/docs/guides/banner-experiments).|
|`waitUntil`|none|Receives work that outlives the render so it survives the response: the session report, a manifest refresh, and a manifest request that `timeoutMs` stopped waiting for. In the App Router pass `(task) => after(() => task)` with `after` from `next/server`. The promise never rejects.|
|`now`|`Date.now()`|Clock used to validate stored records and stamped into the result.|
|`cookieName`|`c15t`|Cookie holding persisted consent. Must match the client `storageConfig.storageKey`.|
|`country`|header detection|Overrides the country read from request headers.|
|`language`|header detection|Overrides the language read from `accept-language`.|
|`request`|`next/headers`|Request context adapter with `cookies()` and `headers()`. The default only works in the App Router.|

`resolveConsent` throws when the request adapter's `headers()` or `cookies()`
rejects (the default adapter rejects outside a request scope), and when your
`onError` callback throws. Thrown URL resolution, network, timeout and policy
resolution errors are handled: they return the same baseline state as the
cookie-only call, with stored records, geography, language and GPC from the
request but no resolved policy. The page still renders and the browser initializes
consent on mount. Non-2xx responses from backend `/init` are failures too, so
a `500` renders the baseline rather than throwing. A successful response whose
body reports `policyResolution.status: 'failed'`, for example an unsupported
policy contract, is different: that failed resolution is kept as the prepared
state, the browser does not re-initialize on mount, and the consent UI stays
hidden until the cause is fixed.

### Slow or unavailable backends

`resolveConsent` waits at most `timeoutMs` (500 ms by default) for policy. A
warm manifest cache answers in about a millisecond, and a cold read over a new
connection to a hosted backend usually takes a few hundred. When the budget
runs out, the render uses the baseline state: no consent UI in the server HTML,
optional categories denied, and consent-gated scripts and iframes blocked.
`ConsentRoot` then initializes in the browser and shows the banner once the
backend answers, retrying failed attempts with backoff.

The manifest request does not stop when the render gives up. It keeps running,
up to the cache's 5 second request timeout, and stores the manifest for later
renders. Pass `waitUntil` so serverless platforms keep it alive after the
response.

Server manifest reads, in `resolveConsent` and in the route handlers, share
these rules:

* Concurrent requests for the same manifest URL share one upstream request.
* A render that joins a request already in flight waits only for what is left
  of that request's `timeoutMs`.
* After a failed request, with no usable copy cached, that URL is not asked
  again for 1 second. Each further failure doubles the wait, up to 5 seconds.
  Requests in between fail at once with a `ManifestUnavailableError` whose
  `reason` is `'backoff'`, so a struggling backend sees at most one request
  per URL per server instance in each interval.
* A stale copy is served only inside the backend's `stale-while-revalidate`
  window, while one background request refreshes it. Past that window the read
  waits for the backend like a miss and never falls back to the expired copy.

In the App Router, both `resolveConsent` and `createConsentRoute` pass
`next: { revalidate: 300 }` to upstream manifest fetches. Next.js's Data
Cache can satisfy an in-process cache miss, including on a new server instance
when your host provides a shared cache. A `manifestURL` pointing directly at
the backend uses these same cache layers. The consent route also provides a
cacheable response for browsers and your CDN.

Pages Router helpers keep the in-process cache, but ordinary Pages Router
fetches do not use the App Router Data Cache. A build-time snapshot avoids
manifest cache misses in both routers and stays fixed until rebuilding.

Absolute `http(s)` URLs are used as given. `resolveConsent` resolves a
`/`-relative `backendURL` or `manifestURL` against the request's `host`
header. A domain name resolves over `https`. `localhost`, an IP address or a
single-label host such as `app:3000` resolves over `http`. The
`x-forwarded-host`, `x-forwarded-proto`, `forwarded` and `referer` headers
are ignored, because any client can send them and the `/init` call carries the
visitor's consent cookie to the resolved host. When no `host` header is
available, `resolveConsent` reports the error and returns the baseline state.

A render never fetches your own consent route: a URL on the request's origin
under the config's `routePrefix`. `resolveConsent` reports the URL and returns
the baseline state instead. Keep the config's `backendURL` absolute, and use
[`proxy: true`](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
to keep the browser on your origin.

Any other same-origin `backendURL` is a backend reached through your app, such
as `/api/c15t` with a rewrite or a mounted `@c15t/backend`. `resolveConsent`
calls its `/init` like any backend. That request goes back through your own
server, which costs a second function invocation on serverless hosts and fails
behind deployment protection; the render then returns the baseline state and
the browser resolves the policy. Pass the backend's own URL to skip the hop.
If the prefix reaches no backend and a page answers instead, that page's
`resolveConsent` sees the request came from a render and does not fetch again.

Behind a proxy that sets `x-forwarded-host` and `x-forwarded-proto` and drops
the values a client sends, pass `trustForwardedHeaders: true` to resolve
against them instead. Use `https` for any production `backendURL`. Over plain
HTTP to anything but a loopback host, the `/init` call carries no cookie, no
`forwardHeaders` and no client IP.

Forwarded headers differ by path, and only what the backend needs travels:

* The backend `/init` call carries the resolved `x-c15t-country`,
  `x-c15t-region`, `accept-language` and `sec-gpc`, the `user-agent`, and the
  experiment arm while the visitor has no stored choice. Over `https` or to a
  loopback host it also carries the consent cookie (`cookieName`, never the
  rest of the cookie jar), any `forwardHeaders`, and with
  `trustForwardedHeaders` the visitor IP as `x-forwarded-for`. It is sent with
  `cache: 'no-store'`.
* The manifest request carries only the headers named in `forwardHeaders`,
  because the manifest is public policy data.

Cookies are still read locally on both paths to restore records.

An inline `snapshot`, including the one `withConsentManifest` downloaded, is
never refreshed. The manifest transport returns the
object as given instead of fetching it, so the snapshot is the source of truth
for that request rather than a cache seed. A stale snapshot resolves stale
policy until the application ships a new one. One request can still happen:
when the inline manifest has `iab.enabled: true` with an `iab.gvl` reference
and the matched rule uses the `iab` model, the transport fetches the Global
Vendor List with the `fetch` option, and a blocked network there also falls
back to the baseline. `backendURL` is still required because choices post to
`${backendURL}/subjects`.

`onError` replaces the default logging entirely. Without it, production
deployments render the baseline silently; pass `onError` to report failures to
your monitoring. `cookieName` must match the client `storageKey` for stored
choices to be restored at all: with a mismatch the server supplies empty
records, the provider treats them as prepared and skips browser hydration, so
the visitor's existing choice stays ignored for the whole mount, not only at
first paint.

### Cookie-only state

With `mode: offline()`, or when no backend URL is configured anywhere,
`resolveConsent` returns state that needs the visitor's stored records but no
resolved policy. It makes no network request. It reads the request and returns a JSON-serializable
`ConsentState` with `initialRecords`, `initialPrivacySignals.gpc`, `now` and,
when any value was detected, `initialOverrides` with `country`, `region` and
`language`. It does not set cookies and does not cache across requests. Only
these options apply:

|Option|Default|Behavior|
|--|--|--|
|`now`|`Date.now()`|Clock used to validate stored records and stamped into the result.|
|`cookieName`|`c15t`|Cookie holding persisted consent. Must match the client `storageConfig.storageKey`.|
|`country`|header detection|Overrides the country read from request headers.|
|`language`|header detection|Overrides the language read from `accept-language`.|
|`request`|`next/headers`|Request context adapter with `cookies()` and `headers()`. The default only works in the App Router.|

The cookie header is read from `headers().get('cookie')` first and from
`request.cookies()` only when that header is absent. Country and region come
from the headers listed in [geography and privacy signals](#geography-and-privacy-signals).

### Types

|Type|Exported from|What it names|
|--|--|--|
|`ConsentState`|`c15t/next`, `c15t/next/server`, `c15t/next/pages`|The value `resolveConsent` returns and `ConsentRoot` takes as `state`|
|`ResolveConsentOptions`|`c15t/next/server`|The App Router options bag|
|`ConsentRequestOptions`|`c15t/next/server`|The request-reading subset: `now`, `cookieName`, `country`, `language`, `request`|
|`PagesResolveConsentOptions`|`c15t/next/pages`|`ResolveConsentOptions` with `req` in place of `request`|
|`ConsentRootProps`|`c15t/next`|Props of `ConsentRoot`; `ConsentRootProps['state']` also accepts the pending promise|
|`ConsentConfig`|`c15t/next`, `c15t/next/server`, `c15t/next/pages`, `c15t/next/api`|The frozen `defineConsentConfig` result|
|`ConsentMode`|`c15t/next`|What `manifest()`, `hosted()` and `offline()` return|
|`NextConsentRouteOptions`|`c15t/next/api`|Options of `createConsentRoute` and `createPagesConsentRoute`|
|`ConsentPageProps`|`c15t/next/pages`|`pageProps` of a page that exports `withConsentProps`, for `AppProps<ConsentPageProps>`|
|`WithConsentPropsOptions`|`c15t/next/pages`|`PagesResolveConsentOptions` without `req`|

### Pages Router differences

`withConsentProps(getServerSideProps?, options?)` from `c15t/next/pages` is a
`getServerSideProps` that resolves consent and adds it to the page's props as
`consent`. It wraps the page's own `getServerSideProps` when given; consent
resolves while it runs, and its `redirect` and `notFound` results pass
through. `options` takes every option in the App Router table except
`request`. The state is round-tripped through JSON, because Next.js rejects
`undefined` prop values such as an absent GPC signal.

`c15t/next/pages` also exports `resolveConsent` with the Node request in place
of the `request` adapter. `resolveConsent({ req, ...options })` accepts every
option in the App Router table except `request`; `req` is the request from
`getServerSideProps` or an API route. Its result can hold `undefined` fields,
so round-trip it through `JSON.parse(JSON.stringify(result))` before returning
it as a prop, or use `withConsentProps`, which does that for you.

`createPagesRequestContext(req)` builds the `request` adapter itself. Headers
are converted to Web `Headers`, and cookies are read from the `cookie` header.
Use it when calling the `c15t/next/server` helper from a custom server or
test harness where `next/headers` is unavailable:

```ts title="server/consent.ts"
import type { IncomingMessage } from 'node:http';

import { createPagesRequestContext } from 'c15t/next/pages';
import { resolveConsent } from 'c15t/next/server';

export function resolveRequestConsent(req: IncomingMessage) {
	return resolveConsent({ request: createPagesRequestContext(req) });
}
```

## Route handler options

### createConsentRoute options

`createConsentRoute(options?)` from `c15t/next/api` returns `GET` for one
catch-all route, such as `app/api/c15t/[...c15t]/route.ts`. `GET` answers
`/init` and `/manifest` under the route; every other path answers 404. With
`proxy`, it also returns `POST`, `PATCH`, `PUT`, `DELETE` and `OPTIONS`, and
forwards the other consent paths to the backend. Everything defaults to
`c15t.config.ts` and the snapshot `withConsentManifest` downloaded.

|Option|Default|Behavior|
|--|--|--|
|`config`|`c15t.config.ts`|The config to use instead of the file.|
|`backendURL`|the config's, then `NEXT_PUBLIC_C15T_BACKEND_URL` or `NEXT_PUBLIC_INTH_PROJECT_URL`|Backend base URL. Without a snapshot, the route fetches `${backendURL}/manifest`.|
|`manifestURL`|the mode's absolute `manifestURL`|Full upstream manifest URL. Takes precedence over `backendURL` plus `/manifest`.|
|`snapshot`|the snapshot `withConsentManifest` downloaded|Takes precedence over upstream URLs, serves the manifest and resolves each visitor without fetching policy. Stays fixed until rebuilding.|
|`proxy`|`false`|Forward `subjects`, `subjects/:id`, `health` and `status` to the backend, so browser saves stay on your origin. Pair it with `proxy: true` in `c15t.config.ts`. `createPagesConsentRoute` takes it too.|
|`manifestRevalidateSeconds`|`300`|Next.js Data Cache revalidation for the manifest fetch. `false` disables it.|
|`fetch`|`globalThis.fetch`|Fetch implementation for the manifest and Global Vendor List requests.|
|`trustForwardedHeaders`|`false`|Resolve a `/`-relative `backendURL` or `manifestURL` against the request's `forwarded`, `x-forwarded-host` and `x-forwarded-proto` headers instead of `request.url`. Set it only behind a proxy that sets those headers and drops the ones a client sends.|
|`onBackgroundRevalidate`|none|Receives detached work started by a request: a background manifest refresh, and the init route's session report. Keep it alive with `after` from `next/server` or a platform `waitUntil`. Called inside the handler; the promises never reject. See [Optimization](/docs/frameworks/next/optimization#configure-manifest-cache-refresh).|
|`reportSessions`|`true`|Report each init the route resolves to the backend's `POST /sessions`, server-to-server and detached from the response, so the backend still counts the visitor. Needs an absolute `backendURL`; nothing is inferred from a manifest URL. `false` sends none.|
|`fetchGvl`|built-in cached fetcher|Loads the Global Vendor List for IAB policies. Called only under the conditions described in this section.|

With no snapshot, `manifestURL` wins over `backendURL`. URLs are resolved per
request, so a missing or invalid value fails the request rather than the
build: with no snapshot and neither `backendURL` nor `manifestURL`, the
handler throws. A
`/`-relative value is resolved against the origin of `request.url`, which
Next.js builds itself. Forwarding headers are read only with
`trustForwardedHeaders: true`. A relative value still points the handler at
your own app, so keep upstream URLs absolute; otherwise the consent route
fetches itself.

A `/`-relative `manifestURL` on the config's mode names the route itself, so
the handler ignores it. Keep the config's `backendURL` absolute. To keep the
browser on your origin, set [`proxy: true`](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
rather than a relative `backendURL`.

The handlers are built on the consent route handler in `@c15t/core/server`,
which the TanStack Start, SvelteKit, Astro and Nuxt adapters share, so the
rules below are the same in every framework.

`GET ${routePrefix}/init` resolves the build snapshot or runtime cached manifest with the request's
geography, language and GPC headers and responds with `cache-control: private, no-store` and
`x-c15t-policy-contract: 1`. The payload echoes the inputs it used as
`resolvedOverrides` and `resolvedPrivacySignals`. The browser sends its
overrides and policy contract as the `country`, `region`, `gpc` and
`contract` query parameters, which win over the matching `x-c15t-*` headers. When the request declares a different policy contract in
either form, the response keeps the
translations and UI data but sets `policyResolution` to `status: 'failed'`
with `reason: 'unsupported-contract'`. Whenever the resolution is not
`matched`, the payload carries no `policySnapshotToken`, `gvl`,
`gvlReference`, `cmpId` or `customVendors`. Requests that declare no contract
are treated as compatible.

With a snapshot, `GET ${routePrefix}/manifest` returns the complete snapshot as
JSON with status `200`. It makes no upstream request, adds no cache or validator
headers and does not answer `If-None-Match` with `304` or slice by `language`.

With runtime fetching, `GET ${routePrefix}/manifest` forwards the upstream `cache-control`,
`etag`, `last-modified` and `content-language` headers, adds `content-type: application/json` and an
`age` computed from the in-process cache, and answers a matching
`If-None-Match` with `304`. It never invents a `cache-control` header the
upstream did not send. The only query parameter passed upstream is a
`language` that looks like a language tag, lower-cased; every other parameter
is dropped, so a visitor's query string neither reaches the backend nor adds
cache entries.

With runtime fetching, when the manifest cannot be read and `backendURL` is
set, `GET ${routePrefix}/init` asks the backend's own `GET /init` instead, forwarding only the geography, language and
GPC headers. This covers backends without `/manifest`. It happens for a `404`
and for the first failure of a failing backend, not for every request while
the manifest cache backs off. Otherwise the handler rejects and Next.js
answers `500`.

`fetchGvl` runs inside the init path only when the manifest has `iab.enabled: true`,
the manifest includes an `iab.gvl` reference, and the resolved policy matched
with `model: 'iab'`. It receives the reference, the `fetch` option, and the
language taken from the first segment of the resolved translations language
(`en` when empty). The default fetcher caches the vendor list in process and
aborts the upstream request after five seconds. A fetched list becomes a
`gvlReference` and a small banner summary in the serialized payload. A `null`
result keeps IAB unavailable. A rejected or timed-out fetch fails the request
rather than answering `gvl: null`, because the browser reads `null` as "IAB is
off" and would show a policy that requires the TCF without it. With
`routePrefix`, the browser reads the list from that same-origin route;
otherwise it uses the manifest's public list URL. The banner shows the same
purpose names and vendor count on the server and during hydration. A
client-only `vendors` allowlist on the IAB config makes that server summary
unusable, so the banner waits for the full list. Filter vendors on the server
when the banner must render immediately.

`createPagesConsentRoute(options?, param?)` from `c15t/next/pages` accepts the
same options except `proxy` and returns the default export of a catch-all
`pages/api` route, `pages/api/c15t/[...c15t].ts`. `param` names the catch-all
parameter and defaults to `c15t`; a file with another name throws
`` @c15t/nextjs: createPagesConsentRoute found no `c15t` catch-all parameter. Name the file [...c15t].ts or pass its parameter name. ``
Because a `pages/api` default export receives every method, requests other
than `GET` and `HEAD` are answered with `405` and an `allow: GET` header before
the wrapped handler runs. The bridge
rebuilds the request URL from the `host` header, over `http` for `localhost`,
IP and single-label hosts and `https` otherwise, and reads forwarding headers
only with `trustForwardedHeaders: true`.

## Manifest request resolution

The [App Router](/docs/frameworks/next/app-router) and
[Pages Router](/docs/frameworks/next/pages-router) manifest setups use this flow:

1. `next build` bundles the backend's `/manifest` response as a snapshot.
   With `manifest({ source: 'runtime' })` instead, the server fetches the
   absolute backend's `/manifest` endpoint and caches the public policy data.
2. `resolveConsent()` resolves policy from that snapshot or cache with the
   current request's inputs and restores valid consent cookies.
3. `ConsentRoot` receives that result as `state` and reads the rest from
   `c15t.config.ts`. Hydration preserves the resolved state.
4. If browser initialization is needed, it asks `${routePrefix}/init`, whose
   route resolves the same snapshot on the server, or `${backendURL}/init`
   without `routePrefix`. `manifest({ resolve: 'browser' })` resolves in the
   browser instead.
5. Browser choices post to `${backendURL}/subjects`.

A warm policy cache avoids backend `/init` during request resolution. The app
may still read its consent route, cold caches fetch upstream data, and choices
still reach the backend. IAB policies can also require a Global Vendor List
fetch. See [manifest caching](/docs/frameworks/next/optimization) for cache
settings, and [rendering and deployment](/docs/frameworks/next/rendering) for
awaiting or streaming prefetch results.

## Static manifest helpers

`c15t/next/static` exports `loadStaticManifest`, `createStaticManifestModule`,
`createStaticConsentResolver` and `resolveUnknownLocationInit` for resolving
consent from a manifest bundled at build time, for example in an
`output: 'export'` site. The two resolvers come from `c15t/static`, which
`c15t/tanstack-start/static` re-exports too.

* `createStaticManifestModule({ manifestURL })` fetches a manifest and returns
  TypeScript source for a module you write to disk and import.
* `loadStaticManifest` fetches and returns the manifest object.
* `createStaticConsentResolver({ manifest, geo, geoURL })` returns a synchronous
  `initial` result and a `resolved` promise. Without `geo`, or when a `geoURL`
  returns no location, it uses the manifest's unknown-location policy: its
  fallback rule, else its default rule. That is the same policy the server
  helpers apply when a request has no location headers. Rules scoped to a
  country or region never apply to an unknown location.
* `resolveUnknownLocationInit(manifest, { language, gpc })` returns that
  unknown-location result on its own.

A manifest with neither a fallback rule nor a default rule cannot resolve an
unknown location. The resolvers then return a failed result with the reason
`insufficient-inputs`, and the client applies its safe fallback. Give your
policy a fallback rule before you bundle it.

A generated manifest contains public policy, not a visitor's choice. The
helpers do not mount a provider, persist choices or send consent to the
backend. You wire them into a custom transport passed as `options.mode`, and
publishing new policy needs a rebuild. The
[static export guide](/docs/frameworks/next/static-export) uses backend `/init`
instead, which needs none of this. Never bake a build machine's location or
cookies into a shared static page.

A static export can also resolve a manifest in the browser without these
helpers. Set `mode: manifest({ resolve: 'browser', manifestURL })` in
`c15t.config.ts`, with an absolute `manifestURL` the browser can fetch from
your site's origin. Browser manifest resolution has no
location input, so every visitor gets your unknown-location rule.

## Geography and privacy signals

Server manifest resolution reads location headers from the hosting platform.
It recognizes country headers such as `cf-ipcountry` and
`x-vercel-ip-country`, and region headers such as `cf-region-code` and
`x-vercel-ip-country-region`. The application overrides `x-c15t-country` and
`x-c15t-region` take precedence. Only trusted infrastructure should supply
location overrides in production.

Request helpers also read language and GPC. Missing location stays unknown;
the resolver does not infer country from the Next.js server's IP. Test unknown
country and region against your configured policy rules.

Browser manifest resolution uses location overrides from prefetch, `inputs`
or `geoURL`. Without them, a location-based policy asks the backend's `/init`.
The [consent route](#do-i-need-the-consent-route) reads geographic headers on
the server and keeps resolver code and translations out of browser
initialization.

## Offline configuration

Not recommended for production environments. Use offline mode for local
development, tests or demos that do not need backend records.

Set `mode: offline()` in `c15t.config.ts`. It needs no backend URL:

```ts title="c15t.config.ts"
import { defineConsentConfig, offline } from 'c15t/next';

export default defineConsentConfig({ mode: offline() });
```

Keep your layout. `resolveConsent()` then makes no network request and the
browser resolves the rules after hydration. `offline()` from `c15t/next` is
data, so the offline rules load with `import()` only in apps that use them.

The default local policy pack handles missing geography; offline mode does not
perform IP lookup. Supply `policyRules` to replace that pack when your local
policy needs different behavior. Browser persistence stores choices, but this
setup has no backend record service. See
[transport choices](/docs/concepts/data-fetching) for the tradeoffs.

Offline mode runs only when you choose it. `ConsentRoot` throws when
`manifest()` or `hosted()` finds no backend URL: not in the mode, the config
or `NEXT_PUBLIC_C15T_BACKEND_URL`. That happens only without a
`c15t.config.ts`, because `defineConsentConfig` throws without a backend URL.
See [troubleshooting](/docs/frameworks/next/troubleshooting#why-does-consentroot-throw-that-it-needs-a-backend-url).

### Authenticated hosted vendor lists

When hosted `resolveConsent()` forwards the consent cookie or additional
request headers, or uses a custom `fetch`, it retains the fetched vendor list
in server state.
The browser cannot replay a private server fetch. This fallback preserves consent
loading and vendor filtering without copying credentials into the page. Its
payload size is unchanged from inline GVL loading. For compact pages with private
upstreams, expose the public list through the consent route with
`routePrefix`.

# DevTools
URL: https://c15t.com/docs/frameworks/next/components/dev-tools
Load the c15t DevTools panel only in Next.js development builds to inspect consent state, scripts, policy and events inside ConsentRoot.

`DevTools` is a floating panel for the c15t v3 kernel. Use it during development to inspect consent values, scripts, location, the resolved policy, IAB state, events, and consent actions. The framework adapter reads the kernel from the nearest v3 provider. It never discovers a store through a window global.

> ⚠️ **Warning:**
> Load DevTools only in development. A conditional JSX expression stops it from mounting in production, but a static import can still add DevTools to the production bundle. Use a development-only dynamic import as shown below. The component renders nothing into the React tree and mounts its panel in document.body.

## Installation

No extra package is required. The React adapter and its engine are included
with the `c15t` package. Install `@c15t/dev-tools` directly only when you
need the imperative `createDevTools({ kernel })` API.

## Add DevTools to `ConsentRoot` in development

Keep the `ConsentRoot` from your router setup. Add this client component as
one of its children, alongside the banner and dialog. It uses the existing
runtime, including its prefetch result and configured transport.

```tsx title="components/consent-dev-tools.tsx"
'use client';

import dynamic from 'next/dynamic';

const DevTools =
	process.env.NODE_ENV === 'development'
		? dynamic(
				() => import('c15t/next/devtools').then(({ DevTools }) => DevTools),
				{ ssr: false }
			)
		: () => null;

export function ConsentDevTools() {
	return <DevTools />;
}
```

Import `ConsentDevTools` into your root layout or `pages/_app.tsx` and render
`<ConsentDevTools />` inside `ConsentRoot`. Keep its `state` and other props
unchanged. A setup that uses `ConsentProvider`
directly can place the same component inside that provider.

The umbrella import is `c15t/next/devtools`. When installing the dedicated
Next.js package, use `@c15t/nextjs/devtools`.

## Configuration

```tsx
<DevTools
  position="bottom-right"
  defaultOpen={false}
  defaultTab="consents"
  maxEvents={100}
  disabled={false}
/>
```

`position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
`bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
to choose that panel. `maxEvents` limits captured kernel and script events.
Set `disabled` to prevent mounting without removing the component. The
panel renders inside a shadow root by default, so page CSS does not reach
it. `shadow={false}` mounts it in the light DOM with its stylesheet in
`<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTriggerToolbar` or the ready-made `ConsentDialogTrigger`
is visible, the trigger shows a DevTools button and DevTools hides its own
floating launcher, so one control occupies the corner. The button sits at the
end of the toolbar farthest from its corner. The panel opens just past the
toolbar, aligned with its outer edge, and follows it when a visitor drags the
toolbar to another corner. `position` applies again once no trigger is
visible.

`ConsentDialogTrigger` becomes a two-button toolbar while DevTools is
mounted. A trigger composed from `ConsentDialogTrigger.Root` keeps its own
markup, and DevTools keeps its floating launcher beside it.

DevTools brings its launcher back whenever no trigger is visible, for example
while `showWhen="after-prompt"` waits for a choice. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

With the imperative engine, call `devTools.dock({ position, inline, block })`
to hide the launcher and anchor the panel `inline` and `block` pixels from the
viewport edges of `position`'s corner. Call `devTools.dock(null)` to restore
the launcher.

## Panels

Accept and reject apply only to categories displayed by the provider, leaving
hidden consent values unchanged. `necessary` always remains enabled. The
React adapter uses the current policy categories by default.

For an imperative integration with a narrower UI, pass
`getConsentCategories: () => ['necessary', 'measurement']` to
`createDevTools`. The getter is read again when an action runs. Headless UI
actions can use `kernel.commands.save('all', { categories: displayed })` or
`kernel.commands.save('none', { categories: displayed })`. These scoped bulk
saves use a `custom` transport action when they cover only part of the policy.
Actions covering the whole policy retain `all` or `necessary`. Without an
explicit scope or policy categories, bulk saves cover all known categories.

|Panel|What it shows|
|--|--|
|**Consents**|Inspect and save categories, accept all, or reject optional categories|
|**Scripts**|Configured scripts, loading status, search, and external page resources|
|**Location**|Resolved country and region, and location overrides|
|**Policy**|Resolved policy and UI configuration|
|**IAB**|Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings|
|**Events**|Timeline of consent changes, kernel events, and script lifecycle events|
|**Actions**|Show the banner, open preferences, hide consent UI, or refresh consent data|

### Script inspection

Set `defaultTab="scripts"` to open script inspection first. It reads all script
loaders attached to the current provider's kernel, including loaders created
before DevTools mounts. Search by script ID, category, URL, or status, then
expand a script to inspect its configuration and latest lifecycle event.

`loading` means an external script was inserted; `loaded` means its browser
load event fired, or an inline script or callback-only integration mounted.
`error` reports a loader error. `blocked` means consent requirements were not
met, and `pending` means an eligible script has not mounted. `present` means
the loader reused an element without a confirmed load result. `retained`
means consent was revoked but `persistAfterConsentRevoked` kept the element.
Retained scripts still receive `onConsentChange` with `hasConsent: false`, so
their integrations can send the vendor's consent-revocation command.
`alwaysLoad` bypasses the loading gate, not consent: callbacks receive the
actual consent state and updates across categories for integrations such as
Google Consent Mode.

Script details distinguish `allowedToLoad` from `consentGranted`. An
`alwaysLoad` integration can be allowed to load while its consent is denied.
Diagnostics expose these as `eligible` and `hasConsent`, respectively.

Lifecycle diagnostics work even when legacy debug forwarding is disabled.
The page scan lists external scripts and iframes present in the
DOM; it does not prove that they loaded successfully or were consent-gated.

For custom inspection tools, import `getScriptDiagnostics(kernel)` and
`subscribeScriptDiagnostics(kernel, listener)` from
`c15t/modules/script-loader`. The subscription reports loader
registration, updates, disposal, and lifecycle events. Read a fresh snapshot
after changes and call the returned unsubscribe function during cleanup.

### IAB editing

Under an IAB policy, the Consents tab is read-only. Edit and save vendors
and purposes in the IAB tab so the derived categories and TC string stay
consistent.

The IAB panel connects to the existing `@c15t/iab` module attached to the
provider's kernel. It does not create a second CMP or replace `__tcfapi`.
Controls become available after initialization, when the current policy uses
IAB and the vendor list is loaded.

Choose Vendors, Purposes, or Special features, then search by name or ID.
Vendors include the provider's custom vendors. Long lists show 20 entries per
page. Legitimate-interest controls appear for declared legitimate interests.
Search only filters the view; Accept all IAB and Reject all IAB apply to the
configured choices, including custom vendors.

Toggles update live IAB state and script gating immediately. Use Save IAB
consent to generate a fresh TC string and run the configured save transport.
The panel displays the last generated string; unsaved edits are not represented
in it. Copy TC string confirms success or reports clipboard failures. Raw IAB
data remains available in an expandable section.

IAB saves normally write the TC string to its standard cookie and localStorage.
For an in-memory playground, set `persistence: false` in the IAB module options
as well as disabling the provider's core persistence. The IAB option prevents
TC-string storage writes; it does not disable the configured save transport
or remove previously stored values.

Save and refresh actions show pending, success, and failure feedback. Controls
are disabled while a request is pending. A failed save does not roll back the
live choices; retry to record them.

For custom inspection tools, `getIABControls(kernel)` and
`subscribeIABControls(kernel, listener)` are exported from `c15t`.
The getter returns undefined before module initialization and after disposal.
A snapshot without an attached IAB module is read-only in DevTools.

## TanStack Devtools

Each embedded panel owns its event history and subscriptions. Unmounting it
destroys the instance; remounting starts a new history. If you need to capture
events while switching plugins, keep the c15t panel mounted. This differs from
the old globally shared DevTools store.

The React v3 DevTools adapter exports a panel component and plugin factory that match TanStack Devtools' plugin API:

```tsx
import * as React from 'react';
import { useRouter } from '@tanstack/react-router';
import { TanStackDevtools } from '@tanstack/react-devtools';
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
import { c15tDevtools } from 'c15t/react/devtools';

export function AppDevtools() {
  const router = useRouter();

  return (
    <TanStackDevtools
      plugins={[
        {
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
        {
          name: 'TanStack Router',
          render: <TanStackRouterDevtoolsPanel router={router} />,
        },
        c15tDevtools(),
      ]}
    />
  );
}
```

In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.

The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:

```tsx
import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';

const c15tPlugin = {
  name: 'Consent',
  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
    <C15tTanStackDevtoolsPanel theme={theme} />
  ),
};
```

## Props

|Property|Value|
|:--|:--|
|Type Name|\`ConsentDevToolsProps\`|
|Source Path|\`./packages/react/src/devtools.tsx\`|

\*ExtractedTypeTable: Could not extract "ConsentDevToolsProps" from "./packages/react/src/devtools.tsx" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.\*

# Troubleshooting
URL: https://c15t.com/docs/frameworks/next/troubleshooting
Diagnose failed c15t consent prefetch and build-time manifest downloads in Next.js, verify manifest requests, and fix a missing c15t.config.ts, config errors, unknown server location and prerendering errors.

## Why does the page render when consent prefetch fails?

**Check.** `resolveConsent` returns its baseline state when a manifest or
backend request fails. The page can still render, and the client retries
initialization. Until policy resolution succeeds, optional categories stay
denied and the stock banner stays hidden. Check the failed URL and response in
your server logs, as browser Network tools cannot show a server-side fetch.

**Fix.** Pass `onError` to `resolveConsent` to report failures in production.
Without it, the helper logs a warning only outside production.

**Check.** If the consent route repeatedly calls itself, check its upstream
URL.

**Fix.** Set the config's `backendURL`, or `NEXT_PUBLIC_C15T_BACKEND_URL` (or
`NEXT_PUBLIC_INTH_PROJECT_URL`), to
the absolute Inth or self-hosted backend endpoint. To send the browser through
`/api/c15t`, set `proxy: true` and `routePrefix` instead of a relative
`backendURL`; the route keeps the absolute URL. See
[Next.js optimization](/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin).

## Why does `next build` or `next dev` fail to fetch the manifest?

**Check.** `withConsentManifest` downloads `${backendURL}/manifest` when
`next build`, `next dev` or `next typegen` loads `next.config.ts`. When the
download fails or takes longer than 10 seconds, `next build` stops with an
error that starts with `@c15t/nextjs/build: could not fetch the consent manifest from <url> during the build`. `next dev` logs the same message as a
warning, and `snapshot` from `c15t/generated` is `undefined`, so the server
fetches the policy at runtime. It never reuses an old snapshot. The part in
parentheses names the cause:

* `fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error,
  or `no response within 10 seconds`. The build machine cannot reach the
  backend.
* `/manifest responded 404`, or another status. The URL is not your
  project's backend. Check for the `https://your-project.inth.app`
  placeholder and a missing path prefix.
* `/manifest returned an invalid consent manifest.` The URL answered, but not
  with a c15t manifest. It may be a different service, or a backend that does
  not support this c15t version.

`no backend URL is set` means the build found no `backendURL` option, no
`backendURL` in `c15t.config.ts` and no `NEXT_PUBLIC_C15T_BACKEND_URL` or
`NEXT_PUBLIC_INTH_PROJECT_URL`, or empty ones. `next build` stops on it and
`next dev` warns. A notice that the build `skipped the consent manifest fetch`
means the backend URL is a path such as `/api/c15t`. With
`onBuildError: 'fail'`, that stops the build with `build-time manifests require an absolute upstream URL.` The same notice ending in
`because c15t.config.ts uses hosted()`, `uses offline()`,
`passes manifest({ snapshot })` or `sets manifest({ source: 'runtime' })` is
expected: those modes read no build-time manifest.

`@c15t/nextjs/build: could not read c15t.config.ts (...)` is a warning: the
build could not evaluate the file, so it fetched the manifest as for
`manifest()`, whatever the file's `mode`. The part in parentheses is the
error. The usual cause is an import Node can't load at build time, such as a
stylesheet. Keep `c15t.config.ts` to the config and the packages it needs.

**Fix.** Set `NEXT_PUBLIC_C15T_BACKEND_URL` (or
`NEXT_PUBLIC_INTH_PROJECT_URL`) to the absolute backend URL from your Inth
project, or your self-hosted origin with its path prefix, wherever
`next build` runs, including CI. To deploy while the backend is down, run the
build with `C15T_ON_BUILD_ERROR=runtime`, or set `onBuildError: 'runtime'`.
The deployment then works without a snapshot, and each server fetches the
policy on its first request. To drop the build-time fetch, use
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data)
instead.

## Why does importing `c15t/generated` from a client component fail the build?

**Check.** `next build` or `next dev` reports that `server-only` cannot be
imported from a Client Component, in a module that imports `c15t/generated`.

**Fix.** `withConsentManifest` keeps the snapshot out of browser bundles, so
`c15t/generated` only works in server code: Server Components, route
handlers, `getServerSideProps` and API routes. Most apps never import it.
`resolveConsent` and the consent route read the snapshot themselves, and
`ConsentRoot` receives the resolved state.

## Why is `snapshot` undefined?

**Check.** `snapshot` from `c15t/generated` is `undefined` in server code.

**Fix.** Check these causes:

* `withConsentManifest` doesn't wrap the config in `next.config.ts`. Without
  it, `c15t/generated` still resolves, but exports `undefined`.
* The fetch failed in `next dev`, or in a build with
  `C15T_ON_BUILD_ERROR=runtime`. The server then fetches the policy at
  runtime.
* The backend URL is relative, or the config sets `output: 'export'`, so the
  build skipped the fetch.
* The code runs in a package listed in `serverExternalPackages`, which stays
  outside the bundle and doesn't see the alias.

`c15t/generated` ships its own types, so `tsc --noEmit` passes on a fresh
clone without running Next.js first.

## Verify manifest fetching

Check the Next.js server and browser requests after following the
[App Router](/docs/frameworks/next/app-router) or
[Pages Router](/docs/frameworks/next/pages-router) guide:

1. Load the page twice. A warm manifest setup resolves policy without calling
   the upstream backend `/init`. A browser request to your local
   `/api/c15t/init` is expected when client initialization is needed.
2. Make a consent choice. Confirm the submission reaches the backend
   `/subjects` endpoint and reload to check that the choice persists.
3. Test two locations with different configured policies. Confirm the resolved
   policy matches each location and that your host passes trusted geography
   headers to Next.js.
4. Change a policy, rebuild, then check it. With runtime fetching, check it
   after the manifest caches refresh instead. Cache the public manifest, never
   the visitor-specific init response.
5. If you set `proxy: true`, confirm browser consent requests use `/api/c15t`,
   including submissions. Direct requests to the backend are expected without
   it.

## Why does ConsentRoot warn that it found no config?

**Check.** The browser console shows this warning outside production:

```txt
[c15t] ConsentRoot found no config. Export `defineConsentConfig()` as the default export of c15t.config.ts at the project root and wrap next.config.ts in `withConsentManifest()`, or pass `config`.
```

**Fix.** `withConsentManifest` finds `c15t.config.ts`, `.mts`, `.js` or
`.mjs` in the directory `next build` and `next dev` run from, and nowhere
else. A config in `src/` is not found. Check that:

* `next.config.ts` exports `withConsentManifest(nextConfig)`.
* The file is at the project root, next to `next.config.ts`.
* It has a default export, `export default defineConsentConfig({ ... })`, not
  only a named one.
* You restarted `next dev` after adding the file.

Without a config, `ConsentRoot` reads `NEXT_PUBLIC_C15T_BACKEND_URL`, which
`withConsentManifest` sets from `NEXT_PUBLIC_INTH_PROJECT_URL` when only that
is set, uses
`manifest()` and runs no `scripts`. With no backend URL either, it throws; see
the next section.

## Why does ConsentRoot throw that it needs a backend URL?

**Check.** The page, or `next build` while it prerenders the page, throws one
of these errors from `ConsentRoot`:

* `` @c15t/nextjs: manifest() needs a backend URL. Set NEXT_PUBLIC_C15T_BACKEND_URL (or NEXT_PUBLIC_INTH_PROJECT_URL), or `backendURL` in c15t.config.ts. ``
* `` @c15t/nextjs: hosted() needs a backend URL. Set NEXT_PUBLIC_C15T_BACKEND_URL (or NEXT_PUBLIC_INTH_PROJECT_URL), or `backendURL` in c15t.config.ts. ``

A production build prints only the first sentence, such as
`@c15t/nextjs: manifest() needs a backend URL.`

`ConsentRoot` found no `c15t.config.ts`, or got a `config` prop without a
backend URL, and neither `NEXT_PUBLIC_C15T_BACKEND_URL` nor
`NEXT_PUBLIC_INTH_PROJECT_URL` was set when Next.js compiled the page.

**Fix.** Set `NEXT_PUBLIC_C15T_BACKEND_URL` (or
`NEXT_PUBLIC_INTH_PROJECT_URL`) wherever `next build` and
`next dev` run, and check that `withConsentManifest` finds `c15t.config.ts`
(see the previous section). Earlier alphas fell back to offline mode here;
now the root throws. To run without a backend, set `mode: offline()` in
`c15t.config.ts`, or pass `options={{ mode: offline() }}` to `ConsentRoot`.

## Why does ConsentRoot warn that a transport ships in the first-load bundle?

**Check.** The browser console shows a warning such as:

```txt
[c15t] ConsentRoot `mode` is the hosted() transport itself, so its code ships in the first-load bundle. Use hosted() from c15t/next instead: it is plain data, and the root loads the code only when it runs.
```

**Fix.** `options.mode` received `hosted()`, `offline()` or `manifest()` from
`c15t/react`, which are transports. Import the mode from `c15t/next` and set
it as `mode` in `c15t.config.ts`. `custom(transport)` does not warn.

## Why does defineConsentConfig throw?

**Check.** `next build`, `next dev` or the first server render fails with a
`TypeError` that starts with `@c15t/nextjs: defineConsentConfig`.
`withConsentManifest` reads `c15t.config.ts` when Next.js loads
`next.config.ts`, so most config errors stop the build before it compiles.
The checks run on the server only; the browser copy of the file skips them.

**Fix.** The [config reference](/docs/frameworks/next/data-fetching-reference#config-reference)
lists each message. The most common is
`` @c15t/nextjs: defineConsentConfig needs `backendURL`, or NEXT_PUBLIC_C15T_BACKEND_URL (or NEXT_PUBLIC_INTH_PROJECT_URL) set at build time. ``
Set the variable in `.env.local` and in your host's build settings, or pass
`backendURL`.

## Why is the visitor's location unknown on the server?

**Check.** `resolveConsent` and the consent route read the visitor's
country and region from hosting platform headers such as `cf-ipcountry` and
`x-vercel-ip-country`; c15t never derives location from an IP address itself.
Some platforms expose those headers to Next.js middleware or proxy but strip
them before Server Components and Route Handlers run, so every visitor falls
back to your unknown-location rule. Log
`(await headers()).get('x-vercel-ip-country')`, or your host's equivalent, in
a Server Component.

**Fix.** If the header is missing there, add `c15tProxy` as described in
[Forward geography headers](/docs/frameworks/next/geography-headers). It
forwards the resolved values as `x-c15t-country` and `x-c15t-region`, which
take precedence everywhere c15t reads location.

## Why does Next.js report an unstable `Date.now()` during prerendering?

**Check.** The error
`Next.js encountered the unstable value Date.now() while prerendering`,
pointing at the `await resolveConsent(...)` line, comes from
`partialPrefetching: true` combined with `cacheComponents: true` (Next.js
16.3 and later). During the runtime-prefetch stage Next.js resolves
`headers()` and then flags the `Date.now()` that follows. It only appears in
`next dev`; `next build` passes because build-time prerenders never resolve
`headers()`.

**Fix.** Use the current c15t release. `resolveConsent` handles this itself:
the default App Router request reader calls `await connection()` from
`next/server` before reading the clock, so the component is already
request-time when the clock is read. You do not need to add `connection()` to
your layout. If you still see the error on the current release, report your
Next.js version and config on
[c15t/c15t#1107](https://github.com/c15t/c15t/issues/1107).

## Why does `next build` fail on a route with `ensureStatic = 'navigation'`?

**Check.** The build fails with one of these errors, and the route sits under a
root layout that calls `resolveConsent`:

* `Next.js encountered data that is not available during a static prerender, but is unable to provide a location` (streamed layout)
* `Next.js encountered uncached or runtime data on a route that must be fully static` (awaited layout)

`'navigation'` requires the whole route to be static, including the root
layout. `resolveConsent` reads the visitor's cookies and headers, so that
layout can't be.

**Fix.** Move those pages into their own route group with the browser layout,
which renders `ConsentRoot` without `state`. See
[Keep pages static with `ensureStatic`](/docs/frameworks/next/rendering#keep-pages-static-with-ensurestatic).
`'shell'` and `'prefetch'` work with the server layouts.

## Why does the page throw that no IABProvider is mounted?

The visitor's policy uses the `iab` model and the backend sent its vendor
list, but no `IABProvider` is mounted. The standard banner and dialog do
not handle the IAB model, so they throw rather than leave the visitor
with no consent UI. Server and browser render the same error.

Fix it one of two ways:

* If the site uses IAB TCF, render `IABProvider` with `IABConsentBanner`
  and `IABConsentDialog` from `c15t/react/iab` inside your consent
  provider. They can sit next to the standard banner.
* If it does not, remove the `iab` model from the policy for that region
  in your Inth project or policy pack.

A backend that answers `gvl: null` turns IAB off for that request. The
policy then runs as opt-in and nothing throws.

The check passes once `c15t/react/iab` has loaded. If you import the IAB
components with a dynamic `import()`, a render of the standard banner
that happens before the import finishes still throws.

## Inspect the active policy

Place this diagnostic component inside your existing consent
boundary. It reads state without recording a choice.

```tsx title="app/consent-policy-debug.tsx"
'use client';

import { useSnapshot } from 'c15t/next';

export function ConsentPolicyDebug() {
	const snapshot = useSnapshot();
	const resolution = snapshot.resolution;

	return (
		<pre>
			{JSON.stringify(
				{
					status: resolution.status,
					policy: resolution.status === 'matched' ? resolution.policy.id : null,
					prompt: snapshot.promptRequirement,
					permissions: snapshot.effectivePermissions,
					location: snapshot.location,
					privacySignals: snapshot.privacySignals,
				},
				null,
				2
			)}
		</pre>
	);
}
```

The diagnostic subscribes to consent changes. Remove it after verification.
For a production feature gate, use `useConsent('marketing')` or the category
your feature needs instead of subscribing to the whole snapshot.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/tanstack-start/quickstart
Resolve consent on the server in a TanStack Start root loader, render the banner in the first HTML, and gate vendor scripts, using Inth as the consent backend.

## Before you start

This guide sets up the recommended path for a TanStack Start app with server
rendering. On each request, a server function in the root loader reads the
visitor's consent cookie and location headers, resolves their policy from a
build-time policy manifest, and hands the result to `ConsentRoot`. The banner is
part of the first HTML, and gated scripts can run right after hydration.

It needs a running Start server. For SPA mode, prerendered pages or a static
host, or to stream the page before consent resolves, see
[rendering](/docs/frameworks/tanstack-start/rendering).

You need an [Inth](https://inth.com) project. In the project, set the policy
rules for your regions, add your site's origin to the trusted origins, and copy
the backend URL.
[Choose your setup](/docs/concepts/choose-your-setup#decide-who-runs-the-consent-backend)
covers self-hosting and offline mode.

The setup bundles your policy into the server at build time, the
recommended production setup. Rebuild after changing policies, translations
or vendors.

## Install c15t

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

`c15t` contains the TanStack Start adapter at `c15t/tanstack-start`.
`@c15t/integrations` holds the vendor loaders used below.

## Bundle your policy at build time

Add the `consentManifest` plugin to `vite.config.ts`, before `tanstackStart()`:

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/tanstack-start/build';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), tanstackStart(), viteReact()],
});
```

During `vite build`, or in `vite dev` when the server first loads it, the
plugin downloads your project's public policy from `${backendURL}/manifest` and serves it to server code as
`snapshot` from `c15t/generated`. In the browser bundle, `snapshot` is
`undefined`, so the policy stays on the server. No file is written into your
project.

Set `VITE_C15T_BACKEND_URL` to your project's backend URL, exactly as Inth
shows it, including any path prefix, in `.env` or wherever you build:

```sh title=".env"
VITE_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `VITE_C15T_BACKEND_URL` wins.

The example app's `.env` points at `https://example-inth.inth.app`, a demo
project. The server function and `ConsentRoot` read the URL from the plugin,
so the app code never repeats it. If you pass `backendURL` to the plugin
instead, the plugin sets the variable to that URL. Vite writes its value into
the server and browser builds, so setting it when you start a built app has
no effect.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

To apply policy edits without rebuilding, pass
`createConsentStateHandler({ mode: manifest({ source: 'runtime' }) })`, with
`manifest` from `c15t/tanstack-start`. The server function then fetches and
caches the policy at runtime; see
[runtime fetching](/docs/frameworks/tanstack-start/rendering#await-consent-in-the-loader).

## Resolve consent in the root route

Replace or merge `src/routes/__root.tsx`:

```tsx title="src/routes/__root.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

// Start's compiler keeps the handler and the bundled policy on the server.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);

const scripts = [
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	loader: async () => ({ consent: await getConsentState() }),
});
```

What each part does:

* **`getConsentState`** runs on the server. `createConsentStateHandler()`
  takes no options here: it uses `manifest()`, the default mode, and reads the
  backend URL and the snapshot from `consentManifest()`. It reads
  the `c15t` cookie and the location headers your host or CDN adds, such as
  `cf-ipcountry` or `x-vercel-ip-country`, then resolves this visitor's policy
  from the bundled snapshot, so the render never waits on Inth.
  [Geography headers](/docs/frameworks/tanstack-start/geography-headers) lists
  the headers it reads. Declare the `createServerFn()` call in your own module,
  as shown. Start's compiler finds server code by that call site and removes
  it from the browser build. The browser build's `c15t/generated` exports
  `snapshot: undefined`, so the policy never ships to the browser. A server
  function built inside a package does not work. In the browser build,
  `@c15t/tanstack-start/server` carries only `consentLoaderOptions`; its other
  helpers throw if browser code calls them.
* **The loader** awaits the result. `consentLoaderOptions` stops the loader
  from running again on client-side navigation, since the visitor's consent
  state does not change between routes.
* **`ConsentRoot`** creates the consent runtime from that state, so the server
  HTML and the first browser render match. The state carries the backend URL,
  the mode and the route prefix, so `ConsentRoot` needs only `state`. The
  browser sends its requests, including consent saves, straight to the
  backend URL the server function used, so saves reach the project the
  snapshot came from.
* **`scripts`** stays in this module. A server function can only return
  serializable data, and vendor loaders contain functions. PostHog waits for
  measurement permission, so your policy must include that category. Replace
  `phc_your_project_key` with your PostHog project key; PostHog uses its EU
  host, so add `region: 'us'` for a US project. Remove any other PostHog
  loader from your app so PostHog loads once.
* **No stylesheet** is linked. `ConsentBanner` renders its rules into the
  server HTML, and `ConsentDialog` adds its own when it opens.

## Gate your own features

Read a category's permission with `useConsent` from `c15t/tanstack-start`:

```tsx title="src/components/marketing-banner.tsx"
import { useConsent } from 'c15t/tanstack-start';

export function MarketingBanner() {
	return useConsent('marketing') ? <aside>Spring sale</aside> : null;
}
```

`useConsent` returns the permission right now. Under an opt-out policy it can be
`true` before the visitor has chosen anything. Read
[how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
before you record or report choices. For iframes, use `ConsentGate`; see
[scripts and embeds](/docs/frameworks/tanstack-start/scripts).

## Check that it works

Build the app with `vite build`, start the production server, and open the site
in a private window with DevTools open on the Network tab. Test under a policy
that asks for a choice, such as an EU opt-in policy. Your host must send a
country header; locally, add `country: 'DE'` to the `createConsentStateHandler`
options for the test only.

1. **Server HTML.** View the page source. It contains an element with
   `data-testid="consent-banner-root"`.
2. **Before a choice.** There are no requests to `posthog.com`.
3. **Reject All.** The banner closes and the vendor requests stay absent.
4. **Reload and view source again.** The HTML no longer contains the banner,
   because the server read the stored rejection from the `c15t` cookie.
5. **Privacy settings.** The footer link opens the dialog with **Analytics** (the
   `measurement` category) and **Marketing** off. Turn on **Analytics** and
   save. PostHog's `array.js` loads.
6. **Turn Analytics off again.** The page reloads and PostHog does not load.

[Troubleshooting](/docs/frameworks/tanstack-start/troubleshooting) covers the
common failures. [Verify consent](/docs/guides/verify-consent) has the full
release checklist.

## Next steps

* [Rendering](/docs/frameworks/tanstack-start/rendering) for streaming, SPA mode,
  prerendering and a same-origin consent route.
* [Scripts and embeds](/docs/frameworks/tanstack-start/scripts) for more vendors,
  iframes and network blocking.
* [Customize](/docs/frameworks/tanstack-start/customize) for colors, fonts, layout
  and copy.
* [Components](/docs/frameworks/tanstack-start/components) and
  [hooks](/docs/frameworks/tanstack-start/hooks).
* The runnable app in `examples/tanstack-start` of the
  [c15t repository](https://github.com/c15t/c15t) contains this setup.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/tanstack-start/rendering
Choose how a TanStack Start app resolves consent, with an awaited or streamed root loader, a same-origin consent route, or SPA mode, prerendered pages and static hosting.

## Pick your rendering path

Rendering choices change `src/routes/__root.tsx`. The recommended build-time
manifest also adds a Vite plugin; the same-origin path adds one server route. Pages, components and hooks stay the same.

|Your app|Root loader|Banner in the server response|Setup|
|--|--|--|--|
|Start server, recommended|Awaits consent from a build-time manifest|Yes|[Quickstart](/docs/frameworks/tanstack-start/quickstart)|
|Policy changes must apply without a rebuild|Awaits consent from a runtime manifest cache|Yes|[Runtime fetching](#await-consent-in-the-loader)|
|Runtime fetching on a serverless or often cold-started server|Streams consent|Yes, in a later chunk, before hydration|[Stream the page](#stream-the-page-while-consent-resolves)|
|Browser must only talk to your origin|Awaits consent|Yes|[Same-origin route](#keep-consent-requests-on-your-origin)|
|SPA mode, prerendered pages or a static host|None|No, the browser resolves consent|[No server render](#spa-mode-prerendered-pages-and-static-hosts)|

## Bundle the manifest during builds

The [quickstart](/docs/frameworks/tanstack-start/quickstart) and
`examples/tanstack-start` use this setup.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Add the plugin before `tanstackStart()`:

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/tanstack-start/build';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), tanstackStart(), viteReact()],
});
```

The plugin reads the backend URL from `backendURL`, or from
`VITE_C15T_BACKEND_URL`, then `VITE_INTH_PROJECT_URL`, when you leave
`backendURL` out. If `VITE_C15T_BACKEND_URL` is unset, the plugin sets it to the URL it used, so app code can read
`import.meta.env.VITE_C15T_BACKEND_URL` instead of repeating the URL.

The plugin fetches the policy during `vite build`, or in `vite dev` when the
server first loads it, and serves it to server code as `snapshot` from `c15t/generated`. In the browser
bundle, `snapshot` is `undefined`, so the policy never ships to the browser.
`createConsentStateHandler()` reads the snapshot and the backend URL from
there, as the
[quickstart root route](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route)
shows:

```ts title="src/routes/__root.tsx"
import { createServerFn } from '@tanstack/react-start';
import { createConsentStateHandler } from 'c15t/tanstack-start/server';

// Reads the backend URL and the policy consentManifest() downloaded.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);
```

`createConsentRoute()` reads them the same way.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

If the fetch fails, `vite build` stops. `vite dev` logs a warning instead,
and `snapshot` is `undefined`, so the server fetches and caches the policy at
runtime. To let a build continue the same way, set `onBuildError: 'runtime'`,
or run it with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="vite.config.ts"
consentManifest({ onBuildError: 'runtime' }),
```

For policy updates without a rebuild, pass
`mode: manifest({ source: 'runtime' })` to `createConsentStateHandler` and
keep the plugin, which still supplies the backend URL. See
[runtime fetching](/docs/frameworks/tanstack-start/rendering#await-consent-in-the-loader).

## Await consent in the loader

The [quickstart](/docs/frameworks/tanstack-start/quickstart) root loader awaits
the consent server function. The server reads the visitor's cookie and location
headers, resolves their policy from the build-time snapshot, and renders the
banner into the HTML. To apply policy updates without rebuilding, pass
`mode: manifest({ source: 'runtime' })` to `createConsentStateHandler`, with
`manifest` from `c15t/tanstack-start`. The server then fetches the manifest
and caches it in memory. Keep the plugin: it still supplies the backend URL.

`createConsentStateHandler({ mode })` takes `manifest()`, `hosted()` or
`offline()` from `c15t/tanstack-start`. They are plain data, so the state
carries the mode to `ConsentRoot`, and the browser loads only that mode's
code. A mode's `snapshot` stays on the server.
[Consent modes](/docs/concepts/modes) compares them.

With runtime fetching, the first request after a server starts has no cached
manifest and waits for
the backend. The server function waits at most 500 ms, then renders without
consent UI and lets the browser resolve consent. Later requests read the cached
manifest and add little time. Change the wait with `timeoutMs` in
`createConsentStateHandler`.

## Stream the page while consent resolves

With runtime fetching, return the pending server function call instead of
awaiting it. TanStack Router streams the promise to the browser and
`ConsentRoot` accepts it as `state`. This root fetches the manifest at
runtime, and its loader does not await:

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

import { scripts } from '../scripts';

// Declare the server function in your own module. Start's compiler splits
// the server code out of the browser bundle at this call site.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	// Not awaited: the page streams without waiting for consent, and
	// ConsentRoot accepts the pending promise.
	loader: () => ({ consent: getConsentState() }),
});
```

The response starts without waiting for the backend. What changes for the
visitor:

* The page streams at once. The banner follows in a later chunk of the same
  response, before hydration. Pass `streamBanner: false` in `ConsentRoot`'s
  `options` to mount it after hydration instead.
* Until then every optional category is denied, so gated scripts and embeds
  stay blocked. A returning visitor's stored choice applies when the state
  arrives.
* If the backend does not answer in time, the promise resolves to the cookie
  and header state and the browser resolves consent itself.

Stream when a slow or unreachable backend must never delay your page, for
example on serverless hosts where many requests start with an empty manifest
cache. Keep the awaited loader when the banner should arrive with the page.

## Keep consent requests on your origin

By default the browser calls your backend URL directly. To keep every consent
request on your own origin, mount the consent route:

```ts title="src/routes/api/c15t/$.ts"
import { createFileRoute } from '@tanstack/react-router';
import { createConsentRoute } from 'c15t/tanstack-start/api';

export const Route = createFileRoute('/api/c15t/$')({
	server: { handlers: createConsentRoute({ proxy: true }) },
});
```

Then give the server function the route's prefix, and `proxy: true` so the
browser saves through the route too:

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

import { scripts } from '../scripts';

// Declare the server function in your own module. Start's compiler splits
// the server code out of the browser bundle at this call site. The browser
// sends init and saves to the consent route in src/routes/api/c15t/$.ts.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler({ proxy: true, routePrefix: '/api/c15t' })
);

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	loader: async () => ({ consent: await getConsentState() }),
});
```

What the route serves:

|Request|Handled by|
|--|--|
|`GET /api/c15t/init` or `GET /api/c15t`|The route, from the bundled manifest, for this request's location, language and privacy signal|
|`GET /api/c15t/manifest`|The route, serving the bundled manifest|
|`POST /api/c15t/subjects` and other consent paths|Forwarded to your backend because `proxy: true`|
|Any other path|`404`, so the route is never an open proxy|

Keep these details right:

* `createConsentStateHandler` keeps the absolute backend URL from
  `consentManifest()` for its own requests. It never fetches under
  `routePrefix`, so the render cannot call its own route.
* `routePrefix` puts the prefix on the state, so `ConsentRoot` sends the
  browser's init to `/api/c15t/init` and binds each save to the policy it
  resolved. It also makes the page load IAB vendor lists through the route.
  It means the same as Next.js `defineConsentConfig({ routePrefix })`, and
  like there it has no default. `'/'` throws
  `` @c15t/tanstack-start: `routePrefix` can't be '/': a consent route at the site root would catch every page. Use a path such as '/api/c15t'. ``
  when the handler is created. An empty string throws too, because it isn't
  a path that starts with `/`. To run without a consent route, leave
  `routePrefix` out.
* `proxy: true` on `createConsentStateHandler` sends saves through the route,
  like Next.js `defineConsentConfig({ proxy: true })`. It needs `routePrefix`,
  and throws
  `` @c15t/tanstack-start: `proxy` sends saves through the consent route, so it needs `routePrefix`. ``
  without it. With `hosted({ backendURL })`, the browser still goes through
  the route; only the server asks that URL, so pass the same URL to
  `createConsentRoute({ backendURL })`. To send only init through the route
  and keep saves going straight to your backend, drop `proxy: true` from
  both and keep `routePrefix`.
* The proxy forwards the visitor's user agent, language, origin and location
  headers so the backend's firewall sees a normal visitor. Set
  `trustForwardedHeaders: true` on `createConsentRoute` only when your
  host overwrites `x-forwarded-for`, as Vercel and Cloudflare do. Otherwise a
  visitor could send a false IP address to your backend.

## SPA mode, prerendered pages and static hosts

A prerendered page is the same HTML for every visitor, so it cannot contain one
visitor's consent. Drop the loader, pass an empty `state`, and let the browser
resolve consent from the backend URL `consentManifest()` read:

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
	consentPrefetchHead,
} from 'c15t/tanstack-start';

import { scripts } from '../scripts';

const backendURL =
	import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://your-project.inth.app';

// No loader: the HTML is built ahead of time, so the browser resolves
// consent after it loads, from the backend URL consentManifest() read.
const RootComponent = () => (
	<html lang="en">
		<head>
			<HeadContent />
		</head>
		<body>
			<ConsentRoot state={{}} scripts={scripts}>
				<Outlet />
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
			<Scripts />
		</body>
	</html>
);

export const Route = createRootRoute({
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
		// Optional: start the /init request while the browser parses <head>.
		...consentPrefetchHead({ backendURL }),
	}),
});
```

* `state={{}}` means no server state. The page renders without consent UI and
  every optional category stays denied until the browser has the policy.
  `ConsentRoot` takes the backend URL from `consentManifest()`; without the
  plugin, an empty state throws, because there is no backend to ask. Pass
  `state={{ mode: offline() }}` to resolve without one.
* The browser sends its `/init` request straight to your backend URL, so the
  host needs no server route or server function. Add the site's origin to
  your Inth project's trusted origins.
* `consentPrefetchHead` is optional. It adds an inline script to `<head>` that
  starts the `/init` request before the app's JavaScript loads, and
  `ConsentRoot` uses that response instead of sending its own.

Drop the consent loader from a prerendered root. A loader that stays anyway
is safe: while TanStack Start prerenders (`TSS_PRERENDERING`),
`resolveConsent` treats the render as shared. It reads no cookie or location
header, returns no stored consent, clock or GPC signal, and makes no manifest
request, so no build-time state is baked into the HTML. Pass `shared: true`
to force the same for other HTML you cache for every visitor. To prerender
every page, configure the Vite plugin as
`tanstackStart({ prerender: { enabled: true } })` and serve the output as
static files. SPA mode renders the same root route
into its shell.

`c15t/tanstack-start/static` is a lower-level alternative that bundles the
manifest at build time. `createStaticConsentResolver({ manifest, geoURL })`
gives first paint the manifest's unknown-location policy, its fallback rule
or else its default rule, then the visitor's regional policy once `geoURL`
answers. You write the consent transport yourself, and new policy needs a
rebuild. A manifest with neither rule resolves to a failed
`insufficient-inputs` result.

## Run on hosts that stop work after the response

After a render, the server function reports the visitor's session to the
backend in the background. With runtime fetching, the manifest cache also
refreshes in the background after its `s-maxage`. Some serverless runtimes
stop background work once the response is sent. Pass your
platform's `waitUntil` as `onBackgroundRevalidate` to
`createConsentStateHandler` and `createConsentRoute` so that work
finishes. The promise never rejects.

## Check the rendering path

1. **View the page source** in a private window under a policy that asks for a
   choice. An awaited loader includes an element with
   `data-testid="consent-banner-root"`, and so does a streamed loader. A
   prerendered page does not.
2. **Filter DevTools Network by `subjects`** and reject. The `POST` goes to
   `/api/c15t/subjects` on your origin with the same-origin route, and to your
   backend URL otherwise.
3. **Vendor requests** stay absent until you allow their category, on every
   path.

# Scripts
URL: https://c15t.com/docs/frameworks/tanstack-start/scripts
Load vendor scripts by consent category in a TanStack Start app with ConsentRoot, and clear stored data or reload the page when a visitor withdraws consent.

## Register vendor scripts

Pass vendor loaders to `ConsentRoot` through its `scripts` prop. `ConsentRoot`
loads each script in the browser when its category is allowed and removes it
when the category is denied. The [quickstart](/docs/frameworks/tanstack-start/quickstart)
registers PostHog in the root route:

```tsx title="src/routes/__root.tsx"
const scripts = [
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

and passes the array to `ConsentRoot`:

```tsx title="src/routes/__root.tsx"
<ConsentRoot state={consent} scripts={scripts}>
```

To share the array with other modules, move it to its own file, such as
`src/scripts.ts`, and import it in the root route.

Import vendor helpers in route modules, not in a server function. A server
function's return value must be serializable, and vendor loaders contain
functions. Scripts only load in the browser, so importing them in the root
route adds nothing to the server HTML.

Each helper from `@c15t/integrations` sets its own category and a stable `id`.
Remove every other loader for the same vendor, such as a `scripts` entry in a
route's `head()` or an SDK you initialize at module level, so the vendor loads
once and only through c15t. [Integrations](/docs/integrations/overview) lists
every helper, and [building integrations](/docs/integrations/building-integrations)
covers a vendor without one.

## What happens when consent changes

* **Allowed.** The script loads, or its SDK starts, the first time its category
  is allowed. With an awaited root loader, a returning visitor's allowed
  scripts start right after hydration.
* **Denied later.** The script element is removed. Code that already ran keeps
  running, so after the visitor turns off a category they had allowed, the page
  reloads once the save finishes. Set `reloadOnConsentRevoked: false` in
  `ConsentRoot`'s `options` only if every gated vendor stops itself.
* **`alwaysLoad` helpers.** Some integrations, such as the Google Consent Mode
  helpers by default, load before consent and pass the visitor's choice to the
  vendor. Read the vendor's guide; a category on a script does not always mean
  zero requests.

## Embeds and other requests

Scripts cover vendor code c15t loads for you. For the rest:

* [Embeds](/docs/frameworks/tanstack-start/embeds) keeps iframes out of the
  page with `ConsentGate` or the iframe blocker.
* [Network blocker](/docs/frameworks/tanstack-start/network-blocker) holds
  `fetch` and XHR calls that match a rule until their category is allowed.

## Clear stored data after revocation

Removing a script does not delete the cookies or storage entries it wrote. Pass
`clearOnRevocation` to `ConsentRoot` to delete the entries you list for each
category when it is denied. `ConsentRoot` reads it once, when it mounts.
[Clear on revocation](/docs/frameworks/tanstack-start/clear-on-revocation) covers
configuration and browser limits.

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Pass
`vendors` to `ConsentRoot`. Helpers from `@c15t/integrations` already carry
their vendor slug. See [vendor consent](/docs/frameworks/tanstack-start/vendor-consent).

## Check the scripts

Open DevTools Network in a private window, filter by each vendor's domain and
reload.

1. Before a choice under an opt-in policy, no vendor script loads. The page
   source has no vendor `<script>` tags.
2. Allow one category. Only that category's vendors load.
3. Turn the category off. The page reloads and the vendor stays absent.
4. Reload again. The rejection holds, and the server HTML shows no banner.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/tanstack-start/embeds
Keep YouTube videos, maps and other iframes out of a TanStack Start page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentRoot.

## Pick a method

|Method|Use it when|
|--|--|
|`ConsentGate`|You render the iframe in a React component and want a placeholder until the visitor allows its category.|
|The iframe blocker|The iframe comes from HTML you do not render with React, such as CMS or Markdown content.|

Both keep the iframe's `src` out of the page until the category is allowed, so
the embed's host receives no request before consent.

## Gate an embed with ConsentGate

Wrap the iframe in `ConsentGate` in any route under the root route that
mounts `ConsentRoot`:

```tsx title="src/components/video-embed.tsx"
import { ConsentDialogLink, ConsentGate } from 'c15t/tanstack-start';

export const VideoEmbed = () => (
	<ConsentGate
		category="measurement"
		placeholder={
			<div>
				<p>
					Allow measurement to load this YouTube video. No video request is sent
					before permission.
				</p>
				<ConsentDialogLink>Open privacy settings</ConsentDialogLink>
			</div>
		}
	>
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			allowFullScreen
		/>
	</ConsentGate>
);
```

The server HTML contains the placeholder, never the iframe, unless the root
loader resolved measurement as allowed. The placeholder shows a message and a
[`ConsentDialogLink`](/docs/frameworks/tanstack-start/components/consent-dialog-link)
until then. When the visitor withdraws measurement, React removes the iframe.

Pick the category that matches what the embed does. The example uses
measurement for YouTube because its player measures views. A map or chat
widget usually belongs under functionality or experience.
[ConsentGate](/docs/frameworks/tanstack-start/components/consent-gate)
documents the built-in placeholder and every prop.

## Gate an iframe with the iframe blocker

`ConsentRoot` runs the iframe blocker in the browser by default. Give an
iframe `data-src` instead of `src`, and a `data-category`:

```html title="Markup from your CMS"
<iframe
  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
  data-category="functionality"
  title="Store map"
></iframe>
```

The server HTML has no `src`, so nothing loads before hydration. After
hydration, c15t sets `src` from `data-src` when the category is allowed and
removes `src` when the category is withdrawn. It watches the page, so iframes
added by client-side navigation are handled too. Add `data-vendor` with a
vendor ID to also block the iframe while the visitor has turned that vendor
off.

To turn the blocker off, set `iframeBlocker: false` in `ConsentRoot`'s
`options`.

## Verify the embeds

Open the production build in a private window with DevTools open, under a
policy that asks for consent.

1. View the page source. No iframe has a `src` pointing at
   `youtube-nocookie.com` or `google.com/maps`, and the Network panel shows no
   request to them.
2. Allow the embed's category and save. The iframe loads.
3. Withdraw the category and save. The page reloads without the embed.

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover sizing and titles.

# Network blocker
URL: https://c15t.com/docs/frameworks/tanstack-start/network-blocker
Hold fetch and XMLHttpRequest calls in a TanStack Start app until their consent category is allowed, with networkBlocker rules on ConsentRoot.

## Add rules

Pass `networkBlocker` rules to `ConsentRoot` to stop `fetch` and
`XMLHttpRequest` calls to a domain until its category is allowed. Use it as a
backstop for beacons an SDK sends itself. Load vendor SDKs through
[`scripts`](/docs/frameworks/tanstack-start/scripts) first, so they do not run
at all before consent.

```tsx title="src/routes/__root.tsx"
const networkBlocker = {
	rules: [
		{
			id: 'google-analytics',
			domain: 'google-analytics.com',
			category: 'measurement',
		},
		{
			id: 'meta-pixel',
			domain: 'facebook.com',
			pathIncludes: '/tr',
			category: 'marketing',
		},
	],
};

<ConsentRoot
	state={consent}
	scripts={scripts}
	networkBlocker={networkBlocker}
>
```

The blocker runs in the browser only. It does not see requests your server
functions or server routes make.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The provider holds matching requests from its first render in the browser,
before any of its children render or run effects. That covers requests from
child components, including their mount effects, and from effects in
components rendered next to the provider. The blocker module itself loads
after mount and decides each held request. Apps without `networkBlocker` do
not download it.

The standalone `useNetworkBlocker` hook works the same way from the first
render of the component that calls it. That render patches `fetch` and
`XMLHttpRequest`. If React throws the render away and never commits it, the
hold ends after 10 seconds. Nothing checked consent for the requests it held,
so they fail the way the blocker fails a blocked request: a 451 response for
`fetch`, a failed XHR. The same happens when the component unmounts before
the blocker loads.

While consent is unknown, a matching request that would be blocked waits
instead of failing. Consent is unknown until the policy has loaded, which is
also when a returning visitor's stored choice takes effect. The request is
then sent if the choice allows it and blocked otherwise. If the policy fails
to load, optional categories stay denied and waiting requests are blocked.
If the policy request never finishes, they keep waiting and are never sent.

A synchronous XHR cannot wait. Before the blocker module has loaded, a
matching one throws a `NetworkError` from `send()`. After that, one that
consent does not allow yet is blocked.

## What the network blocker cannot stop

The blocker only sees requests made after the provider starts rendering in
the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:

* Code that runs before the provider renders: inline scripts in the HTML,
  third-party tags in `<head>`, scripts loaded before hydration (such as
  `next/script` with `beforeInteractive`), and client modules that evaluate
  earlier. Webpack builds evaluate a route's client component modules when
  its chunk loads, so their top-level code runs first. Turbopack evaluates a
  client component module when its first element renders, which inside the
  provider is after blocking starts.
* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
  provider rendered.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` or `<iframe>` elements, web workers and service
  workers.
* With the standalone `useNetworkBlocker` hook instead of the provider
  option, requests sent before the component that calls it renders.
  Blocking starts in that component's first render, not the provider's.

Keep tracking calls out of that window:

* Send them from an effect or an event handler, never at module top level.
* Load vendor SDKs through `scripts` instead of a `<script>` tag or
  `next/script`, so they wait for consent before they run at all.
* Check `useConsent('measurement')` (or the category you need) before you
  call a vendor from your own code, and treat the blocker as a backstop.

## Verify the blocked requests

Open DevTools Network in a private window, under a policy that asks for
consent.

1. Before a choice, requests matching a rule are absent, and the console logs
   each blocked request.
2. Allow the rule's category and save. Matching requests go out.
3. Reject, reload, and check that they stay absent.

# Vendor consent
URL: https://c15t.com/docs/frameworks/tanstack-start/vendor-consent
Let visitors allow a category such as marketing in a TanStack Start app and still turn off one vendor in it, with the vendors prop on ConsentRoot and useVendorAllowed.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in the root route, using the `vendor`
slug each script already carries:

```ts title="src/routes/__root.tsx (partial)"
import type { Vendor } from 'c15t';

const vendors: Vendor[] = [
	{
		id: 'x-pixel',
		name: 'X Pixel',
		category: 'marketing',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];
```

Then pass them to `ConsentRoot` in the same module:

```tsx title="src/routes/__root.tsx (partial)"
<ConsentRoot
	state={consent}
	scripts={scripts}
	vendors={vendors}
>
```

`ConsentRoot` takes `vendors` as a top-level prop, not inside `options`.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. To render a component only while one
vendor is allowed, read `useVendorAllowed('youtube')` and render it when the
hook returns `true`. [Embeds](/docs/frameworks/tanstack-start/embeds) covers the iframe
blocker's `data-vendor` attribute.

## What the preference dialog shows

`ConsentDialog` and `ConsentWidget` list each declared vendor under its
category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`useVendorDraft()` from `c15t/tanstack-start` reads and stages vendor switches on the
same draft the category switches use, so one save records both.
`useVendorAllowed(id)` returns whether a vendor may run now: it is declared,
its category is allowed and the visitor has not switched it off.

```tsx title="src/components/x-pixel-switch.tsx (partial)"
import { useVendorAllowed, useVendorDraft } from 'c15t/tanstack-start';

const { vendors, setVendor, save } = useVendorDraft();
const xPixelAllowed = useVendorAllowed('x-pixel');

<input
  type="checkbox"
  checked={vendors['x-pixel'] ?? true}
  onChange={(event) => setVendor('x-pixel', event.target.checked)}
/>
<button type="button" onClick={() => save()}>Save</button>
```

`save()` resolves `{ ok: false }` without recording anything when the policy
or the vendor list changed under the edit. Call `reset()` to start again.
`useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
returns the recorded vendor decision, or `null` before the visitor made one.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/tanstack-start/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a TanStack Start app when that category is denied, with the clearOnRevocation prop on ConsentRoot.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns and pass them to the
`ConsentRoot` in `src/routes/__root.tsx`. When that category is denied, c15t
deletes them:

```tsx title="src/routes/__root.tsx (partial)"
import type { ClearOnRevocationConfig } from 'c15t';

const clearOnRevocation: ClearOnRevocationConfig = {
	measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
	marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
};

<ConsentRoot
	state={consent}
	scripts={scripts}
	clearOnRevocation={clearOnRevocation}
>
```

`ConsentRoot` takes `clearOnRevocation` as a top-level prop, not inside
`options`. It reads the value once, when it mounts; remount it to change the
list.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/tanstack-start/customize
Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a TanStack Start app with theme tokens, ConsentRoot options and component parts, and load the stylesheet yourself when you need to.

## Pick the right tool

|Change|Use|
|--|--|
|Brand colors, fonts, radius, spacing|[Theme tokens](#change-colors-fonts-and-radius)|
|Which button is filled or outlined|[`consentActions`](#style-the-action-buttons)|
|Banner shape and position|[`ConsentBanner` props or `presentation`](#change-the-banner-shape)|
|One element of a component|[Component parts](#style-one-component-part)|
|Light and dark colors, animation|[Dark mode and motion](#turn-on-dark-mode-and-change-motion)|
|Labels and languages|[Copy and translations](#change-the-copy)|
|Different markup entirely|[Headless](/docs/frameworks/tanstack-start/headless)|

`ConsentRoot` passes every option other than its own props through `options`
to the React provider, so the React styling options apply unchanged.
[Customization](/docs/customization/overview) explains how the choices relate.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## Load the stylesheet yourself

The [quickstart](/docs/frameworks/tanstack-start/quickstart) root route links
no c15t stylesheet. `ConsentBanner`, `ConsentDialog` and the other stock
components render the rules they use as `<style>` elements, in the server
HTML for the banner. The rules live in `@layer components`, so Tailwind 4
utilities override them without extra specificity.

Load the stylesheet yourself with Tailwind CSS 3, to put c15t's rules in a
named cascade layer. Set `styles: false` in `ConsentRoot`'s
`options`, so the components add no second copy, and link the stylesheet
through `head()`:

```tsx title="src/routes/__root.tsx (partial)"
import consentCss from 'c15t/tanstack-start/styles.css?url';

// In createRootRoute({ head: () => ({ links: [...] }) }):
{ href: consentCss, rel: 'stylesheet' }

// On ConsentRoot:
options={{ styles: false }}
```

If your app already has a global stylesheet, you can `@import` the c15t
stylesheet from it instead. Tailwind 3 needs a PostCSS plugin and the import
above the `@tailwind` directives;
[Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3) shows the
setup, and [stylesheets and CSS layers](/docs/customization/stylesheets)
explains the layer order.

## Change colors, fonts and radius

Colors, radii, shadows, typography and motion come from `--c15t-*` CSS
variables. Pick one of two ways to set them:

* **Set the variables in your CSS.** Nothing extra ships to the browser:

  ```css title="src/styles.css"
  :root {
    --c15t-primary: #2f6f4e;
    --c15t-primary-hover: #24563c;
    --c15t-text-on-primary: #fff;
    --c15t-radius-lg: 4px;
  }
  ```

* **Render `ConsentTheme` in the root route.** Use this when the theme lives in
  TypeScript. The root component renders on the server, so the `<style>`
  element is in the first HTML. It also runs in the browser, so the theme
  generator ships in the bundle.

  ```tsx title="src/consent-theme.ts"
  import { defineTheme } from 'c15t/tanstack-start';

  export const theme = defineTheme({
    colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
    radius: { lg: '4px' },
  });
  ```

  In the root component, render `<ConsentTheme theme={theme} />` from
  `c15t/tanstack-start` inside `<head>`, after `<HeadContent />`.

`ConsentTheme` outranks a plain `:root` rule, wherever each one loads. If you
use both, a variable set in both places takes the `ConsentTheme` value. Write
your CSS overrides on `:root:root` to beat it, or move the values into the
theme.

[Theme tokens](/docs/customization/tokens) lists every variable and scoping
tokens to one consent model.

## Style the action buttons

`consentActions` decides how each action looks. `default` applies to every
button, `primary` to the action the policy or your props mark primary, and
`accept`, `reject`, `customize` and `dismiss` to one action each. Pass it
through `ConsentRoot`'s `options`:

```tsx title="src/routes/__root.tsx"
<ConsentRoot
  state={consent}
  scripts={scripts}
  options={{
    theme: {
      consentActions: {
        primary: { variant: 'primary', mode: 'filled' },
      },
    },
  }}
>
```

`options.theme` only reads `consentActions` and slot styles. Tokens passed there
do nothing, and the provider logs a warning in development.

## Change the banner shape

`ConsentBanner` takes `variant` (`floating`, `bar`, `widget` or `wall`) and
`position`, such as `<ConsentBanner variant="bar" position="bottom" />`. To use
one shape everywhere, set `options.presentation.prompt` on `ConsentRoot`
instead. [ConsentBanner](/docs/frameworks/tanstack-start/components/consent-banner#variants)
lists every variant and position.

## Style one component part

Each component part is a slot that accepts any attribute its element takes,
such as `className` or `style`. Set slots in `ConsentRoot`'s
`options.components`, keyed by component and part:

```tsx title="src/routes/__root.tsx"
options={{
  components: {
    banner: {
      card: { className: 'rounded-none shadow-none' },
    },
  },
}}
```

[Component parts](/docs/customization/slots) lists the keys for every component
and when to drop the built-in styles with `noStyle`. The `ConsentGate`
placeholder's parts are `components['consent-gate'].root`, `.title` and
`.button`.
[Class names and CSS-in-JS](/docs/customization/class-names) covers CSS
Modules, vanilla-extract, StyleX and Emotion.

## Turn on dark mode and change motion

Pass `colorScheme` to `ConsentTheme` in the root route and the same value in
`options` on `ConsentRoot`. Leave it unset to follow a `dark` class on
`<html>`, and add dark colors with `theme.dark`.
[Dark mode](/docs/customization/dark-mode) covers each value and a dark first
paint.

`options.disableAnimation` on `ConsentRoot` turns off the banner and dialog
animations, and the same prop on `ConsentBanner` or `ConsentDialog` overrides
it for one surface. [Motion and animation](/docs/customization/motion) covers
the duration and easing tokens and reduced motion.

## Change the copy

Labels, descriptions and languages come from the translations in your Inth
project and from `options.i18n` on `ConsentRoot`. For the visitor's language,
`i18n.messages` replace the project's copy key by key, and keys you leave out
keep the project's wording.
[Copy and translations](/docs/customization/translations) shows the message
keys.

## Check the result

Clear site data and reload under a policy that shows a banner. View the page
source: with an awaited loader, the banner is in the HTML with your classes
and, if you render `ConsentTheme`, a `<style id="c15t-theme">` element. Open
the preference dialog too, since it reads the same tokens. Test a narrow
window, keyboard focus and contrast on the primary button.

# Translations
URL: https://c15t.com/docs/frameworks/tanstack-start/translations
Where c15t banner and dialog copy comes from in TanStack Start, how the server and browser pick the visitor's language, and how to override copy and switch languages from the root route.

## Where the copy comes from

The banner, dialog, widget and gate placeholder read their text from the
translations in your Inth project, or your self-hosted backend's
configuration. The policy carries the copy for the visitor's language. Edit
wording there first, so it changes without a deploy.

Code can override that copy in two places:

* `options.i18n` on `ConsentRoot` changes a message everywhere it appears.
* Text props on `ConsentBanner` change one banner.

[Copy and translations](/docs/customization/translations) lists the message
keys and explains how code messages combine with the project's copy.

## How c15t picks the language

In the [quickstart](/docs/frameworks/tanstack-start/quickstart) setup, the
root loader's `resolveConsent` reads the request's `Accept-Language` header.
It resolves the policy and its copy from the bundled manifest on the server, so
the banner in the first HTML is already in the visitor's language.

To override the header, set `language` in one of these places:

* `consentRequestMiddleware({ language })` in `src/start.ts` fixes one
  language for every request.
* `createConsentStateHandler({ language })` fixes one language for
  the root loader.
* `resolveConsent({ language })` from
  `c15t/tanstack-start/server`, called in your own server function, takes a
  different language per request, such as the locale from your URL.

When the browser resolves consent, as on
[prerendered and static pages](/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts),
the `/init` request carries the browser's own `Accept-Language` header.

When your project has no copy for the requested language, the backend
returns its fallback language.

The banner, dialog and widget set `dir` from the active language. Right-to-left
languages such as Arabic and Hebrew render with `dir="rtl"`, and a floating
banner you did not position yourself moves to the opposite side.

## Change the copy in code

Keep the messages in their own module:

```ts title="src/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/tanstack-start';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

Import it in `src/routes/__root.tsx` and pass it under `options` on
`ConsentRoot`:

```tsx title="src/routes/__root.tsx"
<ConsentRoot
  state={consent}
  scripts={scripts}
  options={{ i18n }}
>
```

The root route component renders on the server and again in the browser, so
both read the same module and your messages are already in the server HTML.
Import the module in the component. Do not return it from the loader or a
server function. Loader data is serialized for the browser, and it should
carry only the consent state.

For the visitor's language, your messages replace the project's copy key by
key. Keys you leave out keep the project's wording, and messages for other
languages are not applied. `ConsentRoot` reads `i18n` once, when it mounts. In
development it logs a warning if `i18n` changes later.

`i18n.locale` sets the language of the copy when no backend or server state
supplies one, as in offline mode. It defaults to `en`.

## Change one banner's copy

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. The props
replace the text in every language, so pass values in the page's language:

```tsx
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>;
```

## Switch the language at runtime

`useSetLanguage()` stores the new language, and `useInit()` resolves the policy
again, which fetches the copy for that language. Call both from your language
switcher:

```tsx title="src/components/language-switcher.tsx"
import { useInit, useSetLanguage, useSnapshot } from 'c15t/tanstack-start';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

Setting the language without calling `init()` changes nothing on screen. Your
`i18n` messages for the new language apply on top of the copy that arrives.
Render the switcher anywhere inside `ConsentRoot`.

If your site changes language through its own i18n library, run the same two
calls when its locale changes. To make the server HTML match too, pass the
locale to `resolveConsent` as `language`.

## Verify

1. Under a policy that shows a banner, request a page with
   `curl -H 'Accept-Language: de' <your-url>`. If your project translates
   German, the banner text in the HTML is German.
2. Open the page in the browser and check that a message you set in `i18n`
   shows in the banner.
3. Switch the language with your switcher. DevTools Network shows a new
   `/init` request, and the banner and dialog text change without a reload.

# Compose your own banner
URL: https://c15t.com/docs/frameworks/tanstack-start/compose
Build a TanStack Start consent banner from the ConsentBanner parts in c15t/tanstack-start, with your own markup and buttons, rendered inside ConsentRoot in the root route.

## When to compose

Compose the banner from its parts when you need its elements in a different
order, an element it does not have, or your design system's button in place
of c15t's. The parts keep the stock
behavior. They read the same policy, record the same choices and render the
same class names, so theme tokens and slots still apply.

Try the lighter tools first:

|Change|Use|
|--|--|
|Colors, type, radius, spacing|[Theme tokens](/docs/customization/tokens)|
|Classes or attributes on one part|[Component parts](/docs/customization/slots)|
|Labels and languages|[Copy and translations](/docs/customization/translations)|
|Shape, position, button order|`ConsentBanner` props such as `variant`, `position`, `layout` and `primaryButton`|
|Different markup or order|Compound parts, on this page|
|Entirely custom UI and behavior|Headless hooks|

For a banner that shares nothing with the stock markup, use the
[headless hooks](/docs/frameworks/tanstack-start/headless). For one changed
class, token or prop, see [customize](/docs/frameworks/tanstack-start/customize).

## Compose the banner

`CookieBanner` keeps the stock card, title and copy, and renders each action
the policy asks for as your design system's button. `BrandButton` stands in
for that button:

```tsx title="src/components/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

```tsx title="src/components/cookie-banner.tsx"
import { ConsentBanner, useTranslations } from 'c15t/tanstack-start';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

`c15t/tanstack-start` re-exports every `c15t/react` component, so
`ConsentBanner` and its parts come from the same import as `ConsentRoot`.

The parts read the provider that `ConsentRoot` renders. In the
`src/routes/__root.tsx` file from the
[quickstart](/docs/frameworks/tanstack-start/quickstart), import
`CookieBanner` from `../components/cookie-banner` and render it in place of
`ConsentBanner`, next to `ConsentDialog`:

```tsx title="src/routes/__root.tsx (partial)"
<ConsentRoot state={consent} scripts={scripts}>
	<Outlet />
	<CookieBanner />
	<ConsentDialog />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</ConsentRoot>;
```

The root route renders on the server, and `CookieBanner` renders there with
it, the same as the stock banner.

`ConsentBanner.Root` renders only while the banner is the active surface,
the same condition the stock `ConsentBanner` uses, so `CookieBanner` needs
no visibility logic. It renders nothing before a policy resolves and closes
once the visitor chooses.

`ConsentBanner.PolicyActions` renders the actions the policy asks for, in
the policy's order and groups, with any rights links, such as "Do not sell
or share my data", before them. For each action it calls `renderAction`
with the action name and the props c15t would give the stock button:
`key`, `consentAction`, `isPrimary`, and a `style` that stretches the
buttons when the layout fills the row. Return an element to replace that
button, or `null` to keep the stock one. The banner never renders `save`,
so the example skips it.

Each action part gets those props plus `asChild` and `noStyle`. `asChild`
renders `BrandButton` in place of c15t's `button`, and `noStyle` drops
c15t's button classes so they do not compete with yours. The part keeps its
behavior. Accept saves every category and Reject saves only necessary, and
both close the banner. Customize opens the preference dialog. Dismiss
records that the visitor saw a notice, without recording a choice.

With `asChild`, the part's default label does not render, because your
element keeps its own children. `useTranslations()` returns the labels the
stock buttons use, in the visitor's language.

Under a notice, the policy asks only for an acknowledgement, so
`PolicyActions` passes `dismiss` and `CookieBanner` renders one button. If
you place `ConsentBanner.AcceptButton` and `ConsentBanner.RejectButton`
yourself instead, they render under every policy, including one that owes
only a notice.

## Banner parts

Every part is a property of `ConsentBanner`. All parts except `Root` and
`PolicyActions` forward their ref, and they accept the attributes of the
element they render plus `noStyle`.

|Part|Renders|Props|
|--|--|--|
|`Root`|The `div` that positions the banner, only while the banner shows. Renders the backdrop itself when blocking.|`variant`, `position`, `blocking`, `models` (default `['opt-in', 'opt-out']`), `uiSource` (default `'banner'`), `noStyle`, `disableAnimation`|
|`Card`|The visible `div`, labelled with the title. `role="region"`, or `role="dialog"` with `aria-modal="true"` and a focus trap when blocking.|`asChild`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`Title`|An `h2` with the translated title, or the notice title under a notice.|children replace the text|
|`Description`|A `div` with the translated copy and the configured legal links.|`legalLinks`, `asChild`|
|`PolicyActions`|`Footer`, the rights links and the policy's action groups.|`renderAction`, children replace the rights links|
|`Footer`|A `div` for the actions.|`asChild`|
|`FooterSubGroup`|A `div` for one group of actions. `Actions` is an alias.|`asChild`|
|`AcceptButton`|A `button` that saves every category and closes the banner.|action button props|
|`RejectButton`|A `button` that saves only necessary and closes the banner.|action button props|
|`CustomizeButton`|A `button` that opens the preference dialog.|action button props|
|`DismissButton`|A `button` that acknowledges a notice.|action button props|
|`Rights`|A `div` with one `RightLink` per right the policy recommends, or nothing.|`rights`, `asChild`|
|`RightLink`|A `button` styled as underlined text that opens the preference dialog.|`right` (`'opt-out'` or `'preferences'`), `asChild`|
|`Overlay`|The backdrop of a blocking banner. `Root` already renders it, so do not add it.|none|

`Content` is an alias of `Card`.

The action buttons take `asChild`, `noStyle`, `consentAction`, `isPrimary`,
`variant` (`'primary'` or `'neutral'`), `mode` (`'filled'`, `'stroke'`,
`'lighter'` or `'ghost'`), `onClick` and any `button` attribute. Your
`onClick` runs before the action, and calling `event.preventDefault()` in
it skips the action. `consentAction` sets `data-action` and selects the
`theme.consentActions` entry. `PolicyActions` passes it for you, and
`DismissButton` sets it itself. A button you place yourself has no
`data-action` and no per-action theme until you pass `consentAction`.

`useConsentBannerSurface()` returns the `variant`, `position`,
`positionSource` and `blocking` that `Root` resolved, for your own elements
that depend on the banner's shape.

[ConsentBanner](/docs/frameworks/tanstack-start/components/consent-banner)
lists the stock banner's props, variants and data attributes.

## Render a part as your own element

`asChild` swaps the part's element for the one element you pass as its
child. `Card`, `Header`, `Description`, `Footer`, `FooterSubGroup`,
`Rights`, `RightLink` and the action buttons support it. `Root` and
`Overlay` ignore it, and `Title` always renders an `h2`, so a child you pass
to `Title` ends up inside that `h2`. `Description` with `asChild` drops the
inline legal links.

The part merges its props onto your element:

* The part's props apply first, and props you set on the child win.
* `className` keeps both, the part's classes first.
* `style` merges, and your values win per property.
* Event handlers both run, yours first. On an action button, calling
  `event.preventDefault()` in yours skips c15t's action.
* The part's ref and your child's ref both receive the DOM node.
* Your child keeps its own children. The part's default content, such as a
  button label, does not render.

Your component has to pass its ref and every prop it does not use to its
DOM element. Otherwise c15t's click handler, `data-action` and focus
handling never reach the page. The `BrandButton` in the example does both.
Pass exactly one element. Text, a fragment or several children render
nothing.

Action buttons pass no `type` under `asChild`, so give your button a
default of `type="button"`. Without it, the button submits a surrounding
form.

## Compose the preference dialog

`ConsentDialog` has parts too. Compose it when the dialog needs a different
header or footer, and keep `ConsentWidget` inside `Content`. The widget
owns the category switches, the draft and the policy's Save, Accept and
Reject buttons.

|Part|Renders|Props|
|--|--|--|
|`Root`|The dialog in a portal on `document.body`, with its open state, backdrop, focus trap, scroll lock and Escape to close.|`open`, `models` (default `['opt-in', 'opt-out', 'none']`), `overlay` (a node, or `false` for none), `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`, `uiSource` (default `'dialog'`)|
|`Card`|The panel `div`.|`className`, `style`, `noStyle`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`HeaderTitle`|An `h2` with `id="consent-dialog-title"`.|children replace the text|
|`HeaderDescription`|A `div` with `id="consent-dialog-description"` and the legal links.|`legalLinks`, `asChild`|
|`Content`|A `div` for `ConsentWidget`.|`asChild`|
|`Footer`|A `div` with the branding tag, unless you pass children or `hideBranding`.|`hideBranding`, `asChild`|
|`ConsentCustomizationCard`|The stock card with all of the above.|`legalLinks`, `hideBranding`, `noStyle`|
|`Overlay`|The backdrop. `Root` already renders it.|none|

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Render the composed dialog in place of `ConsentDialog`, next to your
banner. The stock `ConsentDialog` downloads its code when the dialog first
opens. The parts load that same code when they first render, and a
composed `ConsentDialog.Root` renders on every page, so the code downloads
with the page. `c15t/react/components/consent-dialog` exports the same
parts without the deferral.

`ConsentWidget` has parts as well, such as `ConsentWidget.Root`,
`ConsentWidget.Accordion`, `ConsentWidget.AccordionItems` and
`ConsentWidget.PolicyActions`, for a preference list with your own layout.

`c15t/tanstack-start` exports `ConsentDialog` and `ConsentWidget` with their
parts. It has no `components/consent-dialog` subpath, so import the parts
without the deferral from `c15t/react/components/consent-dialog`.
[ConsentDialog](/docs/frameworks/tanstack-start/components/consent-dialog)
and [ConsentWidget](/docs/frameworks/tanstack-start/components/consent-widget)
list every part and its slots.

## Keep the banner accessible

The stock parts carry the roles, labels and focus handling. A composed
banner keeps them as long as you keep the parts that own them:

* `Card` owns the banner's role, label and focus trap. With `asChild`, your
  element receives them, so do not set `role` or `aria-modal` on it.
* `Card` takes its `aria-label` from the translated title, not from text you
  pass to `Title`. If you change the title text, pass the same text as
  `aria-label` on `Card`.
* To attach your own ref to `Card`, pass a ref object from `useRef`. A
  callback ref turns off the focus trap on a blocking banner.
* Render each action as a real `button`. Its text is the accessible name,
  so keep the label inside your button.
* Keep a way to reopen preferences after the banner closes, such as the
  `ConsentDialogLink` in your footer.
* The dialog's `Root` names the panel with the ids on `HeaderTitle` and
  `HeaderDescription`. Keep both parts, or put `id="consent-dialog-title"`
  and `id="consent-dialog-description"` on your own heading and copy.

## Keep theme tokens and slots working

The parts render the stock class names, and the banner's `Root` renders
c15t's rules, so c15t's styles and `--c15t-*` tokens style a composed
banner the way they style the stock one.

Slots in the provider's `options.components` reach each part by key:
`banner.root`, `banner.card`, `banner.header`, `banner.title`,
`description.banner`, `banner.footer` and `banner.actions`,
`banner.actionGroup`, `banner.rights` and `banner.rightLink`. A class you
pass to a part joins its stock and slot classes. The stock `ConsentBanner`
also renders the `banner.cardShell` wrapper and the "Secured by" tag, and a
composed banner renders neither.

Action buttons read the `button.primary` or `button.secondary` slot and the
`theme.consentActions` entry for their `consentAction`. `noStyle` on a
button drops c15t's button classes and keeps slot classes. `noStyle` on
`Root` removes the built-in styling from every part inside it.

[Customize](/docs/frameworks/tanstack-start/customize) shows where to set
tokens, slots and `consentActions` through `ConsentRoot`'s `options`.

## Check the result

1. Clear site data and reload. The composed banner appears with your
   buttons. In DevTools Elements, each action is your element with a
   `data-action` attribute. In DevTools Network, no optional vendor request
   has fired.
2. Tab through the banner. Every action is reachable in the policy's order
   and shows a focus ring. Press Enter on Customize, and the preference
   dialog opens.
3. Click Reject all. The banner closes. Reload, and it stays closed with
   the vendors still blocked.
4. Reopen preferences from your footer link. The optional categories are
   off. Allow one, save, and only that category's vendors load.
5. If your policies include a notice region, test it too. The banner shows
   your acknowledgement button and no Accept or Reject.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Headless
URL: https://c15t.com/docs/frameworks/tanstack-start/headless
Build your own consent banner markup in a TanStack Start app with the c15t/tanstack-start/headless hooks inside ConsentRoot.

## When to go headless

The pre-built banner and dialog cover most designs through props, slots, and
the stylesheet. Go headless when your markup has to be something else
entirely: a design system component, a native sheet, or a layout the compound
parts cannot express.

Headless code owns the rendered controls, so it also owns the compliance
outcome. The hooks hand you the actions a policy requires, the rights it must
keep reachable, and diagnostics when your presentation drops one. Render from
those lists rather than from a fixed set of buttons, and a site that later adds
a notice region keeps working without a code change.

## Render your own banner

`c15t/tanstack-start/headless` re-exports the headless hooks from
`c15t/react/headless`. They read the runtime from `ConsentRoot`. Render your
component inside `ConsentRoot` in place of `ConsentBanner`, and keep
`ConsentDialog` and a preferences link:

```tsx title="src/components/consent-banner.tsx"
import {
	useHeadlessConsentUI,
	useTranslations,
} from 'c15t/tanstack-start/headless';

const ACTION_LABELS = {
	accept: 'acceptAll',
	reject: 'rejectAll',
	customize: 'customize',
	dismiss: 'acknowledge',
	save: 'save',
} as const;

export function Banner() {
	const { banner, performAction, openDialog } = useHeadlessConsentUI();
	const { common, rights } = useTranslations();

	if (!banner.isVisible) {
		return null;
	}

	return (
		<section role="region" aria-label="Privacy">
			{banner.preferenceControls.map((right) => (
				<button key={right} type="button" onClick={openDialog}>
					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
				</button>
			))}
			{banner.actionGroups.map((group) => (
				<div key={group.join('-')}>
					{group.map((action) => (
						<button
							key={action}
							type="button"
							data-primary={banner.primaryActions.includes(action) || undefined}
							onClick={() => performAction(action)}
						>
							{common[ACTION_LABELS[action]]}
						</button>
					))}
				</div>
			))}
		</section>
	);
}
```

With an awaited root loader, `banner.isVisible` is already `true` on the server
for a visitor who owes a choice, so your banner is in the first HTML like the
stock one. With a streamed loader or a prerendered page it turns `true` after
hydration.

Check for a policy before rendering other custom surfaces. `useModel()` returns
`null` while no policy has resolved and `'none'` under a policy that owes no
consent UI.

`banner.actionGroups` is the resolved layout: reject and accept share a group
at equal prominence, and the rest follow. `banner.orderedActions` is the same
list flattened. Under a notice the only action is `dismiss`, and
`banner.preferenceControls` recommends additional buttons for opening
preferences. Under a notice it contains `opt-out`, which selects the
"Do not sell or share my data" label. The example renders that button and
an "OK" button. Both controls keep their own command: opening
preferences and dismissing the notice.

The list is a rendering helper. It does not establish that your UI implements
all policy rights. Provide disclosure and persistent preferences access.

`performAction` saves all categories for `accept`, none for `reject`, the
current draft for `save`, records a dismissal for `dismiss`, and opens the
preference center for `customize`. `banner.diagnostics` reports when a host
layout drops a required action or gives equivalent actions different
prominence. Review each diagnostic when configuring custom presentation.

`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
shape from `presentation.prompt`, so a headless surface can follow the same
bar, widget, or wall choice the pre-built banner would make, and can trap
focus and lock scroll exactly when `blocking` is true.

# Components
URL: https://c15t.com/docs/frameworks/tanstack-start/components
ConsentRoot and the consent banner, dialog, widget, links, gate and DevTools components a TanStack Start app imports from c15t/tanstack-start.

## Import from c15t/tanstack-start

`c15t/tanstack-start` exports `ConsentRoot` and re-exports every component and
hook from `c15t/react`. Import them from `c15t/tanstack-start` so your app has
one import path. They behave the same as in a React app, and render on the
server with the state the root loader resolved.

|Component|Renders|Reference|
|--|--|--|
|`ConsentRoot`|The consent runtime, seeded with the root loader's state|[Below](#consentroot)|
|`ConsentBanner`|The banner, when the policy asks for one|[ConsentBanner](/docs/frameworks/tanstack-start/components/consent-banner)|
|`ConsentDialog`|The preference dialog|[ConsentDialog](/docs/frameworks/tanstack-start/components/consent-dialog)|
|`ConsentWidget`|The preference controls inline in a page|[ConsentWidget](/docs/frameworks/tanstack-start/components/consent-widget)|
|`ConsentDialogLink`|A button that opens the dialog, for your footer|[ConsentDialogLink](/docs/frameworks/tanstack-start/components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens the dialog. `ConsentDialogTriggerToolbar` adds your own actions beside it|[ConsentDialogTrigger](/docs/frameworks/tanstack-start/components/consent-dialog-trigger)|
|`ConsentGate`|Its children only while a category is allowed|[ConsentGate](/docs/frameworks/tanstack-start/components/consent-gate)|
|`ConsentTheme`|A `<style>` element with your theme tokens|[Customize](/docs/frameworks/tanstack-start/customize)|
|`DevTools` from `c15t/react/devtools`|A development panel for consent state and scripts|[DevTools](/docs/frameworks/tanstack-start/components/dev-tools)|

Render every component inside `ConsentRoot`. Do not also mount
`ConsentProvider`; `ConsentRoot` already renders one.

## ConsentRoot

`ConsentRoot` wraps the app in the root route. It takes the state the root
loader resolved on the server and creates the consent runtime from it, so the
server HTML and the first browser render match. The
[quickstart](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route)
shows it in context.

|Prop|Purpose|
|--|--|
|`state`|Required. The loader's consent state, a promise of it for a [streamed loader](/docs/frameworks/tanstack-start/rendering#stream-the-page-while-consent-resolves), or `{}` for [pages without a server render](/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts)|
|`scripts`|Consent-gated vendor scripts. See [scripts and embeds](/docs/frameworks/tanstack-start/scripts)|
|`vendors`|Vendors listed under their category with their own switch|
|`networkBlocker`|Rules that hold `fetch` and `XMLHttpRequest` calls until their category is allowed|
|`clearOnRevocation`|Cookies and storage keys to delete when a category is denied|
|`persistence`|Stores the visitor's choice. On by default|
|`scriptLoader`|Options for the script loader module|
|`options`|Any other `ConsentProvider` option, such as `theme`, `i18n`, `presentation`, `callbacks`, `consentCategories`, `reloadOnConsentRevoked` or `preloadDialog`|

The state carries the backend URL, the mode and the route prefix you passed
to `createConsentStateHandler`, so `ConsentRoot` has no props for them. With
`state={{}}`, it takes the backend URL from `consentManifest()` and uses
`manifest()`. Without a backend URL from either, it throws, unless the mode is
`offline()`. `options.mode` replaces the state's mode: `manifest()`,
`hosted()` or `offline()` from `c15t/tanstack-start`, or a transport such as
`custom(transport)`.

`ConsentRoot` creates the runtime once, when it mounts, and ignores later
changes to `state`. Keep it in the root route so client navigation never
remounts it.

The root entry also exports `consentPrefetchHead` for pages without a server
render, and `buildPrefetchScript`, the script builder behind it.

## Server and other entry points

|Import|Exports|Use|
|--|--|--|
|`c15t/tanstack-start`|`manifest`, `hosted`, `offline`|The modes, as data for `createConsentStateHandler({ mode })`. See [consent modes](/docs/concepts/modes)|
|`c15t/tanstack-start/server`|`createConsentStateHandler`, `resolveConsent`, `consentLoaderOptions`, `mergeInitIntoConsentState`|Resolve the visitor's state in a server function. `createConsentStateHandler` takes `mode`, `routePrefix`, `proxy`, `snapshot` and the `resolveConsent` options|
|`c15t/tanstack-start/middleware`|`consentRequestMiddleware`|Read location, language and privacy headers on every request. See [geography headers](/docs/frameworks/tanstack-start/geography-headers)|
|`c15t/tanstack-start/api`|`createConsentRoute`|Serve `/api/c15t/*` from `src/routes/api/c15t/$.ts`|
|`c15t/tanstack-start/build`|`consentManifest`|Vite plugin that bundles the manifest at build time. See the [quickstart](/docs/frameworks/tanstack-start/quickstart#bundle-your-policy-at-build-time)|
|`c15t/generated`|`snapshot`, `backendURL`|The manifest and backend URL the plugin fetched. `snapshot` is `undefined` in the browser bundle|
|`c15t/tanstack-start/static`|`createStaticConsentResolver`, `loadStaticManifest`, `createStaticManifestModule`, `resolveUnknownLocationInit`|Lower-level helpers for a build-time manifest. See [rendering](/docs/frameworks/tanstack-start/rendering#spa-mode-prerendered-pages-and-static-hosts)|
|`c15t/tanstack-start/headless`|Headless hooks|[Custom markup](/docs/frameworks/tanstack-start/headless)|
|`c15t/tanstack-start/components/consent-dialog-link`|`ConsentDialogLink` only|A module that needs the link without loading the rest of the adapter|

`resolveConsent` is the function behind `createConsentStateHandler`. Call it
directly from a server route or middleware that already holds the `Request`,
and pass it as `request`. Import `server`, `middleware` and `api` only from
server code.

## IAB TCF components

Import `IABProvider`, `IABConsentBanner` and `IABConsentDialog` from
`c15t/react/iab`, render them inside `ConsentRoot` next to
`ConsentBanner` and `ConsentDialog`, and load
`c15t/tanstack-start/styles.css` and `c15t/tanstack-start/iab/styles.css`
with `styles: false`. The stock banner and dialog stay closed
under an IAB policy. See
[IAB TCF](/docs/frameworks/tanstack-start/iab).

# ConsentBanner
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-banner
Render the c15t consent banner in a TanStack Start app, set its variant and position, and override its labels.

## Render the banner

Render `ConsentBanner` once inside `ConsentRoot`, next to `ConsentDialog`. The
[quickstart](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route)
does this in the root route. With an awaited root loader, the banner is part of
the server HTML for visitors who owe a choice.

```tsx title="src/routes/__root.tsx"
import { ConsentBanner } from 'c15t/tanstack-start';

// Inside ConsentRoot:
<ConsentBanner variant="bar" position="bottom" />;
```

The banner renders what the active policy requires. A `choice` prompt shows
reject and accept at equal prominence, plus customize when the policy offers it.
A `notice` prompt shows an "OK" button and a "Do not sell or share my data"
button that opens preferences. A policy with `prompt: 'none'` renders nothing,
and so does a visitor whose policy has not resolved.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`title`|`ReactNode`|translation|Overrides the title. Under a notice the default is `cookieBanner.noticeTitle`.|
|`description`|`ReactNode`|translation|Overrides the description. Under a notice the default is `cookieBanner.noticeDescription`.|
|`acceptButtonText`|`ReactNode`|`common.acceptAll`|Accept label.|
|`rejectButtonText`|`ReactNode`|`common.rejectAll`|Reject label.|
|`customizeButtonText`|`ReactNode`|`common.customize`|Customize label.|
|`dismissButtonText`|`ReactNode`|`common.acknowledge`|Label of the notice acknowledgement.|
|`variant`|`PromptVariant`|`floating`|Shape of the prompt. See [Variants](#variants).|
|`position`|`PromptPosition`|per variant|Where the prompt sits. Must be valid for the variant.|
|`blocking`|`boolean`|`true` on `wall`|Backdrop, scroll lock, focus trap, and no outside dismissal, as one value.|
|`layout`|`ConsentBannerLayout`|policy default|Orders and groups actions. Required actions the layout omits are restored.|
|`primaryButton`|`ConsentBannerButton \|ConsentBannerButton[]`|`'customize'`|Which actions get the primary treatment. On a notice, dismiss is primary when it is the only action.|
|`direction`|`'row' \|'column'`|`'row'`|How action groups flow.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which configured legal links render inline.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`scrollLock`|`boolean`|unset|Deprecated. Use `blocking` to control scrolling, focus and backdrop together.|
|`trapFocus`|`boolean`|unset|Deprecated. Use `blocking`.|
|`disableAnimation`|`boolean`|`false`|Skips enter and exit animations.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Variants

The policy decides which actions the banner offers. The variant decides their
shape. Set `variant` on the banner, or `options.presentation.prompt` on
`ConsentRoot` for every banner. The prop wins.

|Variant|Positions|Default|
|--|--|--|
|`floating`|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|`top`, `bottom`|`bottom`|
|`widget`|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|`center`|`center`|

A `wall` blocks the page until the visitor answers. A notice never blocks, so a
notice `wall` falls back to `floating`. Every part is also available as
`ConsentBanner.<Part>` for custom layouts, such as `ConsentBanner.Root`,
`ConsentBanner.Card` and `ConsentBanner.PolicyActions`.
[Customize](/docs/frameworks/tanstack-start/customize) covers tokens and slots.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog
Open the c15t preference dialog in a TanStack Start app, reopen it from your own controls, and control blocking, focus and policy gating.

## Render the preference dialog

`ConsentDialog` is the modal preference center. Render it once inside
`ConsentRoot`, next to the banner. It opens when the banner's Customize button,
a `ConsentDialogLink`, a `ConsentDialogTrigger` or your own code makes `dialog`
the active surface:

```tsx title="src/components/privacy-menu-item.tsx"
import { useSetActiveUI } from 'c15t/tanstack-start';

export function PrivacyMenuItem() {
	const setActiveUI = useSetActiveUI();
	return (
		<button type="button" onClick={() => setActiveUI('dialog')}>
			Cookie preferences
		</button>
	);
}
```

Under an IAB policy the dialog stays closed; render `IABConsentDialog` as
described in [IAB TCF](/docs/frameworks/tanstack-start/iab). Provider options
such as `preloadDialog` go through `ConsentRoot`'s `options` prop.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`open`|`boolean`|follows the active surface|Controls the open state. When set, Escape and the dialog's own Save Settings, Accept All and Reject All buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed.|
|`showTrigger`|`boolean \|ConsentDialogTriggerProps`|`false`|Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'none']`|Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag in the card.|
|`uiSource`|`string`|`'dialog'`|Source identifier recorded with saves made from this dialog.|
|`scrollLock`, `trapFocus`|`boolean`|from `blocking`|Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.|
|`disableAnimation`|`boolean`|`false`|Skips the enter and exit animation of the backdrop and the card.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The dialog is a modal wrapper around the preference center. Its card has a
header with the title `consentManagerDialog.title` and the description
`consentManagerDialog.description` followed by the legal links, then the
same category accordion and Reject All, Accept All and Save Settings actions that
`ConsentWidget` renders, then the branding tag. It mounts through a portal
into `document.body` after hydration, so it is never part of the server
HTML.

Without an `open` prop, the dialog follows the active surface and opens while
it is `dialog`. These set that surface:

* The Customize button on a `ConsentBanner`, and the "Manage preferences"
  or "Do not sell or share my data" button a notice renders.
* `ConsentDialogLink` and `ConsentDialogTrigger`.
* The button in a `ConsentGate` placeholder.
* `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
  from `useHeadlessConsentUI()` on the headless subpath.

The component code is split into its own chunk, so it is not part of the
first page load. It renders nothing until that chunk is ready, and the
chunk downloads at the first of these:

* The browser's first idle period after the page's `load` event, while the
  banner is shown or a `ConsentDialogLink`, `ConsentDialogTrigger`,
  `ConsentGate` button or other button that opens the dialog is mounted.
  This covers a visitor who taps or presses Enter with no hover or focus
  first. Browsers without `requestIdleCallback`, such as Safari, wait
  200 ms after `load` instead.
* Hover or focus on a button that opens the dialog.
* The dialog opening.

Passing `open={true}` or `showTrigger` loads it on mount. A visit with
saved consent and nothing on the page that opens the dialog never
downloads it.

Idle loading is skipped when the visitor has Save-Data on
(`navigator.connection.saveData`), on a `2g` or `slow-2g` connection, and
while offline; hover and focus still load it. To load the chunk only on
hover, focus or open, set `preloadDialog: 'intent'` in the provider
options. The default is `'idle'`. With Next.js, pass it through
`ConsentRoot`'s `options` prop.

If a preload fails, for example because the visitor is offline, nothing is
cached: the next hover, focus or open tries the download again.

The dialog's CSS travels in the same chunk and is applied before the dialog
renders, so the first page load carries only the banner's rules.

Without an `open` prop, Escape closes the dialog without saving. If the
policy still owes a choice, the banner comes back. Save Settings, Accept All and
Reject All close it as soon as the choice is recorded in the browser, in
the same task as the click; the exit animation still plays. The request to
the backend runs afterwards and never reopens the dialog: a failed request
keeps the choice, reports through `onError` and is retried later. See
[when a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
for the order of events. A draft that went stale because the policy changed keeps the dialog open
for review. With `open={true}`, these actions leave the dialog visible; the
parent must set `open={false}` to close it. Clicking the backdrop does not
close it. Closing discards toggles that were not saved: the next open starts
from the recorded choice again. After a save from an uncontrolled dialog,
every consent surface hides unless the policy still owes a prompt, in which
case the banner returns.

The preference center is blocking by default: a backdrop, body scroll lock
and focus trap, all as one value. Set `presentation.preferences.blocking`
to `false` in the provider options to remove all three; the deprecated
`scrollLock` and `trapFocus` props do the same for one dialog. `variant`
and `position` are prompt options. Setting them under
`presentation.preferences` logs an `invalid-variant` diagnostic in
development and changes nothing; the dialog is always centered.

The dialog never opens without a resolved policy rule, even when the
active surface is already `dialog`; it appears as soon as a rule resolves,
without a remount. A rule with `model: 'none'` and no rights owes no consent
UI, so the dialog stays closed under it. When such a rule lists any right,
for example `rights: ['disclosure']` or `rights: ['preferences']`, the dialog
can open as a settings route and Save completes without writing a consent
record.

Copy comes from these translation keys: `consentManagerDialog.title`,
`consentManagerDialog.description`, `common.acceptAll`, `common.rejectAll`,
`common.save`, and `consentTypes.<category>.title` and `.description` for
each row.

## Accessibility

The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
while it is blocking. Its `dir` attribute follows the active language.

While blocking, focus moves on open to the first tabbable control in the
panel, so a keyboard user sees the focus ring on a control rather than
around the whole panel; the `aria-labelledby` and `aria-describedby`
wiring means a screen reader still announces the title and description as
focus enters. Tab and Shift+Tab wrap inside the panel, and on close focus
returns to the element that opened the dialog. A non-blocking dialog manages no focus: nothing moves focus into the
panel or back to the opener. The backdrop is `aria-hidden` and is not
focusable.

Each category switch has the category title as its accessible name. The
`necessary` switch is disabled and always on. A saved grant that the current
policy or a privacy signal overrides gets a note under its row, linked to
the switch through `aria-describedby`.

## Composition

Every part is available as `ConsentDialog.<Part>`: `Root`, `Overlay`,
`Card`, `Header`, `HeaderTitle`, `HeaderDescription`, `Content`, `Footer`
and `ConsentCustomizationCard`, the stock card. `Root` provides the portal,
open state, focus trap, scroll lock and backdrop, and accepts `open`,
`models`, `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`,
`uiSource` and `overlay`. Pass `overlay={false}` to render no backdrop, or a
node to replace the built-in one.

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription legalLinks={['privacyPolicy']} />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Keep `ConsentWidget` inside `Content`: it owns the draft, the switches and
the policy actions, and inherits the dialog's `uiSource`. `Footer` renders
the branding tag unless you pass children or `hideBranding`.

The positioner carries `data-slot="dialog-positioner"`, and both it and the
panel carry `data-blocking="true"` while blocking. Provider component slots
for the stock structure are `dialog.root`, `dialog.container`,
`dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
`dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.

`ConsentDialog` from the package root and from the
`c15t/react/consent-dialog` subpath is the deferred component described
under Behavior, and each `ConsentDialog.<Part>` loads with the same chunk.
`c15t/react/components/consent-dialog` exports the dialog without the
deferral, plus each part as a named export (`Card`, `Header`, `Overlay`,
`Root` and the rest). Importing from that path puts the dialog's code in
the bundle of every page that imports it, so the first open needs no
download but every visitor downloads the dialog.

## Verify

Use the default blocking, uncontrolled dialog and an optional in-scope
category that is not restricted by policy or privacy signals such as GPC.
Open the dialog from the banner's Customize button or a preferences link.
A centered card appears over a dimmed backdrop, the page behind it stops
scrolling, and Tab stays inside the card. Press Escape: the card closes and
focus returns to the button you used. Open it again, turn a category on and
choose Save. The dialog closes and `useConsent('<category>')` reports
`true` in your components; under a choice prompt the banner does not return,
while a `notice` prompt keeps its banner until it is acknowledged. Reload the
page and reopen the dialog: the switch reflects the saved choice.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-widget
Embed the c15t preference controls inline on a TanStack Start privacy page with ConsentWidget, recording a choice only when the visitor saves.

## Embed the preference center in a page

`ConsentWidget` renders the category switches and the Reject All, Accept All
and Save Settings actions in the page flow instead of a modal. Use it on a privacy or
settings route. Keep `ConsentDialog` in the root route too, so the banner's
Customize button still has a dialog to open.

```tsx title="src/routes/privacy.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { ConsentWidget } from 'c15t/tanstack-start';

const PrivacyPage = () => (
	<main>
		<h1>Privacy</h1>
		<section aria-labelledby="cookie-preferences">
			<h2 id="cookie-preferences">Cookie preferences</h2>
			<ConsentWidget />
		</section>
	</main>
);

export const Route = createFileRoute('/privacy')({ component: PrivacyPage });
```

The widget uses `ConsentRoot`'s policy, translations and backend. It needs no
second provider. `useConsentDraft` and `ConsentDraftProvider` also import from
`c15t/tanstack-start`.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|A standalone widget hides the "Secured by" tag. Pass `false` to show it.|
|`uiSource`|`string`|`'widget'`|Source identifier recorded with saves made from this widget. Inside `ConsentDialog` it inherits `'dialog'`.|
|`disableAnimation`|`boolean`|`false`|Skips animations in the widget's parts.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The widget is the preference center without the modal around it: an
accordion with one row per category, each with a switch, followed by the
Reject All, Accept All and Save Settings actions. `ConsentDialog` renders this same
widget inside its card. Standalone, the widget renders in place, takes part
in server rendering, and does not touch the active surface, so it suits a
privacy page or an account settings screen.

The rows are `necessary` plus the categories in the active policy's scope,
narrowed to the categories the provider declares: `options.consentCategories`
and the categories of its scripts, network rules, vendors and discovered
frames. When nothing is declared, a permissive policy shows only `necessary`
and a strict one its whole scope.
The `necessary` switch is on and disabled. Row titles and descriptions come
from `consentTypes.<category>.title` and `.description`; the action labels
from `common.rejectAll`, `common.acceptAll` and `common.save`. One row is
expanded at a time.

### Draft and save

Switches edit a draft, not the visitor's permissions. Nothing is recorded
until Save. The draft seeds each category from the recorded choice; without
one it uses `presentation.preferences.defaults` from the provider options,
and without that it is on under an opt-out rule and on only for the rule's
preselected categories under an opt-in rule. Save records the displayed
categories, then reseeds the draft from the new record. Accept All and
Reject All record immediately without a separate Save. A save answers a
choice prompt, so an open choice banner closes; it does not dismiss a
`notice` prompt, which keeps its own acknowledgement record. Unsaved toggles
are lost when the widget unmounts.

When the policy changes in a way that affects the choice while the draft has
unsaved toggles, the widget shows an alert, "The privacy policy changed.
Review the current choices before saving.", with a Review choices button
that resets the draft. Save is refused until then. A draft without unsaved
toggles reseeds silently.

A saved grant that the current policy or a privacy signal such as Global
Privacy Control overrides shows a note under its row: "Your saved choice is
restricted by the current privacy settings." The switch still reflects the
saved value; the effective permission is off.

### Vendors

When the provider declares `vendors`, each category's expanded description
ends with one card per vendor whose category condition names that category,
styled like a category row: the vendor's name and a switch on the header,
and its description and privacy policy link behind the card's own expand
control. Cards start collapsed, so a long list stays one line per vendor,
and the category list scrolls inside the dialog rather than growing it.
A collapsed category or card renders its content element empty and mounts
the content the first time it opens, then keeps it mounted, so a long
vendor list costs nothing until a visitor expands its category.
Vendor switches edit the same draft as the category
switches and record on Save. Saving with one vendor off denies that vendor
only; the category stays granted and its other vendors keep loading. While
the category is off in the draft the vendor switches are disabled, with the
hint "Turn on this category to choose vendors." A vendor declared
`disabled`, or one that only falls under `necessary`, is listed without a
switch. Accept All and Reject All clear every vendor denial, including one
staged but not yet saved. Under an `iab` policy no vendor rows render.
Vendors that are only referenced by a script slug, without a name and
privacy policy URL, still gate loading but are not listed, and so does a
vendor whose condition negates a category, since no category row can
host it. See
[vendor consent](../vendor-consent).

### Actions

The preference center always renders Reject All, Accept All and Save Settings, with
Save Settings as the primary action. `presentation.preferences.layout`,
`primaryActions`, `direction` and `uiProfile` in the provider options
reorder and restyle them; a layout that omits one of the three has it
restored. Customize and dismiss actions never render here.

### When consent is not owed

Without a resolved policy rule the widget renders nothing and appears as
soon as a rule resolves, without a remount. A rule with `model: 'none'` and
an empty `rights` list renders nothing; a `none` rule that lists any right,
such as `['disclosure']`, renders the widget and Save completes without
writing a consent record.

For a fully custom preference center, `useConsentDraft()` returns the same
draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
the declared list, the recorded denials and one vendor's effective result.

## Accessibility

Each row is a disclosure: a button that expands the category description
and a switch beside it, so a visitor can read the description without
changing the choice. Each switch has the category title as its accessible
name. A category's vendor cards sit in a `region` named "Vendors" with the
count; each card's expand button carries `aria-expanded`, each vendor
switch is named "Allow" followed by the vendor name, and is described by
the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
an `output` element linked to its switch through `aria-describedby`. The
root's `dir` attribute follows the active language.

## Composition

Every part is available as `ConsentWidget.<Part>`. `Root` provides the
draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
and `AccordionItems` render the stock rows; `AccordionItem`,
`AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
`AccordionArrow` and `Switch` build your own; `VendorList` renders one
category's vendor rows and takes a `category` prop. `PolicyActions` renders the
resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
`CustomizeButton` are the individual buttons.

`Accordion` is controlled: pass `value` and `onValueChange`, or no
category description ever opens. The stock `ConsentWidget` holds that state
for you. In this component, `ConsentWidget` comes from the same import as
the example at the top of the page:

```tsx
import { useState } from 'react';

export function PreferenceCenter() {
  const [open, setOpen] = useState<string[]>([]);

  return (
    <ConsentWidget.Root>
      <ConsentWidget.Accordion
        value={open}
        onValueChange={(next) => setOpen(Array.isArray(next) ? next : [next])}
      >
        <ConsentWidget.AccordionItems />
      </ConsentWidget.Accordion>
      <ConsentWidget.PolicyActions />
    </ConsentWidget.Root>
  );
}
```

Provider component slots for the stock structure are `manager.root`,
`manager.footer`, `manager.actionGroup`, `accordion.root`,
`accordion.triggerRow`, `accordion.title`, `accordion.control`,
`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
`vendor-list.item`, `vendor-list.header`,
`vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
`vendor-list.control` and `tag.manager`.

`ConsentWidget` from the package root and from the
`c15t/react/consent-widget` subpath loads its code in a separate chunk the
first time it renders, so a page that never renders it does not download
it. `c15t/react/components/consent-widget` exports the widget without that
deferral, plus each part as a named export.

## Verify

Visit the page with the widget. Use a displayed optional category whose permission is
not restricted by policy or privacy signals such as GPC. One row per displayed
category appears, with `necessary` on and disabled. Turn that category on:
`useConsent('<category>')`
elsewhere on the page still reports the old value. Choose Save: it now
reports `true`. An open choice banner closes when the save answers its
prompt; a notice banner stays open until acknowledged. Reload the page: the
switch keeps the saved value. Without a saved choice or configured draft
defaults, optional switches start on under an opt-out rule.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog-link
Add a ConsentDialogLink to a TanStack Start footer so visitors can reopen the c15t preference dialog from your own text link.

## Reopen preferences from your footer

`ConsentDialogLink` is an unstyled button that opens the preference dialog.
Put it where your site keeps its legal links so preferences stay reachable
after the banner closes. The
[quickstart](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route)
renders one in the root route's footer.

```tsx title="src/components/site-footer.tsx"
import { ConsentDialogLink } from 'c15t/tanstack-start';

export function SiteFooter() {
	return (
		<footer>
			<a href="/privacy">Privacy policy</a>
			<ConsentDialogLink className="footer-link">
				Privacy settings
			</ConsentDialogLink>
		</footer>
	);
}
```

Render the footer inside `ConsentRoot`, with `ConsentDialog` mounted. It
renders a `button`; pass `asChild` to render your own link element instead.

`c15t/tanstack-start/components/consent-dialog-link` exports `ConsentDialogLink`
and nothing else. Import from that path when a module needs only the link, so
it does not load the rest of the adapter.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`children`|`ReactNode`|required|The visible label, such as "Privacy settings" or "Manage preferences". It is also the accessible name.|
|`asChild`|`boolean`|`false`|Renders your own element, such as an anchor, instead of a `button`, and attaches the click handler to it.|
|`noStyle`|`boolean`|`true`|Omits c15t button classes. Native browser styles remain unless your CSS resets them. Pass `false` to render it as a consent button with `variant` and `mode`.|
|`onClick`|`(event) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to keep it closed.|

Other `button` attributes such as `className`, `style`, `id` and `aria-*`
pass through to the rendered element.

## Behavior

`ConsentDialogLink` renders a `button` with `type="button"` and no c15t
styling by default. Clicking it makes `dialog` the active surface, which opens a
mounted `ConsentDialog`. It performs no save and does not change any
permission.

The element carries `data-c15t-rights` listing the rights of the active
policy rule, for example `disclosure opt-out preferences` under a US
opt-out rule and `disclosure preferences` under an opt-in rule, so a
stylesheet or a `::after` label can adapt the wording by region.

Without a resolved policy rule the link renders nothing and appears as soon
as a rule resolves, without a remount. A rule with `model: 'none'` and an
empty `rights` list owes no consent UI, so the link hides under it; a `none`
rule that lists any right, such as `['disclosure']`, shows the link and the
dialog opens as a settings route.

Mount exactly one `ConsentDialog` inside the same provider. If none is
mounted, the click still switches the active surface: nothing opens, and a
banner that was showing closes because the surface is no longer `banner`.

With `asChild`, the child's own `onClick` runs first; if it calls
`event.preventDefault()` the dialog stays closed. c15t does not prevent the
child's native behavior, so an anchor still follows its `href`. Use a
fragment or the current page as the destination, or render a `button`.

### ConsentDialogLink or ConsentDialogTrigger

Both open the same dialog and carry `data-c15t-rights`. Use
`ConsentDialogLink` where the control belongs in your own layout: a footer,
a privacy page, a settings menu. It has no position, icon or visibility
rule of its own. Use `ConsentDialogTrigger` when you want a floating,
draggable button that positions itself in a corner and can wait until the
prompt is answered.

## Accessibility

The rendered `button` is keyboard-focusable and activates with Enter and
Space; its accessible name is the text you pass as `children`, so give it
words that describe the destination rather than "click here". Because the
dialog it opens is labelled by its own title and, while blocking, returns
focus to the link on close, no additional `aria-haspopup` or
`aria-controls` is added; a non-blocking dialog manages no focus, so the
link does not regain it. With `asChild`,
focusability comes from your element: use a `button` or an anchor with an
`href`.

## Verify

Scroll to the footer. With the footer button reset applied, the link uses
your footer's text styles and has no button chrome. Activate it with a click or with Enter: the preference
center opens as a centered dialog. Close it with Escape: with the default
blocking dialog, focus returns to the link. In your browser's element
inspector the link has
`data-c15t-rights`; change the visitor's region to a US opt-out rule and
the value includes `opt-out`. Under a rule with `model: 'none'` and no
rights, the link is absent.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-dialog-trigger
Add a floating button or toolbar to a TanStack Start app that reopens the c15t preference dialog after the first prompt.

## Add a floating preferences button

`ConsentDialogTrigger` is a draggable floating button that opens the
preference dialog. Render it once inside `ConsentRoot`, next to the banner and
dialog:

```tsx title="src/routes/__root.tsx"
import { ConsentDialogTrigger } from 'c15t/tanstack-start';

// Inside ConsentRoot, next to ConsentDialog:
<ConsentDialogTrigger showWhen="after-prompt" />;
```

`showWhen="after-prompt"` hides the button while a choice or notice is owed, so
it never competes with the banner. It renders nothing until a policy resolves,
and nothing under a policy that owes no rights.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`icon`|`'branding' \|'fingerprint' \|'settings' \|ReactNode`|`'branding'`|Icon rendered inside the button.|
|`defaultPosition`|`'bottom-left' \|'bottom-right' \|'top-left' \|'top-right'`|`'bottom-right'`|Corner the button starts in.|
|`persistPosition`|`boolean`|`true`|Remember the corner the visitor dragged it to.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the button is visible. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

## Add your own controls with the toolbar

`ConsentDialogTriggerToolbar` renders one built-in preferences action plus
controls your app owns, such as a theme toggle. Each action needs a stable
`id`, a `label`, an `icon` and an `onSelect` callback. Import it from
`c15t/tanstack-start`.

|Prop|Type|Default|Description|
|--|--|--|--|
|`actions`|`ConsentDialogTriggerToolbarAction[]`|`[]`|App-owned actions rendered beside the preferences action.|
|`preferences`|`ConsentDialogTriggerToolbarPreferences`|`{}`|Overrides for the built-in action: `icon`, `label`, `onSelect`, `className`, `style`. The label defaults to the opt-out or preferences right on the active rule.|
|`orientation`|`'horizontal' \|'vertical'`|`'horizontal'`|Layout direction.|
|`defaultPosition`|`CornerPosition`|`'bottom-right'`|Corner the toolbar starts in.|
|`persistPosition`|`boolean`|`true`|Remember the dragged corner.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the built-in preferences action is visible. App-owned actions always render. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Size of each action.|
|`ariaLabel`|`string`|`'Privacy controls'`|Accessible name for the toolbar group.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

While `<ConsentDevTools>` is mounted, the toolbar adds a DevTools button at
the end farthest from its corner and opens the DevTools panel beside itself.
The ready-made `ConsentDialogTrigger` switches to this toolbar layout for as
long as DevTools is mounted.

# ConsentGate
URL: https://c15t.com/docs/frameworks/tanstack-start/components/consent-gate
Gate a YouTube video, map or other iframe behind consent in a TanStack Start app with ConsentGate, showing a placeholder until the category is allowed.

## Gate an embed behind consent

`ConsentGate` mounts its children only while one category is allowed and shows
a placeholder otherwise. Wrap any iframe or widget that contacts a vendor when
it loads:

```tsx title="src/components/product-video.tsx"
import { ConsentGate } from 'c15t/tanstack-start';

export function ProductVideo() {
	return (
		<ConsentGate category="marketing" style={{ aspectRatio: '16 / 9' }}>
			<iframe
				src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
				title="Product tour"
				allowFullScreen
			/>
		</ConsentGate>
	);
}
```

With an awaited root loader, the server HTML already contains the placeholder
or, for a visitor who allowed the category, the iframe. The category must be in
your policy's scope.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The consent category whose effective permission gates the children, for example `'marketing'` or `'functionality'`.|
|`children`|`ReactNode`|required|The embed. It is not mounted until the category is allowed, so it makes no requests before permission.|
|`placeholder`|`ReactNode`|built-in placeholder|Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content.|

Other `div` attributes such as `className`, `style` and `ref` apply to the
wrapper element that stays in the page in both states. `ConsentGateProps` also
declares `noStyle` and `theme`, but the component does not apply them yet;
style the wrapper with `className`, and style the built-in placeholder
through its parts in the provider options.

## Behavior

`ConsentGate` renders a `div` wrapper. Inside it, when the effective permission for
`category` is granted, it renders the children; otherwise it renders the
placeholder. Permission is the same value `useConsent(category)` returns,
so it can be granted under an opt-out rule before the visitor records a
choice, and a recorded grant can be overridden by a privacy signal.

While effective permission is denied, the children are absent from the DOM,
so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
children unmount and the embed disappears. `ConsentGate` does not depend on the
network blocker or the iframe blocker modules; use those for markup you
cannot wrap in a component.

The built-in placeholder shows the title `consentGate.title`,
`Accept {category} consent to view this content.`, with `{category}`
replaced by `consentTypes.<category>.title`, and a button labelled
`consentGate.actionButton`, `Enable {category} consent`. The button opens the
preference center; it
does not grant the category by itself, because the visitor still has to
save. Mount a `ConsentDialog` in the same provider so the button has
something to open.

Under a policy with `scopeMode: 'strict'`, a category outside the rule's
scope cannot be granted. The built-in placeholder then shows `consentGate.policyBlocked`,
"This content is unavailable under your region's consent policy.", without
the button, and a stored grant for that category stays blocked.

When the provider starts from a snapshot prefetched on the server, the
server renders the placeholder for a denied category. For a granted
category it renders the empty wrapper, and the children mount once
hydration completes, so an iframe loads once even when the page streams
inside a `Suspense` boundary. A grant in the request cookie allows the
embed only when policy and privacy signals permit it. Browser privacy signals detected during hydration can
withdraw that permission. In a browser-only setup the
provider has no permission until it resolves policy on the client, so
`ConsentGate` shows the placeholder first and swaps in the embed after resolution
when the category is already granted.

`ConsentGate` is one component on this page; the per-vendor embed guides for
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) show a complete embed
configuration with sizing, titles and the same `ConsentGate` usage across
frameworks.

## Composition

The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
translated text; pass children to either to replace it.

```tsx
<ConsentGate
  category="marketing"
  placeholder={
    <ConsentGate.Root>
      <ConsentGate.Title category="marketing" />
      <p>The video is also available on our channel.</p>
      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
    </ConsentGate.Root>
  }
>
  <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
</ConsentGate>
```

To restyle the built-in placeholder without replacing it, set its parts
under `components['consent-gate']` in the provider options. `root` is the
card, and `title` and `button` are its text and button. The `consentGate`, `consentGateTitle` and
`consentGateButton` theme slots reach the same parts. The button part
applies on top of `button.primary`.

```tsx
components: {
  'consent-gate': {
    root: { className: 'rounded-none' },
    button: { className: 'font-semibold' },
  },
},
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

## Accessibility

The placeholder is plain text and a `button`, so it is readable and
operable without the embed. Give the iframe a descriptive `title`, and keep a
transcript, address or link outside the `ConsentGate` for visitors who decline
the category. A denied category may be fixed by policy, so opening the
preference center does not guarantee that the visitor can grant it.

## Verify

Use an optional in-scope category that is available in the preference
center and is not restricted by policy or privacy signals such as GPC.
Load the page with the category denied. The placeholder text names the
category and the network panel shows no request to the embed's host. With a
prefetched snapshot, the server HTML contains the placeholder for a denied
category and neither placeholder nor embed for a granted category; the
embed appears after hydration and the network panel shows one request for
its document. Browser-only initialization
shows the placeholder before policy resolves, then replaces it with the
embed if the category is granted. After policy resolves, activate the
placeholder button: the preference center opens. Turn the category on and
Save: the placeholder is replaced by the embed and its requests start. Reject the
category again from the preference center: the embed disappears.

# Hooks
URL: https://c15t.com/docs/frameworks/tanstack-start/hooks
Read consent permissions, open the preference dialog and save choices in TanStack Start components with the hooks exported from c15t/tanstack-start.

## Read only the state you need

`c15t/tanstack-start` re-exports every hook from `c15t/react`. Each hook reads
the runtime from `ConsentRoot`, so call hooks in components rendered inside it.
Any route component qualifies, because `ConsentRoot` wraps the `Outlet` in the
root route.

```tsx title="src/components/optional-feature.tsx"
import { useConsent } from 'c15t/tanstack-start';

export function OptionalFeature() {
	const allowed = useConsent('marketing');
	return allowed ? <div>Optional marketing content</div> : null;
}
```

On the server, hooks read the state the root loader resolved, so a route
renders the same result in the server HTML and in the first browser render.

Call hooks inside the consent provider. `useConsent` reads effective permission,
which can be true under an opt-out policy without a recorded grant.

|Need|Hook|
|--|--|
|One category's current permission|`useConsent(category)`|
|All current permissions|`useConsents()`|
|Recorded per-category choices|`useExplicitChoice()`|
|Whether one declared vendor may run|`useVendorAllowed(id)`|
|Whether a prompt is required|`usePromptRequirement()`|
|Active policy and resolution|`usePolicyRule()`, `usePolicyResolution()`|
|Save an explicit choice|`useSaveConsents()`|
|Open or close a consent surface|`useSetActiveUI()`|
|Acknowledge a notice|`useDismissNotice()`|

## Open the preference dialog

Set the active surface to `'dialog'` from any component inside `ConsentRoot`:

```tsx title="src/components/privacy-menu-item.tsx"
import { useSetActiveUI } from 'c15t/tanstack-start';

export function PrivacyMenuItem() {
	const setActiveUI = useSetActiveUI();
	return (
		<button type="button" onClick={() => setActiveUI('dialog')}>
			Cookie preferences
		</button>
	);
}
```

`ConsentDialogLink` does the same without a hook.

## Save from a visitor action

```tsx title="src/components/reject-button.tsx"
import { useSaveConsents } from 'c15t/tanstack-start';

export function RejectButton() {
	const save = useSaveConsents();
	return (
		<button type="button" onClick={() => void save('none')}>
			Reject optional
		</button>
	);
}
```

This is an isolated action example, not a complete policy-aware banner. Use the
stock UI or headless surface actions for a complete prompt. Do not call save on
mount to persist a state derived from permissions.

Use focused hooks for feature gates. For a complete custom prompt or preference
center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
for staged choices, inside one `ConsentDraftProvider` so the save commits the
same draft. v3 has no `useConsentManager()`; the
[`use-consent-manager-to-hooks` codemod](/docs/cli/commands/codemods#migrate-useconsentmanager-to-v3-hooks)
rewrites most of its calls to hooks. Read [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) before
treating a callback as evidence of a choice.

## Where hooks do not work

Hooks need React context, so they do not run in loaders, `beforeLoad`, server
functions or server routes. On the server, read the request's consent state
with `resolveConsent` from `c15t/tanstack-start/server`.

# Callbacks
URL: https://c15t.com/docs/frameworks/tanstack-start/callbacks
Run code in a TanStack Start app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, from ConsentRoot in the root route.

## Pass callbacks to ConsentRoot

Keep the callbacks in their own module:

```ts title="src/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/tanstack-start';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

Import it in `src/routes/__root.tsx` and pass it under `options` on
`ConsentRoot`:

```tsx title="src/routes/__root.tsx"
<ConsentRoot
  state={consent}
  scripts={scripts}
  options={{ callbacks }}
>
```

The root route component renders on the server and again in the browser, and
each side imports the module itself. Do not return callbacks from the root
loader or a server function. Loader data is serialized for the browser, and
functions cannot be serialized, so it should carry only the consent state.

`ConsentRoot` subscribes the callbacks after it mounts in the browser. Server
rendering never calls them. The provider calls the latest `callbacks` object
it received, so a new object on a later render takes effect without a
remount.

## Available callbacks

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useSaveConsents()`.|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time as a millisecond timestamp|
|`onPermissionsChanged`|Any effective permission changes value.|`snapshot`, the state after the change; `previous`, the permissions before it|
|`onError`|A consent command fails in the browser, such as a failed `/init` request or a save the backend rejects.|`error`, a message string|
|`onBeforeConsentRevocationReload`|A save withdrew a granted category or vendor, right before c15t reloads the page.|`preferences`, the permissions after the save|

The type for the whole object is `ConsentProviderCallbacks` from
`c15t/tanstack-start`. Callbacks run after c15t updates its state, so
`snapshot` and hooks such as `useConsent()` already hold the new values.

`resolveConsent` on the server has no error callback. When the manifest
request fails or runs out of `timeoutMs`, the loader returns the request-only
state, and the browser resolves consent after hydration. A failure there
reaches `onError`.

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only for a visitor's action. `onPermissionsChanged`
runs whenever effective permissions change, whatever the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|A policy resolves in the browser and allows categories before any choice|No|Yes|
|Global Privacy Control turns off a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent analytics and audit trails, because it
fires only when the visitor chose. Use `onPermissionsChanged` to start or stop
your own code. Never treat it as proof that the visitor agreed to anything,
and never save consent from it.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

Dismissing a notice records no choice and changes no permission. Read it with
`useNoticeDismissal()` instead. For consent inside one component, use the
[hooks](/docs/frameworks/tanstack-start/hooks), which re-render the component
when consent changes.

## Before a revocation reload

Removing a script tag cannot stop code that already ran, so c15t reloads the
page after an accept, reject or save turns off a category or vendor that was
granted. The reload waits for the save request to finish. Right before it,
`onBeforeConsentRevocationReload` runs synchronously. Use it to call a
vendor's shutdown API or flush queued events. Keep it short, because the
reload does not wait for promises.

A choice that expires, a new policy and a privacy signal change permissions
without a visitor action, so they do not reload the page.

To handle revocation yourself, set `reloadOnConsentRevoked: false` in
`options` on `ConsentRoot`. Code the visitor turned off then keeps running
until the next full page load, and `onBeforeConsentRevocationReload` never
runs.

## Verify

1. Add the callbacks from this page, open the console and DevTools Network,
   clear site data and reload under a policy that shows a banner.
2. Click **Accept All**. `onChoiceRecorded` and `onPermissionsChanged` both log,
   and the save request to your backend appears in Network.
3. Reload. `onChoiceRecorded` does not log again.
4. Open Privacy settings, turn off a category you allowed and save.
   `onBeforeConsentRevocationReload` logs, then the page reloads. After the
   reload, that category's vendor requests are absent from Network.

# IAB TCF
URL: https://c15t.com/docs/frameworks/tanstack-start/iab
Show the IAB TCF banner and dialog in a TanStack Start app for visitors whose policy uses the IAB model, with c15t/react/iab inside ConsentRoot.

## Before you start

Use the IAB integration when your site needs the Transparency and Consent
Framework. Enable IAB in your Inth project and give a policy the `iab` model.
You also need a CMP ID, which IAB Europe assigns when a company registers as a
CMP at [register.consensu.org/CMP](https://register.consensu.org/CMP). Every TC
String names the CMP that wrote it, so do not use an ID you did not register.

The IAB components ship with the `c15t` package; no extra install is needed.
With the quickstart's root loader, the server resolves IAB visitors like any
other visitor, and the policy manifest carries the vendor list reference.

## Render the IAB banner and dialog

The stock `ConsentBanner` and `ConsentDialog` stay closed under the `iab`
model. Render the IAB components inside `ConsentRoot`, next to them:

```tsx title="src/components/iab-consent.tsx"
import {
	IABConsentBanner,
	IABConsentDialog,
	IABProvider,
} from 'c15t/react/iab';
import { useModel } from 'c15t/tanstack-start';

export const IABConsent = ({ cmpId }: { cmpId: number }) => {
	const model = useModel();
	if (model !== 'iab') {
		return null;
	}
	return (
		<IABProvider cmpId={cmpId}>
			<IABConsentBanner />
			<IABConsentDialog />
		</IABProvider>
	);
};
```

Render `<IABConsent cmpId={YOUR_CMP_ID} />` in the root route, next to
`ConsentBanner`. Checking `useModel()` renders the IAB components only for
visitors whose policy uses the IAB model.

The IAB banner and dialog render their own styles by default. Leave
`ConsentRoot`'s `styles` option enabled. The banner's styles render in the
server HTML, and the dialog loads its rules when opened.

Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
preferences entry point through the surrounding consent provider.

## Resolve the policy before rendering

IAB components remain hidden until an applicable policy resolves. Forcing a
dialog open does not create a policy or vendor list. Inspect resolution and the
Global Vendor List response before changing rendering conditions.

IAB presentation follows `presentation.prompt.blocking` and
`presentation.preferences.blocking`. A blocking dialog needs focus management,
scroll locking and a backdrop together.

## Mount IABProvider for every IAB policy

IAB is opt-in. The standard `ConsentBanner` and `ConsentDialog` do not
handle the IAB model, so when a visitor's policy uses it, the backend
sends its vendor list and the app has no `IABProvider`, they throw an
`IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`):
`c15t: this visitor's policy uses IAB TCF, but no <IABProvider> is mounted`.
The error happens during render, on the server and in the browser, so
your error boundary or the framework's error overlay shows it. Render `IABProvider` from
`c15t/react/iab` for those visitors, or remove the `iab` model from the
policy.

## Verify vendor and purpose choices

Test category choices alongside vendor, purpose, legitimate-interest and special
feature controls used by your integration. Confirm the TC String and `__tcfapi`
reflect the saved state, and verify the vendor's actual requests. A category-only
banner test does not establish that the IAB flow works.

## Load an external stylesheet

With Tailwind CSS 3, or when you want to put c15t in a named cascade layer,
link the base stylesheet and then the IAB stylesheet in the root route's
`head()`. The IAB stylesheet holds the IAB rules and uses the base
stylesheet's tokens. Set `styles: false` in `ConsentRoot`'s `options` so the
components use those stylesheets:

```tsx title="src/routes/__root.tsx (partial)"
import consentCss from 'c15t/tanstack-start/styles.css?url';
import iabCss from 'c15t/tanstack-start/iab/styles.css?url';

// In head().links:
{ href: consentCss, rel: 'stylesheet' },
{ href: iabCss, rel: 'stylesheet' },

// On ConsentRoot:
options={{ styles: false }}
```

Tailwind CSS 3 also needs the
[PostCSS plugin](/docs/customization/tailwind#set-up-tailwind-css-3).

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Pass
them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
placeholders; use vendors from your list whose declarations allow each
restriction:

```tsx title="src/components/iab-consent.tsx"
const publisherRestrictions = [
  // Vendors 10 and 755 may not use purpose 4.
  { purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
  // Vendor 755 must use legitimate interest for purpose 7.
  { purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
];

<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
```

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

# IAB GPP
URL: https://c15t.com/docs/frameworks/tanstack-start/gpp
Add the IAB Global Privacy Platform API (__gpp) to a TanStack Start app with ConsentGPP from c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

`ConsentGPP` from `c15t/react/gpp` installs `window.__gpp`, the GPP 1.1 CMP
API, and keeps its GPP string in step with the visitor's choices. Prebid.js,
Google Ad Manager and other ad tech read US privacy signals from it.

## Turn on GPP

Render `ConsentGPP` inside `ConsentRoot` in `src/routes/__root.tsx`:

```tsx title="src/routes/__root.tsx"
import { ConsentGPP } from 'c15t/react/gpp';

<ConsentRoot state={consent} scripts={scripts}>
	<ConsentGPP />
	<Outlet />
</ConsentRoot>;
```

`ConsentGPP` renders nothing. `__gpp` exists only in the browser: the
component installs it after it mounts and removes it when it unmounts. Apps
that do not import `c15t/react/gpp` bundle none of the GPP code.

The props are the GPP options listed below, for example
`<ConsentGPP usFallback="none" />`.

The GPP string follows the policy and location the root loader resolves for
the visitor. A US visitor's state comes from the geo headers your host sends;
see [geography headers](/docs/frameworks/tanstack-start/geography-headers) if
it is missing.

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/tanstack-start/iab) as well.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Geography headers
URL: https://c15t.com/docs/frameworks/tanstack-start/geography-headers
Which request headers c15t reads for country, region, language and Global Privacy Control in TanStack Start, where the server functions and consent route send them, and how to test another location.

## Where the location comes from

Your consent policy picks a rule by the visitor's country and region, such as
opt-in in Europe, opt-out in US states with privacy laws, and no banner where
no law applies. In TanStack Start, the c15t server helpers read that location from
request headers your host or CDN adds. They never look up an IP address. With
no location header, the policy resolves with its rule for an unknown location.

## Which headers are read

`consentRequestMiddleware`, `createConsentStateHandler`, `resolveConsent` and
the `/api/c15t/init` route read the same headers, in this order. The first one
with a value wins.

|Input|Headers, highest priority first|Set by|
|--|--|--|
|Country|`x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country`|c15t override, Cloudflare, Vercel, CloudFront, generic proxies|
|Region|`x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`|c15t override, Cloudflare, Vercel, generic proxies|
|Language|`accept-language`, negotiated by quality value to a primary tag such as `de`|The browser|
|Global Privacy Control|`x-c15t-gpc`, `sec-gpc`. Only `1` and `0` count|c15t override, the browser|

Vercel adds its country and region headers to every request. Cloudflare adds
`cf-ipcountry`; for `cf-region-code`, turn on Cloudflare's visitor location
headers. On another host, or a Node server without a CDN, set `x-c15t-country`
and `x-c15t-region` at your edge from whatever location data it has.

## Read the headers once per request

The server function and the consent route read these headers from the request
themselves, so the
[quickstart](/docs/frameworks/tanstack-start/quickstart) needs no middleware.
Register `consentRequestMiddleware` in `src/start.ts` when your own server
code needs the location, or to force one location for every request:

```ts title="src/start.ts"
import { createStart } from '@tanstack/react-start';
import { consentRequestMiddleware } from 'c15t/tanstack-start/middleware';

export const startInstance = createStart(() => ({
	requestMiddleware: [consentRequestMiddleware()],
}));
```

On every request, including server function calls and server routes, the
middleware:

* reads the headers in the table above,
* writes the result back onto the request as `x-c15t-country`,
  `x-c15t-region` and `sec-gpc`, so later code sees one format whichever CDN
  sent the value,
* and exposes the same values as `context.consent` to server routes and server
  functions.

Some runtimes hand middleware a request whose headers cannot change. The
middleware also keeps the values for that request, and the c15t helpers read
them from there first, so they still see the location. Pass
`normalizeHeaders: false` to leave the request headers untouched.

## Where the location goes

What happens next depends on your
[rendering setup](/docs/frameworks/tanstack-start/rendering):

|Code|What it does with the location|
|--|--|
|`createConsentStateHandler` and `resolveConsent`|Resolve the visitor's policy in the Start server, from the bundled manifest or, with runtime fetching, a cached one. The manifest request to your backend carries no visitor location, only headers you name in `forwardHeaders`|
|`/api/c15t/init` from `createConsentRoute`|Resolves the policy in the Start server from the same inputs, for the browser's init request|
|`createConsentRoute({ proxy: true })`|Forwards the location headers, `accept-language`, `sec-gpc`, `user-agent`, `origin` and `referer` to your backend on proxied requests such as `POST /subjects`|
|A state without `routePrefix`|The browser calls your backend's `/init` directly, and the backend reads the location its own host adds|

The server render in the quickstart always uses the Start server's headers,
even though the browser's init request goes to your backend.

## Forwarding headers are ignored by default

A relative `backendURL` or `manifestURL`, such as `/api/c15t`, resolves
against the URL the Start server received the request under. c15t does not
read `x-forwarded-host`, `x-forwarded-proto` or `forwarded` for this, because
any client can send them. If it did, a visitor could point the server's
manifest fetch, or the proxied consent save, at a host of their choosing.

The request URL still carries the request's `Host` header. If your server
answers requests for any `Host`, such as a Node server exposed directly or a
proxy that forwards `Host` from its default virtual host, use an absolute
server-side `backendURL` and `manifestURL`. A relative one resolves against
whatever `Host` the request sent.

The consent proxy follows the same rule. It never copies those headers from the
browser. It sets `x-forwarded-host` and `x-forwarded-proto` from the request
URL, and sends the client IP chain in `x-forwarded-for` only when you opt in.

Set `trustForwardedHeaders: true` on `createConsentStateHandler` and
`createConsentRoute` only when your app runs behind a proxy that sets
those headers and drops any the client sent. Check your host's documentation.
Some hosts overwrite `x-forwarded-for`, and others append to the value the
client sent.

## Trust the location headers

The `x-c15t-*` headers always win, and a browser can send them.
`consentRequestMiddleware` does not remove them. A visitor who sends
`x-c15t-country: US` gets the policy for the United States. That changes only
their own banner, but if you need the policy to follow your CDN's location,
delete incoming `x-c15t-*` headers at your edge before the request reaches the
Start server. The provider's `overrides` option sends the same headers on the
browser's init request, so stripping them also turns off that testing path
through your edge.

The generic `x-country-code`, `x-country` and `x-region-code` headers carry
whatever the client sent unless your proxy overwrites them. Behind your own
proxy, overwrite or delete them. `cf-ipcountry` and the Vercel headers come
from the platform, as long as visitors cannot reach your origin directly.

## Force a location

Pass `country`, `region` or `language` to force an input:

* On `consentRequestMiddleware({ country: 'DE' })`, for every request, such as
  a site that serves one country or a local test.
* On `createConsentStateHandler({ country: 'DE' })`, for that
  server function. It accepts `country` and `language`, not `region`.

An option on the server function wins over the middleware. In the browser,
`ConsentRoot` takes `options={{ overrides: { country, region, language } }}`
for the same purpose after hydration.

## Test another location

Send the override header with a request and look for the banner in the HTML.
With the awaited loader from the quickstart:

```sh
curl -s -H 'x-c15t-country: DE' http://localhost:3000/ | grep -c consent-banner-root
curl -s -H 'x-c15t-country: US' -H 'x-c15t-region: CA' http://localhost:3000/ | grep -c consent-banner-root
```

Use the port your server listens on. The first request prints `1` under a
policy that asks Europe for opt-in. What the second prints depends on your
policy's rule for California. With the consent route mounted, request
`/api/c15t/init` with the same headers. Its JSON has `location` and
`policyResolution` for that location.

## Verify

1. On your deployed site, log `context.consent` once from a server route or
   server function. It shows the country and region your CDN sent. An empty
   country means no location header reaches the Start server.
2. View the page source from two locations with different policy rules, for
   example through a VPN. The banner is in the HTML where the rule asks for a
   choice, and absent where it does not.
3. Send `x-c15t-country` from outside your edge. If you strip the header, the
   response still follows your real location.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/tanstack-start/content-security-policy
Run c15t in a TanStack Start app under a Content Security Policy, pass the router's per-request nonce to ConsentRoot, and allow the consent backend and vendor hosts.

## What c15t adds to the page

A TanStack Start app with c15t adds these to the page, and your policy must
allow them:

|What|Directive|
|--|--|
|The `<style>` elements the banner, dialog and other stock components render with c15t's rules|`style-src` with the request nonce|
|The c15t stylesheet, only if you link it yourself with `styles: false`|`style-src 'self'`|
|The `<style id="c15t-theme">` element, if you render `ConsentTheme`|`style-src` with the request nonce|
|`<script>` elements the script loader creates for `scripts` entries, both `src` and inline|`script-src` with the request nonce, or each vendor's host|
|The inline `consentPrefetchHead` script, on prerendered pages that use it|`script-src` with its hash|
|Browser requests to `/api/c15t/*`, when you mount the consent route|`connect-src 'self'`|
|Browser requests to your backend's `/init` and `/subjects`|`connect-src` with the backend origin|
|Iframes inside `ConsentGate`, and the frames, images and requests your vendors load|`frame-src`, `img-src`, `connect-src` for each vendor|

Requests the Start server makes, such as the manifest fetch in
`createConsentStateHandler` and the proxied saves from
`createConsentRoute`, run outside the browser. The browser's policy does
not apply to them.

## Pass the request nonce to c15t

TanStack Router stamps a nonce on the scripts, styles and links it renders when
the router has `ssr.nonce`. Give c15t the same value, so the script loader,
the `<style>` elements the stock components render, and `ConsentTheme` use it
too. This takes three steps.

**1. Create the nonce and the policy in request middleware.** Generate a new
nonce for every request, send the policy header, and hand the nonce to the rest
of the request through the middleware context:

```ts title="src/csp-middleware.ts"
import { createMiddleware } from '@tanstack/react-start';
import { setResponseHeader } from '@tanstack/react-start/server';

export const cspMiddleware = createMiddleware().server(({ next }) => {
	const bytes = crypto.getRandomValues(new Uint8Array(16));
	const nonce = btoa(String.fromCharCode(...bytes));
	setResponseHeader(
		'Content-Security-Policy',
		[
			"default-src 'self'",
			`script-src 'nonce-${nonce}' 'strict-dynamic'`,
			`style-src 'self' 'nonce-${nonce}'`,
			"connect-src 'self' https://<your-backend-host>",
			"img-src 'self' data:",
		].join('; ')
	);
	return next({ context: { nonce } });
});
```

Add `cspMiddleware` to `requestMiddleware` in `src/start.ts`, creating the file
with `createStart` if your app has none. If the list also has
`consentRequestMiddleware()`, put `cspMiddleware` first. Replace
`https://<your-backend-host>` with the origin of the backend URL from your Inth
project or self-hosted backend, and add your vendors' hosts.

**2. Give the router the nonce.** `getRouter` runs on the server after the
global request middleware, so it can read the nonce from the Start context. In
the browser, TanStack Router reads it back from the
`<meta property="csp-nonce">` tag that `HeadContent` renders:

```tsx title="src/router.tsx"
import { createRouter } from '@tanstack/react-router';
import { getGlobalStartContext } from '@tanstack/react-start';

import { routeTree } from './routeTree.gen';

export const getRouter = function getRouter() {
	return createRouter({
		routeTree,
		ssr: { nonce: getGlobalStartContext()?.nonce },
	});
};
```

**3. Pass the router's nonce to ConsentRoot.** In the root component from the
[quickstart](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route),
read the nonce with `useRouter` from `@tanstack/react-router` and pass it as
`options.nonce`:

```tsx title="src/routes/__root.tsx (partial)"
const nonce = useRouter().options.ssr?.nonce;

<ConsentRoot
  state={consent}
  options={{ nonce }}
  scripts={scripts}
>
```

If you render `ConsentTheme`, pass it the same value:
`<ConsentTheme theme={theme} nonce={nonce} />`.

`ConsentRoot` reads `options.nonce` when it mounts, and the script loader
stamps it on every `<script>` it creates. A `nonce` on a single `scripts` entry
takes precedence for that element. Each full page load gets the nonce of its
own request. Do not serve nonce pages from a shared cache, because every
visitor would get the same nonce.

## What the nonce does not cover

* **Scripts that a vendor script loads itself**, such as the tags a tag manager
  injects. `'strict-dynamic'` in the policy above allows scripts that a nonced
  script adds. Without it, list each vendor's hosts in `script-src`.
* **Inline `style` attributes.** In the browser, c15t components set their
  inline styles through React, and a policy does not restrict styles set that
  way. If the console shows `Refused to apply inline style` for a
  server-rendered c15t element, add `style-src-attr 'unsafe-inline'`. A nonce
  cannot allow style attributes.
* **Iframes, images and requests** your vendors make. Add their hosts to
  `frame-src`, `img-src` and `connect-src`. A YouTube player inside
  `ConsentGate` needs `https://www.youtube-nocookie.com` in `frame-src`, for
  example.
* **The DevTools panel.** It adds a `<style>` element without a nonce, so under
  this policy it renders unstyled. Load it only in development.

## Allow the consent backend

Which consent requests the browser makes depends on your
[rendering setup](/docs/frameworks/tanstack-start/rendering):

|Setup|Browser requests|Policy|
|--|--|--|
|Quickstart|`/init` and `/subjects` on your backend URL|`connect-src` with the backend origin|
|Consent route with `createConsentStateHandler({ routePrefix: '/api/c15t' })`|`/api/c15t/init` on your origin, `/subjects` on your backend URL|`connect-src 'self'` plus the backend origin|
|Consent route with `proxy: true` on the route and on `createConsentStateHandler({ proxy: true, routePrefix: '/api/c15t' })`|Every consent request on your origin|`connect-src 'self'`|

Under an IAB TCF policy the browser also loads the Global Vendor List. With the
consent route and `routePrefix`, it comes through `/api/c15t/init`, which
`'self'` covers. Otherwise the browser fetches it from the URL the policy
provides, so allow that host in `connect-src`. See
[IAB TCF](/docs/frameworks/tanstack-start/iab).

## Prerendered pages and SPA mode

A prerendered page is the same HTML for every visitor, so it cannot carry a
per-request nonce. Use host allowlists and hashes instead:

* List `'self'` and each vendor's script host in `script-src`.
* `consentPrefetchHead` adds an inline script whose content depends only on
  its options. Load the page with the policy enforced, copy the `sha256-...`
  value from the `Refused to execute inline script` console error, and add it
  to `script-src`. Recompute it when you change the options.
* `ConsentTheme` output depends only on the theme, so a hash works for it in
  `style-src` the same way. Recompute it when you change the theme.

TanStack Start adds its own inline scripts to prerendered pages. Its
documentation covers how to allow those.

## Verify

Build the app, start the production server, and load a page with the policy
enforced, not in report-only mode. Test under a policy that asks for a choice,
such as an EU opt-in policy.

1. The banner renders with its theme colors, and the console shows no
   `Refused to` error that mentions a c15t element, your backend or a vendor.
2. In the Elements panel, `<style id="c15t-theme">` and the
   `<meta property="csp-nonce">` tag carry the same nonce as the response's
   `Content-Security-Policy` header. Browsers hide the `nonce` attribute from
   `getAttribute`, so read the element's `nonce` property in the console.
3. Before a choice, DevTools Network shows no vendor requests.
4. Click **Accept All**. The script loader's `<script>` elements, with ids starting
   `c15t-`, carry the nonce, and the vendor requests appear.
5. The save to `/subjects` succeeds. A `connect-src` violation here means the
   backend origin is missing.
6. Reload. The header has a new nonce, and the elements carry the new value.

# DevTools
URL: https://c15t.com/docs/frameworks/tanstack-start/components/dev-tools
Inspect consent state, location, loaded scripts and consent events in a TanStack Start app during development, on its own or inside TanStack Devtools.

`DevTools` is a floating panel for the c15t v3 kernel. Use it during development to inspect consent values, scripts, location, the resolved policy, IAB state, events, and consent actions. The framework adapter reads the kernel from the nearest v3 provider. It never discovers a store through a window global.

> ⚠️ **Warning:**
> Load DevTools only in development. A conditional JSX expression stops it from mounting in production, but a static import can still add DevTools to the production bundle. Use a development-only dynamic import as shown below. The component renders nothing into the React tree and mounts its panel in document.body.

## Installation

No extra package is required. The React adapter and its engine are included
with the `c15t` package. Install `@c15t/dev-tools` directly only when you
need the imperative `createDevTools({ kernel })` API.

## Render DevTools inside `ConsentRoot` in development

Render `DevTools` from `c15t/react/devtools` inside `ConsentRoot`, and load it
only in development builds with Vite's `import.meta.env.DEV`:

```tsx title="src/components/consent-devtools.tsx"
import { lazy, Suspense } from 'react';

const DevTools = import.meta.env.DEV
	? lazy(() =>
			import('c15t/react/devtools').then(({ DevTools }) => ({
				default: DevTools,
			}))
		)
	: null;

export function ConsentDevTools() {
	return DevTools ? (
		<Suspense fallback={null}>
			<DevTools />
		</Suspense>
	) : null;
}
```

If your app already renders TanStack Devtools, add `c15tDevtools()` to its
`plugins` instead, as shown below.

## Configuration

```tsx
<DevTools
  position="bottom-right"
  defaultOpen={false}
  defaultTab="consents"
  maxEvents={100}
  disabled={false}
/>
```

`position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
`bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
to choose that panel. `maxEvents` limits captured kernel and script events.
Set `disabled` to prevent mounting without removing the component. The
panel renders inside a shadow root by default, so page CSS does not reach
it. `shadow={false}` mounts it in the light DOM with its stylesheet in
`<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTriggerToolbar` or the ready-made `ConsentDialogTrigger`
is visible, the trigger shows a DevTools button and DevTools hides its own
floating launcher, so one control occupies the corner. The button sits at the
end of the toolbar farthest from its corner. The panel opens just past the
toolbar, aligned with its outer edge, and follows it when a visitor drags the
toolbar to another corner. `position` applies again once no trigger is
visible.

`ConsentDialogTrigger` becomes a two-button toolbar while DevTools is
mounted. A trigger composed from `ConsentDialogTrigger.Root` keeps its own
markup, and DevTools keeps its floating launcher beside it.

DevTools brings its launcher back whenever no trigger is visible, for example
while `showWhen="after-prompt"` waits for a choice. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

With the imperative engine, call `devTools.dock({ position, inline, block })`
to hide the launcher and anchor the panel `inline` and `block` pixels from the
viewport edges of `position`'s corner. Call `devTools.dock(null)` to restore
the launcher.

## Panels

Accept and reject apply only to categories displayed by the provider, leaving
hidden consent values unchanged. `necessary` always remains enabled. The
React adapter uses the current policy categories by default.

For an imperative integration with a narrower UI, pass
`getConsentCategories: () => ['necessary', 'measurement']` to
`createDevTools`. The getter is read again when an action runs. Headless UI
actions can use `kernel.commands.save('all', { categories: displayed })` or
`kernel.commands.save('none', { categories: displayed })`. These scoped bulk
saves use a `custom` transport action when they cover only part of the policy.
Actions covering the whole policy retain `all` or `necessary`. Without an
explicit scope or policy categories, bulk saves cover all known categories.

|Panel|What it shows|
|--|--|
|**Consents**|Inspect and save categories, accept all, or reject optional categories|
|**Scripts**|Configured scripts, loading status, search, and external page resources|
|**Location**|Resolved country and region, and location overrides|
|**Policy**|Resolved policy and UI configuration|
|**IAB**|Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings|
|**Events**|Timeline of consent changes, kernel events, and script lifecycle events|
|**Actions**|Show the banner, open preferences, hide consent UI, or refresh consent data|

### Script inspection

Set `defaultTab="scripts"` to open script inspection first. It reads all script
loaders attached to the current provider's kernel, including loaders created
before DevTools mounts. Search by script ID, category, URL, or status, then
expand a script to inspect its configuration and latest lifecycle event.

`loading` means an external script was inserted; `loaded` means its browser
load event fired, or an inline script or callback-only integration mounted.
`error` reports a loader error. `blocked` means consent requirements were not
met, and `pending` means an eligible script has not mounted. `present` means
the loader reused an element without a confirmed load result. `retained`
means consent was revoked but `persistAfterConsentRevoked` kept the element.
Retained scripts still receive `onConsentChange` with `hasConsent: false`, so
their integrations can send the vendor's consent-revocation command.
`alwaysLoad` bypasses the loading gate, not consent: callbacks receive the
actual consent state and updates across categories for integrations such as
Google Consent Mode.

Script details distinguish `allowedToLoad` from `consentGranted`. An
`alwaysLoad` integration can be allowed to load while its consent is denied.
Diagnostics expose these as `eligible` and `hasConsent`, respectively.

Lifecycle diagnostics work even when legacy debug forwarding is disabled.
The page scan lists external scripts and iframes present in the
DOM; it does not prove that they loaded successfully or were consent-gated.

For custom inspection tools, import `getScriptDiagnostics(kernel)` and
`subscribeScriptDiagnostics(kernel, listener)` from
`c15t/modules/script-loader`. The subscription reports loader
registration, updates, disposal, and lifecycle events. Read a fresh snapshot
after changes and call the returned unsubscribe function during cleanup.

### IAB editing

Under an IAB policy, the Consents tab is read-only. Edit and save vendors
and purposes in the IAB tab so the derived categories and TC string stay
consistent.

The IAB panel connects to the existing `@c15t/iab` module attached to the
provider's kernel. It does not create a second CMP or replace `__tcfapi`.
Controls become available after initialization, when the current policy uses
IAB and the vendor list is loaded.

Choose Vendors, Purposes, or Special features, then search by name or ID.
Vendors include the provider's custom vendors. Long lists show 20 entries per
page. Legitimate-interest controls appear for declared legitimate interests.
Search only filters the view; Accept all IAB and Reject all IAB apply to the
configured choices, including custom vendors.

Toggles update live IAB state and script gating immediately. Use Save IAB
consent to generate a fresh TC string and run the configured save transport.
The panel displays the last generated string; unsaved edits are not represented
in it. Copy TC string confirms success or reports clipboard failures. Raw IAB
data remains available in an expandable section.

IAB saves normally write the TC string to its standard cookie and localStorage.
For an in-memory playground, set `persistence: false` in the IAB module options
as well as disabling the provider's core persistence. The IAB option prevents
TC-string storage writes; it does not disable the configured save transport
or remove previously stored values.

Save and refresh actions show pending, success, and failure feedback. Controls
are disabled while a request is pending. A failed save does not roll back the
live choices; retry to record them.

For custom inspection tools, `getIABControls(kernel)` and
`subscribeIABControls(kernel, listener)` are exported from `c15t`.
The getter returns undefined before module initialization and after disposal.
A snapshot without an attached IAB module is read-only in DevTools.

## TanStack Devtools

Each embedded panel owns its event history and subscriptions. Unmounting it
destroys the instance; remounting starts a new history. If you need to capture
events while switching plugins, keep the c15t panel mounted. This differs from
the old globally shared DevTools store.

The React v3 DevTools adapter exports a panel component and plugin factory that match TanStack Devtools' plugin API:

```tsx
import * as React from 'react';
import { useRouter } from '@tanstack/react-router';
import { TanStackDevtools } from '@tanstack/react-devtools';
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
import { c15tDevtools } from 'c15t/react/devtools';

export function AppDevtools() {
  const router = useRouter();

  return (
    <TanStackDevtools
      plugins={[
        {
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
        {
          name: 'TanStack Router',
          render: <TanStackRouterDevtoolsPanel router={router} />,
        },
        c15tDevtools(),
      ]}
    />
  );
}
```

In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.

The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:

```tsx
import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';

const c15tPlugin = {
  name: 'Consent',
  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
    <C15tTanStackDevtoolsPanel theme={theme} />
  ),
};
```

## Props

|Property|Value|
|:--|:--|
|Type Name|\`ConsentDevToolsProps\`|
|Source Path|\`./packages/react/src/devtools.tsx\`|

\*ExtractedTypeTable: Could not extract "ConsentDevToolsProps" from "./packages/react/src/devtools.tsx" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.\*

# Troubleshooting
URL: https://c15t.com/docs/frameworks/tanstack-start/troubleshooting
Fix build-time manifest failures, a missing server-rendered banner, server function errors, proxy and firewall failures, and early vendor requests in a TanStack Start app that uses c15t.

## vite build or vite dev can't fetch the manifest

**Check.** Read the message. The `consentManifest` plugin downloads the
manifest once per build, and in `vite dev` the first time the server loads
it. When the download fails or takes longer than 10
seconds, `vite build` stops with an error that starts with
`@c15t/tanstack-start/build: could not fetch the consent manifest from <url> during the build`. `vite dev` logs the same message as a warning and keeps
going. `snapshot` from `c15t/generated` is then `undefined`, so the server
fetches the policy at runtime.

|Message|Fix|
|--|--|
|`no backend URL is set`|Set `VITE_C15T_BACKEND_URL` (or `VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass `backendURL`. `vite build` stops on this; `vite dev` warns|
|`skipped the consent manifest fetch because ... is not an absolute http(s) URL`|Set `VITE_C15T_BACKEND_URL` to the absolute backend URL, such as `https://your-project.inth.app`, not `/api/c15t`. With `onBuildError: 'fail'`, this is the error `build-time manifests require an absolute upstream URL`|
|`/manifest responded 404`|The URL is not a c15t backend, or it is missing a path prefix. Copy the backend URL from Inth exactly|
|`/manifest responded` with another status|The backend refused or failed the request. Check that the project exists and that the build machine can reach it|
|`/manifest returned an invalid consent manifest`|The URL answered with something other than a c15t manifest, such as an HTML page. Check the URL|
|`fetch failed`, with `ENOTFOUND` or another network error, or `no response within 10 seconds`|The build machine cannot reach the backend. Allow the request. To deploy while the backend is down, build with `C15T_ON_BUILD_ERROR=runtime`, or switch to [runtime fetching](/docs/frameworks/tanstack-start/rendering#await-consent-in-the-loader)|

## snapshot is undefined

**Check.** Log `snapshot` from `c15t/generated` in the server function. In the
browser bundle it is always `undefined`: the plugin keeps the policy on the
server. On the server, it is `undefined` when Vite had no policy to serve:
`consentManifest` is missing from `plugins` in `vite.config.ts`, the fetch
failed in `vite dev` or in a build with `C15T_ON_BUILD_ERROR=runtime`, or the
backend URL is relative.

**Fix.** `createConsentStateHandler` and `createConsentRoute` read the
snapshot themselves, so most apps never import it. On the server, add the
plugin or fix the
[fetch error](#vite-build-or-vite-dev-cant-fetch-the-manifest), then restart
`vite dev` or rebuild. While `snapshot` is `undefined`, the
server fetches and caches the policy at runtime.

## The banner is not in the server HTML

**Check.** View the page source under a policy that asks for a choice. Look for
`data-testid="consent-banner-root"`.

|Cause|Fix|
|--|--|
|The root loader streams the consent promise and sets `streamBanner: false`|Expected. The banner mounts after hydration. Remove the option, or await the server function; see [rendering](/docs/frameworks/tanstack-start/rendering)|
|The page is prerendered or the app runs in SPA mode|Expected. The browser resolves consent after the page loads|
|With runtime fetching, the backend took longer than 500 ms, often on the first request after a start|The server rendered without consent and the browser resolved it. Later requests use the cached manifest. Raise `timeoutMs` in `createConsentStateHandler` if needed|
|No country header reaches the server|Check that your host or CDN adds a geo header; [geography headers](/docs/frameworks/tanstack-start/geography-headers) lists the ones c15t reads. Without one the visitor gets your fallback policy|
|The visitor has a stored choice|Expected. The server reads the `c15t` cookie and renders no banner|

## The server function fails to resolve at runtime

**Check.** Find where you call `createServerFn()`. Start's compiler
identifies each server function by the file and the top-level assignment where
you call it, so a call inside a package, a function or a conditional fails.

**Fix.** Declare `const getConsentState = createServerFn(...).handler(createConsentStateHandler())`
at the top level of your own route module, as in the
[quickstart](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route).

## A serialization error mentions a function

**Check.** Look at what your server functions and loaders return. Something
with functions in it, such as vendor script configurations or a `hosted()`
transport from `c15t/react`, cannot be serialized. `hosted()` from
`c15t/tanstack-start` is plain data and can be returned.

**Fix.** Return only the consent state from the server function. Import
`scripts` in the root route module and pass them to `ConsentRoot` there.

## The same-origin setup never renders the banner on the server

**Check.** Look at the `backendURL` you pass to `createConsentStateHandler`,
or `VITE_C15T_BACKEND_URL`. When it is `/api/c15t`, the helper skips the fetch
and returns only the cookie and header state, because a server that fetches
its own route during a render can stall.

**Fix.** Keep `VITE_C15T_BACKEND_URL` absolute, and don't pass `backendURL: '/api/c15t'`. To send the browser's requests through the route, pass
`routePrefix: '/api/c15t'` and `proxy: true` to `createConsentStateHandler`
instead.

## Saves through /api/c15t fail with 403 or a challenge page

**Check.** The backend's firewall blocks the proxied `POST /subjects`. A
server cannot solve a browser challenge, such as Vercel Attack Challenge Mode
or Cloudflare Super Bot Fight Mode.

**Fix.** Exempt the consent paths from the challenge. Requests from the route
carry an `x-c15t-proxy: @c15t/tanstack-start` header you can match in a
firewall rule. If rate limits treat every visitor as one IP address, and your
host overwrites `x-forwarded-for`, set `trustForwardedHeaders: true` on
`createConsentRoute`.

## The browser calls /api/c15t/init and gets a 404

**Check.** `ConsentRoot` calls `/api/c15t/init` only when the state carries
`routePrefix: '/api/c15t'`, from `createConsentStateHandler`. Confirm that the
app mounts the consent route at `src/routes/api/c15t/$.ts`.

**Fix.** Mount the
[same-origin route](/docs/frameworks/tanstack-start/rendering#keep-consent-requests-on-your-origin),
or remove `routePrefix`, so the browser calls your backend directly. Earlier
alphas sent init to `/api/c15t/init` by default; now there is no default.

## ConsentRoot throws that it needs a backend URL

**Check.** The page throws one of these errors from `ConsentRoot`:

* `` c15t: manifest() needs a backend URL. Set `backendURL` in your config. ``
* `` c15t: hosted() needs a backend URL. Set `backendURL` on the mode or in your config. ``

The state names no backend URL and `consentManifest()` supplied none, for
example on a page with `state={{}}` and no plugin in `vite.config.ts`.

**Fix.** Add `consentManifest()` to `vite.config.ts` and set
`VITE_C15T_BACKEND_URL` (or `VITE_INTH_PROJECT_URL`). Earlier alphas fell back to offline mode here; now
the root throws. To run without a backend, pass `mode: offline()` to
`createConsentStateHandler`, or `state={{ mode: offline() }}`.

## A vendor loads before the visitor chooses

**Check.** Search route `head()` definitions, your root component and any tag
manager for the vendor's script or SDK initializer.

**Fix.** Remove every loader except the one in `ConsentRoot`'s `scripts`. c15t
only gates scripts registered with it.
[Scripts and embeds](/docs/frameworks/tanstack-start/scripts) covers the
options.

## The page throws that no IABProvider is mounted

The visitor's policy uses the `iab` model and the backend sent its vendor
list, but no `IABProvider` is mounted. The standard banner and dialog do
not handle the IAB model, so they throw rather than leave the visitor
with no consent UI. Server and browser render the same error.

Fix it one of two ways:

* If the site uses IAB TCF, render `IABProvider` with `IABConsentBanner`
  and `IABConsentDialog` from `c15t/react/iab` inside your consent
  provider. They can sit next to the standard banner.
* If it does not, remove the `iab` model from the policy for that region
  in your Inth project or policy pack.

A backend that answers `gvl: null` turns IAB off for that request. The
policy then runs as opt-in and nothing throws.

The check passes once `c15t/react/iab` has loaded. If you import the IAB
components with a dynamic `import()`, a render of the standard banner
that happens before the import finishes still throws.

## Inspect the active policy

Render this component inside `ConsentRoot`. It reads state and records no
choice:

```tsx title="src/components/consent-policy-debug.tsx"
import { useSnapshot } from 'c15t/tanstack-start';

export function ConsentPolicyDebug() {
	const snapshot = useSnapshot();
	const resolution = snapshot.resolution;

	return (
		<pre>
			{JSON.stringify(
				{
					status: resolution.status,
					policy: resolution.status === 'matched' ? resolution.policy.id : null,
					prompt: snapshot.promptRequirement,
					location: snapshot.location,
				},
				null,
				2
			)}
		</pre>
	);
}
```

`location` shows the country and region the server resolved. Remove the
component after you finish.

## Names from an earlier alpha are missing

**Check.** TypeScript or the build reports a missing export or option, such as
`createConsentServerRoute`, `DEFAULT_INIT_ROUTE` or `ConsentRoot`'s
`backendURL` prop. The v3 alphas removed names that never shipped in a stable
release, with no alias.

**Fix.** Use the current names:

|Removed|Use instead|
|--|--|
|`ConsentRoot`'s `backendURL` and `routePrefix` props|`createConsentStateHandler({ routePrefix })`. The state carries the backend URL, the mode and the route prefix.|
|`ConsentRoot`'s `initRoute` prop, and `DEFAULT_INIT_ROUTE`|`createConsentStateHandler({ routePrefix: '/api/c15t' })`. There is no default route any more.|
|`createConsentServerRoute`, and its `manifestGET`, `initGET` and `proxyHandler`|`createConsentRoute()`, which returns `GET`, plus the write methods with `proxy`|
|`createConsentStateHandler({ backendURL, manifest })`|`createConsentStateHandler()`, which reads both from `consentManifest()`, or `{ snapshot }`|
|`manifestURL` on the state handler|`mode: manifest({ manifestURL })`|
|`ConsentManifestOptions`, `resolveStrictestDefaultInit`|`ResolveConsentOptions`; `resolveUnknownLocationInit`|
|Falling back to offline mode when no backend URL is set|`ConsentRoot` throws. Pass `mode: offline()` to run without a backend.|
|`hosted`, `offline` and `manifest` from `c15t/tanstack-start` as transports|They are data for `createConsentStateHandler({ mode })` now.|

The renames shared by every framework:

|Removed|Use instead|
|--|--|
|`hosted({ url })`|`hosted({ backendURL })`, or the framework's backend URL variable|
|`createManifestTransport({ manifest })`|`createManifestTransport({ snapshot })`|
|`assertDecisionInputs` defaulting to `false` on `hosted()`|It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.|
|`hostedModes` from `c15t/runtime/provider`|`readHostedMode(mode)`|
|`buildManifest: true` in Astro and Nuxt|`onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`.|
|A generated `c15t-manifest.ts` and its `.gitignore` entry|`import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.|
|The build options `outputFile`, `exportName`, `importSource` and `rootDir`|Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.|

`Frame` and its parts still work, with a one-time warning outside production.
Use `ConsentGate` instead.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/react/quickstart
Add a consent banner, preferences dialog and consent-gated scripts to a React single-page app built with Vite, using Inth as the consent backend.

## Before you start

This guide sets up a client-rendered React app built with Vite. The build
bundles your project's public policy. The browser loads the page, resolves the
visitor's policy from that bundle, then shows the banner or runs the scripts
the visitor allowed. Regional policies may still need a backend location
request.

* **Next.js or TanStack Start?** Use that framework's guide from the
  [framework list](/docs/frameworks). Their adapters resolve consent on the
  server.
* **React Router framework mode, Remix or another server-rendered React app?**
  This guide still works. The server renders the page without consent state and
  the browser resolves it after hydration. Read
  [rendering](/docs/frameworks/react/rendering#react-router-remix-and-other-server-rendered-apps)
  for what that means for the first paint.

You need an [Inth](https://inth.com) project. In the project, set the policy
rules for your regions, add your site's origin to the trusted origins, and copy
the backend URL.
[Choose your setup](/docs/concepts/choose-your-setup#decide-who-runs-the-consent-backend)
covers self-hosting and offline mode.

Bundling the policy at build time is the recommended production setup.
Rebuild after changing policies, translations or vendors.

## Install c15t

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

`c15t` contains the React adapter at `c15t/react` and the Vite plugin at
`c15t/build`. `@c15t/integrations` holds the vendor loaders used below.

## Bundle your policy

Add `consentManifest` to `vite.config.ts`:

```ts title="vite.config.ts"
import react from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/build';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [react(), consentManifest()] });
```

The plugin reads `VITE_C15T_BACKEND_URL`. Set it to your project's backend URL,
exactly as Inth shows it, including any path prefix, in `.env` or wherever you
build:

```sh title=".env"
VITE_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `VITE_C15T_BACKEND_URL` wins.

`consentManifest` downloads your project's public policy from `/manifest`
during `vite build`, or in `vite dev` when the app first loads it, and serves
it to your app as `snapshot`
from `c15t/generated`. No file is written into your project.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

## Mount the provider

Create `src/consent.tsx`. `ConsentProvider` creates the consent runtime and
loads the scripts. `ConsentBanner` and `ConsentDialog` render when the policy
asks for them, and `ConsentDialogLink` keeps preferences reachable after the
banner closes.

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

`manifest()` resolves the policy from the bundled snapshot in the browser,
with no `/manifest` request. It reads the snapshot and the backend URL from
what `consentManifest` downloaded. Consent choices go to that backend, and so
does an `/init` request when the policy depends on the visitor's country or
region and the browser does not know it. That request returns the backend's
current policy, which can be newer than the snapshot. Vite reads
`VITE_C15T_BACKEND_URL` at build time, so set it before you build, not when
you serve the files.

To apply policy edits without rebuilding, use `hosted()` from `c15t/react` as
the mode. The browser then requests the policy from `/init` on every page load.
[Consent modes](/docs/concepts/modes) compares the three modes.

PostHog waits for measurement permission, so your policy must include that
category. Replace `phc_your_project_key` with your PostHog project key.
PostHog uses its EU host; add `region: 'us'` for a US project. Remove any
other PostHog loader from your app so PostHog loads once.

`loadMode: 'after-consent'` keeps the PostHog SDK off the page until the
visitor allows measurement. `cookieless_mode: 'never'` turns off PostHog's
cookieless capture. See [integrations](/docs/integrations/overview) for other
vendors.

Wrap your app with it in `src/main.tsx`:

```tsx title="src/main.tsx"
import { createRoot } from 'react-dom/client';

import { App } from './app';
import { Consent } from './consent';

const root = document.getElementById('root');
if (!root) {
	throw new Error('Missing #root element');
}
createRoot(root).render(
	<Consent>
		<App />
	</Consent>
);
```

Keep `Consent` mounted for the life of the app. If you use a client-side
router, render the router inside `Consent` so navigation does not remount the
provider. There is no stylesheet to import: the banner and dialog render their
own rules as `<style>` elements.

## Gate your own features

Read a category's permission with `useConsent` inside the provider:

```tsx title="src/marketing-banner.tsx"
import { useConsent } from 'c15t/react';

export function MarketingBanner() {
	return useConsent('marketing') ? <aside>Spring sale</aside> : null;
}
```

`useConsent` returns the permission right now. Under an opt-out policy it can be
`true` before the visitor has chosen anything. Read
[how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
before you record or report choices. For iframes, use
[`ConsentGate`](/docs/frameworks/react/components/consent-gate).

## Check that it works

Build and preview the production bundle with `vite build` and `vite preview`,
then open the site in a private window with DevTools open on the Network tab.
Test under a policy that asks for a choice, such as an EU opt-in policy.

1. **Before a choice.** The banner shows, with no `/manifest` request. There
   are no requests to `posthog.com`.
2. **Reject All.** The banner closes and the vendor requests stay absent.
3. **Reload.** The banner stays closed and the vendor requests stay absent.
4. **Privacy settings.** The footer link opens the dialog with **Analytics** (the
   `measurement` category) and **Marketing** off. Turn on **Analytics** and
   save. PostHog's `array.js` loads.
5. **Turn Analytics off again.** The page reloads and PostHog does not load.

If the banner never appears, check the generated policy and any location
request to `/init` on your backend URL. [Troubleshooting](/docs/frameworks/react/troubleshooting)
covers the common causes. [Verify consent](/docs/guides/verify-consent) has the
full release checklist.

## Next steps

* [Rendering](/docs/frameworks/react/rendering) for server-rendered React apps and
  what the first paint contains.
* [Scripts and embeds](/docs/frameworks/react/scripts) for more vendors, network
  blocking and data cleanup.
* [Customize](/docs/frameworks/react/customize) for colors, fonts, layout and copy.
* [Components](/docs/frameworks/react/components/consent-provider) for
  every provider option and component prop.
* The runnable app in `examples/react` of the
  [c15t repository](https://github.com/c15t/c15t) contains this setup.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/react/rendering
How c15t resolves consent in client-rendered React apps, React Router framework mode, Remix and other server-rendered React apps without a c15t adapter.

## Pick your rendering path

`c15t/react` resolves consent in the browser. That works for every React app,
including server-rendered ones. What changes is what the first HTML contains.

|Your app|Where consent resolves|Setup|
|--|--|--|
|Vite, or another client-rendered single-page app|Browser, after the bundle loads|[Quickstart](/docs/frameworks/react/quickstart)|
|Prerendered or static HTML|Browser, after the page loads|[Quickstart](/docs/frameworks/react/quickstart), see [static pages](#static-and-prerendered-pages)|
|React Router framework mode, Remix, or another server-rendered React app|Browser, after hydration|[Quickstart](/docs/frameworks/react/quickstart), see [server-rendered apps](#react-router-remix-and-other-server-rendered-apps)|
|Next.js or TanStack Start|Server, per request|That framework's guide in the [framework list](/docs/frameworks)|

Pick the Next.js or TanStack Start adapter if you use those frameworks. They
read the visitor's cookie and location on the server, so the banner can be in
the first HTML. [Choose your setup](/docs/concepts/choose-your-setup#server-rendering-or-browser-rendering)
explains the difference in general terms.

## Bundle the manifest during Vite builds

The [quickstart](/docs/frameworks/react/quickstart) and `examples/react` in
the c15t repository use this setup.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Add `consentManifest` to your existing Vite plugin list:

```ts title="vite.config.ts (plugins option)"
import { consentManifest } from 'c15t/build';

export default {
	plugins: [
		// Keep your existing framework plugins here.
		consentManifest({ backendURL: 'https://your-project.inth.app' }),
	],
};
```

Without `backendURL`, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`. The plugin
fetches the policy during `vite build`, or in `vite dev` when the app first
loads it, and serves it as `snapshot` from `c15t/generated`. A build fetches
only when the app uses `manifest()`. In `src/consent.tsx`, create the
provider's mode with `manifest()` from `c15t/react` instead of `hosted()`. It
reads the snapshot and the backend URL from `c15t/generated`:

```tsx title="src/consent.tsx"
import { manifest } from 'c15t/react';

const mode = manifest();
```

Keep passing `mode` to `ConsentProvider`. The browser resolves the snapshot
without `/manifest` when it has the geography the policy needs, or the policy
does not depend on geography. Supply known country and region through `inputs`
or overrides to keep regional resolution on the snapshot.

When the build has no snapshot, as in `vite dev` after a failed fetch,
`snapshot` is `undefined`, and the browser fetches
`${backendURL}/manifest` instead.

When the required country or region is missing, the transport calls backend
`/init` and uses its resolved policy and translations. `consentManifest` warns
during the build when it downloads such a policy, and suggests `hosted()`. That response can use
newer backend policy than the build snapshot. This is a full consent resolution,
so these visitors still wait for a backend round trip. `ConsentProvider` sends
that request while it first renders, before the page mounts, unless the visitor
has a stored choice.

The browser cannot guess the banner from the snapshot alone when locations
differ. With a European opt-in rule and no banner elsewhere, a banner shown
before `/init` answers would vanish for most of the world. The exception is a
policy whose country and region rules all show the same banner, with a default
rule that covers everywhere else: the browser resolves it at once. To skip the
round trip for location-specific rules, pass the country your CDN or edge
already knows through `inputs`.

Policy and resolver code are part of the browser bundle.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy updates without a rebuild, use `hosted({ backendURL })` from `c15t/react`
as the mode and omit the build plugin. That setup resolves policy through the
backend `/init` on each page load.

## Client-rendered apps

The recommended [quickstart](/docs/frameworks/react/quickstart) bundles the
manifest and resolves it in the browser. See [build-time manifests](#bundle-the-manifest-during-vite-builds).

For policy updates without rebuilding, use `hosted()` from `c15t/react` as
the mode. It reads the backend URL `consentManifest` read from
`VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`; without the plugin, pass
`hosted({ backendURL })`.
That runtime path works as follows:

1. The page loads with no consent state. Every optional category is denied.
2. `ConsentProvider` requests `GET /init` from your backend URL while it first
   renders, before the page paints. The backend picks the visitor's policy
   from their location. With an `experiment`, the request waits until the
   provider mounts, because it carries the visitor's arm.
3. The provider applies the policy and any stored choice. It shows the banner
   if the policy asks for one, and loads the scripts the visitor allowed.

Until step 3 finishes, gated scripts and `ConsentGate` embeds stay blocked. If
the backend request fails, they stay blocked and no banner shows.

## React Router, Remix and other server-rendered apps

React Router framework mode, Remix and similar frameworks have no c15t adapter.
Use the quickstart's `Consent` component and render it in your root component,
around the outlet. In React Router framework mode that is `app/root.tsx`.

`ConsentProvider` renders on the server without touching browser APIs, and the
browser takes over after hydration:

* The server HTML contains your page but no banner and no consent state.
* After hydration the browser resolves the bundled manifest, then shows the
  banner if the policy asks for one. When the banner depends on a country or
  region the browser does not know, it calls `/init` and uses the backend's
  current policy and translations, which can differ from the build snapshot.
  With `hosted()`, it always calls `/init`.
* The server render and the first browser render agree, so hydration does not
  warn or change a stored choice.

The Vite setup needs no change. The banner renders in the browser and brings
its own `<style>` element, so there is no stylesheet to import.

### Skip the browser's first init request

This is optional. `fetchSSRData` from `c15t/react/server` calls the backend's
`/init` from your server loader, forwarding the visitor's location and
language headers. Pass the result to the browser, wrap it in a promise and give
it to `hosted({ backendURL, initialData })`. The provider's first init then uses that
response instead of a network request.

Know its limits before you add it:

* It saves the browser's round trip to the backend. It does not put the banner
  in the server HTML; the banner still mounts after hydration.
* Every page view makes a server-to-server `/init` request. Do not cache the
  loader response, because it contains one visitor's policy.
* It returns `undefined` when the request has no location or language headers,
  and the browser then requests `/init` as usual.
* `mode` is read once, when the provider mounts. Create the `hosted()` mode once
  in the browser rather than on every render.
* A relative `backendURL` resolves against the request's `host` header, over
  `https` for a domain name and over `http` for `localhost`, an IP address or
  a single-label host. `fetchSSRData` ignores `x-forwarded-host`,
  `x-forwarded-proto` and `forwarded`, and does not send them to the backend.
  Behind a proxy that overwrites those headers, pass
  `trustForwardedHeaders: true` to use them.
* If your server answers requests for any `Host` header, such as a Node server
  exposed directly or a proxy that forwards `Host` from its default virtual
  host, pass `fetchSSRData` an absolute `backendURL`. A relative one resolves
  against whatever `Host` the request sent.

### Render the banner in the server HTML

c15t has no framework-neutral helper for this. `ConsentProvider` accepts a
server-resolved `prefetch` state, but the Next.js and TanStack Start adapters
build that state from the request's cookie, headers and a cached policy
manifest. Building it by hand ties your app to internal shapes. If the banner
must be part of the first paint, use one of those adapters. Otherwise keep the
browser path.

## Static and prerendered pages

A prerendered page is the same HTML for every visitor, so it cannot contain one
visitor's consent. Use the quickstart's build-time snapshot. Consent saves and
any `/init` requests go to the backend URL directly, so the static host
needs no server route. Add the site's
origin to the trusted origins in your Inth project.

Do not cache a response that contains a visitor's consent in a CDN or a shared
page cache. [Data fetching](/docs/concepts/data-fetching) covers what is safe to
cache.

## Where the browser sends requests

With `hosted()`, the browser calls two backend endpoints:

|Request|When|
|--|--|
|`GET {url}/init`|Once per page load, to resolve the policy|
|`POST {url}/subjects`|When the visitor accepts, rejects or saves|

With a bundled manifest, `manifest()` sends the same
`/subjects` request, and requests `/init` only when the policy depends on a
country or region the browser does not know.

These requests go to the backend's origin, so it must list your site as a
trusted origin.
[Data fetching](/docs/concepts/data-fetching) compares this with proxies and
custom transports.

## Check the rendering path

1. Open the page in a private window and view the page source. In a
   server-rendered app the HTML contains your content and no element with
   `data-testid="consent-banner-root"`.
2. In DevTools Network, confirm there is no `/manifest` request with a
   build-time snapshot. A regional policy may still need an `/init` request
   to resolve consent when geography is missing. With `hosted()`, one `/init`
   request runs unless you supply `initialData`.
3. The banner appears once the policy resolves. Vendor requests stay absent
   until you allow their category.

# Upgrade from v2
URL: https://c15t.com/docs/frameworks/react/upgrade-v3
Upgrade a React app from c15t v2 (@c15t/react) to v3. Covers packages, ConsentProvider and transports, the useConsentManager codemod, callbacks, policies, styles, IAB and stored consent.

**Upgrade this React app to c15t v3**

Paste into Claude Code, Codex, Cursor or another coding agent at the root of your app.

```prompt
Upgrade this React app from c15t v2 to c15t v3.

Read [https://v3.c15t.com/docs/frameworks/react/upgrade-v3.md](https://v3.c15t.com/docs/frameworks/react/upgrade-v3.md) first and follow it in order. Do not guess v3 APIs from memory.

1. List every c15t dependency and import: `@c15t/react`, `@c15t/scripts`, `@c15t/dev-tools` and `c15t`.
2. Check that React is 18 or later. Stop and tell me if it needs a major upgrade.
3. Replace the packages with `c15t@alpha`, plus `@c15t/integrations@alpha` if the app uses vendor helpers.
4. Run `npx @c15t/cli@alpha codemods packages-to-c15t consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks scripts-to-integrations dev-tools-to-c15t policy-packs-to-policy-rules callbacks-to-v3 theme-to-consent-theme iab-option-to-iab-provider css-variables-to-v3 postcss-tailwind3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
5. Check that `ConsentManagerProvider` is now `ConsentProvider` from `c15t/react`, with a transport such as `hosted()` as `mode`. Finish any custom mode the codemod marked.
6. Update callbacks, policy presets, renamed options and components, theme CSS, CSS variables and IAB setup as the guide describes.
7. Keep the existing backend URL. If the app runs its own c15t backend, stop and tell me, because it has to be upgraded in the same release with [https://v3.c15t.com/docs/self-host/upgrade-v3.md](https://v3.c15t.com/docs/self-host/upgrade-v3.md).
8. Run the typecheck and build, and resolve every `TODO(c15t v3)` comment.

When you finish, list the files you changed, anything you could not migrate, and how you checked that vendor requests still wait for consent.
```

## Before you start

* Upgrade React and React DOM to 18 or later.
* If you run your own c15t backend, upgrade it in the same release. A v3
  client can't read a v2 backend. See
  [Upgrade a self-hosted backend](/docs/self-host/upgrade-v3).
  Inth-hosted backends need no change.

## Replace the packages

Remove `@c15t/react` and `@c15t/scripts`, then install `c15t` from the
`alpha` dist-tag. npm's default tag still resolves v2.

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

Drop `@c15t/integrations@alpha` if you don't use its vendor helpers.

|v2 import|v3 import|
|--|--|
|`@c15t/react`|`c15t/react`|
|`@c15t/react/headless`|`c15t/react/headless`|
|`@c15t/react/styles.css`|Nothing: remove the import. Keep `c15t/react/styles.css` only with `styles: false`|
|`DevTools` from `@c15t/dev-tools/react`|`DevTools` from `c15t/react/devtools`|
|`@c15t/scripts/*`|`@c15t/integrations/*`|

The `packages-to-c15t` codemod rewrites the `@c15t/react` imports and removes
the stylesheet import. It doesn't edit `package.json`.

`@c15t/react` is still published at v3, so its imports keep working if you pin
it to `@alpha`. These docs use `c15t/react`.

Every v3 package ships ESM only. If a CommonJS file in your app calls
`require()` on a c15t package, convert it to ESM.

## Rename the integrations dependency

v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts`
from your dependencies and install `@c15t/integrations` from the `alpha`
dist-tag:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

Replace the package name in each import. Vendor subpaths and helper names stay
the same.

Before, in v2:

```ts
import { googleTagManager } from '@c15t/scripts/google-tag-manager';
import { posthog } from '@c15t/scripts/posthog';
```

After:

```ts
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { posthog } from '@c15t/integrations/posthog';
```

The `scripts` configuration option and the `Script` type keep their names.

Two helper behaviors change. A helper that needs an ID, such as `metaPixel`,
`googleTagManager` or `posthog`, now logs an error and skips its script when
the ID is empty or only whitespace, where v2 loaded a broken script. And if
your code reads `@c15t/integrations/registry`, an entry's `consentCategory` can
now be a compound condition such as `{ and: ['marketing', 'measurement'] }`,
not only a category name.

`@c15t/scripts` stays available as a deprecated compatibility package for all
of v3. It re-exports the implementation and types of `@c15t/integrations`, so
you can migrate imports separately from the rest of the upgrade. Compatibility
ends in v4; versions already published stay on npm.

To preview the import changes in JavaScript and TypeScript files:

```bash
npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
```

Review the output, then run it again without `--dry-run`. The codemod runs
only when you name it. It does not change `package.json`, lockfiles, or
imports inside `.vue`, `.svelte` or `.astro` files; update those by hand, then
reinstall dependencies and build the app.

## Replace `useConsentManager()`

`useConsentManager()` returned the whole consent state, so every component
that called it re-rendered on every change. v3 has one hook per field. Run the
codemod first:

```bash
npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
```

Review the proposed files, then run it again without `--dry-run`. For this v2
component:

```tsx title="Before (v2): components/accept-button.tsx"
import { useConsentManager } from '@c15t/react';

export function AcceptButton() {
	const { activeUI, has, saveConsents } = useConsentManager();
	if (activeUI !== 'banner' || has('marketing')) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

the codemod writes:

```tsx title="After (v3): components/accept-button.tsx"
import { useActiveUI, useConsent } from '@c15t/react';
import { useHeadlessConsentUI } from '@c15t/react/headless';

export function AcceptButton() {
	const activeUI = useActiveUI() ?? 'none';
	const hasMarketing = useConsent('marketing');
	const { saveCustomPreferences: saveConsents } = useHeadlessConsentUI();
	if (activeUI !== 'banner' || hasMarketing) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

The codemod keeps the entry you imported from. Change `@c15t/react` to
`c15t/react` afterwards if you moved to the umbrella package. Fields it cannot
rewrite stay on a `useConsentManager()` call under a `TODO(c15t v3)` comment,
which fails the build until you replace them. The table lists the v2 fields
components read. The other fields held provider configuration, such as
`legalLinks`, `scripts` and `storageConfig`, or store internals; set
configuration through `ConsentProvider` props.
Import hooks from `c15t/react`, `c15t/next` or `c15t/tanstack-start`, and
`useHeadlessConsentUI` from the matching `/headless` entry.

|v2 field|v3 replacement|
|--|--|
|`activeUI`|`useActiveUI()`. It returns `null` until c15t picks a surface, where v2 returned `'none'`.|
|`setActiveUI(ui)`|`useSetActiveUI()`|
|`has(category)`|`useConsent(category)`, one call per category at the top of the component|
|`consents`|`useConsents()`|
|`saveConsents('all')`|`useHeadlessConsentUI().saveCustomPreferences('all')`|
|`saveConsents('necessary')`|`useHeadlessConsentUI().saveCustomPreferences('none')`|
|`saveConsents('custom')`|`useConsentDraft().save()`, or `useHeadlessConsentUI().saveCustomPreferences()` inside a `ConsentDraftProvider`|
|`selectedConsents`|`useConsentDraft().values`|
|`setSelectedConsent(name, value)`|`useConsentDraft().set(name, value)`|
|`setConsent(name, value)`|`useSaveConsents()`, called with `{ [name]: value }`|
|`consentInfo`|`useExplicitChoice()`|
|`hasConsented()`|`useExplicitChoice() !== null`|
|`consentCategories`, `consentTypes`, `getDisplayedConsents()`|`useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`|
|`policyCategories`|`usePolicyCategories()`. The v2 list started with `'necessary'`; this one does not.|
|`policyScopeMode`|`usePolicyScopeMode()`|
|`policyBanner`|`usePromptPresentation()`|
|`policyDialog`|`usePreferencesPresentation()`|
|`model`|`useModel()`. It returns `null` while no policy matches, where v2 returned `'opt-in'`.|
|`branding`|`useBranding()`. It returns `null` when unset, where v2 returned `'c15t'`.|
|`iab`|`useIABSnapshot()`|
|`locationInfo`|`useLocation()`|
|`overrides`, `setOverrides()`|`useOverrides()`, `useSetOverrides()`|
|`setLanguage()`|`useSetLanguage()`|
|`user`, `identifyUser()`|`useUser()`, `useIdentify()`|
|`translationConfig`|`useTranslations()` for the active strings|
|`subscribeToConsentChanges(listener)`|`useSubscribeToConsentChanges()`, or the `onPermissionsChanged` callback|
|`updateConsentCategories(categories)`|`useRegisterConsentCategories()`|
|`manager`|Nothing. Use the hooks above.|

`saveCustomPreferences()` saves the way the stock buttons do. It closes the
banner or dialog after a successful save. `useSaveConsents()` calls the engine
directly and does not close anything.

In v2, `useConsentManager()` kept one draft per component. In v3,
`useConsentDraft()` and `useHeadlessConsentUI()` share a draft only inside a
`ConsentDraftProvider`. Without one, `saveCustomPreferences()` saves a fresh
draft and ignores what `useConsentDraft().set()` staged, even in the same
component. Save with `useConsentDraft().save()`, or render the code that stages
and the code that saves inside one `ConsentDraftProvider`. `ConsentWidget`
already includes one. The codemod
adds a `TODO(c15t v3)` comment where this applies.

## Replace `ConsentManagerProvider`

Swap `ConsentManagerProvider` for `ConsentProvider` from `c15t/react`, and pass
a transport as `mode`:

|v2 option|v3 option|
|--|--|
|`mode: 'hosted'` with `backendURL`|`mode: hosted({ backendURL })`|
|`mode: 'offline'` with `offlinePolicy`|`mode: offline({ policyRules })`|
|`mode: 'custom'` with `endpointHandlers`|`mode: custom(transport)`, where `transport` implements the v3 transport interface. `endpointHandlers` throws.|

```tsx title="After (v3): the provider, changed lines"
import { ConsentBanner, ConsentDialog, ConsentProvider, hosted } from 'c15t/react';

// Replace ConsentManagerProvider:
<ConsentProvider
  options={{ mode: hosted({ backendURL: 'https://your-project.c15t.dev' }) }}
>
```

The `consent-provider-options` codemod rewrites the hosted and offline modes
and adds the transport import. It can't translate `endpointHandlers`, so it
leaves a `TODO(c15t v3)` comment on a custom mode:

```bash
npx @c15t/cli@alpha codemods consent-provider-options --dry-run --json
```

Keep your backend URL. An existing hosted URL such as
`https://your-project.c15t.dev` keeps working with v3 clients. New Inth
projects use URLs such as `https://your-project.inth.app`. The
[React quickstart](/docs/frameworks/react/quickstart) shows the full provider,
and [data fetching](/docs/concepts/data-fetching) covers custom transports.

v3 also adds `manifest()`, which the quickstart uses: `consentManifest()` from
`c15t/build` downloads the policy when Vite builds, and the browser resolves it
without asking `/init`. `manifest()` and `hosted()` then read the backend URL
from `VITE_C15T_BACKEND_URL`, so they need no arguments. See
[consent modes](/docs/concepts/modes).

Offline mode keeps choices in the browser and records nothing on a server. Not
recommended for production environments.

If your app renders on the server with React Router or Remix, the banner still
mounts after hydration, as in v2. `fetchSSRData()` from `c15t/react/server`
can save the browser its first `/init` request. See
[rendering](/docs/frameworks/react/rendering).

## Replace callbacks

Callbacks stay under `callbacks` in your options, with new names:

|v2 callback|v3 callback|
|--|--|
|`onConsentSet`|`onPermissionsChanged` to react to what may run now. `onChoiceRecorded` to react to the visitor's accept, reject or save.|
|`onConsentChanged`|`onChoiceRecorded`. See the note below the table.|
|`onBannerFetched`|No callback. In React and Next.js, read `usePolicyResolution()` to know when the policy has resolved. In JavaScript, read `resolution` from the kernel snapshot.|
|`onError`, `onBeforeConsentRevocationReload`|Unchanged|

The `callbacks-to-v3` codemod renames `onConsentChanged` to
`onChoiceRecorded`. It leaves a `TODO(c15t v3)` comment there about the new
payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
replacement for:

```bash
npx @c15t/cli@alpha codemods callbacks-to-v3 --dry-run --json
```

v2's `onConsentChanged` fired only when a save changed at least one category's
value, and passed `preferences` and `previousPreferences`. v3's
`onChoiceRecorded` fires for every accept, reject or save that confirms a
category, including one that saves the same values again, because each save
renews the choice's confirmation time. Its payload carries `snapshot`,
`confirmed` and `actionAt`. v3 has no callback that fires only when a save
changes a value. If you need the before and after values, use
`onPermissionsChanged`: it passes `previous` and the new `snapshot` whenever
effective permissions change, whether a save or something else changed them.

v2's `onConsentSet` also fired on initialization and hydration. In v3,
`onChoiceRecorded` runs only when the visitor acts, and `onPermissionsChanged`
runs when effective permissions change for any reason, including expiry, a
policy update or a privacy signal. Neither runs at startup if the resolved
permissions match the defaults, such as an opt-in policy that leaves every
category denied. If an external API needs the starting state, read it once at
startup as well: in React and Next.js from `useEffectivePermissions()` in an
effect, which also runs on later changes, and in JavaScript from
`kernel.events.on('init:applied', ({ snapshot }) => ...)`.

```ts title="After (v3): callbacks in your options"
callbacks: {
  onChoiceRecorded(event) {
    console.log('Visitor recorded a choice', event);
  },
  onPermissionsChanged(event) {
    console.log('Effective permissions changed', event);
  },
},
```

## Move policy packs to policy rules

v2 policy packs become policy rules, and `policyPackPresets` becomes
`policyRulePresets`, exported from `c15t`. Where the rules live depends on your
backend:

* **Inth**: set the rules in your Inth project. Rules in client code do not
  change a hosted policy.
* **Self-hosted**: move the backend's `policyPacks` to `manifest.policyRules`.
  See [policy configuration](/docs/self-host/guides/policy-packs).
* **Offline**: move `offlinePolicy.policyPacks` to `offline({ policyRules })`.

```tsx title="After (v3): offline policy rules"
import { offline, policyRulePresets } from 'c15t';

const mode = offline({
	policyRules: [
		policyRulePresets.europeOptIn(),
		policyRulePresets.worldOptOutNoPrompt(),
	],
});
```

In Next.js, import `offline` from `c15t/next` instead and set the result as
`mode` in `c15t.config.ts`. Both take the same `policyRules`.

|v2 preset|v3 preset|
|--|--|
|`europeOptIn()`, `europeIab()`|Same names|
|`californiaOptIn()`, `californiaOptOut()`|Same names|
|`quebecOptIn()`|Same name|
|`worldNoBanner()`|`worldOptOutNoPrompt()`|

`worldNone()` is a separate, new preset: it shows nothing and grants no
rights, while `worldOptOutNoPrompt()` keeps v2's opt-out and preference rights.

The `policy-packs-to-policy-rules` codemod renames `policyPackPresets` and
`worldNoBanner()`, and moves the import to `c15t` where it came from
`c15t/react` or `c15t/next`. `consent-provider-options` moves
`offlinePolicy.policyPacks` into `offline({ policyRules })`. Preset calls need
no other change, but a hand-written v2 pack uses `consent` and `ui` keys,
which v3 rules replace with flat keys such as `model` and `prompt`; the
codemods mark those with a `TODO(c15t v3)` comment.

v3 adds presets for more regions. `offline()` without `policyRules` uses
`recommendedPolicyRules()`. Read [policies](/docs/concepts/policies) before you
change a rule's model or prompt, and
[how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice.

## Rename options and components

|v2|v3|
|--|--|
|`translations`|`i18n`|
|`backendURL`, `mode: 'hosted'`|`mode: hosted({ backendURL })` from `c15t/react` on `ConsentProvider`. Next.js `ConsentRoot`: `NEXT_PUBLIC_C15T_BACKEND_URL` and `c15t.config.ts`.|
|`ssrData` (Next.js)|`ConsentRoot` with `state` from `resolveConsent()`|
|`iframeBlockerConfig`|`iframeBlocker`, or `false` to turn it off|
|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, `FrameProps`|`ConsentGate` and its parts. The `Frame` names still work as deprecated aliases and log a one-time warning outside production.|
|`frame` translations, such as `frame.title`|`consentGate`, such as `consentGate.title`. Copy under `frame` still applies and logs a warning outside production.|
|`FrameTranslations`|`ConsentGateTranslations`. `FrameTranslations` still works as a deprecated alias.|
|`--frame-*` CSS variables|`--consent-gate-*`, with the same suffixes, such as `--consent-gate-placeholder-background-color`. The old names no longer apply.|
|`YouTubeEmbed`, `GoogleMap`|Removed. Wrap your own embed in `ConsentGate`.|
|`useConsentScript()`|Removed. Register the script in `scripts` with a `@c15t/integrations` helper.|
|`useSSRStatus()`|Removed|
|`ConsentButton`|Removed. Use the `ConsentBanner` and `ConsentWidget` buttons, or call `useHeadlessConsentUI()` from your own button.|
|`@c15t/react/cookie-banner`|`c15t/react/consent-banner`|
|`retryConfig`|Removed|
|`store`, including `namespace`, `debug`, `initialConsentCategories` and `initialTranslationConfig`|Removed. Use the top-level `consentCategories` and `i18n` options. Debug information is on `window.c15t`.|
|`window.c15tStore`|`window.c15t`|
|`iab: iab({ ... })`|`IABProvider`. See [Move IAB setup](#move-iab-setup-to-iabprovider).|

The `consent-provider-options` codemod renames `ConsentManagerProvider` and
its option and prop types, turns `mode` and `backendURL` into `hosted()` or
`offline()`, and renames `iframeBlockerConfig`. v2 still accepted the
deprecated `translations` option; the `translations-to-i18n` codemod moves it
to `i18n`.

```bash
npx @c15t/cli@alpha codemods consent-provider-options translations-to-i18n --dry-run --json
```

`ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
and `ConsentWidget` keep their names. The `scripts`, `networkBlocker`,
`legalLinks`, `overrides`, `theme` and `colorScheme` options keep theirs too,
but `theme` tokens no longer produce CSS on their own. See
[Update styles and themes](#update-styles-and-themes).

`persistence` and `storageConfig` are read once, when the provider mounts. v2
moved a stored choice when the storage key changed. Remount the provider to
change storage. Reading a vendor that nothing declares, through `vendors`, a
script or the backend, returns `false`.

Some names left the root `c15t/react` entry:

|v2 import from the root|v3 import|
|--|--|
|`useHeadlessConsentUI`, `useConsentDialogTrigger`, `useColorScheme`, `useFocusTrap` and the translation helpers|`c15t/react/headless`|
|Flat banner parts such as `ConsentBannerCard` and `ConsentBannerAcceptButton`|`ConsentBanner.Card`, `ConsentBanner.AcceptButton` and the other compound parts, or the same names from `c15t/react/components/consent-banner`|
|`TriggerRoot`, `TriggerButton`, `TriggerIcon`, `TriggerText`, `useTriggerContext`, `useDraggable`|`c15t/react/consent-dialog-trigger`|
|Token types such as `ColorTokens` and `TypographyTokens`|`c15t/react/types`. `Theme` stays on the root.|
|`configureConsentManager`, `policyPackPresets`, `ConsentStoreState`, `ConsentManagerInterface`|Removed. Use `policyRulePresets` from `c15t`.|

The `root-exports-to-subpaths` codemod moves these imports to their new
entries and marks removed names with a `TODO(c15t v3)` comment:

```bash
npx @c15t/cli@alpha codemods root-exports-to-subpaths --dry-run --json
```

`ConsentGate` changes one behavior from `Frame`. When its category is granted,
the embed now mounts after hydration instead of in the server HTML, so an
iframe loads once instead of twice. Size the wrapper with `className` or
`style` to hold its space. Test ids change from `frame-placeholder` and
`frame-open-dialog` to `consent-gate-placeholder` and `consent-gate-button`.

## Update styles and themes

### Render theme CSS

In v2 the provider built CSS from `options.theme` in the browser. In v3 it
doesn't. Without a change, custom colors, fonts and radii fall back to the
defaults, and you only see a development warning.

Render `ConsentTheme` with the same theme object, or put the output of
`generateThemeCSS(theme)` in your own stylesheet. Keep `options.theme` for
`consentActions` and `slots`. See
[customization](/docs/customization/overview) and
[tokens](/docs/customization/tokens).

The `theme-to-consent-theme` codemod marks a provider `theme` that sets
tokens with a `TODO(c15t v3)` comment.

A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
`:root` lose to it. Put them in the theme instead, or raise your selector.

### Stylesheets

* Remove the c15t stylesheet import, such as `@c15t/react/styles.css` or
  `@c15t/nextjs/styles.css`. The stock components in `c15t/react`,
  `c15t/next` and `c15t/tanstack-start` render the rules they use as
  `<style>` elements, so no stylesheet request holds back the first paint. An
  import you keep still styles the components, but the rules ship twice and
  the stylesheet still delays the first paint.
* Keep an import of the v3 stylesheet, such as `c15t/react/styles.css`, only
  with Tailwind CSS 3 or a named cascade layer, and set
  `styles: false` in the provider options so the components add no second
  copy. See
  [stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself).
  The `packages-to-c15t` codemod removes `@c15t/react` and `@c15t/nextjs`
  stylesheet imports. With Tailwind CSS 3 or a cascade layer it keeps them,
  pointed at `c15t`, with a `TODO(c15t v3)` comment.
* With manual styles, `iab/styles.css` no longer repeats the default tokens.
  Import it after `styles.css`. Automatic IAB styling needs neither import.
* Tailwind CSS 3 needs a PostCSS plugin for c15t's `styles.css`. Add
  `'c15t/postcss-tailwind3': {}` before `tailwindcss` in `postcss.config`,
  and set `styles: false`. See [Tailwind CSS 3](/docs/customization/tailwind#set-up-tailwind-css-3).
  Create React App can't run the plugin. The `postcss-tailwind3` codemod adds
  it to an object-form `postcss.config` and warns about configs it can't
  edit.

### CSS variables and slots

|v2|v3|
|--|--|
|`--consent-widget-*`|`--consent-manager-*`, used by `ConsentDialog` and `ConsentWidget`|
|`--consent-widget-accordion-*`|Removed. Set `--accordion-*` instead.|
|`--frame-*`|`--consent-gate-*`|
|`--consent-banner-entry-animation`, `--consent-banner-exit-animation`|Removed|
|`theme.slots.frame`|`consentGate`, `consentGateTitle` and `consentGateButton`|
|`theme.slots.consentDialogFooter`|`consentWidgetFooter`|

The `css-variables-to-v3` codemod renames `--consent-widget-*` and
`--frame-*` in stylesheets and inline styles, and marks
`--consent-widget-accordion-*` with a comment instead of renaming it, because
`--accordion-*` styles every accordion. `theme-to-consent-theme` renames
`theme.slots.consentDialogFooter` and marks `theme.slots.frame`.

```bash
npx @c15t/cli@alpha codemods theme-to-consent-theme css-variables-to-v3 postcss-tailwind3 --dry-run --json
```

`theme.slots` now applies in React. v2 accepted it in types and ignored it, so
check slots you set before the upgrade.

## Move IAB setup to `IABProvider`

React, Next.js and TanStack Start no longer take an `iab` provider option.
Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or
`ConsentRoot`, around the IAB components. Its props are the options you passed
to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new
`publisherRestrictions`.

The `iab-option-to-iab-provider` codemod marks the `iab` option with a
`TODO(c15t v3)` comment; move it by hand.

A `cmpId` that isn't an integer from 2 to 4095 now throws. Without a `cmpId`,
the CMP doesn't mount, so there is no `__tcfapi` and no TC string.

`@c15t/iab` no longer exports `createIABManager`, `decodeTCString`,
`generateTCString` or `c15tToIabPurposes`. Use `createIAB({ kernel, cmpId })`,
which returns a handle with `generateTCString()`, `acceptAll()`, `rejectAll()`
and `save()`. If your app depends on `@c15t/iab` directly, upgrade it to
`@c15t/iab@alpha` too, or your import resolves to the v2 package. Remove it if
`IABProvider` now covers everything you used it for.

Server integrations now send a reference to the Global Vendor List instead of
the list, and the browser fetches it when the IAB module mounts. If you set a
Content Security Policy, allow the list's origin in `connect-src`, or `'self'`
for same-origin routes.

See the [IAB guide](/docs/frameworks/react/iab) for a complete setup.

## Update headless UI code

`useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`.
The `root-exports-to-subpaths` codemod moves the import.
Some of its methods take different arguments:

|v2|v3|
|--|--|
|`performAction(action, { surface })`|`performAction(action)`. It also accepts `'dismiss'` and `'customize'`.|
|`openBanner({ force })`|`openBanner()`|
|`saveCustomPreferences({ uiSource })`|`saveCustomPreferences()`, `saveCustomPreferences('all')` or `saveCustomPreferences('none')`|
|`banner.layout`, `dialog.layout`, `hasPolicyHints`|`banner` and `dialog` carry `variant`, `position`, `rights`, `requiredActions` and `diagnostics`|

The `UseHeadlessConsentUIResult` type is no longer exported. Use
`ReturnType<typeof useHeadlessConsentUI>` if you need it.

## Update complete translation objects

Partial overrides through `i18n.messages` and objects typed as `Translations`
need no change. A complete translation object typed as `CompleteTranslations`
fails type-checking until you add the new sections and keys: `consentGate`, which
replaces `frame`, `rights`, the notice and dismiss strings such as
`common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy
under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves
`frame` copy to `consentGate`.

`i18n.messages` for the visitor's language now merge over the backend's copy
instead of being replaced by it.

## Keep visitors' existing choices

v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It
does not rewrite them on page load; the next accept, reject or save writes a
v3 record.

A v2 denial keeps restricting its category. A v2 grant keeps applying until
the policy's validity period runs out, and then c15t asks again. If the rule
comes from a preset and the v2 record noted the policy it was made under, c15t
also asks again when that policy has changed. Under custom rules, a v2 grant
applies until it expires. Do not copy permissions into new
records yourself; c15t decides which v2 choices still count.

## Update dev tools

`@c15t/dev-tools/react` and `@c15t/dev-tools/tanstack` are gone. Import
`DevTools`, `C15tTanStackDevtoolsPanel` and `c15tDevtools()` from
`c15t/react/devtools`. Dev tools read the consent engine, so `namespace`,
`createStoreConnector()` and `getC15tStore()` are gone too. See
[dev tools](/docs/frameworks/react/components/dev-tools).

The `dev-tools-to-c15t` codemod points the imports at `c15t/react/devtools` and
removes the `namespace` prop:

```bash
npx @c15t/cli@alpha codemods dev-tools-to-c15t --dry-run --json
```

## Upgrade from an earlier v3 alpha

The v3 alphas renamed and removed APIs that never shipped in a stable release.
Names that were in stable v2 keep a deprecated alias. Every other renamed name
is removed with no alias, so a build that still uses one fails to type-check
or throws at runtime.

### Deprecated, still working

Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside
production, log a one-time warning such as
`` c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead. ``

|Package|Deprecated|Use instead|
|--|--|--|
|`c15t/react`, `c15t/next`, `c15t/tanstack-start`|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, and the `FrameProps` type|`ConsentGate` and its parts, and `ConsentGateProps`|

v2's `ConsentManagerProvider` and string modes such as `mode: 'hosted'` are
handled by the `consent-provider-options` codemod, not by aliases.

### Removed

|Removed|Use instead|
|--|--|
|`hosted({ url })`|`hosted({ backendURL })`, or the framework's backend URL variable|
|`createManifestTransport({ manifest })`|`createManifestTransport({ snapshot })`|
|`assertDecisionInputs` defaulting to `false` on `hosted()`|It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.|
|`hostedModes` from `c15t/runtime/provider`|`readHostedMode(mode)`|
|`buildManifest: true` in Astro and Nuxt|`onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`.|
|A generated `c15t-manifest.ts` and its `.gitignore` entry|`import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.|
|The build options `outputFile`, `exportName`, `importSource` and `rootDir`|Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.|

React removes nothing besides the modes above. Import `manifest()` from
`c15t/react`, next to `hosted()` and `offline()`, instead of from
`@c15t/browser/headless`; React apps need nothing from `@c15t/browser`.

## Update the CLI

* Run `c15t login` again. The CLI signs in through Inth now and no longer
  reads sessions saved by v2.
* `c15t setup` no longer writes `.env.local` or `.env.example` and no longer
  accepts `--env`. It writes the backend URL into the files it generates.
* `c15t setup` no longer detects Remix or Gatsby. Pick a guide from
  [Choose your setup](/docs/concepts/choose-your-setup) for those apps.

## Check the migration

1. Run your typecheck and build. Remaining `TODO(c15t v3)` comments from the
   codemod fail the build until you resolve them.
2. Load the app with a v2 consent cookie from before the upgrade. The banner
   stays closed if that choice still applies, and a rejected category stays
   blocked.
3. In a private window, check in DevTools Network that vendor requests wait for
   consent, start after you accept, and stay absent after you reject and
   reload.
4. Reopen preferences from your privacy settings link and change a category.

The [verification guide](/docs/guides/verify-consent) has the full release
checklist.

# Scripts
URL: https://c15t.com/docs/frameworks/react/scripts
Load vendor scripts by consent category in a React app with ConsentProvider, and clear stored data or reload the page when a visitor withdraws consent.

## Register vendor scripts

Pass vendor loaders to `ConsentProvider` through `options.scripts`. The
provider loads each script when its category is allowed and removes it when
the category is denied. The [quickstart](/docs/frameworks/react/quickstart)
registers PostHog this way in `src/consent.tsx`:

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

Each helper from `@c15t/integrations` sets its own category and a stable `id`.
Remove every other loader for the same vendor, such as a `<script>` tag in
`index.html` or an SDK you initialize at module level, so the vendor loads
once and only through c15t. [Integrations](/docs/integrations/overview) lists
every helper, and [building integrations](/docs/integrations/building-integrations)
covers a vendor without one.

## What happens when consent changes

* **Allowed.** The script loads, or its SDK is started, the first time its
  category is allowed.
* **Denied later.** The provider removes the script element. Code that already
  ran keeps running, so after the visitor turns off a category they had
  allowed, the provider reloads the page once the save finishes. Set
  `reloadOnConsentRevoked: false` only if every gated vendor stops itself.
* **`alwaysLoad` helpers.** Some integrations, such as the Google Consent Mode
  helpers by default, load before consent and pass the visitor's choice to the
  vendor. Read the vendor's guide; a category on a script does not always mean
  zero requests.

## When the script loader downloads

The script loader is a separate chunk, downloaded only when `scripts` is not
empty. `ConsentProvider` loads it when it mounts. The Next.js and TanStack
Start `ConsentRoot` start the download earlier, during their first render,
when the visitor's consent already lets a script run.

## Embeds and other requests

Scripts cover vendor code c15t loads for you. For the rest:

* [Embeds](/docs/frameworks/react/embeds) keeps iframes out of the page with
  `ConsentGate` or the iframe blocker.
* [Network blocker](/docs/frameworks/react/network-blocker) holds `fetch` and
  XHR calls that match a rule until their category is allowed.

## Clear stored data after revocation

Removing a script does not delete the cookies or storage entries it wrote. Add
`clearOnRevocation` to the provider options to delete the entries you list for
each category when it is denied. The option is read once, when the provider
mounts. [Clear on revocation](/docs/frameworks/react/clear-on-revocation) covers
configuration and browser limits.

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Pass
`vendors` to the provider options. Helpers from `@c15t/integrations` already carry
their vendor slug. See [vendor consent](/docs/frameworks/react/vendor-consent).

To send your own events only to allowed integrations, see
[send events only to allowed integrations](/docs/integrations/overview#send-events-only-to-allowed-integrations).

## Check the scripts

Open DevTools Network in a private window, filter by each vendor's domain and
reload.

1. Before a choice under an opt-in policy, no vendor script loads.
2. Allow one category. Only that category's vendors load.
3. Turn the category off. The page reloads and the vendor stays absent.
4. Reload again. The rejection holds.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/react/embeds
Keep YouTube videos, maps and other iframes out of a React page until their consent category is allowed, with ConsentGate or the iframe blocker in ConsentProvider.

## Pick a method

|Method|Use it when|
|--|--|
|`ConsentGate`|You render the iframe in a React component and want a placeholder until the visitor allows its category.|
|The iframe blocker|The iframe comes from markup you do not render with React, such as CMS or Markdown content.|

Both keep the iframe's `src` out of the page until the category is allowed, so
the embed's host receives no request before consent.

## Gate an embed with ConsentGate

Wrap the iframe in `ConsentGate` anywhere inside `ConsentProvider`:

```tsx title="src/video-embed.tsx"
import { ConsentDialogLink, ConsentGate } from 'c15t/react';

export const VideoEmbed = () => (
	<ConsentGate
		category="measurement"
		placeholder={
			<div className="placeholder">
				<p>Allow measurement to load this YouTube video.</p>
				<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
			</div>
		}
	>
		<iframe
			title="YouTube video"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
			allow="encrypted-media; picture-in-picture"
			allowFullScreen
		/>
	</ConsentGate>
);
```

The iframe is absent from the page until the visitor allows measurement. The
`placeholder` shows a message and a
[`ConsentDialogLink`](/docs/frameworks/react/components/consent-dialog-link)
until then. When the visitor withdraws measurement, React removes the iframe.

Pick the category that matches what the embed does. The example uses
measurement for YouTube because its player measures views. A map or chat
widget usually belongs under functionality or experience.
[ConsentGate](/docs/frameworks/react/components/consent-gate) documents the
built-in placeholder and every prop.

## Gate an iframe with the iframe blocker

`ConsentProvider` runs the iframe blocker by default. Give an iframe
`data-src` instead of `src`, and a `data-category`:

```html title="Markup from your CMS"
<iframe
  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
  data-category="functionality"
  title="Store map"
></iframe>
```

c15t sets `src` from `data-src` when the category is allowed and removes `src`
when the category is withdrawn. It watches the page, so iframes added later
are handled too. Add `data-vendor` with a vendor ID to also block the iframe
while the visitor has turned that vendor off.

To turn the blocker off, set `iframeBlocker: false` in the provider `options`.

## Verify the embeds

Open the production build in a private window with DevTools open, under a
policy that asks for consent.

1. No iframe has a `src` pointing at `youtube-nocookie.com` or
   `google.com/maps`, and the Network panel shows no request to them.
2. Allow the embed's category and save. The iframe loads.
3. Withdraw the category and save. The page reloads without the embed.

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover sizing and titles.

# Network blocker
URL: https://c15t.com/docs/frameworks/react/network-blocker
Hold fetch and XMLHttpRequest calls in a React app until their consent category is allowed, with networkBlocker rules in the ConsentProvider options.

## Add rules

Some SDKs are already on the page and send beacons or API calls of their own.
Add `networkBlocker` rules to the provider options to stop `fetch` and
`XMLHttpRequest` calls to those domains until the category is allowed. Load
vendor SDKs through [`scripts`](/docs/frameworks/react/scripts) first, so they
do not run at all before consent.

This partial example adds the option next to the existing `mode` and
`scripts`:

```tsx title="src/consent.tsx"
const networkBlocker = {
	rules: [
		{
			id: 'google-analytics',
			domain: 'google-analytics.com',
			category: 'measurement',
		},
		{
			id: 'meta-pixel',
			domain: 'facebook.com',
			pathIncludes: '/tr',
			category: 'marketing',
		},
	],
};

<ConsentProvider options={{ mode, scripts, networkBlocker }}>
```

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The provider holds matching requests from its first render in the browser,
before any of its children render or run effects. That covers requests from
child components, including their mount effects, and from effects in
components rendered next to the provider. The blocker module itself loads
after mount and decides each held request. Apps without `networkBlocker` do
not download it.

The standalone `useNetworkBlocker` hook works the same way from the first
render of the component that calls it. That render patches `fetch` and
`XMLHttpRequest`. If React throws the render away and never commits it, the
hold ends after 10 seconds. Nothing checked consent for the requests it held,
so they fail the way the blocker fails a blocked request: a 451 response for
`fetch`, a failed XHR. The same happens when the component unmounts before
the blocker loads.

While consent is unknown, a matching request that would be blocked waits
instead of failing. Consent is unknown until the policy has loaded, which is
also when a returning visitor's stored choice takes effect. The request is
then sent if the choice allows it and blocked otherwise. If the policy fails
to load, optional categories stay denied and waiting requests are blocked.
If the policy request never finishes, they keep waiting and are never sent.

A synchronous XHR cannot wait. Before the blocker module has loaded, a
matching one throws a `NetworkError` from `send()`. After that, one that
consent does not allow yet is blocked.

## What the network blocker cannot stop

The blocker only sees requests made after the provider starts rendering in
the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:

* Code that runs before the provider renders: inline scripts in the HTML,
  third-party tags in `<head>`, scripts loaded before hydration (such as
  `next/script` with `beforeInteractive`), and client modules that evaluate
  earlier. Webpack builds evaluate a route's client component modules when
  its chunk loads, so their top-level code runs first. Turbopack evaluates a
  client component module when its first element renders, which inside the
  provider is after blocking starts.
* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
  provider rendered.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` or `<iframe>` elements, web workers and service
  workers.
* With the standalone `useNetworkBlocker` hook instead of the provider
  option, requests sent before the component that calls it renders.
  Blocking starts in that component's first render, not the provider's.

Keep tracking calls out of that window:

* Send them from an effect or an event handler, never at module top level.
* Load vendor SDKs through `scripts` instead of a `<script>` tag or
  `next/script`, so they wait for consent before they run at all.
* Check `useConsent('measurement')` (or the category you need) before you
  call a vendor from your own code, and treat the blocker as a backstop.

## Verify the blocked requests

Open DevTools Network in a private window, under a policy that asks for
consent.

1. Before a choice, requests matching a rule are absent, and the console logs
   each blocked request.
2. Allow the rule's category and save. Matching requests go out.
3. Reject, reload, and check that they stay absent.

# Vendor consent
URL: https://c15t.com/docs/frameworks/react/vendor-consent
Let visitors allow a category such as marketing in a React app and still turn off one vendor in it, with the vendors option on ConsentProvider and useVendorAllowed.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in `src/scripts.ts`, using the `vendor`
slug each script already carries:

```ts title="src/scripts.ts (partial)"
import type { Vendor } from 'c15t';

export const vendors: Vendor[] = [
	{
		id: 'x-pixel',
		name: 'X Pixel',
		category: 'marketing',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];
```

Then add them to the provider options in `src/consent.tsx`:

```tsx title="src/consent.tsx (partial)"
import { scripts, vendors } from './scripts';

<ConsentProvider options={{ mode, scripts, vendors }}>
```

`vendors` is a live option, like `scripts`: passing a new list replaces the
declared vendors. A provider that borrows a `runtime` does not accept
`vendors`; declare them in `createConsentRuntime({ vendors })` instead.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. To render a component only while one
vendor is allowed, read `useVendorAllowed('youtube')` and render it when the
hook returns `true`. [Embeds](/docs/frameworks/react/embeds) covers the iframe
blocker's `data-vendor` attribute.

## What the preference dialog shows

`ConsentDialog` and `ConsentWidget` list each declared vendor under its
category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`useVendorDraft()` from `c15t/react` reads and stages vendor switches on the
same draft the category switches use, so one save records both.
`useVendorAllowed(id)` returns whether a vendor may run now: it is declared,
its category is allowed and the visitor has not switched it off.

```tsx title="src/x-pixel-switch.tsx (partial)"
import { useVendorAllowed, useVendorDraft } from 'c15t/react';

const { vendors, setVendor, save } = useVendorDraft();
const xPixelAllowed = useVendorAllowed('x-pixel');

<input
  type="checkbox"
  checked={vendors['x-pixel'] ?? true}
  onChange={(event) => setVendor('x-pixel', event.target.checked)}
/>
<button type="button" onClick={() => save()}>Save</button>
```

`save()` resolves `{ ok: false }` without recording anything when the policy
or the vendor list changed under the edit. Call `reset()` to start again.
`useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
returns the recorded vendor decision, or `null` before the visitor made one.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/react/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a React app when that category is denied, with the clearOnRevocation option on ConsentProvider.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns and add them to the
provider options in `src/consent.tsx`. When that category is denied, c15t
deletes them:

```tsx title="src/consent.tsx (partial)"
import type { ClearOnRevocationConfig } from 'c15t';

const clearOnRevocation: ClearOnRevocationConfig = {
  measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
  marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
};

<ConsentProvider options={{ mode, scripts, clearOnRevocation }}>
```

The provider reads `clearOnRevocation` once, when it mounts; remount it to
change the list. A provider that borrows a `runtime` does not read it.
Configure cleanup on the runtime owner instead, with
`createConsentRuntime({ clearOnRevocation })`.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/react/customize
Change the colors, fonts, layout, button styles and copy of the c15t banner and dialog in a React app with theme tokens, provider options and slots, and load the stylesheet yourself when you need to.

## Pick the right tool

|Change|Use|
|--|--|
|Brand colors, fonts, radius, spacing|[Theme tokens](#change-colors-fonts-and-radius)|
|Light and dark colors, animation|[Dark mode and motion](#turn-on-dark-mode-and-change-motion)|
|Which button is filled or outlined|[`consentActions`](#style-the-action-buttons)|
|Banner shape and position|[`ConsentBanner` props or `presentation`](#change-the-banner-shape)|
|One element of a component|[Component parts](#style-one-component-part)|
|Labels and languages|[Copy and translations](#change-the-copy)|
|Different markup entirely|[Headless](/docs/frameworks/react/headless)|

[Customization](/docs/customization/overview) explains how these choices relate
across frameworks.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## Import the stylesheet yourself

A React app imports no c15t stylesheet. `ConsentBanner`, `ConsentDialog` and
the other stock components render the rules they use as `<style>` elements.

Import the stylesheet yourself with Tailwind CSS 3, to put c15t's rules in a
named cascade layer. Set `styles: false` in the provider
options, so the components add no second copy, and import the stylesheet once
in the module that renders `ConsentProvider`:

```tsx title="src/consent.tsx (partial)"
import 'c15t/react/styles.css';

// In the ConsentProvider options:
styles: false,
```

To import the stylesheet from CSS instead, put it at the top of your global
stylesheet, above any `@tailwind` directives. `postcss-import`, which Vite
uses, ignores an `@import` that follows other rules. Tailwind 3 also needs a
PostCSS plugin;
[Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3) shows the
setup.

## Change colors, fonts and radius

Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
properties. The rules the components render set the default values, as
does `styles.css` when you import it with `styles: false`. To change them,
render `ConsentTheme` with your theme where your app renders on the server,
or override the variables directly in your CSS.

`ConsentTheme` renders a `<style id="c15t-theme">` element with the
variables for `theme`. It is not a client component: rendered from a Server
Component or another server-only file, the theme generator stays out of the
browser bundle. Rendered from a client component it still works, but the
browser downloads the generator (about 1.7 KB gzip). The provider no longer
turns `theme` tokens into CSS. It still reads `consentActions` and slot
styles from its `theme` option, and warns in development when `theme` holds
tokens but the page has no `c15t-theme` stylesheet.

|`ConsentTheme` prop|Purpose|
|--|--|
|`theme`|Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.|
|`colorScheme`|`'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`.|
|`nonce`|Content Security Policy nonce for the `<style>` element.|

Pass the same `colorScheme` to `ConsentTheme` and to the provider. If your
app manages dark mode through a root class, such as next-themes' `dark`
class, omit `colorScheme` and include that class in the server HTML.
[Dark mode](/docs/customization/dark-mode) covers `theme.dark`, `null` and
a dark first paint.

To switch between different token sets at runtime, render `ConsentTheme`
from a client component and change its props, which ships the generator.

Outside a component, call `generateThemeCSS(theme, colorScheme)` from
`c15t/react/utils`, or `@c15t/react/utils` with the scoped package. It
writes the same CSS as `ConsentTheme`. Outside React, import it from
`@c15t/ui/theme`. Call it on the server or at build time and put the result in a
`<style>` element or your stylesheet. It escapes `<`, so the result is safe
inside `<style>`.

A single-page app has no server render, so pick one of two ways:

* **Set the variables in your CSS.** Nothing extra ships to the browser:

  ```css title="src/index.css"
  :root {
    --c15t-primary: #2f6f4e;
    --c15t-primary-hover: #24563c;
    --c15t-text-on-primary: #fff;
    --c15t-radius-lg: 4px;
  }
  ```

* **Render `ConsentTheme` next to the provider.** Use this when the theme lives
  in TypeScript or changes at runtime. The browser downloads the theme
  generator.

  ```tsx title="src/consent-theme.ts"
  import { defineTheme } from 'c15t/react';

  export const theme = defineTheme({
    colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
    radius: { lg: '4px' },
  });
  ```

  In `src/consent.tsx`, render `<ConsentTheme theme={theme} />` from
  `c15t/react` just before `<ConsentProvider>`.

In a server-rendered app, such as React Router framework mode, render
`ConsentTheme` in the root component so the `<style>` element is part of the
server HTML. [Theme tokens](/docs/customization/tokens) lists every variable.

`ConsentTheme` outranks a plain `:root` rule, wherever each one loads. If you
use both, a variable set in both places takes the `ConsentTheme` value. Write
your CSS overrides on `:root:root` to beat it, or move the values into the
theme.

## Style the action buttons

`consentActions` decides how each action looks. `default` applies to every
button, `primary` to the action the policy or your props mark primary, and
`accept`, `reject`, `customize` and `dismiss` to one action each. Pass it
through the provider's `theme` option:

```tsx title="src/consent.tsx"
<ConsentProvider
  options={{
    mode,
    scripts,
    theme: {
      consentActions: {
        primary: { variant: 'primary', mode: 'filled' },
        dismiss: { variant: 'neutral', mode: 'stroke' },
      },
    },
  }}
>
```

The provider's `theme` option only reads `consentActions` and slot styles.
Tokens passed there do nothing, and the provider logs a warning in development.
Changing button styles does not change the policy or expire a saved choice.

## Change the banner shape

`ConsentBanner` takes `variant` (`floating`, `bar`, `widget` or `wall`) and
`position`. To use one shape everywhere, set `presentation.prompt` in the
provider options instead. This banner is a full-width bar for notices and a
card for choices:

```tsx title="src/regional-banner.tsx"
import { ConsentBanner, usePolicyRule } from 'c15t/react';

export function RegionalBanner() {
	const policy = usePolicyRule();
	return (
		<ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />
	);
}
```

Render `RegionalBanner` in place of `ConsentBanner` inside the provider.
[ConsentBanner](/docs/frameworks/react/components/consent-banner#variants)
lists every variant and position, and how to order buttons per policy.

## Style one component part

Each component part is a slot. Set slots in the provider options under
`components`, keyed by component and part. A slot takes any attribute the
element accepts, such as `className` or `style`.

The root also carries `data-variant`, so you can restyle one shape without
touching the others. Tailwind, giving a `bar` a brand-colored top edge and
tighter text:

```tsx
<ConsentProvider
	options={{
		mode,
		presentation: { prompt: { variant: 'bar' } },
		components: {
			banner: {
				root: { className: 'group' },
				card: {
					className:
						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
				},
			},
			description: {
				banner: { className: 'group-data-[variant=bar]:text-xs' },
			},
		},
	}}
/>
```

`data-variant` sits on the root, so child slots use Tailwind's `group`
prefix to read it.

[Class names and CSS-in-JS](/docs/customization/class-names) shows CSS
Modules, vanilla-extract, StyleX and Emotion classes on a part.

Set `noStyle` on a component to drop the built-in classes from every part and
keep only what your slots pass. Set `noStyle` in the provider options to do it
for every component.

[Component parts](/docs/customization/slots) lists every part key under
`components` and the `data-*` attributes each part carries. Action buttons
carry `data-action`, so a single rule such as `[data-action='dismiss']`
styles one role across every surface. Right links are underlined text by
default, so the only button on a notice is the primary action.

[Component parts](/docs/customization/slots) lists every component's part keys
and when to drop the built-in styles with `noStyle`. The `ConsentGate`
placeholder's parts are `components['consent-gate'].root`, `.title` and
`.button`.
[Class names and CSS-in-JS](/docs/customization/class-names) covers CSS
Modules, vanilla-extract, StyleX and Emotion, and
[Tailwind CSS](/docs/customization/tailwind) covers utilities on parts.

## Turn on dark mode and change motion

Pass `colorScheme` in the provider options and the same value to
`ConsentTheme`. Leave it unset to follow a `dark` class on `<html>`, and add
dark colors with `theme.dark`. [Dark mode](/docs/customization/dark-mode)
covers each value and a dark first paint.

`disableAnimation` in the provider options turns off the banner and dialog
animations, and the same prop on `ConsentBanner` or `ConsentDialog` overrides
it for one surface. [Motion and animation](/docs/customization/motion) covers
the duration and easing tokens and reduced motion.

## Change the copy

Labels, descriptions and languages come from the translations in your Inth
project and from the provider's `i18n` option. For the visitor's language,
`i18n.messages` replace the project's copy key by key, and keys you leave out
keep the project's wording.
[Copy and translations](/docs/customization/translations) shows the message
keys. For one banner, `ConsentBanner` also accepts text props such as
`dismissButtonText`.

## Check the result

Clear site data and reload under a policy that shows a banner. Check the banner
and the preferences dialog, since both read the same tokens. Test a narrow
window, keyboard focus and contrast on the primary button. In development, the
console warns if `theme` holds tokens but the page has no `c15t-theme` style.

# Translations
URL: https://c15t.com/docs/frameworks/react/translations
Where c15t banner and dialog copy comes from in a React app, how the browser picks the visitor's language, and how to override copy and switch languages with the provider's i18n option and hooks.

## Where the copy comes from

The banner, dialog, widget and gate placeholder read their text from one set
of translations for the visitor's language. Which set depends on the
provider's `mode`:

|Mode|Copy comes from|
|--|--|
|`hosted()`|The backend's `/init` response for the visitor's language, from the translations in your Inth project or your self-hosted backend's configuration, with your `i18n` messages for that language on top|
|`offline()`|Your `i18n` messages, merged over bundled English|

With a backend, edit wording in your Inth project first, so it changes without
a deploy. Code can override that copy in two places:

* `i18n` in the `ConsentProvider` options changes a message everywhere it
  appears.
* Text props on `ConsentBanner` change one banner.

[Copy and translations](/docs/customization/translations) lists the message
keys and explains how code messages combine with the project's copy.

## How c15t picks the language

In `hosted()` mode the browser's `/init` request carries its own
`Accept-Language` header, and the backend answers with copy in that language.
When your project has no copy for it, the backend returns its fallback
language. Set `overrides.language` in the provider options to request a
specific language instead.

In `offline()` mode, `i18n.locale` picks the language, `en` by default. The
browser's language is not read.

The banner, dialog and widget set `dir` from the active language. Right-to-left
languages such as Arabic and Hebrew render with `dir="rtl"`, and a floating
banner you did not position yourself moves to the opposite side.

## Change the copy in code

Keep the messages in their own module:

```ts title="src/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/react';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

Pass them to the provider in the file that renders it, such as
`src/consent.tsx` from the [quickstart](/docs/frameworks/react/quickstart):

```tsx title="src/consent.tsx"
<ConsentProvider options={{ mode, scripts, i18n }}>
```

For the visitor's language, your messages replace the backend's copy key by
key. Keys you leave out keep the project's wording, and messages for other
languages are not applied. In `offline()` mode c15t bundles only English, so
keys you leave out for another language show in English.

The provider reads `i18n` once, when it mounts. In development it logs a
warning if `i18n` changes later. Define the object at module level, as above,
rather than inside a component.

## Change one banner's copy

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. The props
replace the text in every language, so pass values in the page's language:

```tsx
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>;
```

## Switch the language at runtime

`useSetLanguage()` stores the new language, and `useInit()` resolves the policy
again, which fetches the copy for that language. Call both from your language
switcher:

```tsx title="src/language-switcher.tsx"
import { useInit, useSetLanguage, useSnapshot } from 'c15t/react';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

Setting the language without calling `init()` changes nothing on screen. Your
`i18n` messages for the new language apply on top of the copy that arrives.
Render the switcher anywhere inside `ConsentProvider`.

Switching needs a backend. In `offline()` mode the copy stays in the
`i18n.locale` language.

If your site changes language through its own i18n library, you can instead
pass its locale as `overrides.language` in the provider options. When that
value changes, the provider resolves the policy again in the new language.

## Verify

1. Set your browser language to one your project translates, clear site data
   and reload under a policy that shows a banner. DevTools Network shows the
   `/init` request with that `Accept-Language` header, and the banner uses
   that language.
2. Check that a message you set in `i18n` shows in the banner.
3. Switch the language with your switcher. A new `/init` request runs, and the
   banner and dialog text change without a reload.

# Compose your own banner
URL: https://c15t.com/docs/frameworks/react/compose
Build a React consent banner from the ConsentBanner parts in c15t/react, with your own markup and buttons, while the policy still decides which actions appear.

## When to compose

Compose the banner from its parts when you need its elements in a different
order, an element it does not have, or your design system's button in place
of c15t's. The parts keep the stock
behavior. They read the same policy, record the same choices and render the
same class names, so theme tokens and slots still apply.

Try the lighter tools first:

|Change|Use|
|--|--|
|Colors, type, radius, spacing|[Theme tokens](/docs/customization/tokens)|
|Classes or attributes on one part|[Component parts](/docs/customization/slots)|
|Labels and languages|[Copy and translations](/docs/customization/translations)|
|Shape, position, button order|`ConsentBanner` props such as `variant`, `position`, `layout` and `primaryButton`|
|Different markup or order|Compound parts, on this page|
|Entirely custom UI and behavior|Headless hooks|

For a banner that shares nothing with the stock markup, use the
[headless hooks](/docs/frameworks/react/headless). For one changed class,
token or prop, see [customize](/docs/frameworks/react/customize).

## Compose the banner

`CookieBanner` keeps the stock card, title and copy, and renders each action
the policy asks for as your design system's button. `BrandButton` stands in
for that button:

```tsx title="src/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner, useTranslations } from 'c15t/react';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

The parts read the nearest `ConsentProvider`. In the `src/consent.tsx` file
from the [quickstart](/docs/frameworks/react/quickstart), import
`CookieBanner` from `./cookie-banner` and render it in place of
`ConsentBanner`, next to `ConsentDialog`:

```tsx title="src/consent.tsx (partial)"
<ConsentProvider options={{ mode, scripts }}>
	{children}
	<CookieBanner />
	<ConsentDialog />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</ConsentProvider>;
```

`ConsentBanner.Root` renders only while the banner is the active surface,
the same condition the stock `ConsentBanner` uses, so `CookieBanner` needs
no visibility logic. It renders nothing before a policy resolves and closes
once the visitor chooses.

`ConsentBanner.PolicyActions` renders the actions the policy asks for, in
the policy's order and groups, with any rights links, such as "Do not sell
or share my data", before them. For each action it calls `renderAction`
with the action name and the props c15t would give the stock button:
`key`, `consentAction`, `isPrimary`, and a `style` that stretches the
buttons when the layout fills the row. Return an element to replace that
button, or `null` to keep the stock one. The banner never renders `save`,
so the example skips it.

Each action part gets those props plus `asChild` and `noStyle`. `asChild`
renders `BrandButton` in place of c15t's `button`, and `noStyle` drops
c15t's button classes so they do not compete with yours. The part keeps its
behavior. Accept saves every category and Reject saves only necessary, and
both close the banner. Customize opens the preference dialog. Dismiss
records that the visitor saw a notice, without recording a choice.

With `asChild`, the part's default label does not render, because your
element keeps its own children. `useTranslations()` returns the labels the
stock buttons use, in the visitor's language.

Under a notice, the policy asks only for an acknowledgement, so
`PolicyActions` passes `dismiss` and `CookieBanner` renders one button. If
you place `ConsentBanner.AcceptButton` and `ConsentBanner.RejectButton`
yourself instead, they render under every policy, including one that owes
only a notice.

## Banner parts

Every part is a property of `ConsentBanner`. All parts except `Root` and
`PolicyActions` forward their ref, and they accept the attributes of the
element they render plus `noStyle`.

|Part|Renders|Props|
|--|--|--|
|`Root`|The `div` that positions the banner, only while the banner shows. Renders the backdrop itself when blocking.|`variant`, `position`, `blocking`, `models` (default `['opt-in', 'opt-out']`), `uiSource` (default `'banner'`), `noStyle`, `disableAnimation`|
|`Card`|The visible `div`, labelled with the title. `role="region"`, or `role="dialog"` with `aria-modal="true"` and a focus trap when blocking.|`asChild`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`Title`|An `h2` with the translated title, or the notice title under a notice.|children replace the text|
|`Description`|A `div` with the translated copy and the configured legal links.|`legalLinks`, `asChild`|
|`PolicyActions`|`Footer`, the rights links and the policy's action groups.|`renderAction`, children replace the rights links|
|`Footer`|A `div` for the actions.|`asChild`|
|`FooterSubGroup`|A `div` for one group of actions. `Actions` is an alias.|`asChild`|
|`AcceptButton`|A `button` that saves every category and closes the banner.|action button props|
|`RejectButton`|A `button` that saves only necessary and closes the banner.|action button props|
|`CustomizeButton`|A `button` that opens the preference dialog.|action button props|
|`DismissButton`|A `button` that acknowledges a notice.|action button props|
|`Rights`|A `div` with one `RightLink` per right the policy recommends, or nothing.|`rights`, `asChild`|
|`RightLink`|A `button` styled as underlined text that opens the preference dialog.|`right` (`'opt-out'` or `'preferences'`), `asChild`|
|`Overlay`|The backdrop of a blocking banner. `Root` already renders it, so do not add it.|none|

`Content` is an alias of `Card`.

The action buttons take `asChild`, `noStyle`, `consentAction`, `isPrimary`,
`variant` (`'primary'` or `'neutral'`), `mode` (`'filled'`, `'stroke'`,
`'lighter'` or `'ghost'`), `onClick` and any `button` attribute. Your
`onClick` runs before the action, and calling `event.preventDefault()` in
it skips the action. `consentAction` sets `data-action` and selects the
`theme.consentActions` entry. `PolicyActions` passes it for you, and
`DismissButton` sets it itself. A button you place yourself has no
`data-action` and no per-action theme until you pass `consentAction`.

`useConsentBannerSurface()` returns the `variant`, `position`,
`positionSource` and `blocking` that `Root` resolved, for your own elements
that depend on the banner's shape.

[ConsentBanner](/docs/frameworks/react/components/consent-banner) lists the
stock banner's props, variants and data attributes.

## Render a part as your own element

`asChild` swaps the part's element for the one element you pass as its
child. `Card`, `Header`, `Description`, `Footer`, `FooterSubGroup`,
`Rights`, `RightLink` and the action buttons support it. `Root` and
`Overlay` ignore it, and `Title` always renders an `h2`, so a child you pass
to `Title` ends up inside that `h2`. `Description` with `asChild` drops the
inline legal links.

The part merges its props onto your element:

* The part's props apply first, and props you set on the child win.
* `className` keeps both, the part's classes first.
* `style` merges, and your values win per property.
* Event handlers both run, yours first. On an action button, calling
  `event.preventDefault()` in yours skips c15t's action.
* The part's ref and your child's ref both receive the DOM node.
* Your child keeps its own children. The part's default content, such as a
  button label, does not render.

Your component has to pass its ref and every prop it does not use to its
DOM element. Otherwise c15t's click handler, `data-action` and focus
handling never reach the page. The `BrandButton` in the example does both.
Pass exactly one element. Text, a fragment or several children render
nothing.

Action buttons pass no `type` under `asChild`, so give your button a
default of `type="button"`. Without it, the button submits a surrounding
form.

## Compose the preference dialog

`ConsentDialog` has parts too. Compose it when the dialog needs a different
header or footer, and keep `ConsentWidget` inside `Content`. The widget
owns the category switches, the draft and the policy's Save, Accept and
Reject buttons.

|Part|Renders|Props|
|--|--|--|
|`Root`|The dialog in a portal on `document.body`, with its open state, backdrop, focus trap, scroll lock and Escape to close.|`open`, `models` (default `['opt-in', 'opt-out', 'none']`), `overlay` (a node, or `false` for none), `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`, `uiSource` (default `'dialog'`)|
|`Card`|The panel `div`.|`className`, `style`, `noStyle`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`HeaderTitle`|An `h2` with `id="consent-dialog-title"`.|children replace the text|
|`HeaderDescription`|A `div` with `id="consent-dialog-description"` and the legal links.|`legalLinks`, `asChild`|
|`Content`|A `div` for `ConsentWidget`.|`asChild`|
|`Footer`|A `div` with the branding tag, unless you pass children or `hideBranding`.|`hideBranding`, `asChild`|
|`ConsentCustomizationCard`|The stock card with all of the above.|`legalLinks`, `hideBranding`, `noStyle`|
|`Overlay`|The backdrop. `Root` already renders it.|none|

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Render the composed dialog in place of `ConsentDialog`, next to your
banner. The stock `ConsentDialog` downloads its code when the dialog first
opens. The parts load that same code when they first render, and a
composed `ConsentDialog.Root` renders on every page, so the code downloads
with the page. `c15t/react/components/consent-dialog` exports the same
parts without the deferral.

`ConsentWidget` has parts as well, such as `ConsentWidget.Root`,
`ConsentWidget.Accordion`, `ConsentWidget.AccordionItems` and
`ConsentWidget.PolicyActions`, for a preference list with your own layout.

The parts come from `c15t/react`, like `ConsentDialog` and `ConsentWidget`.
[ConsentDialog](/docs/frameworks/react/components/consent-dialog) and
[ConsentWidget](/docs/frameworks/react/components/consent-widget) list every
part and its slots.

## Keep the banner accessible

The stock parts carry the roles, labels and focus handling. A composed
banner keeps them as long as you keep the parts that own them:

* `Card` owns the banner's role, label and focus trap. With `asChild`, your
  element receives them, so do not set `role` or `aria-modal` on it.
* `Card` takes its `aria-label` from the translated title, not from text you
  pass to `Title`. If you change the title text, pass the same text as
  `aria-label` on `Card`.
* To attach your own ref to `Card`, pass a ref object from `useRef`. A
  callback ref turns off the focus trap on a blocking banner.
* Render each action as a real `button`. Its text is the accessible name,
  so keep the label inside your button.
* Keep a way to reopen preferences after the banner closes, such as the
  `ConsentDialogLink` in your footer.
* The dialog's `Root` names the panel with the ids on `HeaderTitle` and
  `HeaderDescription`. Keep both parts, or put `id="consent-dialog-title"`
  and `id="consent-dialog-description"` on your own heading and copy.

## Keep theme tokens and slots working

The parts render the stock class names, and the banner's `Root` renders
c15t's rules, so c15t's styles and `--c15t-*` tokens style a composed
banner the way they style the stock one.

Slots in the provider's `options.components` reach each part by key:
`banner.root`, `banner.card`, `banner.header`, `banner.title`,
`description.banner`, `banner.footer` and `banner.actions`,
`banner.actionGroup`, `banner.rights` and `banner.rightLink`. A class you
pass to a part joins its stock and slot classes. The stock `ConsentBanner`
also renders the `banner.cardShell` wrapper and the "Secured by" tag, and a
composed banner renders neither.

Action buttons read the `button.primary` or `button.secondary` slot and the
`theme.consentActions` entry for their `consentAction`. `noStyle` on a
button drops c15t's button classes and keeps slot classes. `noStyle` on
`Root` removes the built-in styling from every part inside it.

[Customize](/docs/frameworks/react/customize) shows where to set tokens,
slots and `consentActions` in a React app.

## Check the result

1. Clear site data and reload. The composed banner appears with your
   buttons. In DevTools Elements, each action is your element with a
   `data-action` attribute. In DevTools Network, no optional vendor request
   has fired.
2. Tab through the banner. Every action is reachable in the policy's order
   and shows a focus ring. Press Enter on Customize, and the preference
   dialog opens.
3. Click Reject all. The banner closes. Reload, and it stays closed with
   the vendors still blocked.
4. Reopen preferences from your footer link. The optional categories are
   off. Allow one, save, and only that category's vendors load.
5. If your policies include a notice region, test it too. The banner shows
   your acknowledgement button and no Accept or Reject.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Headless
URL: https://c15t.com/docs/frameworks/react/headless
Build a custom consent banner in React with the c15t/react/headless hooks inside your ConsentProvider.

## When to go headless

The pre-built banner and dialog cover most designs through props, slots, and
the stylesheet. Go headless when your markup has to be something else
entirely: a design system component, a native sheet, or a layout the compound
parts cannot express.

Headless code owns the rendered controls, so it also owns the compliance
outcome. The hooks hand you the actions a policy requires, the rights it must
keep reachable, and diagnostics when your presentation drops one. Render from
those lists rather than from a fixed set of buttons, and a site that later adds
a notice region keeps working without a code change.

Check for a policy before rendering your own surfaces. `useModel()` from
`c15t/react` returns `null` while no rule has resolved and `'none'` under a
rule that owes no consent UI, and the pre-built surfaces render nothing in that
state.

## Minimal example

The headless hooks read the runtime from the nearest `ConsentProvider` from
`c15t/react`. Render this component inside that provider in place of the stock
banner, and keep the dialog and persistent preferences control.

```tsx title="src/consent-banner.tsx"
import { useHeadlessConsentUI, useTranslations } from 'c15t/react/headless';

const ACTION_LABELS = {
	accept: 'acceptAll',
	customize: 'customize',
	dismiss: 'acknowledge',
	reject: 'rejectAll',
	save: 'save',
} as const;

export const Banner = () => {
	const { banner, performAction, openDialog } = useHeadlessConsentUI();
	const { common, rights } = useTranslations();

	if (!banner.isVisible) {
		return null;
	}

	return (
		<section aria-label="Privacy">
			{banner.preferenceControls.map((right) => (
				<button key={right} type="button" onClick={openDialog}>
					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
				</button>
			))}
			{banner.actionGroups.map((group) => (
				<div key={group.join('-')}>
					{group.map((action) => (
						<button
							key={action}
							type="button"
							data-primary={banner.primaryActions.includes(action) || undefined}
							onClick={() => performAction(action)}
						>
							{common[ACTION_LABELS[action]]}
						</button>
					))}
				</div>
			))}
		</section>
	);
};
```

`banner.actionGroups` is the resolved layout: reject and accept share a group
at equal prominence, and the rest follow. `banner.orderedActions` is the same
list flattened. Under a notice the only action is `dismiss`, and
`banner.preferenceControls` recommends additional buttons for opening
preferences. Under a notice it contains `opt-out`, which selects the
"Do not sell or share my data" label. The example renders that button and
an "OK" button. Both controls keep their own command: opening
preferences and dismissing the notice.

The list is a rendering helper. It does not establish that your UI implements
all policy rights. Provide disclosure and persistent preferences access.

`performAction` saves all categories for `accept`, none for `reject`, the
current draft for `save`, records a dismissal for `dismiss`, and opens the
preference center for `customize`. `banner.diagnostics` reports when a host
layout drops a required action or gives equivalent actions different
prominence. Review each diagnostic when configuring custom presentation.

`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
shape from `presentation.prompt`, so a headless surface can follow the same
bar, widget, or wall choice the pre-built banner would make, and can trap
focus and lock scroll exactly when `blocking` is true.

# Components
URL: https://c15t.com/docs/frameworks/react/components
Every c15t component a React app imports from c15t/react, what each renders, where each one mounts, and which to start with.

## Component reference

`c15t/react` exports the provider, the consent UI and the hooks from one
import path. Every component except `ConsentProvider` and `ConsentTheme`
reads the runtime the provider creates, so render them inside
`ConsentProvider`.

|Component|Renders|Reference|
|--|--|--|
|`ConsentProvider`|The consent runtime, which loads the policy, stores the choice and loads scripts. No markup of its own|[ConsentProvider](/docs/frameworks/react/components/consent-provider)|
|`ConsentBanner`|The banner, when the visitor's policy asks for one|[ConsentBanner](/docs/frameworks/react/components/consent-banner)|
|`ConsentDialog`|The preference center as a modal|[ConsentDialog](/docs/frameworks/react/components/consent-dialog)|
|`ConsentWidget`|The preference center inline in a page, for a privacy route|[ConsentWidget](/docs/frameworks/react/components/consent-widget)|
|`ConsentDialogLink`|An unstyled button that opens the dialog, for your footer|[ConsentDialogLink](/docs/frameworks/react/components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens the dialog. `ConsentDialogTriggerToolbar` adds your own actions beside it|[ConsentDialogTrigger](/docs/frameworks/react/components/consent-dialog-trigger)|
|`ConsentGate`|Its children while a category is allowed, a placeholder otherwise|[ConsentGate](/docs/frameworks/react/components/consent-gate)|
|`ConsentTheme`|A `<style>` element with your theme tokens|[Customize](/docs/frameworks/react/customize)|
|`DevTools` from `c15t/react/devtools`|A development panel for consent state, scripts and events|[DevTools](/docs/frameworks/react/components/dev-tools)|

Mount one `ConsentProvider` at the root of the app and keep it mounted across
client navigation. The provider reads `mode` and its module options once,
when it mounts.

## Start with the provider, banner and dialog

Most apps start with four components. `ConsentProvider` holds the runtime,
`ConsentBanner` and `ConsentDialog` ask for a choice, and a
`ConsentDialogLink` lets visitors reopen their preferences. The [quickstart](/docs/frameworks/react/quickstart) puts them in
one file:

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

Add `ConsentWidget`, `ConsentDialogTrigger` or `ConsentGate` later, where a
page needs them. Keep `ConsentDialog` mounted even when you add a widget,
because the banner's Customize button and every dialog link open it.

## Server-rendered React apps

React Router framework mode, Remix and other server-rendered React apps use the
same components. `ConsentProvider` renders on the server without touching
browser APIs, and the banner mounts after hydration, once the browser has
resolved the policy. [Rendering](/docs/frameworks/react/rendering#react-router-remix-and-other-server-rendered-apps)
explains the trade-off.

## IAB TCF components

Import `IABProvider`, `IABConsentBanner` and `IABConsentDialog` from
`c15t/react/iab`, render them inside `ConsentProvider` next to
`ConsentBanner` and `ConsentDialog`, and load `c15t/react/styles.css` and
`c15t/react/iab/styles.css` with `styles: false`. The stock banner and dialog stay closed
under an IAB policy. See
[IAB TCF](/docs/frameworks/react/iab).

## Other entry points

|Import|Exports|Use|
|--|--|--|
|`c15t/react/consent-banner`, `c15t/react/consent-dialog`, `c15t/react/consent-widget`, `c15t/react/consent-dialog-link`, `c15t/react/consent-dialog-trigger`, `c15t/react/consent-gate`|One component each|A module that needs one component without the rest of the adapter|
|`c15t/react/headless`|Headless hooks|Your own banner and dialog markup. See [headless](/docs/frameworks/react/headless)|
|`c15t/react/server`|`fetchSSRData` and its helpers|Resolve `/init` in a server loader. See [rendering](/docs/frameworks/react/rendering#skip-the-browsers-first-init-request)|
|`c15t/react/devtools`|`DevTools`|Development only|

## Check the components

Load the app in a private window under a policy that asks for a choice:

1. The banner shows, and DevTools Network has no requests to your vendors'
   hosts.
2. Click the footer's `ConsentDialogLink`. The dialog opens with every optional
   category off.
3. Allow one category and save. Its vendor requests appear, and a
   `ConsentGate` for that category mounts its children.
4. Reload. The banner stays closed, and the link still reopens the dialog.

# ConsentProvider
URL: https://c15t.com/docs/frameworks/react/components/consent-provider
Mount ConsentProvider in a React app and configure its backend, scripts, storage, blocking and presentation options.

## Mount one provider

`ConsentProvider` creates the consent runtime, loads the policy, stores the
visitor's choice and loads consent-gated scripts. Render one provider at the
root of your app and put the banner, dialog and a preferences link inside it.
The [quickstart](/docs/frameworks/react/quickstart) does this in
`src/consent.tsx`:

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

`manifest()` from `c15t/react` resolves the policy from the snapshot
`consentManifest()` bundled, and sends consent choices to the backend URL the
plugin read from `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`. Set one
to the backend URL from your Inth project. To fetch the policy from the backend on every page
load instead, pass `hosted()` from `c15t/react`. The Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
this provider and passes it server-resolved state.

## Provider options

Keep the provider mounted across client navigation. It reads `mode`,
`prefetch`, `persistence`, `storageConfig`, `clearOnRevocation`, `i18n` and
`experiment` once, when it mounts. Outside production, changing `mode`,
`i18n`, `experiment`, `persistence` or `storageConfig` logs a warning. Remount
the provider to change them. `scripts`, `vendors`, `networkBlocker`,
`iframeBlocker`, `consentCategories`, `overrides`, `user`, `callbacks` and
`enabled` apply when they change.

|Option|Purpose|
|--|--|
|`mode`|Required. `manifest()` for a bundled policy, `hosted()` for the backend's `/init`, `offline()` for local policies, all from `c15t/react`, or `custom()` for your own transport. See [consent modes](/docs/concepts/modes)|
|`prefetch`|Server-resolved state, or a promise of it, from a framework adapter's server helper|
|`scripts`|Consent-gated vendor scripts. See [scripts and embeds](/docs/frameworks/react/scripts)|
|`vendors`|Vendors listed under their category with their own switch. See [vendor consent](/docs/frameworks/react/vendor-consent)|
|`scriptLoader`|Options for the script loader module|
|`networkBlocker`|Rules that hold `fetch` and `XMLHttpRequest` calls until their category is allowed, or `false`|
|`iframeBlocker`|Gates DOM iframes that carry `data-category`. On by default; `false` turns it off|
|`persistence`|Stores the visitor's choice in a cookie and localStorage. On by default|
|`storageConfig`|Storage key and cookie settings for the stored choice|
|`clearOnRevocation`|Cookies and storage keys to delete when a category is denied|
|`reloadOnConsentRevoked`|Reload the page after the visitor turns off a granted category or vendor. Defaults to `true`|
|`consentCategories`|Categories the preference dialog offers alongside those your scripts use, within the policy's scope|
|`overrides`|Force the country, region or language the policy is resolved for, for testing|
|`user`|Link consent records to a signed-in user|
|`callbacks`|Choice, permission and error events|
|`i18n`|Languages and message overrides|
|`legalLinks`|Privacy policy and other links shown in the banner and dialog|
|`theme`|`consentActions` and slot styles. Tokens go through `ConsentTheme`; see [customize](/docs/frameworks/react/customize)|
|`components`|Slot attributes per component part|
|`presentation`|Banner and dialog shape, position and blocking|
|`experiment`|A/B test of `presentation`, read once at mount. See [banner experiments](/docs/guides/banner-experiments)|
|`journey`|Random id that links each `/init` to the save that follows. See [session reports](/docs/concepts/data-fetching#link-an-init-to-the-save-that-follows)|
|`colorScheme`|`'light'`, `'dark'`, `'system'`, or `null` to leave the `c15t-dark` class alone|
|`noStyle`, `disableAnimation`|Drop the built-in styles, or turn off animations|
|`preloadDialog`|When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](/docs/frameworks/react/components/consent-dialog#behavior)|
|`nonce`|Content Security Policy nonce for script elements c15t inserts|
|`enabled`|Set `false` only when you deliberately bypass consent enforcement|

`enabled: false` grants categories and allows gated loading while suppressing
consent UI. It is not a way to fix failed initialization or hide a banner in
production.

## Observe changes without inventing choices

`onChoiceRecorded` reports explicit accept, reject and save actions.
`onPermissionsChanged` also covers changes caused by policy, expiry or privacy
signals. Hydration and notice dismissal do not become explicit choices.

An externally owned runtime can be passed through `runtime`. Its owner must
start and dispose it. A provider borrowing that runtime must not initialize or
dispose a second copy. Passing a different `runtime` moves the provider and its
hooks to the new runtime's kernel and unsubscribes them from the previous one.
The previous runtime keeps running until its owner disposes it. Switch the
provider to another runtime, or unmount it, before disposing the runtime it
renders. Changing between a borrowed runtime and a provider-created one still
requires remounting the provider. IAB actions taken before its handle is ready
wait for that handle. If the provider unmounts or switches runtimes first, a
pending `save()` rejects with an `AbortError` instead of waiting indefinitely.
See [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) and
[choose your setup](/docs/concepts/choose-your-setup).

## Reload after revocation

Removing a script cannot stop code that already ran. A vendor's listeners,
timers and widgets keep working until the page unloads. When an accept, reject
or save turns off a category or vendor that was granted, the provider reloads
the page once the save request settles, so the next page runs only permitted
code. `onBeforeConsentRevocationReload` runs just before the reload.

Otherwise, expiry, policy changes and privacy signals do not reload the page. Set
`reloadOnConsentRevoked: false` only when every gated vendor stops itself on
revocation, for example through its own opt-out API.

## Clear data when consent is denied

Set `options.clearOnRevocation` to declare cookies, localStorage keys, and
sessionStorage keys by optional consent category. Cleanup waits for policy
resolution, then clears denied categories and later allowed-to-denied
transitions. This option is initial-only. See
[clear on revocation](/docs/frameworks/react/clear-on-revocation) for examples,
cookie scopes, and browser limits.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/react/components/consent-banner
Render the c15t consent banner in a React app, choose its variant and position, and compose its parts.

## Render the banner inside `ConsentProvider`

Render `ConsentBanner` once inside `ConsentProvider`, next to `ConsentDialog`.
The [quickstart](/docs/frameworks/react/quickstart) mounts both in
`src/consent.tsx`:

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

The banner renders whatever the active policy rule requires. It reads the rule
through the provider, so the same component serves every region:

* A `choice` prompt shows the actions the rule allows: reject and accept at
  equal prominence, plus customize when the rule offers it.
* A `notice` prompt shows an "OK" button and a button styled as
  underlined text, labeled "Do not sell or share my data". The latter opens
  preferences. A notice never traps focus or locks scroll.
* A rule with `prompt: 'none'` renders nothing.

An opt-out rule with `prompt: 'none'` still has rights, so the preference
center and the dialog trigger stay available as the route to preferences. A
rule with `model: 'none'` owes no rights, so nothing renders unless you add
`rights: ['preferences']`. With no resolved rule at all, because resolution
failed, no rule matched and you set no default, or init is still withheld, no
consent surface renders: not the banner, the dialog, the widget, the
preferences link, or the trigger. They appear as soon as a rule resolves,
without a remount. `offline()` without `policyRules` resolves the recommended
pack, so it shows the strict opt-in banner until you pass a country.

Acknowledging a notice records its dismissal. It does not record consent or
change category permissions, including existing denials and privacy-signal
restrictions. Customize the label through `common.acknowledge` in your
translations, or use `dismissButtonText` for one banner.

The additional preferences button uses the opt-out label when appropriate.
A choice prompt without Customize renders a "Manage preferences" button.
Both are button elements that open the preference center; CSS gives them
an underlined text appearance. They do not submit an opt-out by themselves.

`preferenceControls` recommends these extra buttons for the stock UI.
It does not verify disclosure or access to rights. Configure your legal links
and keep preferences reachable after the banner closes.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`title`|`ReactNode`|translation|Overrides the title. Under a notice the default is `cookieBanner.noticeTitle`.|
|`description`|`ReactNode`|translation|Overrides the description. Under a notice the default is `cookieBanner.noticeDescription`.|
|`acceptButtonText`|`ReactNode`|`common.acceptAll`|Accept label.|
|`rejectButtonText`|`ReactNode`|`common.rejectAll`|Reject label.|
|`customizeButtonText`|`ReactNode`|`common.customize`|Customize label.|
|`dismissButtonText`|`ReactNode`|`common.acknowledge`|Label of the notice acknowledgement.|
|`variant`|`PromptVariant`|`floating`|Shape of the prompt. See [Variants](#variants).|
|`position`|`PromptPosition`|per variant|Where the prompt sits. Must be valid for the variant.|
|`blocking`|`boolean`|`true` on `wall`|Backdrop, scroll lock, focus trap, and no outside dismissal, as one value.|
|`layout`|`ConsentBannerLayout`|policy default|Orders and groups actions. Required actions the layout omits are restored.|
|`primaryButton`|`ConsentBannerButton \|ConsentBannerButton[]`|`'customize'`|Which actions get the primary treatment. On a notice, dismiss is primary when it is the only action.|
|`direction`|`'row' \|'column'`|`'row'`|How action groups flow.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which configured legal links render inline.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`scrollLock`|`boolean`|unset|Deprecated. Use `blocking` to control scrolling, focus and backdrop together.|
|`trapFocus`|`boolean`|unset|Deprecated. Use `blocking`.|
|`disableAnimation`|`boolean`|`false`|Skips enter and exit animations.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Per-policy buttons

The default already makes Customize primary on a choice banner and OK
primary on a notice. To set button order and treatment for specific rules,
read the active policy inside the provider:

```tsx
import { ConsentBanner, usePolicyRule } from 'c15t/react';
import type { ConsentBannerProps } from 'c15t/react';

const banners: Record<
	string,
	Pick<ConsentBannerProps, 'layout' | 'primaryButton' | 'variant'>
> = {
	europe_opt_in: {
		layout: [['reject', 'accept'], 'customize'],
		primaryButton: 'customize',
	},
	us_privacy_states: {
		layout: ['dismiss'],
		primaryButton: 'dismiss',
		variant: 'bar',
	},
};

export function RegionalBanner() {
	const policy = usePolicyRule();
	return <ConsentBanner {...(policy ? banners[policy.id] : undefined)} />;
}
```

Render `RegionalBanner` inside `ConsentProvider`. The layout controls the
action groups; the opt-out preferences button still appears on a notice.
Required actions omitted from a layout are restored. Accept and Reject
keep equivalent default prominence.

Choose one brand color and make whichever action is primary use a filled
button through the provider's theme:

```ts
const theme = {
	colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
	consentActions: { primary: { variant: 'primary', mode: 'filled' } },
} as const;
```

Pass `theme` in `ConsentProvider` options. Per-action theme overrides such
as `consentActions.dismiss` take precedence over this primary style.
See [customize](/docs/frameworks/react/customize) for tokens and slots, and
[policies](/docs/concepts/policies) for the rule IDs and coverage.

## Variants

The policy decides which actions the banner offers. The variant decides the
shape those actions take. Both come from the same component, so a bar for a
notice region and a card for an opt-in region need no extra components.

Set the variant on the banner, or on the provider under
`presentation.prompt` when every banner should share it. The prop wins.

```tsx
<ConsentBanner variant="floating" position="bottom-center" />;
```

A floating card in a corner or centered on an edge. This is the default for
every prompt. A notice keeps the same card, with its right link and "OK" in the footer.

```tsx
<ConsentBanner variant="bar" position="top" />;
```

A bar across the full width of the viewport. From 1024px wide the text, the
right links, and the controls share one row. Opt in to it for regions that
expect a classic cookie bar.

```tsx
<ConsentBanner variant="widget" position="bottom-right" />;
```

A compact card with smaller type. The full description and its legal links
remain visible. Pair it with a short notice.

```tsx
<ConsentBanner variant="wall" />;
```

A centered card over a backdrop that blocks the page until the visitor
answers. A wall is always blocking.

Each variant accepts its own positions:

|Variant|Positions|Default|
|--|--|--|
|`floating`|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|`top`, `bottom`|`bottom`|
|`widget`|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|`center`|`center`|

A default corner mirrors left and right for right-to-left languages. A
position you set is never mirrored. A position that is not valid for the
variant falls back to the default and logs an `invalid-position` diagnostic
in development.

`blocking` controls the backdrop, scroll lock, and focus trap together.
An explicit value overrides the deprecated `scrollLock` and `trapFocus`
options. Without `blocking`, either legacy option set to `false` selects
non-blocking behavior; otherwise a legacy `true` selects blocking behavior.

A choice `wall` always blocks. Notices always stay non-blocking, and asking
for a notice `wall` falls back to `floating` with an `invalid-variant`
diagnostic. Blocking banners carry `role="dialog"` and `aria-modal="true"`.
Non-blocking banners leave page controls usable by keyboard and pointer.

`PromptVariant` and `PromptPosition` are exported from `c15t/react`.
Compound parts can read the resolved shape with `useConsentBannerSurface()`,
which returns `variant`, `position`, `positionSource` (`host` or `default`),
and `blocking`.

## Composition

Every part is available as `ConsentBanner.<Part>` for custom layouts. The
parts read the same policy state the pre-built banner does, so a custom layout
still gets the right actions for the active rule.

```tsx
import { ConsentBanner } from 'c15t/react';

export function CompactBanner() {
	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions />
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
}
```

`ConsentBanner.PolicyActions` renders the resolved action groups and, before
them, the additional preferences buttons. Pass children to replace those
buttons while retaining the policy action groups. This supports custom labels
and button markup.

Use the individual parts when you need a different order or your own markup:

* `ConsentBanner.AcceptButton`, `ConsentBanner.RejectButton`,
  `ConsentBanner.CustomizeButton`, and `ConsentBanner.DismissButton` render one
  action each. `DismissButton` defaults its label to `common.acknowledge`.
* `ConsentBanner.Rights` renders the additional preferences buttons. It
  renders nothing when the list is empty. Pass `rights` to override the
  list.
* `ConsentBanner.RightLink` renders a single right. `right` is `'opt-out'`
  or `'preferences'`. By default it is a button element styled as an
  underlined text link, carrying `data-action="right"` and `data-right`; it
  opens the preference center on click and accepts `asChild` to render your
  own element, such as an anchor to a dedicated opt-out page.

```tsx
<ConsentBanner.Rights>
	<ConsentBanner.RightLink right="opt-out" asChild>
		<a href="/privacy/do-not-sell">Do not sell or share my data</a>
	</ConsentBanner.RightLink>
</ConsentBanner.Rights>;
```

`useBannerCopy()` returns the title, description, and prompt kind the banner
would use, for custom headers that still follow the notice copy.

## Data attributes

The root element carries attributes you can target from CSS or Tailwind. The
card carries `data-state` (`open` or `closed`) for the enter and exit
animations.

|Attribute|Values|
|--|--|
|`data-prompt`|`choice`, `notice`|
|`data-model`|`opt-in`, `opt-out`, `iab`|
|`data-variant`|`floating`, `bar`, `widget`, `wall`|
|`data-position`|The resolved position for the variant|
|`data-blocking`|`true`, present only while blocking|

Each action button carries `data-action`, and each right link carries
`data-action="right"` plus `data-right`. The built-in stylesheet keys every
variant's geometry on `data-variant` and `data-position`, and uses
`data-prompt="notice"` to lay the footer out as one row with the right
links leading and "OK" trailing.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/react/components/consent-dialog
Open the c15t preference center as a modal ConsentDialog in a React app, wire its triggers and control blocking, focus and policy gating.

## Open the preference center

`ConsentDialog` is the modal preference center. Mount it once inside
`ConsentProvider`, next to the banner, and it opens whenever something makes
`dialog` the active surface: the banner's Customize button, a
`ConsentDialogLink` in your footer, a `ConsentDialogTrigger`, or your own
code.

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

To hide the "Secured by" tag in the dialog card, pass `hideBranding`:

```tsx
<ConsentDialog hideBranding />;
```

To open it from your own component, set the active surface:

```tsx
import { useSetActiveUI } from 'c15t/react';

export function PrivacyMenuItem() {
	const setActiveUI = useSetActiveUI();
	return (
		<button type="button" onClick={() => setActiveUI('dialog')}>
			Cookie preferences
		</button>
	);
}
```

`ConsentDialogLink` does the same with the policy's rights exposed for
styling; see [ConsentDialogLink](./consent-dialog-link). For a floating
button, see [ConsentDialogTrigger](./consent-dialog-trigger). Under an IAB
policy, mount `IABConsentDialog` from the [IAB guide](/docs/frameworks/react/iab)
instead; this dialog stays closed for the `iab` model.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`open`|`boolean`|follows the active surface|Controls the open state. When set, Escape and the dialog's own Save Settings, Accept All and Reject All buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed.|
|`showTrigger`|`boolean \|ConsentDialogTriggerProps`|`false`|Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'none']`|Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag in the card.|
|`uiSource`|`string`|`'dialog'`|Source identifier recorded with saves made from this dialog.|
|`scrollLock`, `trapFocus`|`boolean`|from `blocking`|Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.|
|`disableAnimation`|`boolean`|`false`|Skips the enter and exit animation of the backdrop and the card.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The dialog is a modal wrapper around the preference center. Its card has a
header with the title `consentManagerDialog.title` and the description
`consentManagerDialog.description` followed by the legal links, then the
same category accordion and Reject All, Accept All and Save Settings actions that
`ConsentWidget` renders, then the branding tag. It mounts through a portal
into `document.body` after hydration, so it is never part of the server
HTML.

Without an `open` prop, the dialog follows the active surface and opens while
it is `dialog`. These set that surface:

* The Customize button on a `ConsentBanner`, and the "Manage preferences"
  or "Do not sell or share my data" button a notice renders.
* `ConsentDialogLink` and `ConsentDialogTrigger`.
* The button in a `ConsentGate` placeholder.
* `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
  from `useHeadlessConsentUI()` on the headless subpath.

The component code is split into its own chunk, so it is not part of the
first page load. It renders nothing until that chunk is ready, and the
chunk downloads at the first of these:

* The browser's first idle period after the page's `load` event, while the
  banner is shown or a `ConsentDialogLink`, `ConsentDialogTrigger`,
  `ConsentGate` button or other button that opens the dialog is mounted.
  This covers a visitor who taps or presses Enter with no hover or focus
  first. Browsers without `requestIdleCallback`, such as Safari, wait
  200 ms after `load` instead.
* Hover or focus on a button that opens the dialog.
* The dialog opening.

Passing `open={true}` or `showTrigger` loads it on mount. A visit with
saved consent and nothing on the page that opens the dialog never
downloads it.

Idle loading is skipped when the visitor has Save-Data on
(`navigator.connection.saveData`), on a `2g` or `slow-2g` connection, and
while offline; hover and focus still load it. To load the chunk only on
hover, focus or open, set `preloadDialog: 'intent'` in the provider
options. The default is `'idle'`. With Next.js, pass it through
`ConsentRoot`'s `options` prop.

If a preload fails, for example because the visitor is offline, nothing is
cached: the next hover, focus or open tries the download again.

The dialog's CSS travels in the same chunk and is applied before the dialog
renders, so the first page load carries only the banner's rules.

Without an `open` prop, Escape closes the dialog without saving. If the
policy still owes a choice, the banner comes back. Save Settings, Accept All and
Reject All close it as soon as the choice is recorded in the browser, in
the same task as the click; the exit animation still plays. The request to
the backend runs afterwards and never reopens the dialog: a failed request
keeps the choice, reports through `onError` and is retried later. See
[when a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
for the order of events. A draft that went stale because the policy changed keeps the dialog open
for review. With `open={true}`, these actions leave the dialog visible; the
parent must set `open={false}` to close it. Clicking the backdrop does not
close it. Closing discards toggles that were not saved: the next open starts
from the recorded choice again. After a save from an uncontrolled dialog,
every consent surface hides unless the policy still owes a prompt, in which
case the banner returns.

The preference center is blocking by default: a backdrop, body scroll lock
and focus trap, all as one value. Set `presentation.preferences.blocking`
to `false` in the provider options to remove all three; the deprecated
`scrollLock` and `trapFocus` props do the same for one dialog. `variant`
and `position` are prompt options. Setting them under
`presentation.preferences` logs an `invalid-variant` diagnostic in
development and changes nothing; the dialog is always centered.

The dialog never opens without a resolved policy rule, even when the
active surface is already `dialog`; it appears as soon as a rule resolves,
without a remount. A rule with `model: 'none'` and no rights owes no consent
UI, so the dialog stays closed under it. When such a rule lists any right,
for example `rights: ['disclosure']` or `rights: ['preferences']`, the dialog
can open as a settings route and Save completes without writing a consent
record.

Copy comes from these translation keys: `consentManagerDialog.title`,
`consentManagerDialog.description`, `common.acceptAll`, `common.rejectAll`,
`common.save`, and `consentTypes.<category>.title` and `.description` for
each row.

## Accessibility

The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
while it is blocking. Its `dir` attribute follows the active language.

While blocking, focus moves on open to the first tabbable control in the
panel, so a keyboard user sees the focus ring on a control rather than
around the whole panel; the `aria-labelledby` and `aria-describedby`
wiring means a screen reader still announces the title and description as
focus enters. Tab and Shift+Tab wrap inside the panel, and on close focus
returns to the element that opened the dialog. A non-blocking dialog manages no focus: nothing moves focus into the
panel or back to the opener. The backdrop is `aria-hidden` and is not
focusable.

Each category switch has the category title as its accessible name. The
`necessary` switch is disabled and always on. A saved grant that the current
policy or a privacy signal overrides gets a note under its row, linked to
the switch through `aria-describedby`.

## Composition

Every part is available as `ConsentDialog.<Part>`: `Root`, `Overlay`,
`Card`, `Header`, `HeaderTitle`, `HeaderDescription`, `Content`, `Footer`
and `ConsentCustomizationCard`, the stock card. `Root` provides the portal,
open state, focus trap, scroll lock and backdrop, and accepts `open`,
`models`, `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`,
`uiSource` and `overlay`. Pass `overlay={false}` to render no backdrop, or a
node to replace the built-in one.

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription legalLinks={['privacyPolicy']} />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Keep `ConsentWidget` inside `Content`: it owns the draft, the switches and
the policy actions, and inherits the dialog's `uiSource`. `Footer` renders
the branding tag unless you pass children or `hideBranding`.

The positioner carries `data-slot="dialog-positioner"`, and both it and the
panel carry `data-blocking="true"` while blocking. Provider component slots
for the stock structure are `dialog.root`, `dialog.container`,
`dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
`dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.

`ConsentDialog` from the package root and from the
`c15t/react/consent-dialog` subpath is the deferred component described
under Behavior, and each `ConsentDialog.<Part>` loads with the same chunk.
`c15t/react/components/consent-dialog` exports the dialog without the
deferral, plus each part as a named export (`Card`, `Header`, `Overlay`,
`Root` and the rest). Importing from that path puts the dialog's code in
the bundle of every page that imports it, so the first open needs no
download but every visitor downloads the dialog.

The compound parts import from `c15t/react` as properties of `ConsentDialog`,
and `ConsentWidget` from the same module. See
[customize](/docs/frameworks/react/customize) for slots and tokens.

## Verify

Use the default blocking, uncontrolled dialog and an optional in-scope
category that is not restricted by policy or privacy signals such as GPC.
Open the dialog from the banner's Customize button or a preferences link.
A centered card appears over a dimmed backdrop, the page behind it stops
scrolling, and Tab stays inside the card. Press Escape: the card closes and
focus returns to the button you used. Open it again, turn a category on and
choose Save. The dialog closes and `useConsent('<category>')` reports
`true` in your components; under a choice prompt the banner does not return,
while a `notice` prompt keeps its banner until it is acknowledged. Reload the
page and reopen the dialog: the switch reflects the saved choice.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/react/components/consent-widget
Embed the c15t preference center inline with ConsentWidget on a React privacy page, with draft toggles that record a choice only on Save.

## Embed the preference center inline

`ConsentWidget` renders the preference center in the page flow instead of in
a modal: the category switches and the Reject All, Accept All and Save Settings
actions, without a title, backdrop or portal. Use it on a privacy or
settings page where the visitor expects the controls to be part of the
content. Render it anywhere inside the `ConsentProvider` from your
[quickstart](../quickstart); keep `ConsentDialog` mounted as well so the
banner's Customize button and preference links still have a dialog to open.

```tsx title="src/pages/privacy.tsx"
import { ConsentWidget } from 'c15t/react';

export function PrivacyPage() {
	return (
		<main>
			<h1>Privacy</h1>
			<p>Choose which optional categories this site may use.</p>
			<section aria-labelledby="cookie-preferences">
				<h2 id="cookie-preferences">Cookie preferences</h2>
				<ConsentWidget />
			</section>
		</main>
	);
}
```

The widget uses the provider's policy, translations and transport. It does
not need a second `ConsentProvider`, and it does not open or close the banner
or dialog by itself.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|A standalone widget hides the "Secured by" tag. Pass `false` to show it.|
|`uiSource`|`string`|`'widget'`|Source identifier recorded with saves made from this widget. Inside `ConsentDialog` it inherits `'dialog'`.|
|`disableAnimation`|`boolean`|`false`|Skips animations in the widget's parts.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The widget is the preference center without the modal around it: an
accordion with one row per category, each with a switch, followed by the
Reject All, Accept All and Save Settings actions. `ConsentDialog` renders this same
widget inside its card. Standalone, the widget renders in place, takes part
in server rendering, and does not touch the active surface, so it suits a
privacy page or an account settings screen.

The rows are `necessary` plus the categories in the active policy's scope,
narrowed to the categories the provider declares: `options.consentCategories`
and the categories of its scripts, network rules, vendors and discovered
frames. When nothing is declared, a permissive policy shows only `necessary`
and a strict one its whole scope.
The `necessary` switch is on and disabled. Row titles and descriptions come
from `consentTypes.<category>.title` and `.description`; the action labels
from `common.rejectAll`, `common.acceptAll` and `common.save`. One row is
expanded at a time.

### Draft and save

Switches edit a draft, not the visitor's permissions. Nothing is recorded
until Save. The draft seeds each category from the recorded choice; without
one it uses `presentation.preferences.defaults` from the provider options,
and without that it is on under an opt-out rule and on only for the rule's
preselected categories under an opt-in rule. Save records the displayed
categories, then reseeds the draft from the new record. Accept All and
Reject All record immediately without a separate Save. A save answers a
choice prompt, so an open choice banner closes; it does not dismiss a
`notice` prompt, which keeps its own acknowledgement record. Unsaved toggles
are lost when the widget unmounts.

When the policy changes in a way that affects the choice while the draft has
unsaved toggles, the widget shows an alert, "The privacy policy changed.
Review the current choices before saving.", with a Review choices button
that resets the draft. Save is refused until then. A draft without unsaved
toggles reseeds silently.

A saved grant that the current policy or a privacy signal such as Global
Privacy Control overrides shows a note under its row: "Your saved choice is
restricted by the current privacy settings." The switch still reflects the
saved value; the effective permission is off.

### Vendors

When the provider declares `vendors`, each category's expanded description
ends with one card per vendor whose category condition names that category,
styled like a category row: the vendor's name and a switch on the header,
and its description and privacy policy link behind the card's own expand
control. Cards start collapsed, so a long list stays one line per vendor,
and the category list scrolls inside the dialog rather than growing it.
A collapsed category or card renders its content element empty and mounts
the content the first time it opens, then keeps it mounted, so a long
vendor list costs nothing until a visitor expands its category.
Vendor switches edit the same draft as the category
switches and record on Save. Saving with one vendor off denies that vendor
only; the category stays granted and its other vendors keep loading. While
the category is off in the draft the vendor switches are disabled, with the
hint "Turn on this category to choose vendors." A vendor declared
`disabled`, or one that only falls under `necessary`, is listed without a
switch. Accept All and Reject All clear every vendor denial, including one
staged but not yet saved. Under an `iab` policy no vendor rows render.
Vendors that are only referenced by a script slug, without a name and
privacy policy URL, still gate loading but are not listed, and so does a
vendor whose condition negates a category, since no category row can
host it. See
[vendor consent](../vendor-consent).

### Actions

The preference center always renders Reject All, Accept All and Save Settings, with
Save Settings as the primary action. `presentation.preferences.layout`,
`primaryActions`, `direction` and `uiProfile` in the provider options
reorder and restyle them; a layout that omits one of the three has it
restored. Customize and dismiss actions never render here.

### When consent is not owed

Without a resolved policy rule the widget renders nothing and appears as
soon as a rule resolves, without a remount. A rule with `model: 'none'` and
an empty `rights` list renders nothing; a `none` rule that lists any right,
such as `['disclosure']`, renders the widget and Save completes without
writing a consent record.

For a fully custom preference center, `useConsentDraft()` returns the same
draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
the declared list, the recorded denials and one vendor's effective result.

`useConsentDraft` and `ConsentDraftProvider` import from `c15t/react`.

## Accessibility

Each row is a disclosure: a button that expands the category description
and a switch beside it, so a visitor can read the description without
changing the choice. Each switch has the category title as its accessible
name. A category's vendor cards sit in a `region` named "Vendors" with the
count; each card's expand button carries `aria-expanded`, each vendor
switch is named "Allow" followed by the vendor name, and is described by
the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
an `output` element linked to its switch through `aria-describedby`. The
root's `dir` attribute follows the active language.

## Composition

Every part is available as `ConsentWidget.<Part>`. `Root` provides the
draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
and `AccordionItems` render the stock rows; `AccordionItem`,
`AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
`AccordionArrow` and `Switch` build your own; `VendorList` renders one
category's vendor rows and takes a `category` prop. `PolicyActions` renders the
resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
`CustomizeButton` are the individual buttons.

`Accordion` is controlled: pass `value` and `onValueChange`, or no
category description ever opens. The stock `ConsentWidget` holds that state
for you. In this component, `ConsentWidget` comes from the same import as
the example at the top of the page:

```tsx
import { useState } from 'react';

export function PreferenceCenter() {
  const [open, setOpen] = useState<string[]>([]);

  return (
    <ConsentWidget.Root>
      <ConsentWidget.Accordion
        value={open}
        onValueChange={(next) => setOpen(Array.isArray(next) ? next : [next])}
      >
        <ConsentWidget.AccordionItems />
      </ConsentWidget.Accordion>
      <ConsentWidget.PolicyActions />
    </ConsentWidget.Root>
  );
}
```

Provider component slots for the stock structure are `manager.root`,
`manager.footer`, `manager.actionGroup`, `accordion.root`,
`accordion.triggerRow`, `accordion.title`, `accordion.control`,
`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
`vendor-list.item`, `vendor-list.header`,
`vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
`vendor-list.control` and `tag.manager`.

`ConsentWidget` from the package root and from the
`c15t/react/consent-widget` subpath loads its code in a separate chunk the
first time it renders, so a page that never renders it does not download
it. `c15t/react/components/consent-widget` exports the widget without that
deferral, plus each part as a named export.

The compound parts import from `c15t/react` as properties of `ConsentWidget`.
See [customize](/docs/frameworks/react/customize) for slots and tokens.

## Verify

Visit the page with the widget. Use a displayed optional category whose permission is
not restricted by policy or privacy signals such as GPC. One row per displayed
category appears, with `necessary` on and disabled. Turn that category on:
`useConsent('<category>')`
elsewhere on the page still reports the old value. Choose Save: it now
reports `true`. An open choice banner closes when the save answers its
prompt; a notice banner stays open until acknowledged. Reload the page: the
switch keeps the saved value. Without a saved choice or configured draft
defaults, optional switches start on under an opt-out rule.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/react/components/consent-dialog-link
Add a ConsentDialogLink to a React footer so visitors reopen the c15t preference center from your own text link, with asChild and rights data.

## Reopen the preference center from your footer

`ConsentDialogLink` is an unstyled button that opens the consent dialog.
Put it where your site already keeps its legal links, so preferences stay
reachable after the banner closes. It needs a mounted `ConsentDialog` in the
same `ConsentProvider`; the [quickstart](../quickstart) mounts both.

```tsx title="src/site-footer.tsx"
import { ConsentDialogLink } from 'c15t/react';

export function SiteFooter() {
	return (
		<footer>
			<nav aria-label="Legal">
				<a href="/privacy">Privacy policy</a>
				<a href="/terms">Terms</a>
				<ConsentDialogLink className="footer-link">
					Privacy settings
				</ConsentDialogLink>
			</nav>
		</footer>
	);
}
```

Render `SiteFooter` inside the `Consent` wrapper from your quickstart so the
link can reach the provider. It renders a `button`, so the CSS for
`.footer-link` should reset button chrome if your footer styles target
anchors only.

To reuse an existing link component, pass `asChild`:

```tsx
<ConsentDialogLink asChild>
	<a href="#cookie-preferences">Manage cookies</a>
</ConsentDialogLink>;
```

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`children`|`ReactNode`|required|The visible label, such as "Privacy settings" or "Manage preferences". It is also the accessible name.|
|`asChild`|`boolean`|`false`|Renders your own element, such as an anchor, instead of a `button`, and attaches the click handler to it.|
|`noStyle`|`boolean`|`true`|Omits c15t button classes. Native browser styles remain unless your CSS resets them. Pass `false` to render it as a consent button with `variant` and `mode`.|
|`onClick`|`(event) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to keep it closed.|

Other `button` attributes such as `className`, `style`, `id` and `aria-*`
pass through to the rendered element.

## Behavior

`ConsentDialogLink` renders a `button` with `type="button"` and no c15t
styling by default. Clicking it makes `dialog` the active surface, which opens a
mounted `ConsentDialog`. It performs no save and does not change any
permission.

The element carries `data-c15t-rights` listing the rights of the active
policy rule, for example `disclosure opt-out preferences` under a US
opt-out rule and `disclosure preferences` under an opt-in rule, so a
stylesheet or a `::after` label can adapt the wording by region.

Without a resolved policy rule the link renders nothing and appears as soon
as a rule resolves, without a remount. A rule with `model: 'none'` and an
empty `rights` list owes no consent UI, so the link hides under it; a `none`
rule that lists any right, such as `['disclosure']`, shows the link and the
dialog opens as a settings route.

Mount exactly one `ConsentDialog` inside the same provider. If none is
mounted, the click still switches the active surface: nothing opens, and a
banner that was showing closes because the surface is no longer `banner`.

With `asChild`, the child's own `onClick` runs first; if it calls
`event.preventDefault()` the dialog stays closed. c15t does not prevent the
child's native behavior, so an anchor still follows its `href`. Use a
fragment or the current page as the destination, or render a `button`.

### ConsentDialogLink or ConsentDialogTrigger

Both open the same dialog and carry `data-c15t-rights`. Use
`ConsentDialogLink` where the control belongs in your own layout: a footer,
a privacy page, a settings menu. It has no position, icon or visibility
rule of its own. Use `ConsentDialogTrigger` when you want a floating,
draggable button that positions itself in a corner and can wait until the
prompt is answered.

`ConsentDialogTrigger` has its own page: [ConsentDialogTrigger](./consent-dialog-trigger).

## Accessibility

The rendered `button` is keyboard-focusable and activates with Enter and
Space; its accessible name is the text you pass as `children`, so give it
words that describe the destination rather than "click here". Because the
dialog it opens is labelled by its own title and, while blocking, returns
focus to the link on close, no additional `aria-haspopup` or
`aria-controls` is added; a non-blocking dialog manages no focus, so the
link does not regain it. With `asChild`,
focusability comes from your element: use a `button` or an anchor with an
`href`.

## Verify

Scroll to the footer. With the footer button reset applied, the link uses
your footer's text styles and has no button chrome. Activate it with a click or with Enter: the preference
center opens as a centered dialog. Close it with Escape: with the default
blocking dialog, focus returns to the link. In your browser's element
inspector the link has
`data-c15t-rights`; change the visitor's region to a US opt-out rule and
the value includes `opt-out`. Under a rule with `model: 'none'` and no
rights, the link is absent.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/react/components/consent-dialog-trigger
Add the c15t ConsentDialogTrigger floating button or toolbar inside a React ConsentProvider so visitors can reopen the preference center after the first prompt.

## Add the trigger inside ConsentProvider

`ConsentDialogTrigger` is a draggable floating button that opens the preference center. Place it once inside `ConsentProvider`, next to the banner and dialog from the [quickstart](/docs/frameworks/react/quickstart), so visitors can revisit their choices without a footer link.

```tsx title="src/consent.tsx"
import { ConsentDialogTrigger } from 'c15t/react';

// Inside the ConsentProvider from your quickstart, next to the dialog:
<ConsentDialogTrigger showWhen="after-prompt" />;
```

`showWhen="after-prompt"` keeps the button out of the way while a choice or notice is still owed and shows it once the visitor has answered, so the banner and the trigger never compete for the same corner. The default, `always`, shows it whenever the preference center is closed.

The button carries `data-c15t-rights` with the rights the active policy guarantees, so a stylesheet can label it differently under an opt-out rule.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`icon`|`'branding' \|'fingerprint' \|'settings' \|ReactNode`|`'branding'`|Icon rendered inside the button.|
|`defaultPosition`|`'bottom-left' \|'bottom-right' \|'top-left' \|'top-right'`|`'bottom-right'`|Corner the button starts in.|
|`persistPosition`|`boolean`|`true`|Remember the corner the visitor dragged it to.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the button is visible. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

## Configurable toolbar

Use `ConsentDialogTriggerToolbar` when you want app-owned controls beside the privacy trigger. It always renders exactly one built-in action that opens the preference center, so `actions` only holds controls your app owns.

```tsx
import { ConsentDialogTriggerToolbar } from 'c15t/react';

<ConsentDialogTriggerToolbar
	ariaLabel="Site controls"
	actions={[
		{
			id: 'theme',
			label: isDark ? 'Switch to light theme' : 'Switch to dark theme',
			icon: isDark ? <SunIcon /> : <MoonIcon />,
			pressed: isDark,
			onSelect: toggleColorScheme,
		},
		{
			id: 'support',
			label: 'Open support chat',
			icon: <ChatIcon />,
			onSelect: openSupportChat,
		},
	]}
	preferences={{ icon: 'fingerprint', label: 'Manage privacy settings' }}
/>;
```

Each custom action needs a stable `id`, an accessible `label`, an `icon`, and an `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable ones. Your app owns the state behind each action. The preferences action moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.

Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and switch arrow-key navigation to up and down:

```tsx
<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />;
```

### When the controls show

Your toolbar actions do not depend on the consent policy, so a theme toggle
stays available while a banner is up. The built-in preferences action, and the
single `ConsentDialogTrigger`, follow the policy:

|Situation|Built-in action and `ConsentDialogTrigger`|
|--|--|
|A choice or notice is still owed, with `showWhen="after-prompt"`|Hidden until the visitor answers|
|`showWhen="never"` on the toolbar|Left out of the toolbar|
|No policy rule has resolved: resolution failed, no rule matched and you set no default, or init is still withheld|Hidden; appears without a remount once a rule resolves|
|The rule has `model: 'none'`|Hidden, unless the rule adds `rights: ['preferences']`|
|Any other case|Shown|

On the toolbar, `showWhen` applies only to the built-in action. On the single
`ConsentDialogTrigger`, it applies to the whole control. The toolbar renders
nothing only when it has no visible item.

### What the built-in action says

* Under a rule with the `opt-out` right, such as a US opt-out notice, its
  accessible name is the translated "Do not sell or share my data" and it
  carries `data-right="opt-out"`.
* Under any other rule it reads "Manage preferences" and carries
  `data-right="preferences"`.
* Either way it opens the preference center. A `preferences.label` you pass
  replaces the default name, and the button carries `data-c15t-rights` with
  every right on the rule.

### Toolbar props

|Prop|Type|Default|Description|
|--|--|--|--|
|`actions`|`ConsentDialogTriggerToolbarAction[]`|`[]`|App-owned actions rendered beside the preferences action.|
|`preferences`|`ConsentDialogTriggerToolbarPreferences`|`{}`|Overrides for the built-in action: `icon`, `label`, `onSelect`, `className`, `style`. The label defaults to the opt-out or preferences right on the active rule.|
|`orientation`|`'horizontal' \|'vertical'`|`'horizontal'`|Layout direction.|
|`defaultPosition`|`CornerPosition`|`'bottom-right'`|Corner the toolbar starts in.|
|`persistPosition`|`boolean`|`true`|Remember the dragged corner.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the built-in preferences action is visible. App-owned actions always render. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Size of each action.|
|`ariaLabel`|`string`|`'Privacy controls'`|Accessible name for the toolbar group.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

While `<ConsentDevTools>` is mounted, the toolbar adds a DevTools button at
the end farthest from its corner and opens the DevTools panel beside itself.
The ready-made `ConsentDialogTrigger` switches to this toolbar layout for as
long as DevTools is mounted.

### Toolbar styling

The toolbar follows the standard precedence: bundled styles, then provider slots, then direct `className` and `style` on the toolbar or on one action. Use `noStyle` for a fully custom implementation.

```tsx
<ConsentProvider
	options={{
		mode,
		components: {
			trigger: {
				toolbar: { className: 'my-toolbar' },
				toolbarItem: { className: 'my-toolbar-item' },
				toolbarIcon: { className: 'my-toolbar-icon' },
			},
		},
	}}
>
	<ConsentDialogTriggerToolbar
		className="fixed-toolbar"
		actions={[
			{
				id: 'support',
				label: 'Open support chat',
				icon: <ChatIcon />,
				onSelect: openSupportChat,
				className: 'support-action',
			},
		]}
	/>
</ConsentProvider>;
```

The toolbar slot keys are `trigger.toolbar`, `trigger.toolbarItem`, and `trigger.toolbarIcon`. With `noStyle`, style the current position and interaction state through `data-corner`, `data-dragging`, and `data-snapping` on the toolbar element.

# ConsentGate
URL: https://c15t.com/docs/frameworks/react/components/consent-gate
Gate a YouTube or map iframe behind consent with ConsentGate in React, showing a placeholder that opens the preference center until the category is allowed.

## Gate an embed behind consent

`ConsentGate` mounts its children only while the effective permission for one
consent category is granted, and shows a placeholder otherwise. Wrap any
iframe or third-party widget that would set cookies or contact a vendor on
load. Render it anywhere inside the `ConsentProvider` from your
[quickstart](../quickstart), which also mounts the `ConsentDialog` the
placeholder button opens.

```tsx title="src/product-video.tsx"
import { ConsentGate } from 'c15t/react';

export function ProductVideo() {
	return (
		<ConsentGate category="marketing" className="video-frame">
			<iframe
				src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
				title="Product tour"
				loading="lazy"
				allowFullScreen
				style={{ width: '100%', aspectRatio: '16 / 9', border: 0 }}
			/>
		</ConsentGate>
	);
}
```

`marketing` must be in your policy scope. If you set a non-empty
`options.consentCategories` list on `ConsentProvider`, include `marketing`
there too so the preference center can display and save it. `ConsentGate` does
not add categories to that list.

The placeholder names the category using its title from your translations. Set `className` or `style`
on `ConsentGate` to reserve the embed's space, so the page does not shift when the
placeholder is replaced.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The consent category whose effective permission gates the children, for example `'marketing'` or `'functionality'`.|
|`children`|`ReactNode`|required|The embed. It is not mounted until the category is allowed, so it makes no requests before permission.|
|`placeholder`|`ReactNode`|built-in placeholder|Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content.|

Other `div` attributes such as `className`, `style` and `ref` apply to the
wrapper element that stays in the page in both states. `ConsentGateProps` also
declares `noStyle` and `theme`, but the component does not apply them yet;
style the wrapper with `className`, and style the built-in placeholder
through its parts in the provider options.

## Behavior

`ConsentGate` renders a `div` wrapper. Inside it, when the effective permission for
`category` is granted, it renders the children; otherwise it renders the
placeholder. Permission is the same value `useConsent(category)` returns,
so it can be granted under an opt-out rule before the visitor records a
choice, and a recorded grant can be overridden by a privacy signal.

While effective permission is denied, the children are absent from the DOM,
so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
children unmount and the embed disappears. `ConsentGate` does not depend on the
network blocker or the iframe blocker modules; use those for markup you
cannot wrap in a component.

The built-in placeholder shows the title `consentGate.title`,
`Accept {category} consent to view this content.`, with `{category}`
replaced by `consentTypes.<category>.title`, and a button labelled
`consentGate.actionButton`, `Enable {category} consent`. The button opens the
preference center; it
does not grant the category by itself, because the visitor still has to
save. Mount a `ConsentDialog` in the same provider so the button has
something to open.

Under a policy with `scopeMode: 'strict'`, a category outside the rule's
scope cannot be granted. The built-in placeholder then shows `consentGate.policyBlocked`,
"This content is unavailable under your region's consent policy.", without
the button, and a stored grant for that category stays blocked.

When the provider starts from a snapshot prefetched on the server, the
server renders the placeholder for a denied category. For a granted
category it renders the empty wrapper, and the children mount once
hydration completes, so an iframe loads once even when the page streams
inside a `Suspense` boundary. A grant in the request cookie allows the
embed only when policy and privacy signals permit it. Browser privacy signals detected during hydration can
withdraw that permission. In a browser-only setup the
provider has no permission until it resolves policy on the client, so
`ConsentGate` shows the placeholder first and swaps in the embed after resolution
when the category is already granted.

`ConsentGate` is one component on this page; the per-vendor embed guides for
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) show a complete embed
configuration with sizing, titles and the same `ConsentGate` usage across
frameworks.

To read the same permission in your own components, use `useConsent` from
`c15t/react`; the `useIframeBlocker` and `useNetworkBlocker` module hooks
also import from there.

## Composition

The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
translated text; pass children to either to replace it.

```tsx
<ConsentGate
  category="marketing"
  placeholder={
    <ConsentGate.Root>
      <ConsentGate.Title category="marketing" />
      <p>The video is also available on our channel.</p>
      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
    </ConsentGate.Root>
  }
>
  <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
</ConsentGate>
```

To restyle the built-in placeholder without replacing it, set its parts
under `components['consent-gate']` in the provider options. `root` is the
card, and `title` and `button` are its text and button. The `consentGate`, `consentGateTitle` and
`consentGateButton` theme slots reach the same parts. The button part
applies on top of `button.primary`.

```tsx
components: {
  'consent-gate': {
    root: { className: 'rounded-none' },
    button: { className: 'font-semibold' },
  },
},
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

## Accessibility

The placeholder is plain text and a `button`, so it is readable and
operable without the embed. Give the iframe a descriptive `title`, and keep a
transcript, address or link outside the `ConsentGate` for visitors who decline
the category. A denied category may be fixed by policy, so opening the
preference center does not guarantee that the visitor can grant it.

## Verify

Use an optional in-scope category that is available in the preference
center and is not restricted by policy or privacy signals such as GPC.
Load the page with the category denied. The placeholder text names the
category and the network panel shows no request to the embed's host. With a
prefetched snapshot, the server HTML contains the placeholder for a denied
category and neither placeholder nor embed for a granted category; the
embed appears after hydration and the network panel shows one request for
its document. Browser-only initialization
shows the placeholder before policy resolves, then replaces it with the
embed if the category is granted. After policy resolves, activate the
placeholder button: the preference center opens. Turn the category on and
Save: the placeholder is replaced by the embed and its requests start. Reject the
category again from the preference center: the embed disappears.

# Hooks
URL: https://c15t.com/docs/frameworks/react/hooks
Gate features and save consent choices in React components with the focused hooks exported from c15t/react.

## Read only the state you need

Every hook reads the runtime from the nearest `ConsentProvider`, so call them
from components rendered inside that provider and import them from
`c15t/react`.

```tsx title="src/optional-feature.tsx"
import { useConsent } from 'c15t/react';

export const OptionalFeature = () => {
	const allowed = useConsent('marketing');
	return allowed ? <div>Optional marketing content</div> : null;
};
```

Call hooks inside the consent provider. `useConsent` reads effective permission,
which can be true under an opt-out policy without a recorded grant.

|Need|Hook|
|--|--|
|One category's current permission|`useConsent(category)`|
|All current permissions|`useConsents()`|
|Recorded per-category choices|`useExplicitChoice()`|
|Whether one declared vendor may run|`useVendorAllowed(id)`|
|Whether a prompt is required|`usePromptRequirement()`|
|Active policy and resolution|`usePolicyRule()`, `usePolicyResolution()`|
|Save an explicit choice|`useSaveConsents()`|
|Open or close a consent surface|`useSetActiveUI()`|
|Acknowledge a notice|`useDismissNotice()`|

## Save from a visitor action

Render this component inside your existing `ConsentProvider`.

```tsx title="src/reject-button.tsx"
import { useSaveConsents } from 'c15t/react';

export const RejectButton = () => {
	const save = useSaveConsents();
	return (
		<button
			type="button"
			onClick={() => {
				void save('none');
			}}
		>
			Reject optional
		</button>
	);
};
```

This is an isolated action example, not a complete policy-aware banner. Use the
stock UI or headless surface actions for a complete prompt. Do not call save on
mount to persist a state derived from permissions.

Use focused hooks for feature gates. For a complete custom prompt or preference
center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
for staged choices, inside one `ConsentDraftProvider` so the save commits the
same draft. v3 has no `useConsentManager()`; the
[`use-consent-manager-to-hooks` codemod](/docs/cli/commands/codemods#migrate-useconsentmanager-to-v3-hooks)
rewrites most of its calls to hooks. Read [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) before
treating a callback as evidence of a choice.

# Callbacks
URL: https://c15t.com/docs/frameworks/react/callbacks
Run code in a React app when a visitor records a consent choice, when permissions change, when a request fails and before the revocation reload, with the ConsentProvider callbacks option.

## Pass callbacks to the provider

Keep the callbacks in their own module:

```ts title="src/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/react';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

Pass them in the `ConsentProvider` options, in the file that renders the
provider, such as `src/consent.tsx` from the
[quickstart](/docs/frameworks/react/quickstart):

```tsx title="src/consent.tsx"
<ConsentProvider options={{ mode, scripts, callbacks }}>
```

The provider subscribes the callbacks after it mounts, so they run in the
browser. If you render on the server, server rendering never calls them. The
provider calls the latest `callbacks` object it received, so a new object on
a later render takes effect without a remount. Defining the object at module
level, as above, keeps it the same across renders.

When you pass your own `runtime` to `ConsentProvider`, the provider does not
wire `callbacks` or `reloadOnConsentRevoked` from its options. Pass them to
`createConsentRuntime` instead.

## Available callbacks

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useSaveConsents()`.|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time as a millisecond timestamp|
|`onPermissionsChanged`|Any effective permission changes value.|`snapshot`, the state after the change; `previous`, the permissions before it|
|`onError`|A consent command fails, such as a failed `/init` request or a save the backend rejects.|`error`, a message string|
|`onBeforeConsentRevocationReload`|A save withdrew a granted category or vendor, right before c15t reloads the page.|`preferences`, the permissions after the save|

The type for the whole object is `ConsentProviderCallbacks` from `c15t/react`.
Callbacks run after c15t updates its state, so `snapshot` and hooks such as
`useConsent()` already hold the new values.

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only for a visitor's action. `onPermissionsChanged`
runs whenever effective permissions change, whatever the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|A policy resolves and allows categories before any choice|No|Yes|
|Global Privacy Control turns off a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent analytics and audit trails, because it
fires only when the visitor chose. Use `onPermissionsChanged` to start or stop
your own code. Never treat it as proof that the visitor agreed to anything,
and never save consent from it.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

Dismissing a notice records no choice and changes no permission. Read it with
`useNoticeDismissal()` instead. For consent inside one component, use the
[hooks](/docs/frameworks/react/hooks), which re-render the component when
consent changes.

## Before a revocation reload

Removing a script tag cannot stop code that already ran, so c15t reloads the
page after an accept, reject or save turns off a category or vendor that was
granted. The reload waits for the save request to finish. Right before it,
`onBeforeConsentRevocationReload` runs synchronously. Use it to call a
vendor's shutdown API or flush queued events. Keep it short, because the
reload does not wait for promises.

A choice that expires, a new policy and a privacy signal change permissions
without a visitor action, so they do not reload the page.

To handle revocation yourself, set `reloadOnConsentRevoked: false` in the
provider options. Code the visitor turned off then keeps running until the
next full page load, and `onBeforeConsentRevocationReload` never runs.

## Verify

1. Add the callbacks from this page, open the console and DevTools Network,
   clear site data and reload under a policy that shows a banner.
2. Click **Accept All**. `onChoiceRecorded` and `onPermissionsChanged` both log,
   and the save request to your backend appears in Network.
3. Reload. `onChoiceRecorded` does not log again.
4. Open Privacy settings, turn off a category you allowed and save.
   `onBeforeConsentRevocationReload` logs, then the page reloads. After the
   reload, that category's vendor requests are absent from Network.

# IAB TCF
URL: https://c15t.com/docs/frameworks/react/iab
Mount the IAB TCF banner and dialog inside a React ConsentProvider and configure the CMP ID, policy and vendor data.

## Prepare the IAB configuration

Use the IAB integration when your application needs the Transparency and Consent
Framework. Configure an IAB policy, the correct CMP identity and vendor data for
your deployment. A demo CMP ID is not a production configuration.

A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your users' consent records to someone else. Omitting it leaves the add-on
unmounted: no `__tcfapi`, and no TC String written.

Install `@c15t/iab` alongside your framework adapter, then mount the IAB
components inside an existing consent provider connected to Inth.

Import the components from `c15t/react/iab` and render them inside your
existing `ConsentProvider` from `c15t/react`.

The IAB banner and dialog render their own styles by default. Leave the
provider's `styles` option enabled and render the components without a CSS
import:

```tsx title="src/iab-consent.tsx"
import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
preferences entry point through the surrounding consent provider.

## Resolve the policy before rendering

IAB components remain hidden until an applicable policy resolves. Forcing a
dialog open does not create a policy or vendor list. Inspect resolution and the
Global Vendor List response before changing rendering conditions.

IAB presentation follows `presentation.prompt.blocking` and
`presentation.preferences.blocking`. A blocking dialog needs focus management,
scroll locking and a backdrop together.

## Mount IABProvider for every IAB policy

IAB is opt-in. The standard `ConsentBanner` and `ConsentDialog` do not
handle the IAB model, so when a visitor's policy uses it, the backend
sends its vendor list and the app has no `IABProvider`, they throw an
`IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`):
`c15t: this visitor's policy uses IAB TCF, but no <IABProvider> is mounted`.
The error happens during render, on the server and in the browser, so
your error boundary or the framework's error overlay shows it. Render `IABProvider` from
`c15t/react/iab` for those visitors, or remove the `iab` model from the
policy.

## Verify vendor and purpose choices

Test category choices alongside vendor, purpose, legitimate-interest and special
feature controls used by your integration. Confirm the TC String and `__tcfapi`
reflect the saved state, and verify the vendor's actual requests. A category-only
banner test does not establish that the IAB flow works.

## Load an external stylesheet

With Tailwind CSS 3, or when you want to put c15t in a named cascade layer,
import `c15t/react/styles.css` and then `c15t/react/iab/styles.css` at your
global stylesheet entry. The IAB stylesheet holds the IAB rules and uses the
base stylesheet's tokens. Set `styles: false` so the components use those
stylesheets:

```tsx title="src/consent.tsx (partial)"
import 'c15t/react/styles.css';
import 'c15t/react/iab/styles.css';

// In the ConsentProvider options:
styles: false,
```

Tailwind CSS 3 also needs the
[PostCSS plugin](/docs/customization/tailwind#set-up-tailwind-css-3).

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Pass
them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
placeholders; use vendors from your list whose declarations allow each
restriction.

```tsx title="src/iab-consent.tsx"
import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

const publisherRestrictions = [
	// Vendors 10 and 755 may not use purpose 4.
	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
	// Vendor 755 must use legitimate interest for purpose 7.
	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
];

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

# IAB GPP
URL: https://c15t.com/docs/frameworks/react/gpp
Add the IAB Global Privacy Platform API (__gpp) to a React app with ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

`ConsentGPP` from `@c15t/react/gpp` installs `window.__gpp`, the GPP 1.1 CMP
API, and keeps its GPP string in step with the visitor's choices. Prebid.js,
Google Ad Manager and other ad tech read US privacy signals from it.

## Turn on GPP

Render `ConsentGPP` inside `ConsentProvider`:

```tsx title="src/consent.tsx"
import { ConsentGPP } from '@c15t/react/gpp';

<ConsentProvider options={{ mode, scripts }}>
	<ConsentGPP />
	{children}
</ConsentProvider>;
```

`ConsentGPP` renders nothing. It installs `__gpp` after it mounts and
removes it when it unmounts. It lives in its own entry, like
`@c15t/react/iab`, so apps that do not import it bundle none of the GPP
code. `@c15t/react` already depends on `@c15t/iab`; with the `c15t`
package, import from `c15t/react/gpp`.

The props are the GPP options listed below, for example
`<ConsentGPP usFallback="none" />`. It works the same with a runtime you
pass to `ConsentProvider` as `runtime`.

The GPP string follows the policy and location your backend resolves for the
visitor, so a US visitor's state comes from the backend. With `offline()`
mode, pass the state yourself, for example
`overrides: { country: 'US', region: 'CA' }`.

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/react/iab) as well.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/react/content-security-policy
Run c15t in a React app under a Content Security Policy, allow the consent backend and vendor hosts, and pass a nonce to ConsentProvider and ConsentTheme.

## What c15t adds to the page

A React app with c15t adds these to the page, and your policy must allow them:

|What|Directive|
|--|--|
|The `<style>` elements the banner, dialog and other stock components render with c15t's rules|`style-src` with a nonce|
|`c15t/react/styles.css`, only if you import it with `styles: false`|`style-src 'self'`|
|The `<style id="c15t-theme">` element, if you render `ConsentTheme`|`style-src` with a nonce or its hash|
|`<script>` elements the script loader creates for `scripts` entries, both `src` and inline|`script-src` with each vendor's host, or a nonce|
|With server rendering, the inline `<script>` before the banner's buttons that holds a tap made before hydration|`script-src` with a nonce or its hash|
|Browser requests to your backend's `/init` and `/subjects`|`connect-src` with the backend origin|
|Iframes inside `ConsentGate`, and the frames, images and requests your vendors load|`frame-src`, `img-src`, `connect-src` for each vendor|

In a client-rendered app, c15t components set their inline styles through
React. A policy does not restrict styles set that way, so they need no
directive.

## Allow the consent backend

With `hosted()`, the browser calls `GET {url}/init` on every page load
and `POST {url}/subjects` when the visitor accepts, rejects or saves. With
`manifest()`, it calls `POST {url}/subjects`, and `GET {url}/init` only when
the policy needs a location the browser does not know. Add the
backend's origin to `connect-src`:

```txt title="Content-Security-Policy (partial)"
connect-src 'self' https://<your-backend-host>;
```

Use the origin of the backend URL from your Inth project or self-hosted
backend. When the URL is a same-origin path such as `/api/c15t` behind your
own proxy, `'self'` covers it.

Under an IAB TCF policy the browser also loads the Global Vendor List from the
URL the policy provides. Allow that host in `connect-src` if you use the
[IAB TCF add-on](/docs/frameworks/react/iab).

## Allow vendor scripts

The script loader adds a `<script>` element for each `scripts` entry once its
category is allowed. List each vendor's script host in `script-src`, and the
hosts its script calls in `connect-src` and `img-src`. The vendor's own
documentation lists them. Scripts that a vendor script adds itself, such as a
tag manager's tags, need their own hosts too, or `'strict-dynamic'` with a
nonce.

A `scripts` entry with inline `textContent` instead of `src` needs a nonce or
its hash in `script-src`.

## Use a nonce

A nonce protects a page only when it changes on every response. A static host
serves the same file to everyone, so use host allowlists there. Use a nonce
when a server renders or rewrites your `index.html` per request.

Pass the nonce as `options.nonce` on `ConsentProvider`. The script loader
stamps it on every `<script>` it creates. A `nonce` on a single `scripts`
entry takes precedence for that element. The stock components put it on the
`<style>` elements that carry c15t's rules.

With Vite, set `html.cspNonce` to a placeholder in `vite.config.ts`, and have
your server replace it with a new nonce on every response. Vite then adds
`<meta property="csp-nonce" nonce="...">` to the page, and the browser keeps the
value in the tag's `nonce` property. Read it where you create the provider, in
the quickstart's `src/consent.tsx`:

```tsx title="src/consent.tsx (partial)"
const nonce =
  document.querySelector<HTMLMetaElement>('meta[property="csp-nonce"]')
    ?.nonce || undefined;

<ConsentProvider options={{ mode, scripts, nonce }}>
```

If you render `ConsentTheme`, pass it the same value:
`<ConsentTheme theme={theme} nonce={nonce} />`.

The provider reads `options.nonce` once, when it mounts. A server-rendered
React app, such as one built with React Router framework mode, reads the nonce
from its own request and passes it the same way.

## Allow c15t's style elements

The banner, dialog and other stock components render c15t's rules as
`<style>` elements. A `style-src` without `'unsafe-inline'` must admit them.
Either:

* Set `options.nonce` on `ConsentProvider`, as in [use a nonce](#use-a-nonce).
  The elements then render next to each component with the nonce. React 19
  would otherwise move them into `<head>` and drop the nonce.
* Or set `styles: false` in the provider options and import
  `c15t/react/styles.css` from your bundle. `style-src 'self'` admits it.

## Allow the theme style element

`ConsentTheme` renders your theme tokens into a `<style id="c15t-theme">`
element. Without a nonce, a `style-src` that lacks `'unsafe-inline'` blocks it,
and the banner falls back to the default theme. The element's content depends
only on the theme, so a hash works:

1. Load the page with the policy enforced.
2. Copy the `sha256-...` value from the `Refused to apply inline style`
   console error.
3. Add it to `style-src` and redeploy.

Recompute the hash when you change the theme. To avoid the hash, set the
tokens in your own stylesheet instead, as
[customize](/docs/frameworks/react/customize) shows.

## Allow embeds and the dev server

Add the host of every iframe you gate to `frame-src`. A YouTube player inside
`ConsentGate` needs `https://www.youtube-nocookie.com`, for example.

Vite's dev server injects CSS as `<style>` elements, and the DevTools panel
adds a `<style>` element without a nonce. Test the policy against a
production build.

## Verify

Build the app, serve it with the policy enforced, not in report-only mode, and
open DevTools. Test under a policy that asks for a choice, such as an EU
opt-in policy.

1. The banner renders with its theme colors, and the console shows no
   `Refused to` error that mentions a c15t element, your backend or a vendor.
2. Before a choice, the Network tab shows no vendor requests.
3. Click **Accept All**. The vendor scripts load, and their `<script>` elements have ids
   starting `c15t-`. With a nonce, read each element's `nonce` property in the
   console. Browsers hide the attribute from `getAttribute`.
4. The save to `/subjects` succeeds. A `connect-src` violation here means the
   backend origin is missing.
5. Reload. The banner stays closed, and the vendors load without a console
   error.

# DevTools
URL: https://c15t.com/docs/frameworks/react/components/dev-tools
Inspect consent state, location, loaded scripts and consent events in a React app during development with the c15t DevTools panel.

`DevTools` is a floating panel for the c15t v3 kernel. Use it during development to inspect consent values, scripts, location, the resolved policy, IAB state, events, and consent actions. The framework adapter reads the kernel from the nearest v3 provider. It never discovers a store through a window global.

> ⚠️ **Warning:**
> Load DevTools only in development. A conditional JSX expression stops it from mounting in production, but a static import can still add DevTools to the production bundle. Use a development-only dynamic import as shown below. The component renders nothing into the React tree and mounts its panel in document.body.

## Installation

No extra package is required. The React adapter and its engine are included
with the `c15t` package. Install `@c15t/dev-tools` directly only when you
need the imperative `createDevTools({ kernel })` API.

## Render DevTools in development builds

Render `DevTools` inside `ConsentProvider`. This example loads it only in
development with Vite's `import.meta.env.DEV` flag, so production bundles never
download it. For another bundler, use its development flag instead; for
example, webpack projects can use a configured
`process.env.NODE_ENV === 'development'` replacement, since `process` is not a
browser global.

```tsx title="src/consent-devtools.tsx"
import { lazy, Suspense } from 'react';

const DevTools = import.meta.env.DEV
	? lazy(() =>
			import('c15t/react/devtools').then(({ DevTools }) => ({
				default: DevTools,
			}))
		)
	: null;

export function ConsentDevTools() {
	return DevTools ? (
		<Suspense fallback={null}>
			<DevTools />
		</Suspense>
	) : null;
}
```

Render `<ConsentDevTools />` inside the provider from your
[quickstart](/docs/frameworks/react/quickstart), next to the banner. Import the
component from `c15t/react/devtools` when you installed the `c15t` package, or
from `@c15t/react/devtools` when you installed `@c15t/react` directly.
`@c15t/dev-tools` exports the imperative engine, not the React component.

If the CLI cannot identify your bundler's development flag, it generates
`const DevTools = false` with a setup comment. Replace `false` with your
configured build-time development flag to enable the panel. The fallback keeps
DevTools disabled instead of assuming browser globals or loading it in production.

## Configuration

```tsx
<DevTools
  position="bottom-right"
  defaultOpen={false}
  defaultTab="consents"
  maxEvents={100}
  disabled={false}
/>
```

`position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
`bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
to choose that panel. `maxEvents` limits captured kernel and script events.
Set `disabled` to prevent mounting without removing the component. The
panel renders inside a shadow root by default, so page CSS does not reach
it. `shadow={false}` mounts it in the light DOM with its stylesheet in
`<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTriggerToolbar` or the ready-made `ConsentDialogTrigger`
is visible, the trigger shows a DevTools button and DevTools hides its own
floating launcher, so one control occupies the corner. The button sits at the
end of the toolbar farthest from its corner. The panel opens just past the
toolbar, aligned with its outer edge, and follows it when a visitor drags the
toolbar to another corner. `position` applies again once no trigger is
visible.

`ConsentDialogTrigger` becomes a two-button toolbar while DevTools is
mounted. A trigger composed from `ConsentDialogTrigger.Root` keeps its own
markup, and DevTools keeps its floating launcher beside it.

DevTools brings its launcher back whenever no trigger is visible, for example
while `showWhen="after-prompt"` waits for a choice. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

With the imperative engine, call `devTools.dock({ position, inline, block })`
to hide the launcher and anchor the panel `inline` and `block` pixels from the
viewport edges of `position`'s corner. Call `devTools.dock(null)` to restore
the launcher.

## Panels

Accept and reject apply only to categories displayed by the provider, leaving
hidden consent values unchanged. `necessary` always remains enabled. The
React adapter uses the current policy categories by default.

For an imperative integration with a narrower UI, pass
`getConsentCategories: () => ['necessary', 'measurement']` to
`createDevTools`. The getter is read again when an action runs. Headless UI
actions can use `kernel.commands.save('all', { categories: displayed })` or
`kernel.commands.save('none', { categories: displayed })`. These scoped bulk
saves use a `custom` transport action when they cover only part of the policy.
Actions covering the whole policy retain `all` or `necessary`. Without an
explicit scope or policy categories, bulk saves cover all known categories.

|Panel|What it shows|
|--|--|
|**Consents**|Inspect and save categories, accept all, or reject optional categories|
|**Scripts**|Configured scripts, loading status, search, and external page resources|
|**Location**|Resolved country and region, and location overrides|
|**Policy**|Resolved policy and UI configuration|
|**IAB**|Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings|
|**Events**|Timeline of consent changes, kernel events, and script lifecycle events|
|**Actions**|Show the banner, open preferences, hide consent UI, or refresh consent data|

### Script inspection

Set `defaultTab="scripts"` to open script inspection first. It reads all script
loaders attached to the current provider's kernel, including loaders created
before DevTools mounts. Search by script ID, category, URL, or status, then
expand a script to inspect its configuration and latest lifecycle event.

`loading` means an external script was inserted; `loaded` means its browser
load event fired, or an inline script or callback-only integration mounted.
`error` reports a loader error. `blocked` means consent requirements were not
met, and `pending` means an eligible script has not mounted. `present` means
the loader reused an element without a confirmed load result. `retained`
means consent was revoked but `persistAfterConsentRevoked` kept the element.
Retained scripts still receive `onConsentChange` with `hasConsent: false`, so
their integrations can send the vendor's consent-revocation command.
`alwaysLoad` bypasses the loading gate, not consent: callbacks receive the
actual consent state and updates across categories for integrations such as
Google Consent Mode.

Script details distinguish `allowedToLoad` from `consentGranted`. An
`alwaysLoad` integration can be allowed to load while its consent is denied.
Diagnostics expose these as `eligible` and `hasConsent`, respectively.

Lifecycle diagnostics work even when legacy debug forwarding is disabled.
The page scan lists external scripts and iframes present in the
DOM; it does not prove that they loaded successfully or were consent-gated.

For custom inspection tools, import `getScriptDiagnostics(kernel)` and
`subscribeScriptDiagnostics(kernel, listener)` from
`c15t/modules/script-loader`. The subscription reports loader
registration, updates, disposal, and lifecycle events. Read a fresh snapshot
after changes and call the returned unsubscribe function during cleanup.

### IAB editing

Under an IAB policy, the Consents tab is read-only. Edit and save vendors
and purposes in the IAB tab so the derived categories and TC string stay
consistent.

The IAB panel connects to the existing `@c15t/iab` module attached to the
provider's kernel. It does not create a second CMP or replace `__tcfapi`.
Controls become available after initialization, when the current policy uses
IAB and the vendor list is loaded.

Choose Vendors, Purposes, or Special features, then search by name or ID.
Vendors include the provider's custom vendors. Long lists show 20 entries per
page. Legitimate-interest controls appear for declared legitimate interests.
Search only filters the view; Accept all IAB and Reject all IAB apply to the
configured choices, including custom vendors.

Toggles update live IAB state and script gating immediately. Use Save IAB
consent to generate a fresh TC string and run the configured save transport.
The panel displays the last generated string; unsaved edits are not represented
in it. Copy TC string confirms success or reports clipboard failures. Raw IAB
data remains available in an expandable section.

IAB saves normally write the TC string to its standard cookie and localStorage.
For an in-memory playground, set `persistence: false` in the IAB module options
as well as disabling the provider's core persistence. The IAB option prevents
TC-string storage writes; it does not disable the configured save transport
or remove previously stored values.

Save and refresh actions show pending, success, and failure feedback. Controls
are disabled while a request is pending. A failed save does not roll back the
live choices; retry to record them.

For custom inspection tools, `getIABControls(kernel)` and
`subscribeIABControls(kernel, listener)` are exported from `c15t`.
The getter returns undefined before module initialization and after disposal.
A snapshot without an attached IAB module is read-only in DevTools.

## TanStack Devtools

Each embedded panel owns its event history and subscriptions. Unmounting it
destroys the instance; remounting starts a new history. If you need to capture
events while switching plugins, keep the c15t panel mounted. This differs from
the old globally shared DevTools store.

The React v3 DevTools adapter exports a panel component and plugin factory that match TanStack Devtools' plugin API:

```tsx
import * as React from 'react';
import { useRouter } from '@tanstack/react-router';
import { TanStackDevtools } from '@tanstack/react-devtools';
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
import { c15tDevtools } from 'c15t/react/devtools';

export function AppDevtools() {
  const router = useRouter();

  return (
    <TanStackDevtools
      plugins={[
        {
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
        {
          name: 'TanStack Router',
          render: <TanStackRouterDevtoolsPanel router={router} />,
        },
        c15tDevtools(),
      ]}
    />
  );
}
```

In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.

The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:

```tsx
import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';

const c15tPlugin = {
  name: 'Consent',
  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
    <C15tTanStackDevtoolsPanel theme={theme} />
  ),
};
```

## Props

|Property|Value|
|:--|:--|
|Type Name|\`ConsentDevToolsProps\`|
|Source Path|\`./packages/react/src/devtools.tsx\`|

\*ExtractedTypeTable: Could not extract "ConsentDevToolsProps" from "./packages/react/src/devtools.tsx" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.\*

# Troubleshooting
URL: https://c15t.com/docs/frameworks/react/troubleshooting
Fix a missing banner, early vendor requests, unstyled components and theme warnings in a React app that uses c15t/react.

## Why does the build fail to download the manifest?

**Check.** `vite build` stops with an error from `consentManifest` that
starts with the plugin's name, such as
`@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite`
for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps
going. The part in parentheses names the cause:

|Message|Cause|Fix|
|--|--|--|
|`fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error|The build cannot reach the backend|Build where the backend is reachable|
|`no response within 10 seconds`|The backend did not answer in time|Check the backend, or build where it is reachable|
|`/manifest responded 404`|The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix|Copy the backend URL exactly as Inth shows it, or set `VITE_C15T_BACKEND_URL`|
|`/manifest returned an invalid consent manifest.`|The URL answered with something other than a consent manifest, such as an HTML page|Point `backendURL` at the backend itself, not your site or a dashboard page|

A failed download never reuses an old snapshot. To deploy while the backend
is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
`undefined`, and the browser fetches the policy from the backend at runtime.

Only a build that uses `manifest()` downloads the manifest. The plugin
fetches after Vite has dropped the code the app does not use, so a `hosted()`
or `offline()` build never contacts the backend and never fails this way.

An error or warning that says `no backend URL is set` means the plugin found
no `backendURL` option and no variable. Set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass the absolute backend URL from your Inth
project. The [troubleshooting guide](/docs/guides/troubleshooting#why-does-the-build-fail-to-download-the-manifest)
lists every message.

A notice that the build `skipped the consent manifest fetch` means the backend
URL is relative, such as `/api/c15t`. Pass the absolute backend URL instead.
With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL`.

## Why is snapshot undefined?

**Check.** `snapshot` from `c15t/generated` is `undefined`, and the browser
requests `${backendURL}/manifest` on page load.

**Fix.** `snapshot` is `undefined` when Vite has no policy to serve:

* `consentManifest` is missing from `plugins` in `vite.config.ts`. Without the
  plugin, `c15t/generated` still resolves, but exports `undefined`.
* The fetch failed in `vite dev`, or in a build with
  `C15T_ON_BUILD_ERROR=runtime`. The terminal shows a `could not fetch the consent manifest` warning.
* The backend URL is relative, so the plugin skipped the fetch.
* `consentManifest({ source: 'runtime' })` is set, so the plugin never
  fetches.

Fix the cause, then restart `vite dev` or rebuild. The plugin fetches once
when Vite starts.

## There is no banner

**Check.** In DevTools Network, find the `GET` request to `/init` on your
backend URL. With the bundled manifest, the browser makes no request before
the banner unless the policy depends on a country or region it does not know.

|What you see|Cause|Fix|
|--|--|--|
|No request and no banner|`ConsentProvider` is not mounted, an error stopped `src/consent.tsx` from rendering, or the bundled policy asks for no banner|Check the console for errors, render one provider at the app root as in the [quickstart](/docs/frameworks/react/quickstart), and inspect the active policy with the component below|
|`/init` fails with a CORS error|Your site's origin is not trusted|Add the exact origin, including port in development, to the trusted origins in your Inth project|
|`/init` returns 200|The policy for this visitor asks for no banner, or a stored choice is still valid|Inspect the active policy with the component below, or clear site data|

A policy with `prompt: 'none'` shows no banner by design, and so does a
returning visitor with a valid stored choice. [Policies](/docs/concepts/policies)
explains why a region may not show one.

## The page throws that no IABProvider is mounted

The visitor's policy uses the `iab` model and the backend sent its vendor
list, but no `IABProvider` is mounted. The standard banner and dialog do
not handle the IAB model, so they throw rather than leave the visitor
with no consent UI. Server and browser render the same error.

Fix it one of two ways:

* If the site uses IAB TCF, render `IABProvider` with `IABConsentBanner`
  and `IABConsentDialog` from `c15t/react/iab` inside your consent
  provider. They can sit next to the standard banner.
* If it does not, remove the `iab` model from the policy for that region
  in your Inth project or policy pack.

A backend that answers `gvl: null` turns IAB off for that request. The
policy then runs as opt-in and nothing throws.

The check passes once `c15t/react/iab` has loaded. If you import the IAB
components with a dynamic `import()`, a render of the standard banner
that happens before the import finishes still throws.

## Inspect the active policy

Render this component inside `ConsentProvider`. It reads state and records no
choice:

```tsx title="src/consent-policy-debug.tsx"
import { useSnapshot } from 'c15t/react';

export function ConsentPolicyDebug() {
	const snapshot = useSnapshot();
	const resolution = snapshot.resolution;

	return (
		<pre>
			{JSON.stringify(
				{
					status: resolution.status,
					policy: resolution.status === 'matched' ? resolution.policy.id : null,
					prompt: snapshot.promptRequirement,
					permissions: snapshot.effectivePermissions,
					location: snapshot.location,
					privacySignals: snapshot.privacySignals,
				},
				null,
				2
			)}
		</pre>
	);
}
```

The component re-renders on every consent change. Remove it after you finish.
For a feature gate, use `useConsent('marketing')` or the category you need.

## A vendor loads before the visitor chooses

**Check.** Search `index.html`, your entry module and any tag manager for the
vendor's script or SDK initializer.

**Fix.** Remove every loader except the one in `options.scripts`. c15t only
gates scripts registered with it, and the network blocker cannot stop code that
runs before the provider renders. [Scripts and embeds](/docs/frameworks/react/scripts)
covers the options.

## The banner has no styles

**Check.** In DevTools Elements, the banner has classes but no rules apply.
Look for c15t's `<style>` element: `<style data-href="c15t-first-paint">` in
`<head>` on React 19, or `<style data-c15t-styles>` next to the banner on
React 18 or with a `nonce`. Check the console for a Content Security Policy
error.

**Fix.**

* No c15t `<style>` element: the provider sets `styles: false` or `noStyle`.
  With `styles: false`, import `c15t/react/styles.css` once in the module
  that renders the provider.
* The console reports a blocked inline style: set the provider's `nonce`, as
  [Content Security Policy](/docs/frameworks/react/content-security-policy)
  shows.
* Under Tailwind 3, buttons lose their padding and cards their borders:
  Tailwind 3's unlayered preflight beats c15t's layered rules. Set
  `styles: false`, import `c15t/react/styles.css` above the `@tailwind`
  directives and add `c15t/postcss-tailwind3` before `tailwindcss` in your
  PostCSS config. Without the plugin, Tailwind 3 drops c15t's rules or fails
  the build with
  `` `@layer components` is used but no matching `@tailwind components` directive is present ``.
  See [Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3).

## The console warns that theme tokens are no longer turned into CSS

**Check.** `options.theme` holds colors, radius or other tokens, and the page
has no `c15t-theme` style element. The provider only reads `consentActions`
and slot styles from `theme`.

**Fix.** Move the tokens to your CSS or render `ConsentTheme`, as shown in
[customize](/docs/frameworks/react/customize#change-colors-fonts-and-radius).

## The banner is missing from server-rendered HTML

**Check.** Your app uses React Router framework mode, Remix or another
server-rendered setup without a c15t adapter. There this is expected: the
browser resolves consent after hydration.

**Fix.** None is needed for consent to work.
[Rendering](/docs/frameworks/react/rendering#react-router-remix-and-other-server-rendered-apps)
explains the options.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/nuxt/quickstart
Add c15t to a server-rendered Nuxt app with the Nuxt module, Inth, consent-gated scripts and a preferences link.

## Before you start

This guide is for a Nuxt app that runs a Nuxt server, built with `nuxt build`
and deployed to Node or a serverless preset. The server resolves each
visitor's policy, so the banner is part of the first HTML. Prerendered routes
and routes cached with `swr`, `isr` or `cache` rules work with the same setup;
the browser resolves the visitor on those routes after hydration. For
`nuxt generate` on a static host, or `ssr: false`, follow
[deploy to static hosting](/docs/frameworks/nuxt/rendering#deploy-to-static-hosting)
instead.
[Choose your setup](/docs/concepts/choose-your-setup) compares every option.

The guide uses [Inth](https://inth.com) for policies and consent records.
Create a project, set its policy rules, add your site's origin to its trusted
origins, and copy the backend URL. To run the service yourself, use a
[self-hosted backend](/docs/self-host/overview) URL instead. Offline mode keeps
policies in your code and choices in the browser, with no consent records.
Not recommended for production environments.

The setup bundles your policy into the server at build time, the
recommended production setup. Rebuild after changing policies, translations
or vendors.

## Install c15t

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

`c15t/vue` is the Nuxt module. You do not install a separate Nuxt package.

## Add the Nuxt module

Register the module in `nuxt.config.ts`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
});
```

Set `NUXT_PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including
any path prefix, in `.env` or wherever you build. The module reads it, so the
config needs no `backendURL`. The policy is fixed at build time: setting
`NUXT_PUBLIC_C15T_BACKEND_URL` on a running server moves consent saves, not
the policy, so build again to switch projects.

```sh title=".env"
NUXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `NUXT_PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `NUXT_PUBLIC_C15T_BACKEND_URL` wins.

The module's default mode, `manifest()`, fetches your project's public
policy once, during `nuxt build` and when `nuxt dev` starts, and embeds it in
the server bundle. It also adds one consent route to your Nuxt server,
`/api/c15t/**`, which answers `/api/c15t/init` and `/api/c15t/manifest`. The
server resolves each visitor from the bundled policy and the request's
location and language headers, so rendering a page never waits on Inth. The
browser bundle carries no policy and no resolver. Consent saves still go to
Inth. [Data fetching](/docs/concepts/data-fetching) compares this with
calling the backend on every request.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without rebuilding, set
`c15t: { mode: manifest({ source: 'runtime' }) }`, with `manifest` imported
from `c15t/vue`. The server then fetches and caches the policy at runtime.
[Rendering and deployment](/docs/frameworks/nuxt/rendering) covers the other
modes.

## Mount the consent UI

Add `ConsentRoot` and a preferences link to `app.vue`:

```vue title="app/app.vue"
<template>
	<ConsentRoot />
	<NuxtPage />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

`ConsentRoot` renders the banner when the visitor's policy asks for one and
loads the preference dialog when it opens. `ConsentDialogLink` renders a
button that reopens preferences, labelled with the dialog's title in the
visitor's language: Privacy Settings in English. It renders nothing until the
policy offers preferences.

The module registers these components and the consent composables, so you
write no imports and no `app.use()`. Keep `ConsentRoot` in `app.vue`, outside
`<NuxtPage />`, so it stays mounted across navigation. The components bring
their own styles.

## Register consent-gated scripts

Remove any existing PostHog snippet so the script loads once, and add
measurement to your Inth policy.

Register PostHog in `app/app.config.ts`. It waits for measurement permission.

```ts title="app/app.config.ts"
import { posthog } from '@c15t/integrations/posthog';

export default defineAppConfig({
	c15t: {
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	},
});
```

Replace `phc_your_project_key` with your PostHog project key. PostHog
defaults to its EU region; set `region: 'us'` for a US project.

The module merges the `c15t` key of `app.config.ts` over its options in
`nuxt.config.ts`, then starts one script loader in the browser after
hydration. Put options that contain functions, such as `scripts` and
`callbacks`, in `app.config.ts`. Module options in `nuxt.config.ts`
reach the browser as JSON, which drops functions.

## Gate an embed

Wrap third-party iframes in `ConsentGate`. The iframe does not exist in the
page until its category is allowed, and it is removed when the visitor
withdraws permission.

```vue title="app/components/VideoEmbed.vue"
<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

Nuxt registers components in `app/components` for you. Render
`<VideoEmbed />` in a page where the video belongs.

## Verify the setup

Build and start the production server with `nuxt build` and
`node .output/server/index.mjs`. Open the site in a private window with your
browser's DevTools on the Network tab, under a policy that asks for consent.

1. Load a page and view its source. The banner markup,
   `data-testid="consent-banner-root"`, is in the HTML. The Network tab shows
   no requests to `posthog.com` or `youtube-nocookie.com`.
2. Click **Reject All**, then reload. The banner stays closed and the vendor
   requests stay absent.
3. Click **Privacy settings**, turn on **Analytics** (the `measurement`
   category) and save. PostHog's `array.js` loads and the video appears.
4. Turn **Analytics** off and save. The page reloads, the video is gone and
   PostHog does not load again.

[Verify consent](/docs/guides/verify-consent) has the full release checklist.

## Next steps

* [Rendering and deployment](/docs/frameworks/nuxt/rendering) covers
  prerendered and cached routes, `nuxt generate` and `ssr: false`.
* [Nuxt module](/docs/frameworks/nuxt/module) lists every option and where it
  goes.
* [Scripts](/docs/frameworks/nuxt/scripts), [embeds](/docs/frameworks/nuxt/embeds)
  and the [network blocker](/docs/frameworks/nuxt/network-blocker) cover
  gating and revocation.
* [Geography headers](/docs/frameworks/nuxt/geography-headers) explains how
  the server finds the visitor's location.
* [Customize](/docs/frameworks/nuxt/customize) changes colors, layout and copy.
* [Components](/docs/frameworks/nuxt/components) and
  [composables](/docs/frameworks/nuxt/composables) list the full API.
* [Troubleshooting](/docs/frameworks/nuxt/troubleshooting) covers common
  failures.

# Nuxt module
URL: https://c15t.com/docs/frameworks/nuxt/module
What the c15t Nuxt module registers, where each option goes between nuxt.config.ts and app.config.ts, and every module option.

## Register the module

Add `c15t/vue` to `modules` in `nuxt.config.ts` and configure it under the
`c15t` key:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
});
```

`c15t/vue` is the Nuxt module. You do not install a separate Nuxt package or
call `app.use()`. The [quickstart](/docs/frameworks/nuxt/quickstart) covers
the whole setup.

## What the module registers

|What|Details|
|--|--|
|Components|`ConsentRoot`, `ConsentWidget`, `ConsentDialogLink`, `ConsentDialogTrigger` and `ConsentGate`, all global. See [components](/docs/frameworks/nuxt/components).|
|Composables|Every composable `c15t/vue/vue-plugin` exports, auto-imported. See [composables](/docs/frameworks/nuxt/composables).|
|A Nuxt plugin|Creates the consent runtime for each request on the server and once in the browser, resolves the visitor's policy during server rendering, and writes the `tokens` option into the page head.|
|A server route|In `manifest()` mode, the default, one catch-all at `${routePrefix}/**` that answers `GET /api/c15t/init` and `GET /api/c15t/manifest`. `routePrefix: false`, `hosted()` and `offline()` add none.|
|The `#c15t/composables` alias|Points at the module's composables, for the few that are not auto-imported.|

In the browser, the plugin starts the consent modules once the app has
mounted. A page with `ssr: false` has no server HTML to hydrate, so there the
plugin starts them before the mount, and the policy request runs while the
app mounts. With `manifest({ resolve: 'browser' })` the resolver starts
loading as soon as the plugin runs, and the modules still start after the
mount. Starting reads the stored choice, applies Global Privacy Control,
and starts the script loader, clear-on-revocation, the network blocker, the
iframe blocker and, with `iab` set and an IAB policy, the IAB module.

With `hosted()`, the module also writes a small inline script into the head
of each `ssr: false` page. It calls your backend's `/init` while the
browser parses the HTML, and the plugin uses that response instead of sending
its own request.

## nuxt.config.ts or app.config.ts

The module merges the `c15t` key of `app/app.config.ts` over its options in
`nuxt.config.ts`. Arrays from both files are combined. The module types both
keys, including when you register it as `c15t/vue`.

|Put it in|Options|
|--|--|
|`nuxt.config.ts`|Plain data: `backendURL`, `tokens`, `presentation`, `components`, `legalLinks`, trigger options, network blocker `rules`. Also the options that only work here: `mode`, `routePrefix`, `onBuildError`, `initPrefetch` and `devtools`.|
|`app/app.config.ts`|Anything with a function: `scripts`, `callbacks`, `networkBlocker.onRequestBlocked`.|

Module options reach the browser as JSON through `runtimeConfig.public`,
which drops functions. `app.config.ts` is part of the browser bundle, so it
keeps functions.

App config can change while the page runs, through `updateAppConfig()` or hot
reload. The browser applies a change to `scripts`, `networkBlocker`,
`iframeBlocker`, `vendors`, `consentCategories`, `callbacks` and
`reloadOnConsentRevoked`. Storage, backend and experiment options are read
once when the page loads. `mode` and `routePrefix` never change at runtime.

## Change the backend URL at runtime

Nuxt applies `NUXT_PUBLIC_*` environment variables over
`runtimeConfig.public` when the server starts. To point a built app at another
backend without rebuilding it, set `NUXT_PUBLIC_C15T_BACKEND_URL`:

```sh
NUXT_PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app \
  node .output/server/index.mjs
```

`NUXT_PUBLIC_INTH_PROJECT_URL` works the same way when the build read its
URL from that variable or had none. It never replaces a `backendURL` from
`nuxt.config.ts` or a `NUXT_PUBLIC_C15T_BACKEND_URL`.

The browser, server rendering and the consent route all use this value. Keep
`backendURL` in `nuxt.config.ts`: a value in `app.config.ts` is bundled with
the app and takes precedence over runtime config.

When the build bundles a manifest, the policy comes from the build. The
consent route serves the bundled snapshot and never downloads one, so the
variable only changes where consent saves and session reports go. To use
another project's policy, set the URL when you build and build again, or use
`manifest({ source: 'runtime' })`.

The consent route can reach the backend at an address the browser does not
use, such as an internal hostname. Set `NUXT_C15T_BACKEND_URL` for that. Only
the consent route reads it, and only when it downloads the manifest at
runtime or falls back to the backend's `/init`.

`nuxt generate` writes the config into the static files, so a static site
picks up a new URL only when you generate it again.

## Options

### Backend and rendering

|Option|Default|What it does|
|--|--|--|
|`backendURL`|`NUXT_PUBLIC_C15T_BACKEND_URL`, then `NUXT_PUBLIC_INTH_PROJECT_URL`|Your Inth or self-hosted backend. The build downloads the manifest from it and consent saves go to it. The module reads the variable when the build starts, and Nuxt applies it again at runtime.|
|`mode`|`manifest()`|Where the visitor's policy comes from. Import `manifest()`, `hosted()` or `offline()` from `c15t/vue`. `nuxt.config.ts` only: the build picks the snapshots and the browser code from its `type` and `resolve`, so a `runtimeConfig.public.c15t.mode` is ignored, and so is a runtime `NUXT_PUBLIC_C15T_MODE_TYPE` or `NUXT_PUBLIC_C15T_MODE_RESOLVE`, with a warning. Its `manifestURL` and `backendURL` can still change at runtime, through `NUXT_PUBLIC_C15T_MODE_MANIFEST_URL` and `NUXT_PUBLIC_C15T_MODE_BACKEND_URL`. See [the modes](#modes).|
|`routePrefix`|`'/api/c15t'`|Path of the consent route the module adds in `manifest()` mode. It answers `${routePrefix}/init` and `${routePrefix}/manifest`. `false` adds no route: the server render resolves from the snapshot directly, and the browser asks the backend's `/init`. `'/'` stops the build with `` @c15t/vue: `routePrefix` can't be '/': a consent route at the site root would catch every page. Use a path such as '/api/c15t'. `` `nuxt.config.ts` only: the route is mounted at build time, so a `runtimeConfig.public.c15t.routePrefix` or a runtime `NUXT_PUBLIC_C15T_ROUTE_PREFIX` is ignored, with a warning.|
|`onBuildError`|Unset|What a failed build-time manifest download does in `manifest()` mode. Unset, `nuxt build` stops and `nuxt dev` logs a warning, and the server fetches the policy at runtime. `'fail'` stops both. `'runtime'` lets both continue. A missing backend URL stops both in `manifest()` mode, with or without a snapshot, because the browser saves consent there. The `C15T_ON_BUILD_ERROR` environment variable overrides it. The download waits at most 10 seconds.|
|`timeoutMs`|`500`|Longest wait for the policy during server rendering. `false` or `Infinity` waits as long as the backend takes; any other value that is not a finite, non-negative number uses the default.|
|`initPrefetch`|`true`|Pages with `ssr: false` in `hosted()` mode start `/init` from an inline script in the page head, before the app's JavaScript loads. Skipped when `consentSource`, `experiment` or `hosted({ headers })` is set, and when Nitro auto-imports are off, as under `future.compatibilityVersion: 5`, because the server cannot then read `app.config.ts`. `false` turns it off. To turn it off for some routes, set the route rule `c15t: { initPrefetch: false }`. See [Content Security Policy](/docs/frameworks/nuxt/content-security-policy#allow-the-early-init-script).|
|`devtools`|`true`|Adds a c15t tab to Nuxt DevTools in development. Production builds don't include it. See [DevTools](/docs/frameworks/nuxt/components/dev-tools).|
|`reportSessions`|`true`|`manifest()` mode only. The server reports each visitor it resolves from the manifest to the backend, so Inth counts visitors it never served `/init` to. Needs an absolute `backendURL`.|

### Modes

|Mode|Where the policy comes from|
|--|--|
|`manifest()`|The default. The build downloads the manifest and the server resolves each visitor from it. The browser bundle holds no snapshot or resolver.|
|`manifest({ source: 'runtime' })`|The server fetches the manifest at runtime, caches it and refreshes it in the background. Policy edits apply without a rebuild.|
|`manifest({ snapshot })`|A manifest you supply, for example imported from a JSON file in `nuxt.config.ts`. The build downloads nothing. Consent saves still go to `backendURL`, so it needs one.|
|`manifest({ resolve: 'browser' })`|The browser resolves the policy from the manifest, for `nuxt generate` and static hosting. Only this mode adds the snapshot to the browser bundle. Takes `geoURL` and `inputs` for the visitor's location. Pair it with `routePrefix: false` on a static host.|
|`hosted()`|Every server render, and the browser on pages the server did not resolve, asks the backend's `/init`. `hosted({ backendURL, headers })` overrides the backend URL and adds headers to `/init`.|
|`offline()`|The browser resolves policy rules with no backend. `offline({ policyRules })` replaces c15t's recommended rules. Not recommended for production environments.|

`manifest()` also takes `manifestURL`, the URL the build and the server
download the manifest from, by default `${backendURL}/manifest`.
[Rendering and deployment](/docs/frameworks/nuxt/rendering) explains which
mode fits which deployment.

### Consent and storage

|Option|Default|What it does|
|--|--|--|
|`consentCategories`|The policy's categories|Limits the categories the dialog and widget show, within the policy's scope.|
|`vendors`|Unset|Vendors listed under their category with their own switch. See [vendor consent](/docs/frameworks/nuxt/vendor-consent).|
|`storageConfig`|`{ storageKey: 'c15t' }`|Cookie and localStorage name, `crossSubdomain`, `defaultDomain` and `defaultExpiryDays`. Use the same value in both config files.|
|`reloadOnConsentRevoked`|`true`|Reloads the page when a save withdraws a granted category or vendor.|
|`clearOnRevocation`|Unset|Deletes first-party cookies and storage keys for a withdrawn category. See [clear on revocation](/docs/frameworks/nuxt/clear-on-revocation).|
|`iab`|Off|Turns IAB TCF on; `{}` is enough. Also takes publisher settings, such as `publisherRestrictions`; fields left out come from the policy. Unset, `false` or `{ enabled: false }` leaves IAB off, and an `iab` policy with a vendor list throws an `IABUnavailableError`. Set it here, not only in `app.config.ts`, so pages prefetch the IAB banner. See [IAB TCF](/docs/frameworks/nuxt/iab).|

### Scripts, blocking and events

|Option|Default|What it does|
|--|--|--|
|`scripts`|Unset|Vendor scripts that load by consent category. `app.config.ts` only. See [scripts](/docs/frameworks/nuxt/scripts).|
|`networkBlocker`|Off|Rules that hold `fetch` and XHR requests until their category is allowed. See [network blocker](/docs/frameworks/nuxt/network-blocker).|
|`iframeBlocker`|On|Gates iframes that carry `data-src` and `data-category`. `false` turns it off. See [embeds](/docs/frameworks/nuxt/embeds).|
|`nonce`|Unset|A nonce for every script the loader creates and for the theme token style tag. See [Content Security Policy](/docs/frameworks/nuxt/content-security-policy).|
|`callbacks`|Unset|`app.config.ts` only. See [callbacks](/docs/frameworks/nuxt/callbacks).|

### Appearance

|Option|Default|What it does|
|--|--|--|
|`tokens`|The default theme|CSS variables the module writes into a `<style id="c15t-css-vars">` tag in the page head on every page. See [customize](/docs/frameworks/nuxt/customize#set-theme-tokens).|
|`presentation`|Policy defaults|Banner and dialog variant, position, action layout and blocking.|
|`components`|Unset|Attributes, such as `class`, for named parts of each component.|
|`legalLinks`, `bannerLegalLinks`, `dialogLegalLinks`|None shown|Links to your privacy policy and similar pages, and which surfaces show them.|
|`hideBranding` and its per-surface forms|`false`|Hide the "Secured by" tag.|
|`showTrigger` and the `trigger*` options|`false`|The floating trigger. See [ConsentDialogTrigger](/docs/frameworks/nuxt/components/consent-dialog-trigger).|
|`disableAnimation`|`false`|Turns off banner and dialog transitions.|
|`models`, `bannerModels`, `iabBannerModels`, `iabDialogModels`|Every model|Limit which policy models show a surface.|

## Verify

Run `nuxt dev` and request `/api/c15t/init` in the default `manifest()` mode.
It returns JSON with the resolved policy for your location. View the source of a page under a policy that asks for consent and
find `data-testid="consent-banner-root"`.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/nuxt/rendering
Choose the c15t Nuxt module's mode and routePrefix for server rendering, prerendered and cached routes, nuxt generate on static hosting, and ssr false.

## Pick the setup for your deployment

Two module options in `nuxt.config.ts` decide where each visitor's policy
comes from. `mode` is `manifest()`, `hosted()` or `offline()`, imported from
`c15t/vue`. `routePrefix` is where the module adds its consent route.

|Your deployment|`c15t` options|Banner in the first HTML|
|--|--|--|
|A Nuxt server renders each request (`nuxt build`)|None: `mode` defaults to `manifest()` and `routePrefix` to `'/api/c15t'`. See the [quickstart](/docs/frameworks/nuxt/quickstart).|Yes|
|A Nuxt server with some prerendered or cached routes (`routeRules` with `prerender`, `swr`, `isr` or `cache`)|The same. See [prerendered and cached routes](#prerendered-and-cached-routes).|No on those routes, yes elsewhere|
|Policy edits must apply without a rebuild|`mode: manifest({ source: 'runtime' })`. See [fetch the manifest at runtime](#fetch-the-manifest-at-runtime).|Yes|
|Static hosting with `nuxt generate`|`mode: manifest({ resolve: 'browser' })` and `routePrefix: false`, or `mode: hosted()`. See [deploy to static hosting](#deploy-to-static-hosting).|No|
|A single-page app with `ssr: false`|The same as static hosting. See [build a single-page app](#build-a-single-page-app-with-ssr-false).|No|

`mode` and `routePrefix` are read from `nuxt.config.ts` only. They decide
what the build bundles and which routes the server has, so `app.config.ts`
cannot change them. Import the modes from `c15t/vue`, the module entry: they
return plain data that reaches the browser through runtime config. Passing a
transport, such as `manifest` from `c15t/vue/vue-plugin`, throws during setup.

The module has one configuration for the whole app. It decides per route
whether the HTML belongs to one visitor or to everyone.

## Render each request on the server

By default, every server render reads the visitor's consent cookie and
location headers, resolves their policy from the bundled snapshot, and sends
the result with the page. The browser reuses it during hydration, so
consent-gated scripts can start right after hydration and the banner needs no
extra request. The browser bundle holds no resolver, snapshot or policy
rules. The [quickstart](/docs/frameworks/nuxt/quickstart) sets this up, and
`examples/nuxt` in the c15t repository runs it.

The module adds one catch-all route at `${routePrefix}/**`, `/api/c15t/**` by
default. It answers `GET /api/c15t/init`, the visitor's resolved policy, and
`GET /api/c15t/manifest`, the deployment's manifest. The server render
resolves through the init route in-process, through Nitro's local fetch, so
it never leaves the server. The browser uses the init route when it resolves
the policy itself, for example on a prerendered route or after a server
render that timed out. Change the path with `routePrefix: '/consent'`.

Server rendering waits at most `timeoutMs`, 500 milliseconds by default, for
the policy. With a bundled snapshot that is local work. When the server
fetches the manifest at runtime and the backend is slow or down, the page
renders without consent UI in the HTML, optional categories stay denied,
gated scripts and iframes stay blocked, and the browser resolves the policy
after hydration.

A banner in the server HTML shows before the app hydrates, which on a slow
phone can take seconds. The stock banner puts a small inline script in front of
its buttons that holds an Accept all, Reject all, notice dismiss or Customize
tap made in that gap. Accept, reject and dismiss hide the banner at once. When
the banner hydrates and the runtime has started, c15t records the choice with
the time of the tap, saves it and loads the scripts it allows; Customize opens
the dialog. A tap on a banner for one model or prompt is dropped when the
browser resolves another, and the banner shows again.

### Without the consent route

`routePrefix: false` adds no route. The server render still resolves each
visitor from the bundled snapshot, and the browser asks the backend's `/init`
whenever it resolves the policy itself, such as on a prerendered page. Keep
the route unless something else owns `/api/c15t`.

### Ask the backend on every render

`mode: hosted()` sends every server render to the backend's `/init`, which
resolves the visitor's location itself. The module adds no route and bundles
no snapshot:

```ts title="nuxt.config.ts"
import { hosted } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { mode: hosted() },
	modules: ['c15t/vue'],
});
```

That request carries the resolved location, language and GPC and the
`user-agent`, and, over `https` or to a loopback host, the consent cookie
alone, never the rest of the cookie jar. Every render waits on the backend,
up to `timeoutMs`. Prefer the default `manifest()`, or
`manifest({ source: 'runtime' })` when you need policy updates without a
rebuild.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

The default mode, `manifest()`, bundles the manifest. The module reads
`NUXT_PUBLIC_C15T_BACKEND_URL`, then `NUXT_PUBLIC_INTH_PROJECT_URL`, when the
`c15t` key sets no `backendURL`, so
`nuxt.config.ts` needs only the module:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
});
```

The module fetches the snapshot during `nuxt build` and when `nuxt dev`
starts, and embeds it in the server bundle. `nuxt prepare` does not fetch, so
dependency installation and type generation do not need the backend. The
consent route and the server render read the snapshot; it stays out of
runtime config and out of the browser bundle. Only
`manifest({ resolve: 'browser' })` adds it to the browser bundle, because the
browser then resolves the policy itself. Production server startup does not
fetch another manifest.

The module skips the fetch for `manifest({ source: 'runtime' })`, a
`manifest({ snapshot })` you supply, and the `hosted()` and `offline()`
modes. A relative backend URL is also skipped, unless `onBuildError` is
`'fail'`.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

Set `onBuildError` under the `c15t` key in `nuxt.config.ts`. In dev, and in a
build with `onBuildError: 'runtime'`, a failed fetch leaves the server without
a snapshot, and the server fetches and caches the policy at runtime.

For policy updates without a rebuild, set `mode: manifest({ source: 'runtime' })`.
The server then fetches and caches the policy at runtime, and refreshes it
in the background.

## Fetch the manifest at runtime

`manifest({ source: 'runtime' })` skips the build-time download. The server
fetches the public manifest the first time it needs it, caches it, and
refreshes it in the background, so policy edits apply without a rebuild:

```ts title="nuxt.config.ts"
import { manifest } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { mode: manifest({ source: 'runtime' }) },
	modules: ['c15t/vue'],
});
```

By default the server fetches `${backendURL}/manifest`. Set
`manifest({ manifestURL })` to fetch from another URL. The consent route and
the server render share the cache. The first render after a cold start waits
for the fetch, up to `timeoutMs`.

## Prerendered and cached routes

A prerendered route, or one with a `prerender`, `swr`, `isr` or `cache` route
rule, sends the same HTML to every visitor. The module renders that HTML
without any visitor's consent record, location or request headers, so it has
no banner. After hydration the browser requests the visitor's policy from
`/api/c15t/init` and reads their stored choice, then shows the banner if the
policy asks for one. With `hosted()`, or `routePrefix: false`, the browser
asks the backend's `/init` instead.

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	routeRules: { '/blog/**': { swr: 3600 }, '/about': { prerender: true } },
});
```

Keep the quickstart setup. Routes without these rules
still render per request with the banner in the HTML. Until the browser has
the policy, optional categories stay denied and gated scripts and iframes stay
blocked.

The browser also keeps the visitor's choice in localStorage. When localStorage
holds a newer denial than the consent cookie the server read, the browser
applies the denial, so an older cookie cannot undo a rejection.

## Deploy to static hosting

`nuxt generate` prerenders every page with server rendering on, so crawlers
get your content in the HTML. A static host has no Nuxt server, so no
consent route exists and no server resolves visitors. With the default
`manifest()`, `nuxt generate` logs a warning that it cannot resolve the
policy there. Pick a mode that lets the browser resolve it:

* **`manifest({ resolve: 'browser' })` with `routePrefix: false`.** The build
  bundles the manifest into the browser bundle, and the browser resolves the
  policy. A policy that depends on location still asks the backend, as
  described below.
* **`hosted()`.** The browser calls your backend's `/init` directly, and the
  backend resolves the visitor's location.

```ts title="nuxt.config.ts"
import { manifest } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: {
		// A static host has no server: the browser resolves the policy the
		// build bundled, and the module adds no consent route.
		mode: manifest({ resolve: 'browser' }),
		routePrefix: false,
	},
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
	ssr: false,
});
```

`examples/nuxt-static` uses `ssr: false` as well; `nuxt generate` works the
same without it. Run `nuxt generate` and deploy `.output/public`. Every page
renders without a banner in its HTML, and the browser resolves each visitor
after hydration, as on a [prerendered route](#prerendered-and-cached-routes).

With browser resolution, only the manifest and English copy are in the
bundle. The resolver loads as its own chunk when the app starts, and a
visitor who resolves to another language loads that language's text the
first time it is needed.

The browser has no request location. When your policy depends on the
visitor's country or region and neither `inputs` nor `geoURL` supplies one,
the browser asks the backend's `/init` on the first visit, as every
single-page app does. It doesn't apply the rule for an unknown location,
which could be another region's. To resolve by location in the browser, pass
`manifest({ resolve: 'browser', geoURL: '/geo' })` with a route on your own
origin, such as an edge function your host runs, that returns the visitor's
`country` and `region` as JSON, for example `{ "country": "DE", "region": "BE" }`. c15t resolves the
policy again when the response arrives. Or use `hosted()`.

Consent saves go to the backend from the browser, so the backend must allow
your site's origin. With Inth, add it to the project's trusted origins.

## Build a single-page app with ssr: false

`ssr: false` turns the site into a single-page app. Nuxt sends an empty shell
and renders every page in the browser, so crawlers that do not run JavaScript
see no content. That is the tradeoff. Prerendering works without it, so use
`ssr: false` only when you want a single-page app for other reasons.

On a static host, use the [static hosting](#deploy-to-static-hosting) config
above. The module reads the visitor's stored choice from their own cookie,
and the browser resolves the policy from the bundled manifest. The banner
appears once the resolver chunk loads. `examples/nuxt-static` in the c15t
repository builds this setup. With a Nuxt server, the default `manifest()`
also works: the browser asks the server's `/api/c15t/init`.

With `hosted()`, the module adds a small inline script to the head of every
`ssr: false` page, prerendered ones included, that starts the backend's
`/init` request while the browser parses the HTML. The app uses that response
once its JavaScript loads, so the policy request no longer waits for the
app's bundle. The script contains your backend URL and nothing about the
visitor. Turn it off with the module option `initPrefetch: false`, or for one
route with `routeRules: { '/path': { c15t: { initPrefetch: false } } }`. Use
the route rule when a client plugin changes c15t's configuration for that
route, because the server cannot see that change and the early request would
go unused.

## Module options

The [Nuxt module](/docs/frameworks/nuxt/module#backend-and-rendering) page
lists `mode`, `routePrefix`, `onBuildError`, `timeoutMs` and
`reportSessions` with their defaults.

The server reads the visitor's location from request headers. See
[geography headers](/docs/frameworks/nuxt/geography-headers) for the list and
for which ones to trust.

## Verify your deployment

For request-time rendering, view the page source under a policy that asks for
consent and find `data-testid="consent-banner-root"`. Reject, reload, and
confirm the banner stays closed.

For a prerendered or cached route, view the page source and confirm it has no
`consent-banner-root`. Open the Network tab and reload. The browser requests
`/api/c15t/init` after the page loads, and the banner appears. Reject, reload,
and confirm the banner stays closed.

For static output with browser resolution, serve `.output/public` and open
the Network tab. The browser makes no request to the backend's `/manifest` or
`/init`, and none to `/api/c15t`. With `hosted()`, it requests the backend's
`/init` once per page load. Reject, reload, and confirm the banner stays
closed. Then follow [verify consent](/docs/guides/verify-consent) for the
vendor checks.

# Scripts
URL: https://c15t.com/docs/frameworks/nuxt/scripts
Load vendor scripts by consent category in a Nuxt app with the c15t Nuxt module, what happens when a visitor withdraws consent, and how to move off @nuxt/scripts and nuxt-gtag.

## Register vendor scripts

A banner does not stop a script you load with a `<script>` tag, `useHead` or a
vendor's Nuxt module. Remove those loaders and register the vendor with c15t
instead, so c15t loads it only while its category is allowed. For
`@nuxt/scripts` and `nuxt-gtag`, follow
[migrate from `@nuxt/scripts`](#migrate-from-nuxtscripts) or
[migrate from `nuxt-gtag`](#migrate-from-nuxt-gtag).

Register the helpers from `@c15t/integrations` under the `c15t` key in
`app/app.config.ts`:

```ts title="app/app.config.ts"
import { posthog } from '@c15t/integrations/posthog';

export default defineAppConfig({
	c15t: {
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	},
});
```

The module starts one script loader in the browser after hydration, once it
has applied the visitor's stored choice and privacy signals. Do not also call
`createScriptLoader` yourself, or each script loads twice.

`scripts` must go in `app.config.ts`. Module options in `nuxt.config.ts`
reach the browser as JSON, which drops the functions inside each script.

Every vendor guide under [integrations](/docs/integrations/overview) gives the
helper and options for that vendor.

## Embeds and other requests

Scripts cover vendor code c15t loads for you. For the rest:

* [Embeds](/docs/frameworks/nuxt/embeds) gates iframes with `ConsentGate` or
  the iframe blocker.
* [Network blocker](/docs/frameworks/nuxt/network-blocker) holds `fetch` and
  XHR calls that match a rule until their category is allowed.

## When a visitor withdraws consent

Removing a script tag cannot stop code that already ran. When a save turns off
a category or vendor that was allowed, c15t reloads the page so the new
document starts with only permitted code. Set `reloadOnConsentRevoked: false`
to handle revocation yourself, or use the
[`onBeforeConsentRevocationReload` callback](/docs/frameworks/nuxt/callbacks#before-a-revocation-reload)
to run code before the reload.

`clearOnRevocation` deletes first-party cookies and storage keys that belong to
a category when it is withdrawn. It is plain data, so it can go in
`nuxt.config.ts`. See [clear on revocation](/docs/frameworks/nuxt/clear-on-revocation).

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Declare
the vendors in the `vendors` option; helpers from `@c15t/integrations` already carry
their vendor slug. See [vendor consent](/docs/frameworks/nuxt/vendor-consent).

## Content Security Policy

Allow each vendor's script host in your `script-src` directive. The module's
`nonce` option is fixed when the app builds, so prefer the host allowlist.
See [Content Security Policy](/docs/frameworks/nuxt/content-security-policy).

## Migrate from `@nuxt/scripts`

`@nuxt/scripts` loads a registry script when its own trigger fires, whatever
the visitor chose in c15t. That covers a `useScriptGoogleAnalytics()` call in
a component, a `scripts.registry` entry with a `trigger` in `nuxt.config.ts`,
and components such as `ScriptYouTubePlayer`. Move every tracking vendor to
c15t's `scripts`. You can keep `@nuxt/scripts` for
[necessary scripts](#keep-nuxtscripts-for-necessary-scripts).

### Map registry scripts to helpers

|`@nuxt/scripts`|c15t helper|
|--|--|
|`useScriptGoogleAnalytics`|[`gtag`](/docs/integrations/google-tag)|
|`useScriptGoogleTagManager`|[`googleTagManager`](/docs/integrations/google-tag-manager)|
|`useScriptMetaPixel`|[`metaPixel`](/docs/integrations/meta-pixel)|
|`useScriptTikTokPixel`|[`tiktokPixel`](/docs/integrations/tiktok-pixel)|
|`useScriptRedditPixel`|[`redditPixel`](/docs/integrations/reddit-pixel)|
|`useScriptSnapchatPixel`|[`snapchatPixel`](/docs/integrations/snapchat-pixel)|
|`useScriptXPixel`|[`xPixel`](/docs/integrations/x-pixel)|
|`useScriptLinkedInInsight`|[`linkedinInsights`](/docs/integrations/linkedin-insights)|
|`useScriptBingUet`|[`microsoftUet`](/docs/integrations/microsoft-uet)|
|`useScriptClarity`|[`clarity`](/docs/integrations/microsoft-clarity)|
|`useScriptHotjar`|[`hotjar`](/docs/integrations/hotjar)|
|`useScriptPostHog`|[`posthog`](/docs/integrations/posthog)|
|`useScriptSegment`|[`segment`](/docs/integrations/segment)|
|`useScriptMixpanelAnalytics`|[`mixpanelAnalytics`](/docs/integrations/mixpanel-analytics)|
|`useScriptPlausibleAnalytics`|[`plausibleAnalytics`](/docs/integrations/plausible-analytics)|
|`useScriptFathomAnalytics`|[`fathomAnalytics`](/docs/integrations/fathom-analytics)|
|`useScriptMatomoAnalytics`|[`matomoAnalytics`](/docs/integrations/matomo-analytics)|
|`useScriptUmamiAnalytics`|[`umamiAnalytics`](/docs/integrations/umami-analytics)|
|`useScriptRybbitAnalytics`|[`rybbitAnalytics`](/docs/integrations/rybbit-analytics)|
|`useScriptDatabuddyAnalytics`|[`databuddy`](/docs/integrations/databuddy)|
|`useScriptVercelAnalytics`|[`vercelAnalytics`](/docs/integrations/vercel-analytics)|
|`useScriptCloudflareWebAnalytics`|[`cloudflareWebAnalytics`](/docs/integrations/cloudflare-web-analytics)|
|`useScriptAhrefsAnalytics`|[`ahrefsAnalytics`](/docs/integrations/ahrefs-analytics)|
|`useScriptCrisp`, `ScriptCrisp`|[`crisp`](/docs/integrations/crisp)|
|`useScriptIntercom`, `ScriptIntercom`|[`intercom`](/docs/integrations/intercom)|
|`ScriptYouTubePlayer`|`ConsentGate` around an iframe. See [embeds](#move-youtube-and-google-maps-embeds).|
|`ScriptGoogleMaps`|`ConsentGate` around an iframe. See [embeds](#move-youtube-and-google-maps-embeds).|

Registry options do not carry over one to one. Copy each vendor's ID into the
helper, then check the vendor guide for the rest. Meta's `id` becomes
`pixelId`, and Tag Manager's `l` or `dataLayer` becomes `dataLayer`. The `gtag`
helper always uses `window.dataLayer`, so Google Analytics' `l` has no
equivalent. The `googleTagManager` helper has no options for Tag Manager's
`auth`, `preview`, `envName`, `cookiesWin` or `onBeforeGtmStart`. A container
environment that needs them, or a vendor without a helper such as AdSense,
needs a [custom integration](/docs/integrations/building-integrations).

Put the helpers in `app/consent-scripts.ts`, keeping the same IDs:

```ts title="app/consent-scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { metaPixel } from '@c15t/integrations/meta-pixel';

export const scripts = [
	// Was useScriptGoogleAnalytics({ id: 'G-XXXXXXXXXX' })
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
	// Was useScriptGoogleTagManager({ id: 'GTM-XXXXXXX' })
	googleTagManager({ id: 'GTM-XXXXXXX' }),
	// Was useScriptMetaPixel({ id: '123456789012345' })
	metaPixel({ pixelId: '123456789012345' }),
];
```

Register `scripts` in `app/app.config.ts` as in
[register vendor scripts](#register-vendor-scripts). Then delete the
`useScript*` calls for those vendors, their `scripts.registry` entries in
`nuxt.config.ts`, and any `scripts.globals` entry that loads a tracker. A
leftover composable call loads a second copy of the vendor outside c15t.

The helpers load each vendor from the host in its guide, usually the vendor's
own domain, and the vendor's requests go straight to it. `@nuxt/scripts`
bundles some registry scripts and proxies many by default, including Google
Analytics, when the app has a server runtime. Before a request reaches the
vendor, the proxy truncates the visitor's IP address, strips cookie and
authorization headers, and, depending on the script, generalizes fingerprinting
fields such as language and hardware. After the move, the vendor receives these
unchanged.

If your privacy notice or legal review relies on that proxy, keep the vendor's
requests on your own domain: write a
[custom integration](/docs/integrations/building-integrations) that loads the
script and points the vendor's collection endpoint at a reverse proxy you run.
Otherwise, update the notice. In both cases, allow the hosts the browser now
contacts in your
[Content Security Policy](/docs/frameworks/nuxt/content-security-policy).

### Choose when Google loads

The `gtag` and `googleTagManager` helpers take a `loadMode` option. It
decides whether the page contacts Google before the helper's category is
allowed:

|`loadMode`|Until the category is allowed|Use it when|
|--|--|--|
|`'always'` (default)|c15t loads Google's script, sends Consent Mode `default` with the current permissions, then sends `update` as they change. Google receives requests with the optional consent types denied.|You want Consent Mode signals from visitors who have not allowed the category.|
|`'after-consent'`|c15t sends no request to Google.|Your site must make no request to Google before opt-in. You give up Consent Mode's cookieless pings and conversion modeling for visitors who haven't allowed the category.|

With `'after-consent'`, `gtag` waits for its `category`, and
`googleTagManager` waits for `measurement` or `marketing` because a container
usually holds both kinds of tag. Pass `category` to `googleTagManager` to
change that, for example `category: 'measurement'` for an analytics-only
container. Until the helper loads, `window.gtag` doesn't exist, and neither
does `window.dataLayer` unless you seeded it, so event calls written as
`window.gtag?.(...)` do nothing.

`'after-consent'` waits for the category to be allowed, not for a recorded
choice. Under an `opt-in` policy, that happens when the visitor allows it.
Under an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

In either mode, the container runs every tag in it once it starts. Google
tags inside follow Consent Mode, but Custom HTML tags and third-party pixels
fire on their own triggers. With the default `category`, a visitor who
allowed only measurement starts the container, and a marketing pixel in it
loads too. With `'always'`, both load before any choice. Add a
consent check to each of those tags in GTM, or move the vendor out of the
container to its own c15t helper. See
[configure consent inside the container](/docs/integrations/google-tag-manager#configure-consent-inside-the-container).

Set it on each Google helper in your `scripts` array:

```ts
gtag({
	id: 'G-XXXXXXXXXX',
	category: 'measurement',
	loadMode: 'after-consent',
}),
googleTagManager({ id: 'GTM-XXXXXXX', loadMode: 'after-consent' }),
```

The [Google Tag](/docs/integrations/google-tag) and
[Google Tag Manager](/docs/integrations/google-tag-manager) guides list what
each mode sends and how to check it in DevTools.

### Remove useScriptTriggerConsent

`useScriptTriggerConsent` loads a script once its own `consented` ref turns
true, through `accept()` or the `consent` option. c15t records consent
separately, so you end up with two answers that can disagree. If any code
calls `accept()`, the script loads even after the visitor rejects in the c15t
banner. Global Privacy Control, vendor switches and policy changes in c15t
never reach the trigger. Delete every `useScriptTriggerConsent` call and the
banner code that called `accept()` or `revoke()`. c15t decides when each
registered script loads.

Remove the Consent Mode calls too: the `defaultConsent` option and
`consent.update()` on the Google registry scripts. The `gtag` and
`googleTagManager` helpers send `default` and `update` from the visitor's c15t
permissions, and a second source sends conflicting commands.

### Keep your event calls

A registry composable returns a `proxy` that queues calls until its script
loads. Calling the composable to get that proxy also loads the script through
`@nuxt/scripts`, so event code has to stop calling it. Call the global the
vendor defines once c15t loads it:

|Before|After|
|--|--|
|`proxy.gtag(...)` from `useScriptGoogleAnalytics()`|`window.gtag?.(...)`|
|`proxy.dataLayer.push(...)` from `useScriptGoogleTagManager()`|`window.dataLayer?.push(...)`, or `window[name]` with a custom `dataLayer` name|
|`proxy.fbq('track', ...)` from `useScriptMetaPixel()`|`metaPixelEvent(...)` from `@c15t/integrations/meta-pixel`, after checking marketing permission|

The proxy did nothing during server rendering. `window` does not exist there,
so call these from an event handler or `onMounted`:

```vue title="app/components/PurchaseButton.vue"
<script setup lang="ts">
import { metaPixelEvent } from '@c15t/integrations/meta-pixel';

const props = defineProps<{ value: number }>();
const consent = useConsent();

const onPurchase = () => {
	// Was proxy.gtag('event', 'purchase', ...) from useScriptGoogleAnalytics()
	window.gtag?.('event', 'purchase', { currency: 'USD', value: props.value });

	// Was proxy.fbq('track', 'Purchase', ...) from useScriptMetaPixel().
	// fbq stays defined after a revocation until the page reloads, so check
	// the permission, not the global.
	if (consent.value.marketing) {
		metaPixelEvent('Purchase', { currency: 'USD', value: props.value });
	}
};
</script>

<template>
	<button type="button" @click="onPurchase">Buy now</button>
</template>
```

Until c15t has set up a vendor, its global is undefined and the optional call
drops the event. Other vendors' event APIs are in their
[integration guides](/docs/integrations/overview).

### Move YouTube and Google Maps embeds

`ScriptYouTubePlayer` puts a `dns-prefetch` or `preconnect` link for
`i.ytimg.com` in the server HTML and loads the video thumbnail from YouTube
before the visitor clicks. `ScriptGoogleMaps` puts a `dns-prefetch` link for
`maps.googleapis.com` in the server HTML. For
a video or a map that only needs to display, render the iframe inside
`ConsentGate`, as in [embeds](/docs/frameworks/nuxt/embeds) and the
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides.

If you need the YouTube IFrame Player API or the Maps JavaScript API, such as
player events or markers, keep the `@nuxt/scripts` component and put it
inside `ConsentGate`. The component then renders only while the category is
allowed, and its links and requests wait with it.

### Keep @nuxt/scripts for necessary scripts

c15t does not need to own every script. A first-party script or an SDK your
checkout needs, such as Stripe, can stay on `@nuxt/scripts` with its usual
trigger, provided your policy does not ask consent for it. Do not load a
tracker there.

## Migrate from `nuxt-gtag`

The `nuxt-gtag` client plugin adds `gtag.js` to every page as soon as the app
loads, unless you set `initMode: 'manual'`. c15t cannot gate it. Replace the
module's configuration and composables:

|`nuxt-gtag`|c15t|
|--|--|
|`gtag.id` in `nuxt.config.ts`|`gtag({ id, category: 'measurement' })` in `app/consent-scripts.ts`|
|`gtag.config`|The `config` option on `gtag`|
|`gtag.tags` with several IDs|One `gtag` helper, when the extra IDs need no `config` of their own. Add them as destinations of that Google tag in Google's tag settings. Otherwise see [tags with their own settings](#tags-with-their-own-settings).|
|`gtag.initCommands` with `consent` `default`|Delete. The helper sends `default` from the visitor's permissions.|
|`initMode: 'manual'` and `useGtag().initialize()`|Delete. c15t loads the tag. The helper needs its `id` when you register `scripts`, so an ID passed to `initialize()` at runtime, as in `nuxt-gtag`'s multi-tenancy setup, needs a [custom integration](/docs/integrations/building-integrations).|
|`useGtag().gtag(...)`|`window.gtag?.(...)`|
|`useTrackEvent(name, params)`|`window.gtag?.('event', name, params)`|
|`useGtag().disableAnalytics()` and `enableAnalytics()`|Delete, and set `loadMode: 'after-consent'` if you used them to stop all Analytics requests. See [stop all requests until consent](#stop-all-requests-until-consent).|
|`enabled: false` for an environment|Leave the helper out of `scripts` in that environment.|
|`url`, `loadingStrategy`|No equivalent. The helper loads `gtag.js` from `googletagmanager.com` with `async`.|

Register one `gtag` helper only. c15t tracks scripts by ID, and every `gtag`
helper uses the script ID `gtag`.

```ts title="app/consent-scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';

export const scripts = [
	// Was gtag: { id: 'G-XXXXXXXXXX' } in nuxt.config.ts. Move a `gtag.config`
	// object to the `config` option unchanged.
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
];
```

Register `scripts` in `app/app.config.ts` as in
[register vendor scripts](#register-vendor-scripts), and choose a
[load mode](#choose-when-google-loads) for the tag. Then remove
`'nuxt-gtag'` from `modules` and the `gtag` key from `nuxt.config.ts`, and
uninstall the package, for example with `npm uninstall nuxt-gtag`. `useGtag`
and `useTrackEvent` were auto-imports, so `nuxt typecheck` reports any call you
missed.

Call `window.gtag` from browser code. `useGtag()` returned a function that did
nothing on the server, and `window` does not exist there.

### Stop all requests until consent

`disableAnalytics()` sets Google's `ga-disable-<ID>` flag, so `gtag.js` sends
nothing to Analytics for that ID. The `gtag` helper's default
`loadMode: 'always'` works differently: it loads `gtag.js` before consent and
sends Consent Mode `default` with the optional types denied. Google then
receives cookieless pings. Turning Google off with
[vendor consent](/docs/frameworks/nuxt/vendor-consent) sends the same denied
signals.

If you called `disableAnalytics()` so that a visitor who has not opted in sends
nothing, set `loadMode: 'after-consent'` on the helper. `gtag.js` then waits
for the helper's `category`.

### Tags with their own settings

The `gtag` helper sends one `config` command, for its `id`. A `gtag.tags`
entry with its own `config`, or a mix of Analytics IDs with Google Ads or
Floodlight IDs, has no direct mapping:

* Destinations added in Google's tag settings share the helper's `config`.
* With `loadMode: 'after-consent'`, every destination waits for the helper's
  one `category`. An Ads ID under `measurement` stays off for a visitor who
  allowed only marketing.

For these setups, replace the `gtag` helper with a
[custom integration](/docs/integrations/building-integrations). It loads
`gtag.js` once, sends Consent Mode `default` and `update` from the visitor's
permissions, as in
[load before consent and signal the vendor](/docs/integrations/building-integrations#load-before-consent-and-signal-the-vendor),
and sends a `config` command for each tag with that tag's settings. To send
nothing before opt-in, leave out `alwaysLoad` and set
`category: { or: ['measurement', 'marketing'] }`. That condition only decides
when `gtag.js` loads. Set each Google consent type from its own category, so
Consent Mode keeps the other purpose's destinations restricted:
`measurement` sets `analytics_storage`, and `marketing` sets `ad_storage`,
`ad_user_data` and `ad_personalization`.

## Verify gating

In a private window, open the Network tab and load a page under a policy that
asks for consent. Requests to your vendors are absent.
Allow one category and save, and only that category's vendors load. Withdraw
it, and the page reloads without loading the vendor again.
[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/nuxt/embeds
Keep YouTube videos, maps and other iframes out of a Nuxt page until their consent category is allowed, with ConsentGate or the iframe blocker.

## Pick a method

|Method|Use it when|
|--|--|
|`ConsentGate`|You render the iframe in a Vue component and want a placeholder with a way to open preferences. The server HTML respects the visitor's choice.|
|The iframe blocker|The iframe comes from markup you do not render with a component, such as CMS content, or you want no wrapper.|

Both keep the iframe's `src` out of the page until the category is allowed,
so the embed's host receives no request before consent.

## Gate an embed with ConsentGate

Wrap the iframe in the globally registered
[`ConsentGate`](/docs/frameworks/nuxt/components/consent-gate):

```vue title="app/components/VideoEmbed.vue"
<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

The iframe is absent from the server HTML and the DOM until the visitor
allows measurement. The `placeholder` slot shows a message and a
[`ConsentDialogLink`](/docs/frameworks/nuxt/components/consent-dialog-link)
until then. When the visitor withdraws measurement, Vue removes the iframe.

Pick the category that matches what the embed does. The example uses
measurement for YouTube because its player measures views. A map or chat
widget usually belongs under functionality or experience.

## Gate an iframe with the iframe blocker

The module runs the iframe blocker in the browser by default. Give an iframe
`data-src` instead of `src`, and a `data-category`:

```vue title="app/components/MapEmbed.vue"
<template>
	<iframe
		data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
		data-category="functionality"
		title="Store map"
	/>
</template>
```

The server HTML has no `src`, so nothing loads before hydration. After
hydration, c15t sets `src` from `data-src` when the category is allowed and
removes it when the category is withdrawn. It watches the page, so iframes
added by later navigation are handled too. The iframe element stays in the
page while blocked, empty. Add `data-vendor` with a vendor ID to also block
the iframe while the visitor has turned that vendor off.

To turn the blocker off, set `iframeBlocker: false` in the module options.

## Verify

View the page source in a private window, under a policy that asks for
consent. No iframe has a `src` pointing at `youtube-nocookie.com` or
`google.com/maps`, and the Network tab shows no request to them. Allow the
category and save: the iframe loads. Withdraw it and save: the page reloads
without the embed. The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover sizing and titles.

# Network blocker
URL: https://c15t.com/docs/frameworks/nuxt/network-blocker
Hold fetch and XMLHttpRequest calls in a Nuxt app until their consent category is allowed, with rules in the c15t module options.

## Add rules

The network blocker stops `fetch` and `XMLHttpRequest` calls in the browser
that match a rule until the rule's category is allowed. Use it as a backstop
for tracking calls your own code or a vendor SDK makes. Load vendor SDKs
through [`scripts`](/docs/frameworks/nuxt/scripts) first, so they do not run
at all before consent.

Rules are plain data, so they can go in the module options:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: {
		networkBlocker: {
			rules: [{ category: 'measurement', domain: 'google-analytics.com' }],
		},
	},
});
```

Module options reach the browser as JSON, so the `onRequestBlocked` callback
goes under the `c15t` key of `app/app.config.ts`. Rules you set there are
added to the rules from `nuxt.config.ts`:

```ts title="app/app.config.ts"
export default defineAppConfig({
	c15t: {
		networkBlocker: {
			onRequestBlocked: (info) => console.info('Blocked', info.url),
			rules: [],
		},
	},
});
```

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains, so `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows a rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. `category`
also takes conditions such as `{ and: ['measurement', 'marketing'] }`.

Add `vendor` with a vendor ID to also block the request while the visitor has
turned that vendor off. Rules for IAB TCF vendors use `vendorId` and the
`iabPurposes` fields instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|Required|The rules above.|
|`enabled`|`true`|`false` keeps the rules but stops blocking.|
|`logBlockedRequests`|`true`|Logs each blocked request with `console.warn`.|
|`onRequestBlocked`|Unset|`app.config.ts` only. Called with `{ method, url, rule }` for each blocked request.|

## What a blocked request looks like

A blocked `fetch` resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The blocker runs in the browser only. It starts holding matching requests
when the c15t plugin runs, before your app hydrates. While consent is
unknown, a matching request waits instead of failing. Once the policy and the
stored choice apply, a waiting request is sent if consent allows it and
blocked otherwise. When the server resolves the policy, in the default `manifest()` mode or `hosted()`,
the policy arrives with the page, so waiting requests are decided as soon as the
app mounts.

Requests your server makes during server rendering, such as `useFetch` on the
server, are not blocked. Check `useConsent()` before you call a vendor from
server code.

## What it cannot stop

The blocker sees only browser `fetch` and `XMLHttpRequest` calls made after
the c15t plugin runs. It cannot stop:

* Scripts you add to the page head with `useHead` or `app.head`, and Nuxt
  plugins that run before the c15t plugin.
* Code that saved its own reference to `fetch` before the plugin ran.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests from
  `<img>`, `<script>` and `<iframe>` elements, web workers and service
  workers.

## Verify

Open the Network tab, clear site data and reload. Requests that match a rule
do not appear until you allow their category, and the console lists each
blocked request. Reject, reload, and check that they still do not appear.

# Vendor consent
URL: https://c15t.com/docs/frameworks/nuxt/vendor-consent
Let visitors allow a category such as marketing in a Nuxt app and still turn off one vendor in it, with the vendors option of the c15t Nuxt module and useConsentDraft.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in `app/consent-scripts.ts`, using the
`vendor` slug each script already carries:

```ts title="app/consent-scripts.ts (partial)"
import type { Vendor } from 'c15t';

export const vendors: Vendor[] = [
	{
		id: 'x-pixel',
		name: 'X Pixel',
		category: 'marketing',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];
```

Then register them under the `c15t` key in `app/app.config.ts`:

```ts title="app/app.config.ts (partial)"
import { scripts, vendors } from './consent-scripts';

export default defineAppConfig({ c15t: { scripts, vendors } });
```

Vendors are plain data, so the `c15t` key in `nuxt.config.ts` accepts them too.
The module combines the arrays from both files.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. For an iframe, add `data-vendor` and use
the iframe blocker; see [embeds](/docs/frameworks/nuxt/embeds).

## What the preference dialog shows

`ConsentManager`, which `ConsentRoot` renders, and `ConsentWidget` list each
declared vendor under its category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`useConsentDraft()`, which the module auto-imports, holds the category and vendor
switches of a preference form. `vendors` has one value per declared vendor,
`setVendor(id, granted)` changes one, and `save()` records the categories and
the vendors that changed:

```vue title="app/components/x-pixel-switch.vue (partial)"
<script setup lang="ts">
const { vendors, setVendor, save } = useConsentDraft();
</script>

<template>
	<input
		type="checkbox"
		:checked="vendors['x-pixel'] ?? true"
		@change="setVendor('x-pixel', ($event.target as HTMLInputElement).checked)"
	/>
	<button type="button" @click="save()">Save</button>
</template>
```

`save()` resolves `{ ok: false }` without recording anything while `isStale`
is `true`. [Composables](/docs/frameworks/nuxt/composables) covers the draft.

## Check whether a vendor may run

`useVendorAllowed(id)`, which the module auto-imports, returns a computed that
is `true` while the vendor may run: it is declared, its category is allowed
and the visitor has not switched it off.

```vue title="app/components/x-pixel-status.vue (partial)"
<script setup lang="ts">
const xPixelAllowed = useVendorAllowed('x-pixel');
</script>
```

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/nuxt/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a Nuxt app when that category is denied, with the clearOnRevocation option of the c15t Nuxt module.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns under the `c15t` key
in `nuxt.config.ts`. When that category is denied, c15t deletes them:

```ts title="nuxt.config.ts (partial)"
export default defineNuxtConfig({
	c15t: {
		clearOnRevocation: {
			measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
			marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
		},
	},
});
```

`clearOnRevocation` is plain data, so it can go in `nuxt.config.ts` or in the
`c15t` key of `app/app.config.ts`. The module reads it once, in the browser,
after hydration.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/nuxt/customize
Change the c15t banner and dialog in Nuxt with theme tokens, layout presentation, component slots and copy.

## Pick the right option

|You want to change|Use|
|--|--|
|Colors, fonts, radius, spacing or motion|`tokens`|
|Banner shape, position, button order or blocking|`presentation`|
|Classes or attributes on one part of a component|`components`|
|Light or dark colors|`colorScheme` and `theme.dark`|
|The text|Your Inth project's translations|
|The markup|[Headless](/docs/frameworks/nuxt/headless)|

The [customization overview](/docs/customization/overview) explains these
choices across frameworks. Add the options below to the `c15t` key in
`nuxt.config.ts`. They are plain data, so they are safe in module options.

See the [design gallery](/docs/customization/recipes) for five banner designs
with tested code. Nuxt uses the Vue components and composables it shows.
`examples/showcase-nuxt-theme` in the c15t repository puts `theme`,
`colorScheme`, `presentation`, `components` and legal links together in one
Nuxt app.

## Set theme tokens

`tokens` sets c15t's CSS variables. Keys are the variable names without the
leading `--`.

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: {
		tokens: {
			'c15t-primary': '#6943a3',
			'c15t-primary-hover': '#533285',
			'c15t-radius-lg': '18px',
			'c15t-text-on-primary': '#ffffff',
		},
	},
});
```

The Nuxt module's plugin writes the tokens, including the defaults you did
not set, into a `<style id="c15t-css-vars">` tag in the page head on every
page, whether or not `ConsentRoot` renders. During server rendering and
prerendering the tag is in the first HTML, so the banner already has your
colors. Cached routes keep the tag, because tokens are the same for every
visitor. With `ssr: false`, the plugin adds the same tag in the browser. The
tag carries the module's `nonce` when you set one. Set tokens through this option rather than
a `:root` rule in your own CSS, which can lose to that tag depending on
stylesheet order. [Theme tokens](/docs/customization/tokens) lists every token.

## Change the banner layout

`presentation.prompt` sets the banner's `variant`, `position`, `layout`,
`primaryActions`, `direction`, `uiProfile` and `blocking`.
`presentation.preferences` sets the same layout fields for the dialog.

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: { presentation: { prompt: { position: 'bottom', variant: 'bar' } } },
});
```

`variant` is `'floating'`, `'bar'`, `'widget'` or `'wall'`, and each accepts
its own positions. `bar` takes `top` or `bottom`, `wall` takes `center`,
`widget` takes the four corners, and `floating` takes the corners plus
`top-center` and `bottom-center`. The policy still has
the last word. A choice wall always blocks, a notice never blocks, and the
policy can restore a required button you left out of `layout`.

## Style one part of a component

`components` adds attributes to named parts, such as a class on the banner
card. The keys match the [component parts](/docs/customization/slots).

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: {
		components: {
			banner: { card: { class: 'brand-consent-card' } },
			trigger: { root: { 'aria-label': 'Cookie settings' } },
		},
	},
});
```

Vue binds these objects with `v-bind`, so use Vue attribute names such as
`class` and `style`. React's `className` does not apply. The `ConsentGate`
placeholder's parts are `components['consent-gate'].root`, `.title` and
`.button`.

With Tailwind CSS, put part classes in `app/app.config.ts` under the same
`c15t` key rather than in `nuxt.config.ts`, because Tailwind scans `app/`. The
module merges both. [Tailwind CSS](/docs/customization/tailwind) shows the
Nuxt setup for Tailwind 4 and 3, and
[class names and CSS-in-JS](/docs/customization/class-names) covers other
class sources.

## Turn on dark mode

`colorScheme` in the `c15t` key in `nuxt.config.ts` decides when the banner and dialog turn dark:
`'light'`, `'dark'`, `'system'`, or unset to copy a `dark` class on `<html>`.
The module ships c15t's stock dark palette, so a `dark` class alone turns the
banner dark. `theme` takes the same token
object as the other frameworks, including `theme.dark`, and wins over `tokens`
where both set a variable. For `'dark'` and `'system'`, the module adds an
inline script to `<head>` that sets the class before the banner paints.
`colorScheme: null` leaves `c15t-dark` to your site when you set it under the
`c15t` key or in `app/app.config.ts`. Nuxt drops a `null` in inline module
options before the module reads it.
[Dark mode](/docs/customization/dark-mode) covers each value and a dark first
paint.

## Change the copy

The banner and dialog text come from the translations of your Inth project,
resolved for the visitor's language. Edit them there. `legalLinks` adds links
to your privacy policy and similar pages:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: {
		bannerLegalLinks: ['privacyPolicy'],
		legalLinks: { privacyPolicy: { href: '/privacy' } },
	},
});
```

[Translations](/docs/frameworks/nuxt/translations) covers the visitor's
language, and [copy and translations](/docs/customization/translations) covers
message keys and writing labels.

## Other display options

|Option|What it does|
|--|--|
|`showTrigger`|Renders the floating [`ConsentDialogTrigger`](/docs/frameworks/nuxt/components/consent-dialog-trigger) from `ConsentRoot`.|
|`triggerDefaultPosition`, `triggerSize`, `triggerIcon`, `triggerShowWhen`|Place and style that trigger.|
|`hideBranding`, `bannerHideBranding`, `dialogHideBranding`|Hide the "Secured by" tag.|
|`disableAnimation`|Turns off banner and dialog animations. See [motion and animation](/docs/customization/motion).|
|`consentCategories`|Limits the categories the dialog shows, within the policy's scope.|

## Check the result

Run `nuxt dev` and clear the `c15t` cookie and localStorage entry, or use a
private window, so the banner shows. View the page source to confirm the
`c15t-css-vars` style tag holds your tokens.

# Translations
URL: https://c15t.com/docs/frameworks/nuxt/translations
Where the c15t banner and dialog text comes from in Nuxt, how the server picks the visitor's language, and how to switch it at runtime.

## Where the text comes from

The banner, dialog and IAB text comes from the translations in your Inth
project, or your self-hosted backend's configuration. The policy carries the
text for the visitor's language. Edit copy there, not in your Nuxt code. The
module has no option for message overrides.

[Copy and translations](/docs/customization/translations) lists the message
keys and how to write labels that describe each action.

## How c15t picks the language

The request's `Accept-Language` header decides:

* In the default `manifest()` mode, the Nuxt server reads the header during
  server rendering and resolves the text from the bundled or cached
  manifest. The banner is in the visitor's language in the first HTML, and
  the browser bundle carries no translations.
* With `hosted()`, the server forwards the header to the backend's `/init`.
* With `manifest({ resolve: 'browser' })`, the browser reads
  `navigator.language` and resolves the text from the bundled manifest. The
  bundle carries English base copy; another language's base copy loads from
  your site the first time a visitor resolves to it.

On prerendered and cached routes the browser requests `/api/c15t/init` after
hydration, and that request carries the browser's own header. When your
project has no text for the language, the backend picks its fallback
language.

The text direction follows the resolved language. Right-to-left languages
render the banner and dialog with `dir="rtl"`, and a default corner position
mirrors.

## Follow your site's language

Bind the `language` prop of the Nuxt `ConsentRoot` to your site's current
language, for example from `@nuxtjs/i18n`. When the prop changes,
`ConsentRoot` stores the language and resolves the policy again, which
fetches the text in that language:

```vue
<ConsentRoot :language="locale" />
```

From your own language switcher, assign the language to
`useConsentLanguage()`. A new language runs init again. Assigning the current
language does nothing:

```vue title="app/components/LanguageSwitcher.vue"
<script setup lang="ts">
const language = useConsentLanguage();
const kernel = useConsentKernel();

// Resolving again with `init()` loads the banner and dialog text in the
// new language.
const switchTo = (code: string) => {
	language.value = code;
	void kernel.commands.init();
};
</script>

<template>
	<button type="button" @click="switchTo('en')">English</button>
	<button type="button" @click="switchTo('de')">Deutsch</button>
</template>
```

The assignment alone loads the new text. The example's extra
`kernel.commands.init()` call repeats the request and is not needed.

## Text that does not come from translations

`ConsentDialogLink` and the `ConsentGate` placeholder read their default
text from the translations, in English until init has delivered copy. One
label is a module option instead. Set it in the visitor's language when your
site has more than one:

|Text|Where|How to change it|
|--|--|--|
|"Open privacy settings"|`ConsentDialogTrigger` label|Set the `triggerAriaLabel` option.|

## Verify

Request a page with `curl -H 'Accept-Language: de' <your-url>` under a policy
that asks for consent, and confirm the banner text in the HTML is German, if
your project translates German. Switch the language in the browser with your
switcher and confirm the banner and dialog text change without a reload.

# Headless
URL: https://c15t.com/docs/frameworks/nuxt/headless
Build your own consent banner and preference form in Nuxt with the auto-imported c15t composables instead of ConsentRoot.

## When to go headless

Tokens, `presentation` and `components` slots change most designs without
new markup. See [customize](/docs/frameworks/nuxt/customize) first. Go
headless when the consent UI has to be your own markup, such as a design
system component.

Headless changes only the UI. The Nuxt module still resolves the policy,
stores choices, loads scripts from `app.config.ts` and gates iframes.

## Write the consent UI

This component shows a banner while `activeUI` is `'banner'` and a preference
form while it is `'manager'`. The module auto-imports the composables.

```vue title="app/components/ConsentPrompt.vue"
<script setup lang="ts">
const activeUI = useConsentActiveUI();
const saveConsent = useConsentSave();
const { displayedCategories, save: saveDraft, values } = useConsentDraft();

// Recording a choice satisfies the prompt, so c15t closes the banner itself.
const choose = (choice: 'all' | 'none') => {
	void saveConsent(choice);
};

// Preferences stay open until you close them. c15t records the draft
// locally before the network request, so closing right away is safe.
const savePreferences = () => {
	void saveDraft();
	activeUI.value = null;
};
</script>

<template>
	<section
		v-if="activeUI === 'banner'"
		class="consent-prompt"
		aria-label="Cookie consent"
	>
		<p>We use cookies for measurement and marketing.</p>
		<button type="button" @click="choose('none')">Reject all</button>
		<button type="button" @click="choose('all')">Accept all</button>
		<button type="button" @click="activeUI = 'manager'">Customize</button>
	</section>
	<section
		v-else-if="activeUI === 'manager'"
		class="consent-prompt"
		aria-label="Privacy settings"
	>
		<label v-for="category in displayedCategories" :key="category">
			<input
				v-model="values[category]"
				type="checkbox"
				:disabled="category === 'necessary'"
			/>
			{{ category }}
		</label>
		<button type="button" @click="savePreferences">Save</button>
	</section>
</template>
```

`useConsentSave()` records Accept all or Reject all. Recording a choice
satisfies the prompt, so c15t sets `activeUI` to `null` and the banner closes.
`useConsentDraft()` holds the preference form. `displayedCategories` lists the
categories the policy lets the visitor choose, `values` holds each switch, and
`save()` records them. Preferences stay open after a save, so close them
yourself. [Composables](/docs/frameworks/nuxt/composables#build-a-preference-form)
lists every field of the draft.

Add focus handling, a close control and styles before you ship this. The
component keeps the bare markup so the consent logic is easy to read.

## Mount it instead of ConsentRoot

Replace `<ConsentRoot />` in `app.vue` with your component. Keep one way to
reopen preferences, such as `ConsentDialogLink`.

```vue title="app/app.vue"
<template>
	<ConsentPrompt />
	<NuxtPage />
	<footer>
		<ConsentDialogLink />
	</footer>
</template>
```

When the server resolves the policy, in the default `manifest()` mode or `hosted()`, the component
renders on the server with the visitor's policy, like `ConsentRoot`.

## Show the buttons the policy requires

A policy can require buttons and forbid others. For a notice, it requires a
dismiss action instead of Accept and Reject. Read the resolved actions with
`useConsentPolicyActions('prompt')` and render `primaryActions` and
`actionGroups` from it, rather than hard-coding the buttons. Call
`useDismissNotice()` for a notice's dismiss action. Dismissing records an
acknowledgement, not consent.

`usePromptRequirement()` tells you whether the policy asks for a choice, a
notice or nothing.

## Verify the custom UI

Run through [verify consent](/docs/guides/verify-consent) with your
component. Check that Reject all is as easy to reach as Accept all, that the
preference form lists the policy's categories, and that a rejection survives a
reload.

# Components
URL: https://c15t.com/docs/frameworks/nuxt/components
Every c15t component in Nuxt, which ones the Nuxt module registers globally, which you import, and a page for each one's props and behavior.

## Component reference

Every component reads the consent runtime the Nuxt module creates, and each
imports its own styles. The module registers the components marked Global, so
you use them in templates without an import. Import the others by path.

|Component|In Nuxt|What it renders|
|--|--|--|
|[`ConsentRoot`](/docs/frameworks/nuxt/components/consent-root)|Global|The banner, rendered on the server, and the preference dialog once opened. Switches to the IAB surfaces under an IAB policy when `iab` is set.|
|[`ConsentWidget`](/docs/frameworks/nuxt/components/consent-widget)|Global|Category switches and save actions inline, for a privacy page.|
|[`ConsentDialogLink`](/docs/frameworks/nuxt/components/consent-dialog-link)|Global|A button that opens preferences.|
|[`ConsentDialogTrigger`](/docs/frameworks/nuxt/components/consent-dialog-trigger)|Global|A floating, draggable button that opens preferences.|
|[`ConsentGate`](/docs/frameworks/nuxt/components/consent-gate)|Global|Its default slot while a category is allowed, otherwise its `placeholder` slot.|
|[`ConsentBanner`](/docs/frameworks/nuxt/components/consent-banner)|`c15t/vue/runtime/components/consent-banner.vue`|The first-layer banner on its own.|
|[`ConsentManager`](/docs/frameworks/nuxt/components/consent-manager)|`c15t/vue/runtime/components/consent-manager.vue`|The preference dialog on its own.|
|[`IABConsentBanner`](/docs/frameworks/nuxt/components/iab-consent-banner)|`c15t/vue/runtime/components/iab-consent-banner.vue`|The IAB TCF first layer.|
|[`IABConsentDialog`](/docs/frameworks/nuxt/components/iab-consent-dialog)|`c15t/vue/runtime/components/iab-consent-dialog.vue`|The IAB TCF preference centre.|
|[`ConsentDevTools`](/docs/frameworks/nuxt/components/dev-tools)|`c15t/vue/devtools`|A development panel for the consent runtime.|

Import the path components inside a Nuxt component's `<script setup>`:

```ts
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
```

## ConsentRoot or the parts

`ConsentRoot` renders `ConsentBanner` and `ConsentManager`, or the IAB
components when `iab` is set, for the visitor's policy. Mount `ConsentRoot`, or mount the parts,
never both, or the visitor sees two banners. Always use the global
`ConsentRoot` in Nuxt, not the one `c15t/vue/vue-plugin` exports. The global
one renders the banner on the server. The module writes theme tokens into the page head
whether you mount `ConsentRoot` or the parts.

## Use the components in Vue Vapor

Nuxt 4.6 and later can compile your components with Vue Vapor. Vapor needs
Vue 3.6, which is a release candidate, so install `vue` 3.6 alongside Nuxt and
turn on `vue.vapor`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: { backendURL: 'https://your-project.inth.app' },
	modules: ['c15t/vue'],
	// Vapor needs Vue 3.6. Opt components in with `<script setup vapor>`.
	vue: { vapor: true },
});
```

Mark a page or component with `<script setup vapor>` to compile it with Vapor.
c15t's components stay on the virtual DOM, and Nuxt renders them inside Vapor
components through its interop layer. Mount `ConsentRoot` in a Vapor
`app.vue`, pass slots to `ConsentGate` or `ConsentDialogLink`, and call
the composables in a Vapor `<script setup>`, as you would elsewhere:

```vue title="app/components/VideoEmbed.vue"
<!-- A Vapor component passing both slots to ConsentGate. -->
<script setup vapor lang="ts"></script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

Vapor does not make the banner or the preference dialog faster, because they
still render with the virtual DOM. The interop layer ships the Vapor runtime
next to the virtual DOM one, so expect more JavaScript, not less: the
`/consent-example` page of `internals/fixtures/nuxt-vapor` downloads about 18%
more JavaScript than the same app without Vapor.

## Building blocks

The stock surfaces are built from smaller components that the package also
exports under `c15t/vue/runtime/components/`: `consent-button.vue`,
`consent-switch.vue`, `consent-actions.vue`, `consent-link.vue`,
`consent-legal-links.vue`, `consent-description.vue`, `consent-tag.vue` and
`consent-branding-icon.vue`. For consent UI in your own markup, use the
[headless composables](/docs/frameworks/nuxt/headless) instead. They give you
the policy's actions and the draft state without the stock markup.

# ConsentRoot
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-root
Mount the c15t banner, preference dialog and floating trigger in Nuxt with the globally registered ConsentRoot, rendered on the server.

## Render `ConsentRoot` in `app.vue`

The Nuxt module registers `ConsentRoot` globally, so you render it without an
import. Put it in `app.vue`, next to `<NuxtPage />`:

```vue title="app/app.vue"
<template>
	<ConsentRoot />
	<NuxtPage />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

`ConsentRoot` reads the consent runtime the module creates. Keep it in
`app.vue` so it stays mounted when the route changes. It brings its own
styles.

`ConsentRoot` is not a provider. The module's plugin already gives every
component the consent runtime, so nothing needs to sit inside it. Render
`<ConsentRoot />` next to `<NuxtPage />` as shown above. If you wrap the app
in it instead, the page still renders after the banner, dialog and trigger,
but wrapping adds nothing.

Always mount the Nuxt `ConsentRoot`, not the Vue one from
`c15t/vue/vue-plugin`. The Nuxt component renders the banner on the
server.

## What ConsentRoot renders

`ConsentRoot` picks the surfaces for the visitor's policy:

|Policy|Banner|Preferences|
|--|--|--|
|Standard, opt-in or opt-out|[`ConsentBanner`](/docs/frameworks/nuxt/components/consent-banner)|[`ConsentManager`](/docs/frameworks/nuxt/components/consent-manager)|
|IAB TCF, with a vendor list|[`IABConsentBanner`](/docs/frameworks/nuxt/components/iab-consent-banner)|[`IABConsentDialog`](/docs/frameworks/nuxt/components/iab-consent-dialog)|

It also renders [`ConsentDialogTrigger`](/docs/frameworks/nuxt/components/consent-dialog-trigger)
when the `showTrigger` option is `true`.

The banner is part of the server render. When the server resolves the policy, in the default `manifest()` mode or `hosted()`,
a visitor whose policy asks for consent gets the banner
in the first HTML, with no layout shift after hydration. On prerendered and
cached routes the banner appears after the browser resolves the policy. See
[rendering](/docs/frameworks/nuxt/rendering).

The IAB surfaces replace the standard ones only when the module's `iab`
option is set and the policy uses the `iab` model. The dialog and the IAB
surfaces load as separate chunks. `ConsentRoot`
prefetches the dialog chunk after the page's `load` event, mounts the dialog
the first time preferences open, and keeps it mounted after that so its close
animation runs.

The banner and the trigger are separate chunks too, so their CSS is not part
of your app's entry stylesheets. Every page preloads the banner chunk. With
Nuxt's `features.inlineStyles`, on by default, it also preloads the banner's
CSS instead of linking it: a server-rendered banner paints with the styles
Nuxt writes into the page head, so no c15t stylesheet blocks the first paint.
The browser applies the CSS with the chunk, before it shows a banner it
renders itself. The trigger chunk loads after the page mounts, and only when
`showTrigger` is `true`.

## Theme tokens

The Nuxt module's plugin, not `ConsentRoot`, writes the `tokens` option
into a `<style id="c15t-css-vars">` tag in the page head, on every page and
with the module's `nonce`. During server rendering and prerendering the tag is
in the first HTML. See
[customize](/docs/frameworks/nuxt/customize#set-theme-tokens).

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`country`|`string`|The location from the request headers|Overrides the visitor's country and resolves the policy again.|
|`region`|`string`|The location from the request headers|Overrides the visitor's region, such as `CA`, and resolves the policy again.|
|`language`|`string`|The browser language|Overrides the language and resolves the policy again, which fetches the banner and dialog text in that language.|

Use `country` and `region` to preview another region's policy while you
build, such as `<ConsentRoot country="DE" />`. Bind `language` to your site's
current language. See [translations](/docs/frameworks/nuxt/translations).

## Compose the surfaces yourself

`ConsentRoot` is the same as rendering the banner, dialog and trigger with the
right conditions. To place them yourself, render them in place of
`ConsentRoot`, as in
[ConsentBanner](/docs/frameworks/nuxt/components/consent-banner#import-the-banner-in-place-of-consentroot). Do not
render `ConsentRoot` next to them, or the visitor sees two banners.

## Verify

Build and start the app, then view the source of a page under a policy that
asks for consent. The HTML holds `data-testid="consent-banner-root"` and the
`c15t-css-vars` style tag. Click Customize and the preference dialog opens.
Reject, reload, and confirm the banner stays closed.

## Next steps

* [Nuxt module](/docs/frameworks/nuxt/module) lists the options `ConsentRoot`
  reads.
* [Customize](/docs/frameworks/nuxt/customize) changes tokens, layout and
  slots.
* [Headless](/docs/frameworks/nuxt/headless) replaces `ConsentRoot` with your
  own markup.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-banner
Render the c15t consent banner in Nuxt, choose its variant and position, and understand what it shows for each policy.

## Import the banner in place of `ConsentRoot`

`ConsentRoot` already renders `ConsentBanner`. Import the banner yourself
only when you compose the surfaces, for example to set its variant in the
template. The Nuxt module does not register `ConsentBanner` globally, so
import it from `c15t/vue/runtime/components/consent-banner.vue`:

```vue title="app/components/ConsentSurfaces.vue"
<script setup lang="ts">
// The module registers ConsentDialogTrigger globally. It does not register
// the banner or the dialog, so import them.
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
import ConsentManager from 'c15t/vue/runtime/components/consent-manager.vue';
</script>

<template>
	<!-- Render these in app.vue in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

Render this component in `app.vue` in place of `ConsentRoot`. Render
`ConsentManager` with it, or Customize opens nothing. A statically imported
`ConsentManager` is part of your main bundle, while `ConsentRoot` loads the
dialog as a separate chunk. Unlike `ConsentRoot`, these components do not
switch to the IAB surfaces under an IAB policy. The module still writes the
`tokens` option to the page head.

## What ConsentBanner renders

`ConsentBanner` renders the first-layer banner while `activeUI` is
`'banner'`. It renders nothing until the visitor's policy has resolved,
when the policy asks for no prompt, and when a `bannerModels` or `models`
option leaves out the policy's model.

The policy decides the buttons:

* A `choice` prompt shows Reject All, Accept All and Customize. Customize is
  the primary button by default, so Accept All and Reject All look the same.
* A `notice` prompt shows an OK button. When the policy grants an opt-out or
  preferences right, the banner adds a button styled as underlined text,
  labelled "Do not sell or share my data" or "Manage preferences", that
  opens preferences.
* A policy with prompt `none` shows no banner.

Each button runs one command. Accept All and Reject All record a choice for
every category the policy covers, and the banner closes. Customize sets
`activeUI` to `'manager'`, which opens `ConsentManager` if it is mounted.
OK records that the visitor dismissed the notice. Dismissing grants nothing
and leaves earlier refusals in place.

The text comes from the translations the backend resolved for the visitor:
`cookieBanner.title` and `cookieBanner.description` for a choice,
`cookieBanner.noticeTitle` and `cookieBanner.noticeDescription` for a
notice, and `common.acceptAll`, `common.rejectAll`, `common.customize` and
`common.acknowledge` for the buttons. `bannerLegalLinks` picks which of your
`legalLinks` appear under the description. The banner has no slots and no
text props.

`ConsentBanner` moves itself into `document.body` once it has mounted.
During server rendering it renders in place, so the banner can be part of
the server HTML.

## Variants and positions

The policy decides which actions the banner offers. The variant decides the
shape they take.

|Variant|Shape|Positions|Default position|
|--|--|--|--|
|`floating`|A card in a corner or centred on an edge. The default.|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|A full-width bar along the top or bottom edge.|`top`, `bottom`|`bottom`|
|`widget`|A compact card with smaller type.|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|A centred card over a backdrop that blocks the page.|`center`|`center`|

The policy has the last word. A choice `wall` always blocks. A notice never
blocks, and a notice `wall` falls back to `floating`. A position the variant
does not accept falls back to the variant's default. Each correction logs a
`[c15t]` warning in the browser console.

A default corner mirrors left and right for right-to-left languages. A
position you set is kept as written.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating' \|'bar' \|'widget' \|'wall'`|`presentation.prompt.variant`, else `'floating'`|Shape of the banner.|
|`position`|`PromptPosition`|`presentation.prompt.position`, else the variant's default|Where the banner sits. Must be valid for the variant.|
|`blocking`|`boolean`|`presentation.prompt.blocking`, else `true` for `wall` only|Backdrop, scroll lock and focus trap, as one value.|

A prop you set beats the matching `presentation.prompt` option. Leave a prop
unset to follow your c15t options. `PromptVariant` and `PromptPosition` are
exported as types from `c15t`.

To set the variant for every banner without importing the component, use
`presentation.prompt` in the module options. See
[customize](/docs/frameworks/nuxt/customize#change-the-banner-layout).

## Accessibility and focus

* A non-blocking banner is a `region` labelled with the banner title. It does
  not trap focus or lock scrolling, so the page stays usable with a keyboard
  and a pointer.
* A blocking banner is a `dialog` with `aria-modal="true"`. It shows a
  backdrop, locks page scrolling, moves focus to the banner card and keeps
  Tab inside the card.
* The banner has no close button, and Escape does not dismiss it. The
  visitor answers with one of its buttons.
* Every action is a native `button`. The banner sets `dir` from the resolved
  language.

## Style the banner

[Theme tokens](/docs/customization/tokens) change colors, type, radius,
spacing and motion. The `components.banner` option adds attributes, such as
`class` or `style`, to these parts: `root`, `overlay`, `cardShell`, `card`,
`header`, `title`, `footer`, `actions`, `actionGroup`, `rights` and
`rightLink`. `components.description.banner` and `components.tag.banner`
reach the description and the branding tag.
[Component slots](/docs/customization/slots) lists every part.

The root element carries attributes you can target from CSS:

|Attribute|Values|
|--|--|
|`data-variant`|`floating`, `bar`, `widget`, `wall`|
|`data-position`|The resolved position|
|`data-prompt`|`choice`, `notice`|
|`data-model`|`opt-in`, `opt-out`, `iab`|
|`data-blocking`|`true`, present only while blocking|

`bannerHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the enter and exit
transitions.

## Verify

Open the page in a private window under a policy that asks for a choice.
The banner appears with Reject All and Accept All side by side. Tab through
it and confirm every button is reachable. Click Customize and the preference
dialog opens. Reject, reload, and confirm the banner stays closed. In the
Elements panel, the root element carries the `data-variant` and
`data-position` you set.

## Next steps

* [ConsentManager](/docs/frameworks/nuxt/components/consent-manager) is the
  dialog Customize opens.
* [Headless](/docs/frameworks/nuxt/headless) builds a banner from your own
  markup.
* [Banner designs](/docs/customization/recipes) shows tested designs.

# ConsentManager
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-manager
Render the c15t preference dialog in Nuxt, open it from your own code, and understand its actions, focus handling and styling.

## Import the dialog when you compose surfaces

`ConsentRoot` already renders `ConsentManager` when preferences open. Import
it yourself only when you compose the surfaces in place of `ConsentRoot`. The
module does not register it globally, so import it from
`c15t/vue/runtime/components/consent-manager.vue`:

```vue title="app/components/ConsentSurfaces.vue"
<script setup lang="ts">
// The module registers ConsentDialogTrigger globally. It does not register
// the banner or the dialog, so import them.
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
import ConsentManager from 'c15t/vue/runtime/components/consent-manager.vue';
</script>

<template>
	<!-- Render these in app.vue in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

## Open the dialog from your code

Set `activeUI` to `'manager'` with the auto-imported `useConsentActiveUI()`.
The Vue components use `'manager'` where the React adapter uses `'dialog'`.

```ts
const activeUI = useConsentActiveUI();
activeUI.value = 'manager';
```

For a footer link, use
[ConsentDialogLink](/docs/frameworks/nuxt/components/consent-dialog-link),
which hides itself when the policy offers no preferences.

## What ConsentManager renders

`ConsentManager` is the preference dialog, the component the React adapter
calls `ConsentDialog`. It opens while `activeUI` is `'manager'`. Anything
that sets `activeUI` to `'manager'` opens it: the banner's Customize button,
`ConsentDialogLink`, `ConsentDialogTrigger` and your own code. It
renders nothing until the visitor's policy has resolved, and nothing when
the policy owes no consent UI.

The dialog holds the same content as `ConsentWidget`: a list of the
categories the policy lets the visitor choose, each with a switch and a
description, and the vendors you declared under each category. Necessary is
always on. The footer shows Reject All, Accept All and Save Settings, with Save Settings as the
primary button.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* After a successful action the dialog closes. The banner comes back only if
  the policy still requires a choice.
* Escape closes the dialog without saving. The banner comes back if the
  policy still requires a choice.
* If the policy changes while the dialog is open, the dialog shows "Privacy
  choices have changed." with a button that reloads the switches from the
  new policy. Save stays blocked until the visitor reviews them.

The title comes from `consentManagerDialog.title` in the resolved
translations. `dialogLegalLinks` picks which of your `legalLinks` appear
under the description. The dialog has no props, slots or text props.

## Accessibility and focus

The dialog renders in `document.body` with `role="dialog"`, labelled by its
title and described by its description. By default it is modal: it shows a
backdrop, sets `aria-modal="true"`, locks page scrolling, moves focus to the
first control inside and keeps Tab inside the dialog. When it closes, focus
returns to the element that had it before. Set
`presentation.preferences.blocking` to `false` for a non-modal dialog with
no backdrop.

Each category switch is a `button` with `role="switch"`, `aria-checked` and
the category title as its label. Each category row expands with a button
that sets `aria-expanded` and `aria-controls`.

## Style the dialog

The `components.dialog` option adds attributes to `root`, `overlay`,
`container`, `card`, `header`, `title` and `content`. The category list
inside uses `components.manager`, `components.accordion`,
`components['accordion-item']`, `components.switch` and
`components['vendor-list']`. [Component slots](/docs/customization/slots)
lists every part. `presentation.preferences` sets the footer's `layout`,
`primaryActions`, `direction`, `uiProfile` and `blocking`.

`dialogHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the transitions.

## Verify

Open preferences, turn one optional category on and click Save. The dialog
closes. Reload and open preferences again: the switch is still on. Press
Escape with the dialog open and confirm it closes and focus returns to the
control that opened it.

## Next steps

* [ConsentWidget](/docs/frameworks/nuxt/components/consent-widget) renders the
  same controls inline on a page.
* [IABConsentDialog](/docs/frameworks/nuxt/components/iab-consent-dialog)
  replaces this dialog under an IAB policy when `iab` is set.
* [Customize](/docs/frameworks/nuxt/customize) sets tokens and slots.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-widget
Put the c15t category switches and save actions inline on a Nuxt privacy settings page with the globally registered ConsentWidget.

## Add the widget to your privacy page

The Nuxt module registers `ConsentWidget` globally. Render it on your privacy
or account settings page without an import:

```vue title="app/pages/privacy.vue"
<template>
	<main>
		<h1>Privacy settings</h1>
		<p>Choose which optional cookies this site may use.</p>
		<ConsentWidget />
	</main>
</template>
```

Keep `ConsentRoot` in `app.vue` too, so visitors on other pages still get the
banner. When the server resolves the policy, in the default `manifest()` mode or `hosted()`, the
widget renders on the server with the visitor's recorded choice already applied to the
switches.

## What ConsentWidget renders

`ConsentWidget` renders the preference controls inline, in the page flow,
for a privacy or account settings page. It shows the categories the policy
lets the visitor choose, each with a switch that expands to its description
and declared vendors, and a footer with Reject All, Accept All and Save Settings.
Necessary is always on and its switch is disabled.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* The switches start from the visitor's recorded choice. Before any choice,
  they start from the policy's defaults: on under an opt-out policy or for
  preselected categories, otherwise off.
* A choice saved elsewhere, such as in the banner, updates switches the
  visitor has not touched and keeps the ones they moved.
* If the policy changes, the widget shows "Privacy choices have changed."
  with a button that reloads the switches. Save stays blocked until then.

The widget renders nothing until the visitor's policy has resolved, and
nothing when the policy owes no consent UI. It does not open or close any
other surface. `ConsentManager` renders the same widget inside the dialog.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Hides the "Secured by" tag.|
|`noStyle`|`boolean`|`false`|Drops the built-in classes from every part, so your own CSS starts from plain markup.|
|`language`|`string`|The resolved language|Sets the text direction. It does not change the text.|

## Accessibility

Each switch is a `button` with `role="switch"`, `aria-checked` and the
category title as its label. Each row expands with a button that sets
`aria-expanded` and `aria-controls`, and one row is open at a time. The
footer actions are native buttons. Give the page a heading that names the
widget, as in the example above.

## Style the widget

The widget reads `components.manager` for its root and footer,
`components.accordion` and `components['accordion-item']` for the rows,
`components.switch` for the switches and `components['vendor-list']` for
vendor rows. [Component slots](/docs/customization/slots) lists every part.
`presentation.preferences` sets the footer's `layout`, `primaryActions`,
`direction` and `uiProfile`, and applies to the dialog too.

## Verify

Open the page with the widget in a private window. Turn **Analytics** (the `measurement` category) on and
click Save. Reload: the switch is still on, and scripts gated on
measurement load. Turn it off and save, and the page reloads without them.

## Next steps

* [ConsentManager](/docs/frameworks/nuxt/components/consent-manager) shows
  these controls in a dialog.
* [Composables](/docs/frameworks/nuxt/composables#build-a-preference-form)
  build a preference form from your own markup.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-dialog-link
Add a Privacy settings button that reopens the c15t preference dialog in Nuxt, and hide it when the policy offers no preferences.

## Add the link to your footer

The Nuxt module registers `ConsentDialogLink` globally. Put it in your
footer without an import:

```vue title="app/app.vue"
<template>
	<ConsentRoot />
	<NuxtPage />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

Pass content in the default slot to change the label. The
[embed example](/docs/frameworks/nuxt/embeds) uses it inside a placeholder as
"Choose video permissions".

## What ConsentDialogLink renders

`ConsentDialogLink` renders one `button` that sets `activeUI` to
`'manager'`, which opens the preference dialog. It matches `ConsentDialogLink`
in the React adapter. It has no props. The default label is the
`consentManagerDialog.title` translation, "Privacy Settings" in English.
The link shows it in the visitor's language once init has delivered copy,
and in English until then. Its default slot replaces the label.

The button renders only while the visitor has somewhere to go:

* It is absent until the visitor's policy has resolved.
* It is absent when the policy owes no consent UI, such as a policy with no
  prompt and no rights.

The link opens the dialog only if something renders `ConsentManager`.
`ConsentRoot` does.

## Accessibility and styling

The component is a native `button` with `type="button"`, so it works with
Enter and Space and has no link semantics. Style it with your own classes on
the element: attributes you pass, such as `class`, go to the button. It
carries `data-testid="consent-dialog-link"` and `data-c15t-rights`, the
policy's rights separated by spaces.

## Verify

Load the page under a policy that asks for consent and click Privacy
Settings. The preference dialog opens. Under a policy with no prompt and no
rights, the button is absent from the DOM.

## Next steps

* [ConsentDialogTrigger](/docs/frameworks/nuxt/components/consent-dialog-trigger)
  is a floating alternative.
* [Composables](/docs/frameworks/nuxt/composables#open-the-banner-or-preferences)
  open preferences from your own button.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-dialog-trigger
Show a floating, draggable button that reopens the c15t preference dialog in Nuxt, and configure its corner, size, icon and label.

## Turn on the trigger in `nuxt.config.ts`

Turn the trigger on with `showTrigger` in the module options. `ConsentRoot`
then renders it. The trigger options are plain data, so they can go in
`nuxt.config.ts`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: { showTrigger: true, triggerDefaultPosition: 'bottom-left' },
});
```

The module also registers `ConsentDialogTrigger` globally. When you compose
the surfaces without `ConsentRoot`, render it yourself:

```vue title="app/components/ConsentSurfaces.vue"
<script setup lang="ts">
// The module registers ConsentDialogTrigger globally. It does not register
// the banner or the dialog, so import them.
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
import ConsentManager from 'c15t/vue/runtime/components/consent-manager.vue';
</script>

<template>
	<!-- Render these in app.vue in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

## What ConsentDialogTrigger renders

`ConsentDialogTrigger` renders a round floating button, fixed to a corner of
the viewport, that opens the preference dialog. Visitors can drag it to
another spot. It has no props. Your c15t options configure it.

The trigger renders in the browser only, after mount, in `document.body`. It
hides while the preference dialog is open, until the visitor's policy has
resolved, and when the policy owes no consent UI. Under the default
`triggerShowWhen: 'after-consent'`, it also stays hidden while the banner
waits for an answer, and appears once the visitor saves a choice or
dismisses a notice.

While `ConsentDevTools` is mounted, the trigger becomes a two-button
toolbar: the preferences button in the corner and a DevTools button beside
it that opens the DevTools panel next to the toolbar.

## Options

|Option|Type|Default|Behavior|
|--|--|--|--|
|`showTrigger`|`boolean`|`false`|Makes `ConsentRoot` render the trigger.|
|`triggerDefaultPosition`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Starting corner.|
|`triggerSize`|`'sm' \|'md' \|'lg'`|`'md'`|32, 40 or 48 pixels.|
|`triggerIcon`|`'branding' \|'fingerprint' \|'settings'`|`'fingerprint'`|The icon inside the button. `'branding'` shows the c15t or Inth mark.|
|`triggerPersistPosition`|`boolean`|`true`|Remembers where the visitor dragged it, in localStorage under `c15t:dialog-trigger-position`.|
|`triggerShowWhen`|`'always' \|'after-consent' \|'never'`|`'after-consent'`|`'after-consent'` shows the trigger once the policy owes no prompt: the visitor saved a choice or dismissed a notice. `'always'` also shows it while the banner is open. `'never'` hides it.|
|`triggerAriaLabel`|`string`|`'Open privacy settings'`|The button's accessible name.|

All trigger options go under the `c15t` key in `nuxt.config.ts` or
`app.config.ts`.

## Accessibility and styling

The trigger is a native `button` with `aria-label` set from
`triggerAriaLabel`. The icon is hidden from assistive technology. Set
`triggerAriaLabel` in the visitor's language, because the default is
English.

The `components.trigger` option adds attributes to `root`, `icon` and
`text`. Setting `components.trigger.text`, even to `{}`, shows
`triggerAriaLabel` as visible text next to the icon. The button carries
`data-size` and, while dragged, `data-dragging`.
The toolbar shown while `ConsentDevTools` is mounted takes `toolbar`,
`toolbarItem` and `toolbarIcon` instead.

## Verify

Load a page under a policy with a prompt and answer the banner. Confirm the
button appears in the corner you set. Click it and the preference dialog opens while the
button hides. Drag it, reload, and confirm it keeps its place when
`triggerPersistPosition` is on.

## Next steps

* [ConsentDialogLink](/docs/frameworks/nuxt/components/consent-dialog-link)
  is an inline alternative for a footer.
* [Nuxt module](/docs/frameworks/nuxt/module) lists every option.

# ConsentGate
URL: https://c15t.com/docs/frameworks/nuxt/components/consent-gate
Render an iframe or widget in Nuxt only while its consent category is allowed, with the globally registered ConsentGate and a placeholder slot.

## Wrap an embed in `ConsentGate`

The Nuxt module registers `ConsentGate` globally. Put the embed in the
default slot and a placeholder in the `placeholder` slot:

```vue title="app/components/VideoEmbed.vue"
<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

The iframe is absent from the page until the visitor allows measurement. The
placeholder uses `ConsentDialogLink` so the visitor can open preferences
from it.

## What ConsentGate renders

`ConsentGate` renders its default slot while the visitor's effective
permission for `category` is granted, and its `placeholder` slot otherwise.
It adds no wrapper element. While permission is denied, the default slot
does not exist in the DOM, so an iframe or widget inside it sends no
requests. When the visitor withdraws permission, Vue removes the slot
content.

Permission is the same value `useConsent()` returns for the category. It can
be granted under an opt-out policy before the visitor has recorded a choice,
and a privacy signal such as Global Privacy Control can deny a category the
visitor granted.

Without a `placeholder` slot, the gate renders the same placeholder as the
React and Svelte gates. It shows the `consentGate.title` text with the
category name, and a button labelled with `consentGate.actionButton` that
opens the preference dialog. Under a strict policy that leaves the category
out, no choice can allow the content, so the placeholder shows
`consentGate.policyBlocked` and no button. The text is in the visitor's
language once init has delivered copy, and in English until then. The
placeholder is a card styled by your theme tokens and the
`--consent-gate-placeholder-*` variables. A `placeholder` slot replaces it
entirely.

To restyle the built-in placeholder instead, set its parts under
`components['consent-gate']` in the options. `root` is the card, and
`title` and `button` are its text and button. Use Vue attribute names such as `class` and `style`. The
`consentGate`, `consentGateTitle` and `consentGateButton` theme slots reach
the same parts. The placeholder carries
`data-testid="consent-gate-placeholder"`, its title
`data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

`ConsentGate` also adds its `category` to the categories the preference
dialog lists, so the button opens a dialog where the visitor can allow it.

## During server rendering

When the server resolves the policy, in the default `manifest()` mode or `hosted()`, the server
reads the visitor's consent cookie and evaluates the category before it renders. A
visitor who allowed the category gets the iframe in the first HTML, and a
visitor who has not gets the placeholder. On prerendered and cached routes,
and with `ssr: false`, every visitor gets the placeholder first, and the
iframe replaces it once the browser resolves the policy.

## Props and slots

|Name|Kind|Type|Behavior|
|--|--|--|--|
|`category`|Prop, required|`'necessary' \|'functionality' \|'measurement' \|'experience' \|'marketing'`|The category whose permission gates the default slot.|
|`default`|Slot||The gated content, such as an iframe.|
|`placeholder`|Slot||Shown while the category is denied.|

## Accessibility

Give the iframe a descriptive `title`. Keep a way to reach the content
without the embed, such as a link or a transcript, for visitors who decline
the category. A policy can fix a category as denied, so opening preferences
does not guarantee the visitor can allow it.

## Verify

View the page source in a private window. It holds the placeholder and no
`youtube-nocookie.com` iframe. Allow the category in preferences and save:
the iframe appears and its requests start. Reload and view the source again:
the iframe is now in the server HTML. Withdraw the category and save, and the
page reloads without the iframe.

## Next steps

* [Embeds](/docs/frameworks/nuxt/embeds) compares `ConsentGate` with the
  iframe blocker.
* [YouTube](/docs/integrations/youtube) and
  [Google Maps](/docs/integrations/google-maps) show complete embeds.

# IABConsentBanner
URL: https://c15t.com/docs/frameworks/nuxt/components/iab-consent-banner
Render the IAB TCF first layer in Nuxt with IABConsentBanner, when to import it instead of relying on ConsentRoot, and its props.

## Import the IAB banner into `app.vue`

`ConsentRoot` renders `IABConsentBanner` for you when the module's `iab`
option is set and the visitor's policy uses IAB TCF. Import it only when every policy on your site is IAB and you
compose the surfaces yourself. The module does not register it globally, so
import it from `c15t/vue/runtime/components/iab-consent-banner.vue`:

```vue title="app/components/IabSurfaces.vue"
<script setup lang="ts">
import IABConsentBanner from 'c15t/vue/runtime/components/iab-consent-banner.vue';
import IABConsentDialog from 'c15t/vue/runtime/components/iab-consent-dialog.vue';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

Render this in `app.vue` in place of `ConsentRoot`, and set the module's `iab`
option; see [IAB TCF](/docs/frameworks/nuxt/iab). A visitor whose policy is
not IAB sees nothing from these components. Without `iab`, an IAB policy
throws an `IABUnavailableError` instead.

## What IABConsentBanner renders

`IABConsentBanner` is the IAB TCF first layer. It renders while `activeUI`
is `'banner'`, the `iab` option is set, and the visitor's policy uses the
`iab` model with a vendor list. `ConsentRoot` renders it in place of
`ConsentBanner` under such a policy, so you only import it to compose the
surfaces yourself.

The banner lists the purposes, stacks and special features your vendors
use, with the vendor count as a link. Its footer has Reject All, Accept All
and Customize.

* Accept All and Reject All save an IAB choice and write the TC String. The
  banner waits for the full Global Vendor List before it saves. If the list
  fails to load, the banner stays open and nothing is granted.
* Customize opens the IAB preference centre on its Purposes tab.
* The vendor count link opens it on its Vendors tab.

Its text comes from the IAB translations the backend resolved. The component
loads its own styles.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'reject' \|'accept' \|'customize'`|`'customize'`|Which action gets the primary style.|

Keep Accept All and Reject All at the same prominence unless your legal
review says otherwise.

## Accessibility and styling

The banner renders in `document.body`. When the prompt is blocking it is a
`dialog` with `aria-modal="true"` and traps focus. Otherwise it is a
`region`. The `components['iab-banner']` option adds attributes to its
parts, such as `root`, `card`, `title`, `purposeList`, `partnersLink` and
`footer`. `iabBannerHideBranding` hides the "Secured by" tag, and
`iabBannerModels` limits which policy models show it.

## Next steps

* [IAB TCF](/docs/frameworks/nuxt/iab) covers the vendor list during server
  rendering and verification.
* [IABConsentDialog](/docs/frameworks/nuxt/components/iab-consent-dialog) is
  the preference centre this banner opens.

# IABConsentDialog
URL: https://c15t.com/docs/frameworks/nuxt/components/iab-consent-dialog
Render the IAB TCF preference centre in Nuxt with IABConsentDialog, choose its first tab, and build a custom one with composables.

## Import the IAB dialog when you compose surfaces

`ConsentRoot` loads `IABConsentDialog` for you when the module's `iab` option
is set, the visitor's policy uses IAB TCF and preferences open. Import it only when you compose the IAB
surfaces yourself. The module does not register it globally, so import it
from `c15t/vue/runtime/components/iab-consent-dialog.vue`:

```vue title="app/components/IabSurfaces.vue"
<script setup lang="ts">
import IABConsentBanner from 'c15t/vue/runtime/components/iab-consent-banner.vue';
import IABConsentDialog from 'c15t/vue/runtime/components/iab-consent-dialog.vue';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

## What IABConsentDialog renders

`IABConsentDialog` is the IAB TCF preference centre. It opens while
`activeUI` is `'manager'`, the `iab` option is set, and the policy uses the
`iab` model. `ConsentRoot` loads it in place of `ConsentManager` under such
a policy.

It has two tabs. Purposes lists each purpose, stack and special feature with
consent and legitimate-interest switches. Vendors lists every vendor,
including your custom vendors, with a search field and per-vendor switches.
The footer saves the selection, or accepts or rejects everything, and writes
the TC String.

To build your own preference centre instead, read and change the selection
with `useConsentIabSelection()` and save it with `useConsentIabSave()`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`initialTab`|`'purposes' \|'vendors'`|The tab the banner asked for, else `'purposes'`|Which tab the dialog opens on.|

## Accessibility and styling

The dialog renders in `document.body` with `role="dialog"`. While blocking
it sets `aria-modal="true"`, locks scrolling and traps focus. It has a close
button. The `components['iab-dialog']` option adds attributes to parts such
as `root`, `card`, `header`, `tabsList`, `tabPanel` and `footer`, and
`components['iab-purpose-item']`, `components['iab-stack-item']` and
`components['iab-vendor-list']` reach the rows. `iabDialogHideBranding`
hides the "Secured by" tag.

## Next steps

* [IAB TCF](/docs/frameworks/nuxt/iab) covers vendor list loading and
  verification.
* [Composables](/docs/frameworks/nuxt/composables#iab-tcf) documents
  `useConsentIabSelection()` and `useConsentIabSave()`.

# Composables
URL: https://c15t.com/docs/frameworks/nuxt/composables
Every c15t composable the Nuxt module auto-imports, grouped by task, with the difference between a permission and a recorded choice.

## Use composables without imports

The Nuxt module auto-imports the consent composables, so a component calls
them directly. This component reads the visitor's permission and recorded
choice, and opens preferences:

```vue title="app/components/ConsentStatus.vue"
<script setup lang="ts">
// May measurement code run right now?
const permissions = useConsent();
// What did the visitor decide? `null` until they accept, reject or save.
const choice = useExplicitChoice();
const activeUI = useConsentActiveUI();
</script>

<template>
	<section aria-label="Your privacy choices">
		<p v-if="choice">You saved your privacy choices.</p>
		<p v-else>You have not made a privacy choice yet.</p>
		<p>
			Measurement is
			{{ permissions.measurement ? 'allowed' : 'not allowed' }} right now.
		</p>
		<button type="button" @click="activeUI = 'manager'">
			Change your choices
		</button>
	</section>
</template>
```

Use `v-if`, not `v-show`, when optional content loads anything from a third
party. For iframes use [`ConsentGate`](/docs/frameworks/nuxt/components/consent-gate),
and for vendor scripts use the `scripts` option in `app.config.ts`. See
[scripts](/docs/frameworks/nuxt/scripts).

A few composables are not auto-imported, among them `useHasConsentPolicy()`,
`useHasConsentUi()`, `useHasConsentPreferences()` and `useIabTranslations()`.
Import them from `#c15t/composables`, the alias the module registers for its
composables:

```ts
import { useHasConsentPreferences } from '#c15t/composables';
```

## Where composables work

Call the composables inside `setup` of a component that renders in the app
where c15t is installed. Anywhere else they throw an error such as
`[c15t] Kernel not found`. Most return a Vue `computed`, so read them with
`.value` in `<script setup>` and without it in the template. They update
whenever the consent runtime changes.

Server routes and middleware under `server/` run outside the Nuxt app, so the
composables do not work there.

## Permission or recorded choice

`useConsent()` and `useHasConsent()` answer "may this run now?" Under an
opt-out policy a category can be allowed before the visitor has done
anything, and Global Privacy Control can deny a category the visitor
allowed. Use them to decide whether to run code or render optional content.

`useExplicitChoice()` answers "what did the visitor decide?" It stays
`null` until the visitor accepts, rejects or saves. Use it to show the
visitor's choice or to report consent rates. Loading a page never changes
it, and dismissing a notice does not set it.

Never save a choice on the visitor's behalf because a permission is `true`.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Read consent state

|Composable|Returns|Use it to|
|--|--|--|
|`useConsent()`|Computed `Record<category, boolean>`|Read every category's current permission, such as `consent.value.marketing`.|
|`useHasConsent()`|Computed array of allowed categories|List what may run now. The array keeps its identity until a category changes.|
|`useEffectivePermissions()`|Computed permissions|The same values as `useConsent()`, read from the snapshot field.|
|`useVendorAllowed(id)`|Computed `boolean`|Check whether one vendor may run: it is declared, its category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`useExplicitChoice()`|Computed recorded choice, or `null`|Read what the visitor decided.|
|`useStoredConsent()`|Computed recorded choice, or `null`|The same value as `useExplicitChoice()`.|
|`useNoticeDismissal()`|Computed dismissal record, or `null`|Check whether the visitor dismissed a notice.|
|`usePrivacySignals()`|Computed privacy signals|Read whether Global Privacy Control was detected and applied.|
|`useConsentRestrictions()`|Computed restrictions|See why a permission is limited, for example by the policy or a privacy signal.|
|`usePolicyRule()`|Computed policy rule|Read the `model`, `prompt`, `scope` and `rights` of the visitor's policy.|
|`usePolicyResolution()`|Computed resolution|Check that a policy matched. `status` is `'matched'` when one applies.|
|`useRequestRegion()`|Computed `{ country, region }`|Read the location the policy resolved for.|

## Composables on the server

The composables work during server rendering. When the server resolves the policy, in the default `manifest()` mode or `hosted()`,
they return the visitor's resolved policy and stored
choice, so the server HTML and
the first client render agree. On prerendered and cached routes, and with
`ssr: false`, they start with every optional category denied and update once
the browser resolves the policy. Until then
`useConsentSnapshot().value.policyPending` is `true`.

## Record a choice

`useConsentSave()` returns a function that records a choice and resolves to
`{ ok }` once the backend has answered. c15t applies the choice in the page
before the request, so gated scripts start without waiting for it.

|Argument|Records|
|--|--|
|`'all'`|Every category the policy covers allowed.|
|`'none'`|Every optional category denied.|
|`['measurement']`|The listed categories allowed and every other optional category denied.|

`useDismissNotice()` returns the function that dismisses a notice. It
records an acknowledgement, grants nothing and leaves earlier refusals in
place. Use it only for a policy whose prompt is `notice`.

## Open the banner or preferences

`useConsentActiveUI()` returns a writable computed. Its value is
`'banner'`, `'manager'` or `null`. Set it to `'manager'` to open
preferences, to `'banner'` to show the banner again, or to `null` to close
both. The Vue adapter uses `'manager'` where the React adapter uses
`'dialog'`. `ConsentDialogLink` does the same as setting `'manager'` and
hides itself when the policy offers no preferences.

## Change the language

`useConsentLanguage()` returns a writable computed with the language
override, or `null`. Assigning a new language code stores it and runs init
again, so c15t fetches the banner and dialog text in that language.
Assigning the current language, or `null`, does nothing.

The `language` prop on the Nuxt
[`ConsentRoot`](/docs/frameworks/nuxt/components/consent-root#props) does the
same from a template binding. See
[translations](/docs/frameworks/nuxt/translations) for a language switcher.

## Build a preference form

`useConsentDraft()` holds the switches of a preference form separately from
the recorded choice, so nothing is saved until the visitor clicks Save.

|Field|Type|Meaning|
|--|--|--|
|`displayedCategories`|`ComputedRef<category[]>`|The categories the policy lets the visitor choose, in the order necessary, functionality, measurement, experience, marketing.|
|`values`|`Ref<Partial<Record<category, boolean>>>`|One value per category. Bind switches to it with `v-model`; a write to `necessary` or to a category the policy does not offer snaps back.|
|`vendors`|`ComputedRef<Record<string, boolean>>`|One value per declared vendor. Change them with `setVendor(id, granted)`.|
|`isDirty`|`ComputedRef<boolean>`|`true` while any value differs from the recorded choice.|
|`isStale`|`ComputedRef<boolean>`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change.|
|`save()`|`() => Promise<{ ok: boolean }>`|Records `values` and changed vendors. Resolves `{ ok: false }` without saving while `isStale` is `true`.|
|`reset()`|`() => void`|Refills the draft from the recorded choice and the policy.|

The draft starts from the recorded choice. Before any choice, it starts
from the policy's defaults: on under an opt-out policy or for preselected
categories, otherwise off. A choice saved elsewhere updates the values the
visitor has not touched. `save()` does not close anything. Set `activeUI`
to `null` yourself after it.

## Render the actions the policy requires

|Composable|Returns|Use it to|
|--|--|--|
|`usePromptRequirement()`|Computed `{ kind }`, where `kind` is `'choice'`, `'notice'` or `'none'`|Decide whether to show a banner at all.|
|`useConsentPolicyActions(surface)`|Computed `actionGroups`, `primaryActions`, `variant`, `position`, `blocking`, `direction` and `preferenceControls`|Render the buttons a banner (`'prompt'`) or preference form (`'preferences'`) must show, in order.|
|`useHasConsentPolicy()`|Computed boolean|Check that a policy matched the visitor.|
|`useHasConsentUi()`|Computed boolean|Check that the policy owes any consent UI. Every stock surface hides while it is `false`.|
|`useHasConsentPreferences()`|Computed boolean|Check whether a preferences control should render.|

Under a notice, `actionGroups` holds `dismiss` instead of accept and
reject. `preferenceControls` lists extra buttons, `'opt-out'` or
`'preferences'`, that open preferences under a policy with those rights.

[Headless](/docs/frameworks/nuxt/headless) builds a complete banner and
preference form from these composables.

## IAB TCF

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentIabSelection()`|Writable computed with purpose, legitimate-interest, vendor and special-feature maps, and `preferenceCenterTab`|Read and change the visitor's IAB selection in a custom preference centre. Writing it updates gating live without saving.|
|`useConsentIabSave()`|`(input, tab?) => Promise<void>`|Save `'all'`, `'none'` or a selection. It waits for the Global Vendor List, then writes the TC String.|
|`useIabTranslations()`|Computed IAB copy|Read the IAB banner and dialog text for the visitor's language.|

## Advanced

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentSnapshot()`|`Ref<ConsentSnapshot>`|Read any snapshot field, such as `policyPending`, `vendors` or `iab`.|
|`useConsentKernel()`|The consent kernel|Call `commands.init()`, `commands.save()`, `commands.identify(user)`, subscribe with `events.on(type, listener)`, or read `getSnapshot()`.|
|`useConsentConfig()`|Computed options, merged with defaults|Read the options you passed.|
|`useConsentInit()`|Computed `{ translations, location, branding, gvl, cmpId, customVendors }`, or `undefined` before the policy resolves|Read display data from the resolved policy.|
|`useConsentComponent(name)`|Computed slot attributes|Read the `components` option for one component, to reuse it in custom markup.|

`useConsentKernel().events.on()` returns an unsubscribe function. Call it in
`onUnmounted`. For choice and permission events, prefer the `callbacks`
option, which c15t wires once for the whole app.

See [callbacks](/docs/frameworks/nuxt/callbacks) for the `callbacks` option.

# Callbacks
URL: https://c15t.com/docs/frameworks/nuxt/callbacks
Run code in a Nuxt app when a visitor records a consent choice, when permissions change, before a revocation reload, and when c15t reports an error.

## Register callbacks

Callbacks are functions, so they go under the `c15t` key of
`app/app.config.ts`, not in `nuxt.config.ts`. Module options reach the
browser as JSON, which drops functions. Keep the callbacks in their own file:

```ts title="app/consent-callbacks.ts"
import type { C15tNuxtConfig } from 'c15t/vue';

export const callbacks = {
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ snapshot }) => {
		console.info('Choice recorded', snapshot.explicitChoice);
	},
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies NonNullable<C15tNuxtConfig['callbacks']>;
```

Then add them next to `scripts` in `app/app.config.ts`:

```ts title="app/app.config.ts"
export default defineAppConfig({ c15t: { callbacks, scripts } });
```

The module wires the callbacks once when its plugin runs. Visitor actions
happen in the browser, so that is where these callbacks run.

## Available callbacks

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useConsentSave()`.|`snapshot`, `confirmed` (the categories the action covered) and `actionAt`|
|`onPermissionsChanged`|Any effective permission changes value.|`snapshot` and `previous`, the permissions before the change|
|`onBeforeConsentRevocationReload`|A save withdraws a granted category or vendor, right before c15t reloads the page.|`preferences`, the permissions after the save|
|`onError`|A consent command fails, for example a save the backend rejects.|`error`, a message string|

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` fires only for a visitor's action. Use it to count consent
decisions or to send the choice to your own analytics.

`onPermissionsChanged` also fires when a stored choice expires, when a new
policy applies, and when a privacy signal such as Global Privacy Control
changes, with no action from the visitor. Use it to start or stop code that
depends on a permission. Do not treat it as evidence that the visitor chose
anything.

Dismissing a notice fires neither callback, because it records no choice and
changes no permission. Subscribe to it with
`useConsentKernel().events.on('notice:dismissed', listener)`.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Before a revocation reload

Removing a script tag cannot stop code that already ran, so c15t reloads the
page after a save withdraws a granted category or vendor.
`onBeforeConsentRevocationReload` runs synchronously right before that. Use
it to call a vendor's shutdown API. Avoid long work, because the reload does
not wait. Set `reloadOnConsentRevoked: false` to handle revocation yourself.

## Verify

Open the console, load a page and click **Accept All**. `onChoiceRecorded` logs
once and `onPermissionsChanged` logs the new permissions. Reload: neither logs
a new choice. Withdraw a category in preferences and save, and the
revocation callback runs before the page reloads.

# IAB TCF
URL: https://c15t.com/docs/frameworks/nuxt/iab
Turn on IAB TCF in Nuxt with the c15t module's iab option, so visitors under an IAB policy get the IAB banner, preference centre and __tcfapi.

## Turn on IAB TCF

IAB TCF is off until you turn it on. Add `iab` under the `c15t` key in
`nuxt.config.ts`; an empty object is enough:

```ts title="nuxt.config.ts (c15t options)"
// Turns IAB TCF on. The CMP ID and vendor list come from `/init`.
iab: {},
```

With `iab` set, `ConsentRoot` renders the IAB banner and preference centre in
place of the standard ones while the visitor's policy uses the `iab` model and
names your CMP ID, and c15t installs `__tcfapi`. Configure the CMP ID and
vendors in your Inth project, or see
[IAB TCF for a self-hosted backend](/docs/self-host/guides/iab-tcf). No extra
component or stylesheet is needed; the IAB components include their own
styles.

Without `iab`, or with `iab: false` or `iab: { enabled: false }`, IAB stays
off: no `__tcfapi` is installed, the app never loads `@c15t/iab`, and pages do
not prefetch it.

If a visitor's policy uses the `iab` model and the backend sends its vendor
list while IAB is off, the app throws an `IABUnavailableError` (code
`C15T_IAB_UNAVAILABLE`). The standard banner does not handle the IAB model,
so the visitor would otherwise get no working consent UI. A server render
fails and Nuxt renders its error page with status 500. On a page the browser
resolves itself, such as a prerendered page or one with `ssr: false`, the
module shows the same error page from the browser. Set `iab`, or remove the
`iab` model from the policy. A backend that answers `gvl: null` turns IAB off
for the request, and the policy runs as opt-in. See
[troubleshooting](/docs/frameworks/nuxt/troubleshooting#the-page-throws-iabunavailableerror).

Set `iab` in `nuxt.config.ts` rather than only in `app.config.ts`. The build
reads the module options to decide whether pages prefetch the IAB banner and
CMP. IAB set only in `app.config.ts` still works, but the browser fetches those
files only once the policy calls for them, so the CMP is ready later and, on
`ssr: false` pages, the IAB banner appears later. `iab` is read once, when the
app starts; changing it with `updateAppConfig()` has no effect.

To compose the IAB surfaces yourself, import
[`IABConsentBanner`](/docs/frameworks/nuxt/components/iab-consent-banner) and
[`IABConsentDialog`](/docs/frameworks/nuxt/components/iab-consent-dialog) and
render them in place of `ConsentRoot`. For a custom preference centre, `useConsentIabSelection()`
reads the visitor's purpose and vendor selection and `useConsentIabSave()`
writes it and the TC String.

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Set
them under the module's `iab` option. The vendor IDs below are placeholders;
use vendors from your list whose declarations allow each restriction.

```ts title="nuxt.config.ts (partial)"
export default defineNuxtConfig({
	modules: ['c15t/vue'],
	c15t: {
		iab: {
			publisherRestrictions: [
				// Vendors 10 and 755 may not use purpose 4.
				{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] },
				// Vendor 755 must use legitimate interest for purpose 7.
				{ purposeId: 7, restrictionType: 2, vendorIds: [755] },
			],
		},
	},
});
```

`iab` also takes `publisherCountryCode`, a `vendors` allowlist,
`customVendors` and `cmpVersion`. Fields you leave out come from the policy:
the CMP ID, custom vendors and vendor list arrive with `/init`. The CMP mounts
only while the visitor's policy uses the `iab` model.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## Vendor list during server rendering

For an IAB policy, the server HTML carries the banner's purpose names, vendor
count and a reference to the Global Vendor List, not the whole list. The banner
renders on the server with the same summary the browser shows. After
hydration, the IAB module fetches the full list and loads it before it saves a
TC String. In the default `manifest()` mode, the
module's init route serves the versioned list with a one-day public cache. Allow that
route, or your backend origin, in your CSP `connect-src`. See
[Content Security Policy](/docs/frameworks/nuxt/content-security-policy).

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Verify IAB consent

Load a page under your IAB policy and confirm the IAB banner appears. In the
browser console, `__tcfapi('getTCData', 2, console.log)` returns a TC String
after you accept or reject. If Nuxt shows its error page with an
`IABUnavailableError` instead, `iab` is not set.

# IAB GPP
URL: https://c15t.com/docs/frameworks/nuxt/gpp
Turn on the IAB Global Privacy Platform API (__gpp) in Nuxt with the c15t Nuxt module's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

The `gpp` option installs `window.__gpp`, the GPP 1.1 CMP API, and keeps its
GPP string in step with the visitor's choices. Prebid.js, Google Ad Manager
and other ad tech read US privacy signals from it.

## Turn on GPP

Set `gpp` under the `c15t` key in `nuxt.config.ts`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: {
		// Loads @c15t/iab/gpp and installs `__gpp` once the app mounts.
		gpp: true,
	},
	modules: ['c15t/vue'],
});
```

The module installs `__gpp` in the browser after the app mounts. The server
HTML does not include it. The browser loads `@c15t/iab/gpp` as its own chunk,
and only when `gpp` is set. The Vue integration already depends on
`@c15t/iab`; nothing else to install. Every GPP option is plain data, so `gpp` also works under
`c15t` in `app.config.ts`.

Replace `https://your-project.inth.app` with your project's backend URL. The
GPP string follows the policy and location the module resolves for the
visitor, so a US visitor's state comes from the location headers your host
or CDN adds. See [Geography headers](/docs/frameworks/nuxt/geography-headers).

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/nuxt/iab) as well.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Geography headers
URL: https://c15t.com/docs/frameworks/nuxt/geography-headers
Which request headers the c15t Nuxt module reads for the visitor's country, region, language and Global Privacy Control, and how to trust and test them.

## How Nuxt finds the visitor's location

The Nuxt server reads the visitor's location from request headers that your
host or CDN adds. It never looks up an IP address itself. The headers are read
in three places:

* During server rendering, the c15t plugin reads them from the page request.
* In the default `manifest()` mode, the `/api/c15t/init` route reads them
  from the browser's own request, for example on a prerendered route.
* In `hosted()` mode, the plugin forwards them to your backend's `/init`.

With `manifest({ resolve: 'browser' })`, no request reaches your server, so
the browser has no location. Pass `geoURL` to `manifest()` with a route that
returns the visitor's `country` and `region`, or a policy that depends on
location asks the backend's `/init` on the first visit. See
[deploy to static hosting](/docs/frameworks/nuxt/rendering#deploy-to-static-hosting).

When no location header is present, the location stays unknown and your
policy's rule for unknown locations applies.

A country can also arrive without a region, for example from Cloudflare
without its visitor location headers setting. If your policy has rules for
regions of that country, such as California, c15t can't tell which one
applies. It uses the rule that lists the country in `regionFallbacks`, and
otherwise the rule for unknown locations. c15t's recommended rules send a US
visitor without a state to the US opt-out rule this way.

## Which headers are read?

Within each row, the first header with a value wins:

|Input|Headers, highest precedence first|Source|
|--|--|--|
|Country|`x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country`|c15t override, Cloudflare, Vercel, CloudFront, generic|
|Region|`x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`|c15t override, Cloudflare, Vercel, generic|
|Global Privacy Control|`x-c15t-gpc`, `sec-gpc`|c15t override, browser signal|
|Language|`accept-language`|Browser|

Vercel sends its headers without setup. Cloudflare sends `cf-region-code`
only with its visitor location headers setting turned on. CloudFront's own
`CloudFront-Viewer-Country` and `CloudFront-Viewer-Country-Region` headers are
not in the list. Map them to `x-c15t-country` and `x-c15t-region` at the edge,
for example with a CloudFront Function, as in
[AWS's viewer-request example](https://github.com/aws-samples/amazon-cloudfront-functions/tree/main/redirect-based-on-country).

The init route responds with `Cache-Control: private, no-store`, because its
answer belongs to one visitor.

## Trust only your own infrastructure

The `x-c15t-*` headers always win, by design. A visitor who sends
`x-c15t-country: US` picks their own policy unless something removes the
header first. The header only changes the policy for the visitor who sent it.
For geography you can trust, configure the edge that terminates all your
traffic, such as your CDN or load balancer, to delete incoming
`x-c15t-country`, `x-c15t-region` and `x-c15t-gpc` headers before it sets any
of its own.

Stripping the headers also turns off the `country` and `region` props of
`ConsentRoot` when the server resolves the policy. In the browser, those
props reach the
`/api/c15t/init` route as `x-c15t-country` and `x-c15t-region` headers, so
the edge removes them too.

Do not strip them in a Nitro server middleware. During server rendering, the
c15t plugin forwards the visitor's location headers to the module's init
route inside the same server, and a middleware runs for that internal request
too. A middleware that deletes or rewrites location headers there removes the
location the plugin has forwarded.

If a client can reach your origin without passing through your CDN, it can
send any platform header, such as `cf-ipcountry`. Block direct origin access
with your host's origin protection.

## Test another region

Use one of these while you build, never in production:

* Render `<ConsentRoot country="DE" />`, or pass `region` too. c15t resolves
  the policy again for that location. When the server resolves the policy,
  this only works while nothing strips the `x-c15t-*` headers.
* Send the override header yourself, for example
  `curl -H 'x-c15t-country: DE' http://localhost:3000/api/c15t/init`. This
  only works while nothing strips the header.
* Use a VPN or your host's geography testing tools against a deployment.

The `internals/fixtures/nuxt` test app in the c15t repository has a demo
middleware that turns `?country=DE` into an override header. It lets any visitor pick their
policy, so do not copy it into production.

## Verify

Deploy and load the site from two locations with different policy rules, for
example through a VPN. View the source of each page: an opt-in region has
`data-testid="consent-banner-root"` in the HTML, and a region with no prompt
does not. Then request `/api/c15t/init` with `curl -H 'x-c15t-country: US'`
against production and confirm the resolved location ignores the header.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/nuxt/content-security-policy
Allow c15t in a Nuxt app under a Content Security Policy, including the theme token style tag, same-origin routes, the backend and vendor scripts.

## What c15t adds to the page

A Nuxt app with c15t adds these to the page, and your policy must allow them:

|What|Directive|
|--|--|
|The `<style id="c15t-css-vars">` tag with your theme tokens, in the page head|`style-src`|
|The components' CSS: inline `<style>` tags Nuxt writes for the server-rendered banner, and stylesheets Nuxt bundles with your app|`style-src`|
|On `ssr: false` pages in `hosted()` mode, an inline `<script>` in the page head that starts `/init`|`script-src`|
|On server-rendered pages with a banner, an inline `<script>` before its buttons that holds a tap made before hydration|`script-src`|
|Browser requests to `/api/c15t/init` and `/api/c15t/manifest` in the default `manifest()` mode|`connect-src 'self'`|
|Consent saves to your backend's `/subjects`, plus `/init` in `hosted()` mode|`connect-src`|
|Chunks Nuxt splits out, such as the browser resolver with `manifest({ resolve: 'browser' })` and the copy for a language other than English|`script-src 'self'`|
|`<script>` elements the script loader creates for `scripts`|`script-src`|
|Scripts, frames, images and requests your vendors load|`script-src`, `frame-src`, `img-src`, `connect-src` for each vendor|

Nuxt adds its own inline scripts and, by default, inline styles. Its
documentation and modules such as `nuxt-security` cover those. The banner's
first paint uses Nuxt's inline styles. If your policy cannot allow them, turn
them off with `features: { inlineStyles: false }` in `nuxt.config.ts`: Nuxt
then links the banner's CSS as stylesheets, and the module leaves those links
in place.

## Allow the theme token style tag

The module writes the `tokens` option into an inline
`<style id="c15t-css-vars">` tag on every page. A `style-src` without
`'unsafe-inline'` blocks it, and the banner falls back to the default theme. The tag's content
is the same for every visitor and only changes when you change `tokens`, so
you can allow it with a hash:

1. Load a page with the policy enforced.
2. Copy the `sha256-...` value from the browser's `Refused to apply inline style` console error.
3. Add it to `style-src` and redeploy.

Recompute the hash whenever you change `tokens`. When you set the module's
`nonce` option, the tag carries that nonce, so a `style-src` that lists the
same nonce allows it. When your policy already allows `'unsafe-inline'` for
Nuxt's own styles, the tag needs nothing more.

## Allow the early init script

On a page with `ssr: false` in `hosted()` mode, the module writes an inline
`<script>` into the page head that requests your backend's `/init` before the
app's JavaScript loads. A `script-src` without `'unsafe-inline'` blocks it, and
the app then sends its own `/init` request after it loads, as it would without
the script.

* **With `nuxt-security`**, the script carries its per-request nonce. Nothing
  more is needed.
* **With the module's `nonce` option**, the script carries that nonce.
* **With a hash-based policy**, the script's content is the same for every
  visitor and changes only when you change `backendURL` or upgrade c15t. Copy
  the `sha256-...` value from the browser's `Refused to execute inline script`
  console error and add it to `script-src`.

To leave the script out, set `initPrefetch: false` in the module options.

A server-rendered banner also writes an inline `<script>` before its buttons.
It holds a tap the visitor makes before the app hydrates. It carries the
module's `nonce` option when set, and its content is the same for every
visitor, so a hash works too. If your policy blocks it, the banner still works
after hydration, but a tap before then does nothing.

## Allow the backend

In the default `manifest()` mode the browser calls your own origin for
`/api/c15t/init`, which `'self'` covers, and sends consent saves to your
backend. Add the backend's origin to `connect-src`. A `manifestURL` or
`geoURL` on another origin needs that origin too. With `iab` set and an IAB
TCF policy, the browser loads the Global Vendor List through the module's
consent route in `manifest()` mode, or from your backend otherwise.

```txt title="Content-Security-Policy (partial)"
connect-src 'self' https://<your-backend-host>;
```

Use the host from your Inth project or your self-hosted backend. Requests the
Nuxt server makes during rendering are not subject to the browser's policy.

## Allow scripts

List each vendor's script host in `script-src`. The
[integration guide](/docs/integrations/overview) for each vendor names its
hosts.

The module's `nonce` option adds a nonce to every script the loader creates.
Module options and `app.config.ts` are fixed when the app builds, so every
response gets the same value. A nonce only protects a page when it changes on
each response, so prefer the host allowlist for c15t's scripts.

## Verify

Enforce the policy, not report-only, and load a page. The banner shows your
token colors, and the console shows no `Refused to apply inline style`,
`Refused to connect` or `Refused to load the script` error that mentions a
c15t element, your backend or a vendor you allowed. Click **Accept All**, and the
vendor scripts load. The save to `/subjects` succeeds.

# DevTools
URL: https://c15t.com/docs/frameworks/nuxt/components/dev-tools
Inspect consent state, the resolved policy, location, scripts and consent events in a Nuxt app during development with ConsentDevTools.

## Load DevTools only in development

The module does not register `ConsentDevTools`. Import it from
`c15t/vue/devtools` with a dynamic import that runs only in development:

```vue title="app/components/ConsentDebugTools.vue"
<script setup lang="ts">
import { defineAsyncComponent } from 'vue';

// Development builds only: the dynamic import keeps DevTools out of
// production bundles.
const ConsentDevTools = import.meta.dev
	? defineAsyncComponent(() => import('c15t/vue/devtools'))
	: null;
</script>

<template>
	<ConsentDevTools v-if="ConsentDevTools" position="bottom-right" />
</template>
```

Render this component anywhere in your app, such as `app.vue`.
`import.meta.dev` is `false` in production builds, so the dynamic import and
the panel stay out of your production bundle. A static `import` would ship
DevTools to every visitor even when `v-if` hides it. The panel mounts in the
browser only.

## What ConsentDevTools renders

`ConsentDevTools` mounts a floating panel for the consent runtime your app
already created. It renders nothing into your component tree and mounts its
panel in `document.body`. It must render inside the app that set up c15t,
or it throws `[c15t] Kernel not found`.

|Panel|What it shows|
|--|--|
|Consents|Each category's value, with save, accept all and reject actions|
|Scripts|Your `scripts`, their loading status, and the scripts and iframes found in the page|
|Location|The resolved country and region|
|Policy|The resolved policy and presentation|
|IAB|Vendors, purposes and the TC String, under an IAB policy|
|Events|A timeline of consent changes and script events|
|Actions|Show the banner, open preferences, hide consent UI, or resolve the policy again|

Accept and reject in the Consents panel apply only to the categories the
policy covers, filtered by `consentCategories`. Necessary stays on.
`DevTools` and `C15TDevTools` are other names for the same component.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar
with a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end farthest
from the trigger's corner. The panel opens just past the toolbar, aligned
with its outer edge, and follows it when a visitor drags the toolbar to
another corner. `position` applies again once no trigger is visible.

DevTools brings its launcher back whenever the trigger is hidden, for
example while `triggerShowWhen: 'after-consent'` waits for a choice. A
production build that loads DevTools only in development shows the single
trigger button.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Corner of the toggle button.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|`'consents' \|'scripts' \|'location' \|'policy' \|'iab' \|'events' \|'actions'`|`'consents'`|Panel shown first.|
|`maxEvents`|`number`|`100`|How many events the Events panel keeps.|
|`getConsentCategories`|`() => readonly ConsentCategory[]`|`consentCategories`|Narrows the categories the Consents panel acts on. It cannot add categories outside the policy.|
|`getPresentation`|`() => ConsentPresentation \|undefined`|Your `presentation` option|Presentation the Policy panel resolves.|
|`clearRecords`|`() => void`|Clears the stored consent records|Runs when you clear records from the panel.|
|`shadow`|`boolean`|`true`|Mounts the panel inside a shadow root that carries its own stylesheet, so your page's CSS cannot restyle it. `:shadow="false"` mounts the panel in the light DOM and adds its stylesheet to `<head>`.|

Changing a prop destroys the panel and creates a new one, which clears its
event history.

## Inspect consent in Nuxt DevTools

In development, the module adds a **c15t** tab to Nuxt DevTools, so you don't
need to render `ConsentDevTools` to inspect consent. Open Nuxt DevTools with
Shift + Option + D (Shift + Alt + D on Windows and Linux) and choose c15t. The
tab shows consent values, scripts, location, the resolved policy, IAB state,
events and consent actions. It follows the DevTools light or dark theme.

Nuxt enables its DevTools by default in development. Production builds don't
register the tab, its `/__c15t_devtools__` page or the client plugin that
exposes the kernel to it. To turn the tab off in development, set
`devtools: false`:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	modules: ['c15t/vue'],
	c15t: { devtools: false },
});
```

The tab's event history starts when you first open it. Nuxt DevTools keeps the
tab loaded, so switching to another tab and back keeps the history. Saves and
actions in the tab change the app's real consent state, as they would through
the banner.

## Embed the panel in your own page

`ConsentDevToolsPanel` from `c15t/vue/devtools` fills its parent element
instead of floating over the page. It has no launcher or close button and
starts open. Use it for your own debug page or another devtools host. Give
the parent a height:

```vue
<script setup lang="ts">
import { ConsentDevToolsPanel } from 'c15t/vue/devtools';
</script>

<template>
  <div style="height: 32rem">
    <ConsentDevToolsPanel default-tab="events" />
  </div>
</template>
```

It accepts `defaultTab`, `maxEvents`, `getConsentCategories`,
`getPresentation` and `clearRecords`, and must render inside the provider
that supplies the kernel.

## Verify

Run `nuxt dev` and open the app. A DevTools button appears in the corner you
set. Open the Location panel and check the country the server resolved. Build
with `nuxt build`, start the server and confirm the button does not appear.

## Next steps

* [Troubleshooting](/docs/frameworks/nuxt/troubleshooting) uses DevTools to
  explain a missing banner.
* [Verify consent](/docs/guides/verify-consent) is the release checklist.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/nuxt/troubleshooting
Fix common c15t Nuxt module problems, from a missing banner and scripts that never load to returning banners and static hosting.

## Why is there no banner?

**Check.** [DevTools](/docs/frameworks/nuxt/components/dev-tools) shows the
matched policy, and `useConsentSnapshot()` exposes `policyRule.prompt`. In the
Network tab, find the init request.

**Fix.** Work through these causes in order:

1. **The visitor's policy asks for no banner.** A policy with prompt `none`
   shows no banner, which is common in opt-out regions. See
   [why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).
2. **`ConsentRoot` is inside a page that unmounts.** Put it in `app.vue`.
3. **The policy did not resolve.** In the default `manifest()` mode,
   `/api/c15t/init` must return 200. With `hosted()`, the backend's `/init`
   must. While resolution fails, c15t shows no UI and keeps every optional
   category denied.
4. **A stored choice exists.** Clear the `c15t` cookie and localStorage entry,
   or use a private window.

## The page throws IABUnavailableError

**Check.** Nuxt shows its error page, and the error has the code
`C15T_IAB_UNAVAILABLE` and reads "c15t: this visitor's policy uses IAB TCF,
but `iab` is not set." The visitor's policy uses the `iab` model and the
backend sent its vendor list, but the module has no `iab` option, or has
`iab: false` or `iab: { enabled: false }`. The standard banner does not
handle the IAB model, so c15t throws rather than leave the visitor with no
consent UI. A server render fails with status 500. A prerendered or
`ssr: false` page shows the error page once the browser resolves the policy.

**Fix.** If the site uses IAB TCF, set `c15t: { iab: {} }` in
`nuxt.config.ts`, or `iab: { cmpId }` when your backend sends no CMP ID. See
[IAB TCF](/docs/frameworks/nuxt/iab). If it does not, remove the `iab` model
from the policy for that region in your Inth project or policy pack. A
backend that answers `gvl: null` turns IAB off for that request, and nothing
throws.

## The banner is not in the server HTML

**Check.** Only request-time rendering in `manifest()` or `hosted()` mode
puts the banner in the HTML. `manifest({ resolve: 'browser' })` and
`offline()` resolve in the browser.
Prerendered routes, routes with a `prerender`, `swr`, `isr` or `cache` rule,
`nuxt generate` output and `ssr: false` send the same HTML to every visitor,
so the banner appears after the browser resolves the policy.

**Fix.** If a route needs the banner in its HTML, render it at request time
with `manifest()`, the default, or `hosted()`.

**Check.** With server rendering, the render waits at most `timeoutMs` for the
policy, 500 milliseconds by default. A slower backend renders the page without
consent UI and the browser resolves the policy after hydration. Check the
server log for backend errors.

**Fix.** Raise `timeoutMs` if your backend is reachable but slow.

## The banner comes back after a visitor rejects

**Check.** Filter the Network tab by `subjects` and check that the `POST` to
your backend returns 2xx. A CORS error means the site's origin is missing from
your Inth project's trusted origins.

**Fix.** Add the site's origin to the trusted origins.

**Check.** Compare `storageConfig.storageKey` in the module options and
`app.config.ts`. When they differ, the choice is written under one name and
read under another.

**Fix.** Use the same `storageKey` in both places.

**Check.** Look for a cache in front of Nuxt, such as a CDN, that stores pages
Nitro renders per request. The module only recognizes Nuxt's own prerendering
and `prerender`, `swr`, `isr` or `cache` route rules.

**Fix.** Use a route rule for those pages, or have the CDN skip HTML. See
[prerendered and cached routes](/docs/frameworks/nuxt/rendering#prerendered-and-cached-routes).

## Scripts never load, or load before consent

**Check.** Look for `scripts` in `nuxt.config.ts`. Module options drop
functions.

**Fix.** Move `scripts` to `app/app.config.ts`.

**Check.** Look at the vendor ID. It is still a placeholder, such as
`phc_your_project_key`.

**Fix.** Replace it with the ID from your vendor account.

**Check.** Look for a second loader, such as the vendor's own Nuxt module or a
`useHead` script, that also loads the vendor.

**Fix.** Remove it, or the vendor loads without consent.

## `nuxt build` or `nuxt dev` can't fetch the manifest

**Check.** The module downloads the manifest when `nuxt build` runs and when
`nuxt dev` starts, and waits at most 10 seconds. When the download fails,
`nuxt build` stops with an error that starts with `could not fetch the consent manifest from <url> during the build`. `nuxt dev` logs the same
message as a warning, and the server fetches the policy at runtime. The
part in parentheses names the cause:

* `fetch failed` with a network error, or `no response within 10 seconds`:
  the build machine can't reach the backend.

* `/manifest responded 404 Not Found`, or another status: the URL doesn't
  point at your project's backend, or the backend is down.

* `returned an invalid consent manifest`: the URL answers, but not with a c15t
  manifest.

* `manifest() needs a backend URL`: neither `backendURL` nor
  `NUXT_PUBLIC_C15T_BACKEND_URL` (or `NUXT_PUBLIC_INTH_PROJECT_URL`) is set. `nuxt build` and `nuxt dev` both
  stop, whatever `onBuildError` says, because the browser saves consent to
  the backend. `manifest({ snapshot })` stops with
  `manifest({ snapshot }) still needs a backend URL` for the same reason.

With `onBuildError: 'fail'`, this error also appears:

* `build-time manifests require an absolute upstream URL`: `backendURL` or
  `manifestURL` is a relative path. Without `onBuildError: 'fail'`, the
  module skips the fetch instead.

**Fix.** Set `NUXT_PUBLIC_C15T_BACKEND_URL` (or
`NUXT_PUBLIC_INTH_PROJECT_URL`), or `backendURL` under the `c15t` key, to your project's absolute backend URL, including any path prefix; the
module adds `/manifest`. To download from another address, set
`mode: manifest({ manifestURL })` to the full manifest URL, which is used as
written. Make sure the build machine can reach the backend. To deploy while
it is down, build with `C15T_ON_BUILD_ERROR=runtime`, or set
`onBuildError: 'runtime'`. To never fetch at build time, set
`mode: manifest({ source: 'runtime' })`. `nuxt prepare` doesn't download the
manifest, so installing dependencies works offline.

## Policy edits don't show up

**Check.** When the build bundles a manifest, the policy is fixed when you
build.
Changing `NUXT_PUBLIC_C15T_BACKEND_URL` on a running server moves consent
saves, not the policy.

**Fix.** Build again after editing policies, translations or vendors. If your
CI caches build output, skip the cache for that build. To pick up edits
without rebuilding, set `mode: manifest({ source: 'runtime' })`.

## Static hosting returns 404 for /api/c15t/init

**Check.** A static host has no Nuxt server routes, so `/api/c15t/init` and
`/api/c15t/manifest` do not exist after deployment. `nuxt generate` warns
about this when `mode` is the default `manifest()`.

**Fix.** Set `mode: manifest({ resolve: 'browser' })` with
`routePrefix: false`, or `mode: hosted()`, as in
[deploy to static hosting](/docs/frameworks/nuxt/rendering#deploy-to-static-hosting).
If the browser reports a CORS error for a consent save or `/init`, add your
site's origin to the Inth project's trusted origins.

## The module throws "`c15t.mode` in nuxt.config.ts is a transport"

**Check.** `nuxt.config.ts` imports `manifest`, `hosted` or `offline` from
`c15t/vue/vue-plugin`. Those return browser transports, which cannot travel
through runtime config.

**Fix.** Import them from `c15t/vue`, the module entry, which returns plain
data.

## Options from an earlier alpha have no effect

**Check.** The `c15t` key sets `manifest`, `manifestURL`, `manifestSnapshot`,
`buildManifest`, `geoURL`, `initRoute` or `manifestRoute`. The module no
longer reads them.

**Fix.** Use `mode` and `routePrefix`:

|Earlier option|Now|
|--|--|
|`manifest: 'server'`|Nothing: `manifest()` is the default|
|`manifest: 'client'`|`mode: manifest({ resolve: 'browser' })`|
|`manifest: false`|`mode: hosted()`|
|`manifestURL`, `geoURL`, `manifestSnapshot`|`manifest({ manifestURL })`, `manifest({ geoURL })`, `manifest({ snapshot })`|
|`buildManifest: false`|`mode: manifest({ source: 'runtime' })`|
|`buildManifest: true`|`onBuildError: 'fail'`|
|`initRoute`, `manifestRoute`|`routePrefix`, one catch-all for both|
|`NUXT_PUBLIC_C15T_MANIFEST_URL`, `NUXT_C15T_MANIFEST_URL`|`mode: manifest({ manifestURL })` in `nuxt.config.ts`. The variables are no longer read, so the manifest URL is fixed at build time. `NUXT_PUBLIC_C15T_BACKEND_URL` and `NUXT_C15T_BACKEND_URL` still work.|
|`domain`|Nothing. Saves send the page's hostname.|
|`ConsentPreferencesLink`|`ConsentDialogLink`. The floating `ConsentDialogTrigger` keeps its name.|
|`ConsentFrame`|`ConsentGate`|

## Every first visit calls /init on a static site

**Check.** With `manifest({ resolve: 'browser' })` the browser has no request
location. When your policy depends on the visitor's country or region, the
browser asks the backend's `/init` for it on the first visit.

**Fix.** Pass `geoURL` to `manifest()` with a route on your site that returns
the visitor's `country` and `region`, so the browser resolves the policy
itself. Or use `hosted()`, which makes the same `/init` request without
bundling the manifest.

## A composable throws "Kernel not found"

**Check.** The composable ran outside the Nuxt app, for example in a server
route or a plain module.

**Fix.** Call consent composables inside a component's `setup`.

## Every visitor resolves the same location

**Check.** The server found no location header, or an `x-c15t-country` header
that your own code adds, such as a test middleware, won. A header a visitor
sends only changes that visitor's policy. Check which headers reach Nuxt.

**Fix.** Choose the headers you trust as
[geography headers](/docs/frameworks/nuxt/geography-headers) describes.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/vue/quickstart
Add c15t to a Vue 3 app built with Vite, using the Vue plugin, Inth, consent-gated scripts and a preferences link.

## Before you start

This guide is for a Vue 3 single-page app built with Vite. The build bundles
your project's public policy, and the browser resolves each visitor's policy
from it after the page loads, so it works on any static host. For a Vue app that renders on the server, use the c15t Nuxt module.
[Choose your setup](/docs/concepts/choose-your-setup) compares every option.

The guide uses [Inth](https://inth.com) for policies and consent records.
Create a project, set its policy rules, add your site's origin to its trusted
origins, and copy the backend URL. To run the service yourself, use a
[self-hosted backend](/docs/self-host/overview) URL instead. Offline mode keeps
policies in your code and choices in the browser, with no consent records.
Not recommended for production environments.

Bundling the policy at build time is the recommended production setup.
Rebuild after changing policies, translations or vendors.

## Install c15t

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

## Add the Vite plugin

Add `consentManifest()` from `c15t/vue/vite` to `vite.config.ts`, next to
`@vitejs/plugin-vue`:

```ts title="vite.config.ts"
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [vue(), consentManifest()] });
```

Set `VITE_C15T_BACKEND_URL` to your project's backend URL, including any
path prefix, in `.env` or wherever you build:

```sh title=".env"
VITE_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `VITE_C15T_BACKEND_URL` wins.

`consentManifest()` downloads your project's public policy from `/manifest`
during `vite build`, or in `vite dev` when the app first loads it, and hands
it and the backend URL to the Vue plugin. A build fetches only when the app
uses `manifest()`. No file is written into your project. It also keeps the c15t
components, which ship as `.vue` files, out of Vite's dependency
pre-bundling.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

## Install the Vue plugin

Install the plugin from `c15t/vue/vue-plugin` in `src/main.ts`:

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

`c15t/vue` is the Nuxt module. Do not pass it to `app.use()`.

The plugin creates the consent runtime for this app. When the app mounts, it
reads the visitor's stored choice, resolves their policy, and starts the
script loader for the `scripts` you pass. `mode: manifest()` resolves the
policy in the browser from the snapshot `consentManifest()` downloaded, with
no `/manifest` or `/init` request, and sends consent choices to the same
backend URL. Vite reads `VITE_C15T_BACKEND_URL` at build time, so set it
before you build, not when you serve the files.

The browser does not know the visitor's location, so without `inputs` or
`geoURL` on `manifest()`, or a `country` and `region` passed to
`ConsentRoot`, every visitor gets the policy your project assigns when the
location is unknown. Configure that fallback rule in your project, or see
[rendering](/docs/frameworks/vue/rendering#tell-the-browser-where-the-visitor-is).
The bundle carries English copy; other languages load on demand.

To apply policy edits without rebuilding, use `manifest({ source: 'runtime' })`
or `hosted()`. [Rendering](/docs/frameworks/vue/rendering) compares the
modes.

## Register consent-gated scripts

Remove any existing PostHog snippet so the script loads once, and add
measurement to your Inth policy. The `scripts` option in `src/main.ts` loads
PostHog once the visitor allows measurement.

Replace `phc_your_project_key` with your PostHog project key. PostHog
defaults to its EU region; set `region: 'us'` for a US project.

## Mount the consent UI

```vue title="src/App.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentRoot } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentRoot />
	<main>
		<h1>c15t with Vue</h1>
		<p>PostHog loads after you allow measurement.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

`ConsentRoot` renders the banner when the visitor's policy asks for one and
loads the preference dialog when it opens. `ConsentDialogLink` renders a
button that reopens preferences. Without slot content, its label is the
dialog's title in the visitor's language: Privacy Settings in English. It
renders nothing until the policy offers preferences. Replace the `<main>`
element with your own content or router view. Keep `ConsentRoot` in the root
component so it stays mounted. The components bring their own styles; there
is no stylesheet to import.

## Gate an embed

Wrap third-party iframes in `ConsentGate`. The iframe does not exist in the
page until its category is allowed, and it is removed when the visitor
withdraws permission.

```vue title="src/VideoEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

Render `<VideoEmbed />` in a page where the video belongs.

## Verify the setup

Build and preview the production app with `vite build` and `vite preview`.
Open it in a private window with your browser's DevTools on the Network tab,
under a policy that asks for consent.

1. Load the page. The bundled manifest resolves the policy and the banner
   appears, with no `/manifest` or `/init` request. Test the unknown-location
   rule, or pass `geoURL` to `manifest()` if you need regional policies. No requests to
   `posthog.com` or `youtube-nocookie.com` appear.
2. Click **Reject All**, then reload. The banner stays closed and the vendor
   requests stay absent.
3. Click **Privacy settings**, turn on **Analytics** (the `measurement` category) and save. PostHog's `array.js`
   loads and the video appears.
4. Turn **Analytics** off and save. The page reloads, the video is gone and
   PostHog does not load again.

[Verify consent](/docs/guides/verify-consent) has the full release checklist.

## Next steps

* [Rendering and deployment](/docs/frameworks/vue/rendering) covers static
  hosting, each `mode` and server rendering.
* [c15tVue plugin](/docs/frameworks/vue/plugin) lists every option.
* [Scripts](/docs/frameworks/vue/scripts), [embeds](/docs/frameworks/vue/embeds)
  and the [network blocker](/docs/frameworks/vue/network-blocker) cover
  gating and revocation.
* [Customize](/docs/frameworks/vue/customize) changes colors, layout and copy.
* [Components](/docs/frameworks/vue/components) and
  [composables](/docs/frameworks/vue/composables) list the full API.
* [Troubleshooting](/docs/frameworks/vue/troubleshooting) covers common
  failures.

# c15tVue plugin
URL: https://c15t.com/docs/frameworks/vue/plugin
Install c15t in a Vue app with app.use(c15tVue), what the plugin starts when the app mounts, and every option it accepts.

## Install the plugin

Import `c15tVue` from `c15t/vue/vue-plugin` and pass it to `app.use()` in
`src/main.ts`:

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

`c15t/vue` is the Nuxt module, not a Vue plugin. Passing it to `app.use()`
does nothing useful. The [quickstart](/docs/frameworks/vue/quickstart) covers
`consentManifest()`, the Vite plugin that downloads the policy `manifest()`
reads.

## What the plugin does

`app.use(c15tVue, options)` creates one consent runtime for the app and
provides it to every component. It also adds your `tokens` to
`document.head` in a `<style id="c15t-css-vars">` element, before the first
render. Nothing else runs in the browser until the root component mounts.
Then the plugin, in order:

1. Reads the visitor's stored choice from the `c15t` cookie and
   localStorage.
2. Applies Global Privacy Control when the browser sends it.
3. Starts the script loader for `scripts`, clear-on-revocation, the network
   blocker and the iframe blocker.
4. Resolves the visitor's policy with the `mode` you passed: from the
   manifest in the browser with `manifest()`, from the backend's `/init` with
   `hosted()`, or from local rules with `offline()`.
5. With the `iab` option set, loads the IAB TCF module once a policy uses the
   `iab` model.

Until the policy arrives, every optional category is denied, so gated scripts
and iframes wait. On Vue 3.5 and later, `app.unmount()` stops every module
and removes the token style element.
Composables called outside this app throw `[c15t] Kernel not found`.

## Options

`mode` is required unless you pass a `runtime`; every other option is
optional. Options that hold
functions, such as `scripts` and `callbacks`, work here because the plugin
runs in the browser.

### Policy source

|Option|Default|What it does|
|--|--|--|
|`mode`|Required|Where the visitor's policy comes from: `manifest()`, `hosted()`, `offline()` or `custom()`, all from `c15t/vue/vue-plugin`. See [rendering](/docs/frameworks/vue/rendering).|
|`consentCategories`|The policy's categories|Limits the categories the dialog and widget show, within the policy's scope.|
|`vendors`|Unset|Vendors listed under their category with their own switch. See [vendor consent](/docs/frameworks/vue/vendor-consent).|
|`storageConfig`|`{ storageKey: 'c15t' }`|Cookie and localStorage name, `crossSubdomain`, `defaultDomain` and `defaultExpiryDays`, 365 by default.|

The backend URL, a custom `fetch` and the save `domain` are options of the
mode, not the plugin:

|Mode|Options|
|--|--|
|`manifest()`|`backendURL` and the build snapshot default to what `consentManifest()` downloaded. `source: 'runtime'` fetches the manifest when the app starts; `manifestURL` fetches it from that URL instead of using the snapshot; `snapshot` takes one you supply. `geoURL`, `inputs`, `initFallback`, `headers`, `credentials`, `fetch`, `domain`.|
|`hosted()`|`backendURL`, by default the one `consentManifest()` read from `VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`. `headers`, `fetch`, `domain`.|
|`offline()`|`policyRules`. Omitted, c15t's recommended rules.|

`manifest()` and `hosted()` throw when they have no backend URL: add
`consentManifest()` to `vite.config.ts` and set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`), or pass `backendURL`.

### Scripts and blocking

|Option|Default|What it does|
|--|--|--|
|`scripts`|Unset|Vendor scripts that load by consent category. See [scripts](/docs/frameworks/vue/scripts).|
|`networkBlocker`|Off|Rules that hold `fetch` and XHR requests until their category is allowed. See [network blocker](/docs/frameworks/vue/network-blocker).|
|`iframeBlocker`|On|Gates iframes that carry `data-src` and `data-category`. `false` turns it off. See [embeds](/docs/frameworks/vue/embeds).|
|`nonce`|Unset|Content Security Policy nonce for every script the loader creates and for the token style element. See [Content Security Policy](/docs/frameworks/vue/content-security-policy).|
|`reloadOnConsentRevoked`|`true`|Reloads the page when a save withdraws a granted category or vendor.|
|`clearOnRevocation`|Unset|Deletes first-party cookies and storage keys for a withdrawn category. See [clear on revocation](/docs/frameworks/vue/clear-on-revocation).|
|`iab`|Off|Turns IAB TCF on; `{}` is enough. Also takes publisher settings, such as `publisherRestrictions`; fields left out come from the policy. Unset, `false` or `{ enabled: false }` leaves IAB off, and an `iab` policy with a vendor list throws an `IABUnavailableError`. See [IAB TCF](/docs/frameworks/vue/iab).|

### Events and other tools

|Option|Default|What it does|
|--|--|--|
|`callbacks`|Unset|`onChoiceRecorded`, `onPermissionsChanged`, `onError` and `onBeforeConsentRevocationReload`. See [callbacks](/docs/frameworks/vue/callbacks).|

### Appearance

|Option|Default|What it does|
|--|--|--|
|`tokens`|The default theme|CSS variables the plugin adds to `document.head` in a `<style id="c15t-css-vars">` element. See [customize](/docs/frameworks/vue/customize#set-theme-tokens).|
|`presentation`|Policy defaults|Banner and dialog variant, position, action layout and blocking.|
|`components`|Unset|Attributes, such as `class`, for named parts of each component.|
|`legalLinks`, `bannerLegalLinks`, `dialogLegalLinks`|None shown|Links to your privacy policy and similar pages, and which surfaces show them.|
|`hideBranding`, `bannerHideBranding`, `dialogHideBranding`, `iabBannerHideBranding`, `iabDialogHideBranding`|`false`|Hide the "Secured by" tag.|
|`showTrigger` and the `trigger*` options|`false`|The floating trigger. See [ConsentDialogTrigger](/docs/frameworks/vue/components/consent-dialog-trigger).|
|`disableAnimation`|`false`|Turns off banner and dialog transitions.|
|`models`, `bannerModels`, `iabBannerModels`, `iabDialogModels`|Every model|Limit which policy models show a surface.|

### Advanced

|Option|What it does|
|--|--|
|`runtime`|A runtime created elsewhere with `createConsentRuntime()`, in place of `mode`. The plugin renders it and neither starts nor stops it, and ignores `callbacks`, blockers, `scripts` and `tokens`, which the runtime's owner configures.|
|`prefetch`, `initialRecords`|A resolved policy and stored records from a server, used for the first render. Plain Vue has no server helper that produces them.|

## Verify

Open the app with the Network tab open. `manifest()` with a bundled snapshot
makes no policy request. `manifest({ source: 'runtime' })` requests
`${backendURL}/manifest`, and `hosted()` requests the backend's `/init`. In
the Application panel, a `c15t` cookie appears after you accept or reject.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/vue/rendering
Pick where a Vue app's consent policy comes from with the plugin's mode option, host it statically, and why server-rendered Vue apps should use Nuxt.

## Pick the setup for your deployment

The Vue plugin runs in the browser only. The `mode` option of
`app.use(c15tVue, { mode })` decides where each visitor's policy comes from.
Import the mode from `c15t/vue/vue-plugin`:

|Your app|`mode`|
|--|--|
|Vue with Vite, served as static files|`manifest()`, as in the [quickstart](/docs/frameworks/vue/quickstart). The build bundles the policy and the browser resolves it. Plan location inputs or an unknown-location rule.|
|Policy edits must apply without a rebuild|[`manifest({ source: 'runtime' })`](#fetch-the-manifest-at-runtime)|
|Regional policies that need the visitor's location from the backend|[`hosted()`](#ask-the-backend-for-each-visitors-policy)|
|A prototype with no backend|[`offline()`](#resolve-the-policy-without-a-backend). Not recommended for production environments.|
|Vue rendered on the server without Nuxt|Any of the above; the banner mounts after hydration. For the banner in server HTML, [use Nuxt](#server-rendering-without-nuxt).|

`mode` is required. Without it, `app.use()` throws and asks for one. Each
mode is imported statically, so the bundle carries only the modes your app
imports.

## Bundle the manifest during builds

The [quickstart](/docs/frameworks/vue/quickstart) and `examples/vue` in the
c15t repository use this setup.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

`consentManifest()` from `c15t/vue/vite` downloads the policy during
`vite build`, when the app uses `manifest()`, and in `vite dev` when the app
first loads it:

```ts title="vite.config.ts"
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [vue(), consentManifest()] });
```

Without a `backendURL` option, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`, from the environment or `.env`. `manifest()` from `c15t/vue/vue-plugin`, with no
options, reads the downloaded policy and the same backend URL, so `src/main.ts`
needs no import from `c15t/generated`:

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

The browser resolves the visitor's policy from the bundled snapshot, with no
`/manifest` request. When the policy depends on the visitor's country or
region and neither `inputs` nor `geoURL` supplies one, the browser asks the
backend's `/init` instead. The app bundles the policy and English copy, and
loads the resolver as its own chunk when it needs it.

When the build has no snapshot, as in `vite dev` after a failed download,
`manifest()` fetches `${backendURL}/manifest` when the app starts.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy edits without a rebuild, use
[`manifest({ source: 'runtime' })`](/docs/frameworks/vue/rendering#fetch-the-manifest-at-runtime),
or [`hosted()`](/docs/frameworks/vue/rendering#ask-the-backend-for-each-visitors-policy)
when you need the backend's geolocation.

### Tell the browser where the visitor is

The browser has no request location. When the policy depends on the
visitor's country or region, `manifest()` asks the backend's `/init` on the
first visit, as React and Svelte do, rather than apply the rule for an
unknown location, which could be another region's. `vite build` warns when
it bundles such a policy and suggests `hosted()`, because the bundled policy
then saves no request. To resolve in the browser instead:

* Pass `country` and `region` props to `ConsentRoot` when the page already
  knows the location, for example from a value your edge server injected.
* Pass `inputs: { country, region }` to `manifest()` for the same purpose,
  set once when the plugin installs.
* Set `geoURL` to a same-origin route you run that returns the visitor's
  `{ country, region }` as JSON. `manifest()` requests it only when the
  policy depends on a location it does not have.
* Pass `initFallback: false` to `manifest()` to resolve the policy for an
  unknown location without asking the backend. Only do this when that rule
  is right for every visitor it reaches.

### Load the visitor's language

The bundle includes English copy. When a visitor resolves to another
language your project has text for, the browser loads the base text for that
language from your site the first time it is needed. A visitor downloads
their own language only, never the full set.

## Fetch the manifest at runtime

`manifest({ source: 'runtime' })` ignores the build's snapshot and fetches
`${backendURL}/manifest` when the app starts. The browser resolves the
policy from it, so policy edits apply without a rebuild:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';

app.use(c15tVue, { mode: manifest({ source: 'runtime' }), scripts });
```

Keep `consentManifest()` in `vite.config.ts`: `manifest()` reads the backend
URL from it. The plugin can't see options you pass in app code, so set
`consentManifest({ source: 'runtime' })` as well. Without it, the build still
downloads the manifest, and fails when the backend is down.

To fetch the manifest from somewhere else, such as a CDN in front of your
backend, pass `manifest({ manifestURL })`. The app fetches that URL when it
starts and ignores the build's snapshot. As with `source: 'runtime'`, set
`consentManifest({ source: 'runtime' })` so the build doesn't download the
manifest. Consent saves still go to the backend URL from `consentManifest()`.

The manifest is the same for every visitor, so a CDN can cache it. Location,
`geoURL` and language loading work as in the
[build-time setup](#tell-the-browser-where-the-visitor-is). Consent saves
still go to the backend.

## Ask the backend for each visitor's policy

`hosted()` sends each visitor's first page load to the backend's `/init`.
The backend reads the visitor's location from the request, resolves the
policy and returns the text in the visitor's language:

```ts title="src/main.ts"
import { c15tVue, hosted } from 'c15t/vue/vue-plugin';

app.use(c15tVue, { mode: hosted(), scripts });
```

`hosted()` reads the backend URL from `consentManifest()`, or takes it as
`hosted({ backendURL: 'https://your-project.inth.app' })`. Keep
`consentManifest()` in `vite.config.ts` either way: it also keeps the c15t
components, which are `.vue` files, out of Vite's dependency pre-bundling.
A `hosted()` build never downloads the manifest, so a backend outage does
not stop it.

Until `/init` answers, every optional category is denied, so gated scripts
and iframes wait. The build output is plain static files. Deploy it to any
static host. The backend must allow your site's origin. With Inth, add it to
the project's trusted origins.
[Data fetching](/docs/concepts/data-fetching) compares the two paths.

## Resolve the policy without a backend

`offline()` resolves policy rules in the browser and stores choices in the
visitor's cookie and localStorage. There is no backend, so no consent
records are kept. Not recommended for production environments.

```ts title="src/main.ts"
import { c15tVue, offline } from 'c15t/vue/vue-plugin';

app.use(c15tVue, { mode: offline(), scripts });
```

Without options, `offline()` uses c15t's recommended policy rules. Pass
`offline({ policyRules })` to replace them.

## Server rendering without Nuxt

c15t has no server helper for plain Vue. The plugin accepts `prefetch` and
`initialRecords`, but nothing produces them for a custom Vue server. A
server-rendered page renders without the banner, and the banner appears after
hydration.

Your theme tokens can still be in the first HTML. `generateTokensCSS()` from
`c15t/vue/vue-plugin` returns the CSS the plugin applies. Put it in a
`<style id="c15t-css-vars">` element in your server HTML, and the plugin
reuses that element in the browser:

```ts
import { generateTokensCSS } from 'c15t/vue/vue-plugin';

const tokensStyle = `<style id="c15t-css-vars">${generateTokensCSS(tokens)}</style>`;
```

For the banner in server-rendered HTML, use the c15t Nuxt module. Start with
the Nuxt quickstart in the [framework list](/docs/frameworks).
It resolves the policy on the server, renders the banner and tokens in the
first HTML, and hydrates without another request.

## Verify your deployment

Serve the production build and open the Network tab:

|`mode`|Policy requests on the first page load|
|--|--|
|`manifest()` with a build snapshot|None to the backend. A language other than English loads its text from your site.|
|`manifest({ source: 'runtime' })`|One `GET` to `${backendURL}/manifest`|
|`manifest({ manifestURL })`|One `GET` to `manifestURL`|
|`hosted()`|One `GET` to `${backendURL}/init`|
|`offline()`|None|

Reject, reload, and confirm the banner stays closed. Then follow
[verify consent](/docs/guides/verify-consent) for the vendor checks.

# Scripts
URL: https://c15t.com/docs/frameworks/vue/scripts
Load vendor scripts by consent category in a Vue app with the c15t Vue plugin, and what happens when a visitor withdraws consent.

## Register vendor scripts

A banner does not stop a script you load with a `<script>` tag in
`index.html` or a vendor SDK you initialize yourself. Remove those loaders and
register the vendor with c15t instead, so c15t loads it only while its
category is allowed.

Pass the helpers from `@c15t/integrations` to the plugin as `scripts`:

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

The plugin starts one script loader when the app mounts, after it has applied
the visitor's stored choice and privacy signals. Do not also call
`createScriptLoader` from a component. A component's `onMounted` runs before
the plugin has read the stored choice, and each script would load twice.

Every vendor guide under [integrations](/docs/integrations/overview) gives the
helper and options for that vendor.

## Embeds and other requests

Scripts cover vendor code c15t loads for you. For the rest:

* [Embeds](/docs/frameworks/vue/embeds) gates iframes with `ConsentGate` or
  the iframe blocker.
* [Network blocker](/docs/frameworks/vue/network-blocker) holds `fetch` and
  XHR calls that match a rule until their category is allowed.

## When a visitor withdraws consent

Removing a script tag cannot stop code that already ran. When a save turns off
a category or vendor that was allowed, c15t reloads the page so the new
document starts with only permitted code. Set `reloadOnConsentRevoked: false`
to handle revocation yourself, or use the
[`onBeforeConsentRevocationReload` callback](/docs/frameworks/vue/callbacks#before-a-revocation-reload)
to run code before the reload.

`clearOnRevocation` deletes first-party cookies and storage keys that belong to
a category when it is withdrawn. See
[clear on revocation](/docs/frameworks/vue/clear-on-revocation).

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Declare
the vendors in the `vendors` option; helpers from `@c15t/integrations` already carry
their vendor slug. See [vendor consent](/docs/frameworks/vue/vendor-consent).

## Content Security Policy

Allow each vendor's script host in `script-src`. The plugin's `nonce` option
adds a nonce to every script the loader creates. See
[Content Security Policy](/docs/frameworks/vue/content-security-policy).

## Verify gating

In a private window, open the Network tab and load the app under a policy that
asks for consent. Requests to your vendors are absent.
Allow one category and save, and only that category's vendors load. Withdraw
it, and the page reloads without loading the vendor again.
[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/vue/embeds
Keep YouTube videos, maps and other iframes out of a Vue page until their consent category is allowed, with ConsentGate or the iframe blocker.

## Pick a method

|Method|Use it when|
|--|--|
|`ConsentGate`|You render the iframe in a Vue component and want a placeholder with a way to open preferences.|
|The iframe blocker|The iframe comes from markup you do not render with a component, such as CMS content, or you want no wrapper.|

Both remove the iframe's `src` until the category is allowed, so the embed's
host receives no request before consent.

## Gate an embed with ConsentGate

Wrap the iframe in [`ConsentGate`](/docs/frameworks/vue/components/consent-gate)
from `c15t/vue/vue-plugin`:

```vue title="src/VideoEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

The iframe does not exist in the page until the visitor allows measurement.
The `placeholder` slot shows a message and a
[`ConsentDialogLink`](/docs/frameworks/vue/components/consent-dialog-link)
until then. When the visitor withdraws measurement, Vue removes the iframe.

Pick the category that matches what the embed does. The example uses
measurement for YouTube because its player measures views. A map or chat
widget usually belongs under functionality or experience.

## Gate an iframe with the iframe blocker

The Vue plugin runs the iframe blocker by default. Give an iframe `data-src`
instead of `src`, and a `data-category`:

```vue title="src/MapEmbed.vue"
<template>
	<iframe
		data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
		data-category="functionality"
		title="Store map"
	/>
</template>
```

c15t sets `src` from `data-src` when the category is allowed and removes it
when the category is withdrawn. It watches the page, so iframes added later,
for example by a route change, are handled too. The iframe element stays in
the page while blocked, empty. Add `data-vendor` with a vendor ID to also
block the iframe while the visitor has turned that vendor off.

Pass `iframeBlocker: false` to the plugin to turn the blocker off.

## Verify

Open the page in a private window with the Network tab open, under a policy
that asks for consent. No request goes to `youtube-nocookie.com` or
`google.com/maps`. Allow the category and save: the iframe loads. Withdraw it
and save: the page reloads without the embed. The
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides cover sizing and titles.

# Network blocker
URL: https://c15t.com/docs/frameworks/vue/network-blocker
Hold fetch and XMLHttpRequest calls in a Vue app until their consent category is allowed, with rules passed to the c15t Vue plugin.

## Add rules

The network blocker stops `fetch` and `XMLHttpRequest` calls that match a
rule until the rule's category is allowed. Use it as a backstop for tracking
calls your own code or a vendor SDK makes. Load vendor SDKs through
[`scripts`](/docs/frameworks/vue/scripts) first, so they do not run at all
before consent.

Define the rules in their own file:

```ts title="src/network-blocker.ts"
import type { UseNetworkBlockerOptions } from 'c15t/vue/vue-plugin';

export const networkBlocker = {
	onRequestBlocked: (info) => {
		console.info('Blocked until consent', info.method, info.url);
	},
	rules: [
		{ category: 'measurement', domain: 'google-analytics.com' },
		{
			category: 'marketing',
			domain: 'facebook.com',
			methods: ['POST'],
			pathIncludes: '/tr',
		},
	],
} satisfies UseNetworkBlockerOptions;
```

Pass them to the plugin in `src/main.ts`:

```ts title="src/main.ts"
app.use(c15tVue, { mode: manifest(), networkBlocker, scripts });
```

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains, so `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows a rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. `category`
also takes conditions such as `{ and: ['measurement', 'marketing'] }`.

Add `vendor` with a vendor ID to also block the request while the visitor has
turned that vendor off. Rules for IAB TCF vendors use `vendorId` and the
`iabPurposes` fields instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|Required|The rules above.|
|`enabled`|`true`|`false` keeps the rules but stops blocking.|
|`logBlockedRequests`|`true`|Logs each blocked request with `console.warn`.|
|`onRequestBlocked`|Unset|Called with `{ method, url, rule }` for each blocked request.|

## What a blocked request looks like

A blocked `fetch` resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The plugin starts holding matching requests when `app.use(c15tVue, ...)`
runs, before your app mounts. While consent is unknown, a matching request
waits instead of failing. Once the policy has loaded and the stored choice
applies, a waiting request is sent if consent allows it and blocked
otherwise. If the policy fails to load, optional categories stay denied and
waiting requests are blocked.

## What it cannot stop

The blocker sees only `fetch` and `XMLHttpRequest` calls made after
`app.use()` runs. It cannot stop:

* Scripts in `index.html` and modules that run before `src/main.ts`.
* Code that saved its own reference to `fetch` before the plugin installed.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests from
  `<img>`, `<script>` and `<iframe>` elements, web workers and service
  workers.

Check `useConsent()` before you call a vendor from your own code, and treat
the blocker as a backstop.

## Verify

Open the Network tab, clear site data and reload. Requests that match a rule
do not appear until you allow their category, and the console lists each
blocked request. Reject, reload, and check that they still do not appear.

# Vendor consent
URL: https://c15t.com/docs/frameworks/vue/vendor-consent
Let visitors allow a category such as marketing in a Vue app and still turn off one vendor in it, with the vendors option on the c15tVue plugin and useConsentDraft.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in `src/scripts.ts`, using the `vendor`
slug each script already carries:

```ts title="src/scripts.ts (partial)"
import type { Vendor } from 'c15t';

export const vendors: Vendor[] = [
	{
		id: 'x-pixel',
		name: 'X Pixel',
		category: 'marketing',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];
```

Then pass them to the plugin in `src/main.ts`:

```ts title="src/main.ts (partial)"
import { scripts, vendors } from './scripts';

createApp(App)
	.use(c15tVue, { mode: manifest(), scripts, vendors })
	.mount('#app');
```

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. For an iframe, add `data-vendor` and use
the iframe blocker; see [embeds](/docs/frameworks/vue/embeds).

## What the preference dialog shows

`ConsentManager`, which `ConsentRoot` renders, and `ConsentWidget` list each
declared vendor under its category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`useConsentDraft()` from `c15t/vue/vue-plugin` holds the category and vendor
switches of a preference form. `vendors` has one value per declared vendor,
`setVendor(id, granted)` changes one, and `save()` records the categories and
the vendors that changed:

```vue title="src/components/x-pixel-switch.vue (partial)"
<script setup lang="ts">
import { useConsentDraft } from 'c15t/vue/vue-plugin';

const { vendors, setVendor, save } = useConsentDraft();
</script>

<template>
	<input
		type="checkbox"
		:checked="vendors['x-pixel'] ?? true"
		@change="setVendor('x-pixel', ($event.target as HTMLInputElement).checked)"
	/>
	<button type="button" @click="save()">Save</button>
</template>
```

`save()` resolves `{ ok: false }` without recording anything while `isStale`
is `true`. [Composables](/docs/frameworks/vue/composables) covers the draft.

## Check whether a vendor may run

`useVendorAllowed(id)` from `c15t/vue/vue-plugin` returns a computed that is
`true` while the vendor may run: it is declared, its category is allowed and
the visitor has not switched it off.

```vue title="src/components/x-pixel-status.vue (partial)"
<script setup lang="ts">
import { useVendorAllowed } from 'c15t/vue/vue-plugin';

const xPixelAllowed = useVendorAllowed('x-pixel');
</script>
```

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/vue/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a Vue app when that category is denied, with the clearOnRevocation option on the c15tVue plugin.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns and pass them to the
plugin in `src/main.ts`. When that category is denied, c15t deletes them:

```ts title="src/main.ts (partial)"
createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts,
		clearOnRevocation: {
			measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
			marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
		},
	})
	.mount('#app');
```

The plugin reads `clearOnRevocation` once, when the app mounts.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/vue/customize
Change the c15t banner and dialog in a Vue app with theme tokens, layout presentation, component slots and copy.

## Pick the right option

|You want to change|Use|
|--|--|
|Colors, fonts, radius, spacing or motion|`tokens`|
|Banner shape, position, button order or blocking|`presentation`|
|Classes or attributes on one part of a component|`components`|
|Light or dark colors|`colorScheme` and `theme.dark`|
|The text|Your Inth project's translations|
|The markup|[Headless](/docs/frameworks/vue/headless)|

The [customization overview](/docs/customization/overview) explains these
choices across frameworks. All three options go in the object you pass to
`app.use(c15tVue, ...)`.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## A customized setup

This `src/main.ts` sets brand tokens, shows the banner as a bar along the
bottom of the page, and adds a class to the banner card:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';
import { scripts } from './scripts';

createApp(App)
	.use(c15tVue, {
		components: { banner: { card: { class: 'brand-consent-card' } } },
		mode: manifest(),
		presentation: { prompt: { position: 'bottom', variant: 'bar' } },
		scripts,
		tokens: {
			'c15t-primary': '#6943a3',
			'c15t-primary-hover': '#533285',
			'c15t-radius-lg': '18px',
			'c15t-text-on-primary': '#ffffff',
		},
	})
	.mount('#app');
```

The banner appears as a bar along the bottom of the page, its primary buttons
use the brand purple, and the card gets the border that your stylesheet sets
for `brand-consent-card`.

## Set theme tokens

`tokens` sets c15t's CSS variables. Keys are the variable names without the
leading `--`. [Theme tokens](/docs/customization/tokens) lists every token.

The c15tVue plugin adds every token, including the defaults you did not set,
to `document.head` in a `<style id="c15t-css-vars">` element when you install
it, before the first render. Every c15t component gets them, with or without
`ConsentRoot`. A `:root` rule in your stylesheet can lose to that element
depending on stylesheet order, so set token values through the `tokens`
option. `defineTheme` from `c15t/vue/vue-plugin` only types a theme object; it
does not apply anything.

## Change the banner layout

`presentation.prompt` sets the banner's `variant`, `position`, `layout`,
`primaryActions`, `direction`, `uiProfile` and `blocking`.
`presentation.preferences` sets the same layout fields for the dialog.

`variant` is `'floating'`, `'bar'`, `'widget'` or `'wall'`, and each accepts
its own positions. `bar` takes `top` or `bottom`, `wall` takes `center`,
`widget` takes the four corners, and `floating` takes the corners plus
`top-center` and `bottom-center`. The policy still has the last word. A choice
wall always blocks, a notice never blocks, and the policy can restore a
required button you left out of `layout`.

[`ConsentBanner`](/docs/frameworks/vue/components/consent-banner#props) also
takes `variant`, `position` and `blocking` as props when you render it
yourself.

## Style one part of a component

`components` adds attributes to named parts, such as the banner card or the
floating trigger. The keys match the
[component parts](/docs/customization/slots). Vue binds these objects with
`v-bind`, so use Vue attribute names such as `class` and `style`. React's
`className` does not apply. The `ConsentGate` placeholder's parts are
`components['consent-gate'].root`, `.title` and `.button`.
[Tailwind CSS](/docs/customization/tailwind) shows the Vue setup for Tailwind 4
and 3, and [class names and CSS-in-JS](/docs/customization/class-names) covers
other class sources.

## Turn on dark mode

`colorScheme` in the `c15tVue` options decides when the banner and dialog turn dark:
`'light'`, `'dark'`, `'system'`, or unset to copy a `dark` class on `<html>`.
The plugin ships c15t's stock dark palette, so a `dark` class alone turns the
banner dark. `theme` takes the same token
object as the other frameworks, including `theme.dark`, and wins over `tokens`
where both set a variable.
[Dark mode](/docs/customization/dark-mode) covers each value and a dark first
paint.

## Change the copy

The banner and dialog text come from the translations of your Inth project,
resolved for the visitor's language. Edit them there. `legalLinks` adds links
to your privacy policy and similar pages:

```ts title="src/main.ts"
app.use(c15tVue, {
	bannerLegalLinks: ['privacyPolicy'],
	legalLinks: { privacyPolicy: { href: '/privacy' } },
	mode: manifest(),
	scripts,
});
```

[Translations](/docs/frameworks/vue/translations) covers the visitor's
language, and [copy and translations](/docs/customization/translations) covers
message keys and writing labels.

## Other display options

|Option|What it does|
|--|--|
|`showTrigger`|Renders the floating [`ConsentDialogTrigger`](/docs/frameworks/vue/components/consent-dialog-trigger) from `ConsentRoot`.|
|`triggerDefaultPosition`, `triggerSize`, `triggerIcon`, `triggerShowWhen`|Place and style that trigger.|
|`hideBranding`, `bannerHideBranding`, `dialogHideBranding`|Hide the "Secured by" tag.|
|`disableAnimation`|Turns off banner and dialog animations. See [motion and animation](/docs/customization/motion).|
|`consentCategories`|Limits the categories the dialog shows, within the policy's scope.|

## Check the result

Run `vite` and open the app in a private window so the banner shows. In the
Elements panel, the `<style id="c15t-css-vars">` element in `<head>` holds
your token values.

# Translations
URL: https://c15t.com/docs/frameworks/vue/translations
Where the c15t banner and dialog text comes from in a Vue app, how c15t picks the visitor's language, and how to switch it at runtime.

## Where the text comes from

The banner, dialog and IAB text comes from the translations in your Inth
project, or your self-hosted backend's configuration. The backend sends the
text for the visitor's language with the policy. Edit copy there, not in your
Vue code. The Vue plugin has no option for message overrides.

[Copy and translations](/docs/customization/translations) lists the message
keys and how to write labels that describe each action.

## How c15t picks the language

By default the browser's own language decides. With `manifest()`, c15t reads
`navigator.language` and resolves the text from the manifest. With
`hosted()`, the browser sends it as `Accept-Language` with the policy request
to `/init`. When your project has no text for that language, the policy's
fallback language applies.

`manifest()` bundles English base copy only. When a visitor resolves to
another language, the browser loads that language's base copy from your site
the first time it is needed. Each visitor downloads their own language only,
and English visitors download no extra copy.

The text direction follows the resolved language. Arabic, Hebrew and other
right-to-left languages render the banner and dialog with `dir="rtl"`, and a
default corner position mirrors.

## Follow your site's language

Bind the `language` prop of `ConsentRoot` to your site's current language.
When the prop changes, `ConsentRoot` stores the language and resolves the
policy again, which fetches the text in that language:

```vue
<ConsentRoot :language="locale" />
```

Without `ConsentRoot`, assign the language to `useConsentLanguage()`. A new
language runs init again, which fetches the banner and dialog text in that
language. Assigning the current language does nothing:

```vue title="src/LanguageSwitcher.vue"
<script setup lang="ts">
import { useConsentKernel, useConsentLanguage } from 'c15t/vue/vue-plugin';

const language = useConsentLanguage();
const kernel = useConsentKernel();

// Resolving again with `init()` loads the banner and dialog text in the
// new language.
const switchTo = (code: string) => {
	language.value = code;
	void kernel.commands.init();
};
</script>

<template>
	<button type="button" @click="switchTo('en')">English</button>
	<button type="button" @click="switchTo('de')">Deutsch</button>
</template>
```

The assignment alone loads the new text. The example's extra
`kernel.commands.init()` call repeats the request and is not needed.

## Text that does not come from translations

`ConsentDialogLink` and the `ConsentGate` placeholder read their default
text from the translations, in English until init has delivered copy. One
label in the Vue components is a c15t option instead. Set it in the visitor's
language when your site has more than one:

|Text|Where|How to change it|
|--|--|--|
|"Open privacy settings"|`ConsentDialogTrigger` label|Set the `triggerAriaLabel` option.|

## Verify

Set your browser's preferred language to one your project translates, open
the app in a private window and confirm the banner uses it. Switch the
language with your switcher and confirm the banner and dialog text change
without a page reload.

# Headless
URL: https://c15t.com/docs/frameworks/vue/headless
Build your own consent banner and preference form in a Vue app with the c15t composables instead of ConsentRoot.

## When to go headless

Tokens, `presentation` and `components` slots change most designs without
new markup. See [customize](/docs/frameworks/vue/customize) first. Go
headless when the consent UI has to be your own markup, such as a design
system component.

Headless changes only the UI. The Vue plugin still resolves the policy,
stores choices, loads your `scripts` and gates iframes.

## Install the plugin as usual

Install `c15tVue` exactly as in the [quickstart](/docs/frameworks/vue/quickstart),
with the Vite plugin and your `scripts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';
import { scripts } from './scripts';

createApp(App).use(c15tVue, { mode: manifest(), scripts }).mount('#app');
```

## Write the consent UI

This component shows a banner while `activeUI` is `'banner'` and a preference
form while it is `'manager'`:

```vue title="src/ConsentPrompt.vue"
<script setup lang="ts">
import {
	useConsentActiveUI,
	useConsentDraft,
	useConsentSave,
} from 'c15t/vue/vue-plugin';

const activeUI = useConsentActiveUI();
const saveConsent = useConsentSave();
const { displayedCategories, save: saveDraft, values } = useConsentDraft();

// Recording a choice satisfies the prompt, so c15t closes the banner itself.
const choose = (choice: 'all' | 'none') => {
	void saveConsent(choice);
};

// Preferences stay open until you close them. c15t records the draft
// locally before the network request, so closing right away is safe.
const savePreferences = () => {
	void saveDraft();
	activeUI.value = null;
};
</script>

<template>
	<section
		v-if="activeUI === 'banner'"
		class="consent-prompt"
		aria-label="Cookie consent"
	>
		<p>We use cookies for measurement and marketing.</p>
		<button type="button" @click="choose('none')">Reject all</button>
		<button type="button" @click="choose('all')">Accept all</button>
		<button type="button" @click="activeUI = 'manager'">Customize</button>
	</section>
	<section
		v-else-if="activeUI === 'manager'"
		class="consent-prompt"
		aria-label="Privacy settings"
	>
		<label v-for="category in displayedCategories" :key="category">
			<input
				v-model="values[category]"
				type="checkbox"
				:disabled="category === 'necessary'"
			/>
			{{ category }}
		</label>
		<button type="button" @click="savePreferences">Save</button>
	</section>
</template>
```

`useConsentSave()` records Accept all or Reject all. Recording a choice
satisfies the prompt, so c15t sets `activeUI` to `null` and the banner closes.
`useConsentDraft()` holds the preference form. `displayedCategories` lists the
categories the policy lets the visitor choose, `values` holds each switch, and
`save()` records them. Preferences stay open after a save, so close them
yourself. [Composables](/docs/frameworks/vue/composables#build-a-preference-form)
lists every field of the draft.

Add focus handling, a close control and styles before you ship this. The
component keeps the bare markup so the consent logic is easy to read.

## Mount it instead of ConsentRoot

Render your component where `ConsentRoot` would go, and keep a way to reopen
preferences:

```vue title="src/App.vue"
<script setup lang="ts">
import { useConsentActiveUI } from 'c15t/vue/vue-plugin';

import ConsentPrompt from './ConsentPrompt.vue';
import HomePage from './HomePage.vue';

const activeUI = useConsentActiveUI();
</script>

<template>
	<ConsentPrompt />
	<HomePage />
	<footer>
		<button type="button" @click="activeUI = 'manager'">
			Privacy settings
		</button>
	</footer>
</template>
```

Setting `activeUI` to `'manager'` opens your preference form. Do not render
`ConsentRoot` as well, or the visitor sees two banners.

## Show the buttons the policy requires

A policy can require buttons and forbid others. For a notice, it requires a
dismiss action instead of Accept and Reject. Read the resolved actions with
`useConsentPolicyActions('prompt')` and render `primaryActions` and
`actionGroups` from it, rather than hard-coding the buttons. Call
`useDismissNotice()` for a notice's dismiss action. Dismissing records an
acknowledgement, not consent.

`usePromptRequirement()` tells you whether the policy asks for a choice, a
notice or nothing.

## Verify the custom UI

Run through [verify consent](/docs/guides/verify-consent) with your
component. Check that Reject all is as easy to reach as Accept all, that the
preference form lists the policy's categories, and that a rejection survives a
reload.

# Components
URL: https://c15t.com/docs/frameworks/vue/components
Every c15t Vue component, its import path and what it renders, with a page for each one's props, behavior, accessibility and styling.

## Component reference

Every component reads the consent runtime that
[the c15tVue plugin](/docs/frameworks/vue/plugin) provides, so it must render
inside the app that called `app.use(c15tVue, ...)`. Each component imports its
own styles; there is no stylesheet to add.

Import every component except `ConsentDevTools` by name from
`c15t/vue/vue-plugin`. A bundler keeps only the components you import.

|Component|What it renders|
|--|--|
|[`ConsentRoot`](/docs/frameworks/vue/components/consent-root)|The banner and, once opened, the preference dialog. Switches to the IAB surfaces under an IAB policy when `iab` is set.|
|[`ConsentBanner`](/docs/frameworks/vue/components/consent-banner)|The first-layer banner on its own.|
|[`ConsentManager`](/docs/frameworks/vue/components/consent-manager)|The preference dialog on its own.|
|[`ConsentWidget`](/docs/frameworks/vue/components/consent-widget)|Category switches and save actions inline, for a privacy page.|
|[`ConsentDialogLink`](/docs/frameworks/vue/components/consent-dialog-link)|A button that opens preferences.|
|[`ConsentDialogTrigger`](/docs/frameworks/vue/components/consent-dialog-trigger)|A floating, draggable button that opens preferences.|
|[`ConsentGate`](/docs/frameworks/vue/components/consent-gate)|Its default slot while a category is allowed, otherwise its `placeholder` slot.|
|[`IABConsentBanner`](/docs/frameworks/vue/components/iab-consent-banner)|The IAB TCF first layer.|
|[`IABConsentDialog`](/docs/frameworks/vue/components/iab-consent-dialog)|The IAB TCF preference centre.|
|[`ConsentDevTools`](/docs/frameworks/vue/components/dev-tools)|A development panel for the consent runtime, from `c15t/vue/devtools`.|

```ts
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
```

The components ship as `.vue` files. Keep
[`consentManifest()`](/docs/frameworks/vue/quickstart#add-the-vite-plugin) in
`vite.config.ts`: it keeps them out of Vite's dependency pre-bundling, which
cannot compile them.

## ConsentRoot or the parts

`ConsentRoot` renders `ConsentBanner` and `ConsentManager`, or the IAB
components when `iab` is set, for the visitor's policy. Mount `ConsentRoot`, or mount the parts,
never both, or the visitor sees two banners. Use the parts when you need a
different variant per route or want to place the surfaces yourself.

## Building blocks

The stock surfaces are built from smaller components that
`c15t/vue/vue-plugin` also exports: `ConsentButton`, `ConsentSwitch`,
`ConsentActions`, `ConsentLink`, `ConsentDescription`, `ConsentTag` and
`ConsentBrandingIcon`. `ConsentLegalLinks` is only at
`c15t/vue/runtime/components/consent-legal-links.vue`. For consent UI in your own markup, use the
[headless composables](/docs/frameworks/vue/headless) instead. They give you
the policy's actions and the draft state without the stock markup.

# ConsentRoot
URL: https://c15t.com/docs/frameworks/vue/components/consent-root
Mount the c15t banner, preference dialog and floating trigger in a Vue app with one ConsentRoot component from c15t/vue/vue-plugin.

## Render `ConsentRoot` in your root component

Render `ConsentRoot` once in your root component, next to your page content.
Import it from `c15t/vue/vue-plugin`:

```vue title="src/App.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentRoot } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentRoot />
	<main>
		<h1>c15t with Vue</h1>
		<p>PostHog loads after you allow measurement.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

`ConsentRoot` reads the consent runtime that
[the c15tVue plugin](/docs/frameworks/vue/plugin) creates in `src/main.ts`.
Keep it in the root component so it stays mounted when the route changes.
It brings its own styles.

`ConsentRoot` is not a provider. The c15tVue plugin already gives every
component the consent runtime, so nothing needs to sit inside it. Render
`<ConsentRoot />` next to your page content as shown above. If you wrap your
content in it instead, the content still renders after the banner, dialog
and trigger, but wrapping adds nothing.

## What ConsentRoot renders

`ConsentRoot` picks the surfaces for the visitor's policy and the current
`activeUI`:

|Policy|`activeUI` is `'banner'`|`activeUI` is `'manager'`|
|--|--|--|
|Standard, opt-in or opt-out|[`ConsentBanner`](/docs/frameworks/vue/components/consent-banner)|[`ConsentManager`](/docs/frameworks/vue/components/consent-manager)|
|IAB TCF, with a vendor list|[`IABConsentBanner`](/docs/frameworks/vue/components/iab-consent-banner)|[`IABConsentDialog`](/docs/frameworks/vue/components/iab-consent-dialog)|

It also renders [`ConsentDialogTrigger`](/docs/frameworks/vue/components/consent-dialog-trigger)
when the `showTrigger` option is `true`.

Nothing renders until the visitor's policy has resolved. The dialog and the
IAB surfaces load as separate chunks. The IAB surfaces replace the standard
ones only when the `iab` option is set and the policy uses the `iab` model. After the page's `load` event,
`ConsentRoot` prefetches the dialog chunk in an idle moment, so the first
Customize click does not wait for the network. The dialog unmounts when it
closes.

## Theme tokens

`ConsentRoot` does not apply theme tokens. The c15tVue plugin adds every
token from the `tokens` option, including the defaults you did not set, to
`document.head` in a `<style id="c15t-css-vars">` element when you install
it, before the first render. Set token values through the `tokens` option
rather than a `:root` rule in your stylesheet. See
[customize](/docs/frameworks/vue/customize#set-theme-tokens).

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`country`|`string`|The location the backend detects|Overrides the visitor's country and resolves the policy again.|
|`region`|`string`|The location the backend detects|Overrides the visitor's region, such as `CA`, and resolves the policy again.|
|`language`|`string`|The browser language|Overrides the language and resolves again, which fetches the banner and dialog text in that language.|

Setting any prop sends it to the backend with the next policy request. Use
`country` and `region` to preview another region's policy while you build.
Bind `language` to your site's language switcher:

```vue
<ConsentRoot :language="locale" />
```

## Compose the surfaces yourself

`ConsentRoot` is the same as rendering `ConsentBanner`, `ConsentManager` and
the IAB components with the right conditions. To place or configure them
yourself, render them in place of `ConsentRoot`, as in
[ConsentBanner](/docs/frameworks/vue/components/consent-banner#import-the-banner-into-your-root-component). Do not
render `ConsentRoot` next to them, or the visitor sees two banners.

## Verify

Load the app in a private window under a policy that asks for consent. The
banner appears after the policy request to your backend completes. In the
Elements panel, the `<style id="c15t-css-vars">` element in `<head>` holds
the `--c15t-*` tokens. Click Customize and the preference dialog opens. Reject,
reload, and confirm the banner stays closed.

## Next steps

* [c15tVue plugin](/docs/frameworks/vue/plugin) lists the options
  `ConsentRoot` reads.
* [Customize](/docs/frameworks/vue/customize) changes tokens, layout and
  slots.
* [Headless](/docs/frameworks/vue/headless) replaces `ConsentRoot` with your
  own markup.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/vue/components/consent-banner
Render the c15t consent banner in a Vue app, choose its variant and position, and understand what it shows for each policy.

## Import the banner into your root component

`ConsentRoot` already renders `ConsentBanner`. Import the banner yourself
only when you compose the surfaces, for example to set its variant in the
template or to render it without `ConsentRoot`. Import it from
`c15t/vue/vue-plugin`:

```vue title="src/ConsentSurfaces.vue"
<script setup lang="ts">
import {
	ConsentBanner,
	ConsentDialogTrigger,
	ConsentManager,
} from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Render these in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

Render this component in your root component in place of `ConsentRoot`.
Render `ConsentManager` with it, or Customize opens nothing. A statically
imported `ConsentManager` is part of your main bundle, while `ConsentRoot`
loads the dialog as a separate chunk. Unlike `ConsentRoot`, these components
do not switch to the IAB surfaces under an IAB policy. The c15tVue plugin
still adds the `tokens` option to the page.

## What ConsentBanner renders

`ConsentBanner` renders the first-layer banner while `activeUI` is
`'banner'`. It renders nothing until the visitor's policy has resolved,
when the policy asks for no prompt, and when a `bannerModels` or `models`
option leaves out the policy's model.

The policy decides the buttons:

* A `choice` prompt shows Reject All, Accept All and Customize. Customize is
  the primary button by default, so Accept All and Reject All look the same.
* A `notice` prompt shows an OK button. When the policy grants an opt-out or
  preferences right, the banner adds a button styled as underlined text,
  labelled "Do not sell or share my data" or "Manage preferences", that
  opens preferences.
* A policy with prompt `none` shows no banner.

Each button runs one command. Accept All and Reject All record a choice for
every category the policy covers, and the banner closes. Customize sets
`activeUI` to `'manager'`, which opens `ConsentManager` if it is mounted.
OK records that the visitor dismissed the notice. Dismissing grants nothing
and leaves earlier refusals in place.

The text comes from the translations the backend resolved for the visitor:
`cookieBanner.title` and `cookieBanner.description` for a choice,
`cookieBanner.noticeTitle` and `cookieBanner.noticeDescription` for a
notice, and `common.acceptAll`, `common.rejectAll`, `common.customize` and
`common.acknowledge` for the buttons. `bannerLegalLinks` picks which of your
`legalLinks` appear under the description. The banner has no slots and no
text props.

`ConsentBanner` moves itself into `document.body` once it has mounted.
During server rendering it renders in place, so the banner can be part of
the server HTML.

## Variants and positions

The policy decides which actions the banner offers. The variant decides the
shape they take.

|Variant|Shape|Positions|Default position|
|--|--|--|--|
|`floating`|A card in a corner or centred on an edge. The default.|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|A full-width bar along the top or bottom edge.|`top`, `bottom`|`bottom`|
|`widget`|A compact card with smaller type.|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|A centred card over a backdrop that blocks the page.|`center`|`center`|

The policy has the last word. A choice `wall` always blocks. A notice never
blocks, and a notice `wall` falls back to `floating`. A position the variant
does not accept falls back to the variant's default. Each correction logs a
`[c15t]` warning in the browser console.

A default corner mirrors left and right for right-to-left languages. A
position you set is kept as written.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating' \|'bar' \|'widget' \|'wall'`|`presentation.prompt.variant`, else `'floating'`|Shape of the banner.|
|`position`|`PromptPosition`|`presentation.prompt.position`, else the variant's default|Where the banner sits. Must be valid for the variant.|
|`blocking`|`boolean`|`presentation.prompt.blocking`, else `true` for `wall` only|Backdrop, scroll lock and focus trap, as one value.|

A prop you set beats the matching `presentation.prompt` option. Leave a prop
unset to follow your c15t options. `PromptVariant` and `PromptPosition` are
exported as types from `c15t`.

To set the variant for every banner without importing the component, use
`presentation.prompt` in the plugin options. See
[customize](/docs/frameworks/vue/customize#change-the-banner-layout).

## Accessibility and focus

* A non-blocking banner is a `region` labelled with the banner title. It does
  not trap focus or lock scrolling, so the page stays usable with a keyboard
  and a pointer.
* A blocking banner is a `dialog` with `aria-modal="true"`. It shows a
  backdrop, locks page scrolling, moves focus to the banner card and keeps
  Tab inside the card.
* The banner has no close button, and Escape does not dismiss it. The
  visitor answers with one of its buttons.
* Every action is a native `button`. The banner sets `dir` from the resolved
  language.

## Style the banner

[Theme tokens](/docs/customization/tokens) change colors, type, radius,
spacing and motion. The `components.banner` option adds attributes, such as
`class` or `style`, to these parts: `root`, `overlay`, `cardShell`, `card`,
`header`, `title`, `footer`, `actions`, `actionGroup`, `rights` and
`rightLink`. `components.description.banner` and `components.tag.banner`
reach the description and the branding tag.
[Component slots](/docs/customization/slots) lists every part.

The root element carries attributes you can target from CSS:

|Attribute|Values|
|--|--|
|`data-variant`|`floating`, `bar`, `widget`, `wall`|
|`data-position`|The resolved position|
|`data-prompt`|`choice`, `notice`|
|`data-model`|`opt-in`, `opt-out`, `iab`|
|`data-blocking`|`true`, present only while blocking|

`bannerHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the enter and exit
transitions.

## Verify

Open the page in a private window under a policy that asks for a choice.
The banner appears with Reject All and Accept All side by side. Tab through
it and confirm every button is reachable. Click Customize and the preference
dialog opens. Reject, reload, and confirm the banner stays closed. In the
Elements panel, the root element carries the `data-variant` and
`data-position` you set.

## Next steps

* [ConsentManager](/docs/frameworks/vue/components/consent-manager) is the
  dialog Customize opens.
* [Headless](/docs/frameworks/vue/headless) builds a banner from your own
  markup.
* [Banner designs](/docs/customization/recipes) shows tested designs.

# ConsentManager
URL: https://c15t.com/docs/frameworks/vue/components/consent-manager
Render the c15t preference dialog in a Vue app, open it from your own code, and understand its actions, focus handling and styling.

## Import the dialog when you compose surfaces

`ConsentRoot` already renders `ConsentManager` when preferences open. Import
it yourself only when you compose the surfaces in place of `ConsentRoot`.
Import it from `c15t/vue/vue-plugin`:

```vue title="src/ConsentSurfaces.vue"
<script setup lang="ts">
import {
	ConsentBanner,
	ConsentDialogTrigger,
	ConsentManager,
} from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Render these in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

## Open the dialog from your code

Set `activeUI` to `'manager'` with `useConsentActiveUI()` from
`c15t/vue/vue-plugin`. The Vue adapter uses `'manager'` where the React
adapter uses `'dialog'`.

```ts
const activeUI = useConsentActiveUI();
activeUI.value = 'manager';
```

For a footer link, use
[ConsentDialogLink](/docs/frameworks/vue/components/consent-dialog-link),
which hides itself when the policy offers no preferences.

## What ConsentManager renders

`ConsentManager` is the preference dialog, the component the React adapter
calls `ConsentDialog`. It opens while `activeUI` is `'manager'`. Anything
that sets `activeUI` to `'manager'` opens it: the banner's Customize button,
`ConsentDialogLink`, `ConsentDialogTrigger` and your own code. It
renders nothing until the visitor's policy has resolved, and nothing when
the policy owes no consent UI.

The dialog holds the same content as `ConsentWidget`: a list of the
categories the policy lets the visitor choose, each with a switch and a
description, and the vendors you declared under each category. Necessary is
always on. The footer shows Reject All, Accept All and Save Settings, with Save Settings as the
primary button.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* After a successful action the dialog closes. The banner comes back only if
  the policy still requires a choice.
* Escape closes the dialog without saving. The banner comes back if the
  policy still requires a choice.
* If the policy changes while the dialog is open, the dialog shows "Privacy
  choices have changed." with a button that reloads the switches from the
  new policy. Save stays blocked until the visitor reviews them.

The title comes from `consentManagerDialog.title` in the resolved
translations. `dialogLegalLinks` picks which of your `legalLinks` appear
under the description. The dialog has no props, slots or text props.

## Accessibility and focus

The dialog renders in `document.body` with `role="dialog"`, labelled by its
title and described by its description. By default it is modal: it shows a
backdrop, sets `aria-modal="true"`, locks page scrolling, moves focus to the
first control inside and keeps Tab inside the dialog. When it closes, focus
returns to the element that had it before. Set
`presentation.preferences.blocking` to `false` for a non-modal dialog with
no backdrop.

Each category switch is a `button` with `role="switch"`, `aria-checked` and
the category title as its label. Each category row expands with a button
that sets `aria-expanded` and `aria-controls`.

## Style the dialog

The `components.dialog` option adds attributes to `root`, `overlay`,
`container`, `card`, `header`, `title` and `content`. The category list
inside uses `components.manager`, `components.accordion`,
`components['accordion-item']`, `components.switch` and
`components['vendor-list']`. [Component slots](/docs/customization/slots)
lists every part. `presentation.preferences` sets the footer's `layout`,
`primaryActions`, `direction`, `uiProfile` and `blocking`.

`dialogHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the transitions.

## Verify

Open preferences, turn one optional category on and click Save. The dialog
closes. Reload and open preferences again: the switch is still on. Press
Escape with the dialog open and confirm it closes and focus returns to the
control that opened it.

## Next steps

* [ConsentWidget](/docs/frameworks/vue/components/consent-widget) renders the
  same controls inline on a page.
* [IABConsentDialog](/docs/frameworks/vue/components/iab-consent-dialog)
  replaces this dialog under an IAB policy when `iab` is set.
* [Customize](/docs/frameworks/vue/customize) sets tokens and slots.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/vue/components/consent-widget
Put the c15t category switches and save actions inline on a Vue privacy settings page with ConsentWidget from c15t/vue/vue-plugin.

## Import the widget into your settings page

Import `ConsentWidget` from `c15t/vue/vue-plugin` and render it on your
privacy or account settings page:

```vue title="src/PrivacySettings.vue"
<script setup lang="ts">
import { ConsentWidget } from 'c15t/vue/vue-plugin';
</script>

<template>
	<section aria-labelledby="privacy-settings-title">
		<h1 id="privacy-settings-title">Privacy settings</h1>
		<p>Choose which optional cookies this site may use.</p>
		<ConsentWidget />
	</section>
</template>
```

Render the page inside the app that installed
[the c15tVue plugin](/docs/frameworks/vue/plugin). Keep `ConsentRoot` mounted
too, so visitors on other pages still get the banner.

## What ConsentWidget renders

`ConsentWidget` renders the preference controls inline, in the page flow,
for a privacy or account settings page. It shows the categories the policy
lets the visitor choose, each with a switch that expands to its description
and declared vendors, and a footer with Reject All, Accept All and Save Settings.
Necessary is always on and its switch is disabled.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* The switches start from the visitor's recorded choice. Before any choice,
  they start from the policy's defaults: on under an opt-out policy or for
  preselected categories, otherwise off.
* A choice saved elsewhere, such as in the banner, updates switches the
  visitor has not touched and keeps the ones they moved.
* If the policy changes, the widget shows "Privacy choices have changed."
  with a button that reloads the switches. Save stays blocked until then.

The widget renders nothing until the visitor's policy has resolved, and
nothing when the policy owes no consent UI. It does not open or close any
other surface. `ConsentManager` renders the same widget inside the dialog.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Hides the "Secured by" tag.|
|`noStyle`|`boolean`|`false`|Drops the built-in classes from every part, so your own CSS starts from plain markup.|
|`language`|`string`|The resolved language|Sets the text direction. It does not change the text.|

## Accessibility

Each switch is a `button` with `role="switch"`, `aria-checked` and the
category title as its label. Each row expands with a button that sets
`aria-expanded` and `aria-controls`, and one row is open at a time. The
footer actions are native buttons. Give the page a heading that names the
widget, as in the example above.

## Style the widget

The widget reads `components.manager` for its root and footer,
`components.accordion` and `components['accordion-item']` for the rows,
`components.switch` for the switches and `components['vendor-list']` for
vendor rows. [Component slots](/docs/customization/slots) lists every part.
`presentation.preferences` sets the footer's `layout`, `primaryActions`,
`direction` and `uiProfile`, and applies to the dialog too.

## Verify

Open the page with the widget in a private window. Turn **Analytics** (the `measurement` category) on and
click Save. Reload: the switch is still on, and scripts gated on
measurement load. Turn it off and save, and the page reloads without them.

## Next steps

* [ConsentManager](/docs/frameworks/vue/components/consent-manager) shows
  these controls in a dialog.
* [Composables](/docs/frameworks/vue/composables#build-a-preference-form)
  build a preference form from your own markup.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/vue/components/consent-dialog-link
Add a Privacy settings button that reopens the c15t preference dialog in a Vue app, and hide it when the policy offers no preferences.

## Import the link into your footer

Import `ConsentDialogLink` from `c15t/vue/vue-plugin` and put it in your
footer, next to your privacy policy link:

```vue title="src/App.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentRoot } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentRoot />
	<main>
		<h1>c15t with Vue</h1>
		<p>PostHog loads after you allow measurement.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

Pass content in the default slot to change the label. The
[embed example](/docs/frameworks/vue/embeds) uses it inside a placeholder as
"Choose video permissions".

## What ConsentDialogLink renders

`ConsentDialogLink` renders one `button` that sets `activeUI` to
`'manager'`, which opens the preference dialog. It matches `ConsentDialogLink`
in the React adapter. It has no props. The default label is the
`consentManagerDialog.title` translation, "Privacy Settings" in English.
The link shows it in the visitor's language once init has delivered copy,
and in English until then. Its default slot replaces the label.

The button renders only while the visitor has somewhere to go:

* It is absent until the visitor's policy has resolved.
* It is absent when the policy owes no consent UI, such as a policy with no
  prompt and no rights.

The link opens the dialog only if something renders `ConsentManager`.
`ConsentRoot` does.

## Accessibility and styling

The component is a native `button` with `type="button"`, so it works with
Enter and Space and has no link semantics. Style it with your own classes on
the element: attributes you pass, such as `class`, go to the button. It
carries `data-testid="consent-dialog-link"` and `data-c15t-rights`, the
policy's rights separated by spaces.

## Verify

Load the page under a policy that asks for consent and click Privacy
Settings. The preference dialog opens. Under a policy with no prompt and no
rights, the button is absent from the DOM.

## Next steps

* [ConsentDialogTrigger](/docs/frameworks/vue/components/consent-dialog-trigger)
  is a floating alternative.
* [Composables](/docs/frameworks/vue/composables#open-the-banner-or-preferences)
  open preferences from your own button.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/vue/components/consent-dialog-trigger
Show a floating, draggable button that reopens the c15t preference dialog in a Vue app, and configure its corner, size, icon and label.

## Turn on the trigger in the plugin options

Turn the trigger on with `showTrigger` in the plugin options. `ConsentRoot`
then renders it:

```ts title="src/main.ts"
app.use(c15tVue, {
	mode: manifest(),
	scripts,
	showTrigger: true,
	triggerDefaultPosition: 'bottom-left',
});
```

When you compose the surfaces without `ConsentRoot`, import the trigger from
`c15t/vue/vue-plugin` and render it yourself:

```vue title="src/ConsentSurfaces.vue"
<script setup lang="ts">
import {
	ConsentBanner,
	ConsentDialogTrigger,
	ConsentManager,
} from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Render these in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

## What ConsentDialogTrigger renders

`ConsentDialogTrigger` renders a round floating button, fixed to a corner of
the viewport, that opens the preference dialog. Visitors can drag it to
another spot. It has no props. Your c15t options configure it.

The trigger renders in the browser only, after mount, in `document.body`. It
hides while the preference dialog is open, until the visitor's policy has
resolved, and when the policy owes no consent UI. Under the default
`triggerShowWhen: 'after-consent'`, it also stays hidden while the banner
waits for an answer, and appears once the visitor saves a choice or
dismisses a notice.

While `ConsentDevTools` is mounted, the trigger becomes a two-button
toolbar: the preferences button in the corner and a DevTools button beside
it that opens the DevTools panel next to the toolbar.

## Options

|Option|Type|Default|Behavior|
|--|--|--|--|
|`showTrigger`|`boolean`|`false`|Makes `ConsentRoot` render the trigger.|
|`triggerDefaultPosition`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Starting corner.|
|`triggerSize`|`'sm' \|'md' \|'lg'`|`'md'`|32, 40 or 48 pixels.|
|`triggerIcon`|`'branding' \|'fingerprint' \|'settings'`|`'fingerprint'`|The icon inside the button. `'branding'` shows the c15t or Inth mark.|
|`triggerPersistPosition`|`boolean`|`true`|Remembers where the visitor dragged it, in localStorage under `c15t:dialog-trigger-position`.|
|`triggerShowWhen`|`'always' \|'after-consent' \|'never'`|`'after-consent'`|`'after-consent'` shows the trigger once the policy owes no prompt: the visitor saved a choice or dismissed a notice. `'always'` also shows it while the banner is open. `'never'` hides it.|
|`triggerAriaLabel`|`string`|`'Open privacy settings'`|The button's accessible name.|

All trigger options go in the object you pass to `app.use(c15tVue, ...)`.

## Accessibility and styling

The trigger is a native `button` with `aria-label` set from
`triggerAriaLabel`. The icon is hidden from assistive technology. Set
`triggerAriaLabel` in the visitor's language, because the default is
English.

The `components.trigger` option adds attributes to `root`, `icon` and
`text`. Setting `components.trigger.text`, even to `{}`, shows
`triggerAriaLabel` as visible text next to the icon. The button carries
`data-size` and, while dragged, `data-dragging`.
The toolbar shown while `ConsentDevTools` is mounted takes `toolbar`,
`toolbarItem` and `toolbarIcon` instead.

## Verify

Load a page under a policy with a prompt and answer the banner. Confirm the
button appears in the corner you set. Click it and the preference dialog opens while the
button hides. Drag it, reload, and confirm it keeps its place when
`triggerPersistPosition` is on.

## Next steps

* [ConsentDialogLink](/docs/frameworks/vue/components/consent-dialog-link)
  is an inline alternative for a footer.
* [c15tVue plugin](/docs/frameworks/vue/plugin) lists every option.

# ConsentGate
URL: https://c15t.com/docs/frameworks/vue/components/consent-gate
Render an iframe or widget in a Vue app only while its consent category is allowed, with a placeholder slot until then.

## Import `ConsentGate` and wrap an embed

Import `ConsentGate` from `c15t/vue/vue-plugin`.
Put the embed in the default slot and a placeholder in the `placeholder`
slot:

```vue title="src/VideoEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

The iframe is absent from the page until the visitor allows measurement. The
placeholder uses `ConsentDialogLink` so the visitor can open preferences
from it.

## What ConsentGate renders

`ConsentGate` renders its default slot while the visitor's effective
permission for `category` is granted, and its `placeholder` slot otherwise.
It adds no wrapper element. While permission is denied, the default slot
does not exist in the DOM, so an iframe or widget inside it sends no
requests. When the visitor withdraws permission, Vue removes the slot
content.

Permission is the same value `useConsent()` returns for the category. It can
be granted under an opt-out policy before the visitor has recorded a choice,
and a privacy signal such as Global Privacy Control can deny a category the
visitor granted.

Without a `placeholder` slot, the gate renders the same placeholder as the
React and Svelte gates. It shows the `consentGate.title` text with the
category name, and a button labelled with `consentGate.actionButton` that
opens the preference dialog. Under a strict policy that leaves the category
out, no choice can allow the content, so the placeholder shows
`consentGate.policyBlocked` and no button. The text is in the visitor's
language once init has delivered copy, and in English until then. The
placeholder is a card styled by your theme tokens and the
`--consent-gate-placeholder-*` variables. A `placeholder` slot replaces it
entirely.

To restyle the built-in placeholder instead, set its parts under
`components['consent-gate']` in the options. `root` is the card, and
`title` and `button` are its text and button. Use Vue attribute names such as `class` and `style`. The
`consentGate`, `consentGateTitle` and `consentGateButton` theme slots reach
the same parts. The placeholder carries
`data-testid="consent-gate-placeholder"`, its title
`data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

`ConsentGate` also adds its `category` to the categories the preference
dialog lists, so the button opens a dialog where the visitor can allow it.

## Props and slots

|Name|Kind|Type|Behavior|
|--|--|--|--|
|`category`|Prop, required|`'necessary' \|'functionality' \|'measurement' \|'experience' \|'marketing'`|The category whose permission gates the default slot.|
|`default`|Slot||The gated content, such as an iframe.|
|`placeholder`|Slot||Shown while the category is denied.|

## Accessibility

Give the iframe a descriptive `title`. Keep a way to reach the content
without the embed, such as a link or a transcript, for visitors who decline
the category. A policy can fix a category as denied, so opening preferences
does not guarantee the visitor can allow it.

## Verify

Load the page in a private window with the Network tab open. The placeholder
shows and no request goes to the embed's host. Allow the category in
preferences and save: the iframe appears and its requests start. Withdraw the
category and save: the page reloads without the iframe.

## Next steps

* [Embeds](/docs/frameworks/vue/embeds) compares `ConsentGate` with the
  iframe blocker.
* [YouTube](/docs/integrations/youtube) and
  [Google Maps](/docs/integrations/google-maps) show complete embeds.

# IABConsentBanner
URL: https://c15t.com/docs/frameworks/vue/components/iab-consent-banner
Render the IAB TCF first layer in a Vue app with IABConsentBanner, when to import it instead of relying on ConsentRoot, and its props.

## Import the IAB banner in place of `ConsentRoot`

`ConsentRoot` renders `IABConsentBanner` for you when the plugin's `iab`
option is set and the visitor's policy uses IAB TCF. Import it only when every policy on your site is IAB and you
compose the surfaces yourself. Import it from
`c15t/vue/vue-plugin`:

```vue title="src/IabSurfaces.vue"
<script setup lang="ts">
import { IABConsentBanner, IABConsentDialog } from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

Render this in place of `ConsentRoot`, and set the plugin's `iab` option; see
[IAB TCF](/docs/frameworks/vue/iab). A visitor whose policy is not IAB sees
nothing from these components. Without `iab`, an IAB policy throws an
`IABUnavailableError` instead.

## What IABConsentBanner renders

`IABConsentBanner` is the IAB TCF first layer. It renders while `activeUI`
is `'banner'`, the `iab` option is set, and the visitor's policy uses the
`iab` model with a vendor list. `ConsentRoot` renders it in place of
`ConsentBanner` under such a policy, so you only import it to compose the
surfaces yourself.

The banner lists the purposes, stacks and special features your vendors
use, with the vendor count as a link. Its footer has Reject All, Accept All
and Customize.

* Accept All and Reject All save an IAB choice and write the TC String. The
  banner waits for the full Global Vendor List before it saves. If the list
  fails to load, the banner stays open and nothing is granted.
* Customize opens the IAB preference centre on its Purposes tab.
* The vendor count link opens it on its Vendors tab.

Its text comes from the IAB translations the backend resolved. The component
loads its own styles.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'reject' \|'accept' \|'customize'`|`'customize'`|Which action gets the primary style.|

Keep Accept All and Reject All at the same prominence unless your legal
review says otherwise.

## Accessibility and styling

The banner renders in `document.body`. When the prompt is blocking it is a
`dialog` with `aria-modal="true"` and traps focus. Otherwise it is a
`region`. The `components['iab-banner']` option adds attributes to its
parts, such as `root`, `card`, `title`, `purposeList`, `partnersLink` and
`footer`. `iabBannerHideBranding` hides the "Secured by" tag, and
`iabBannerModels` limits which policy models show it.

## Next steps

* [IAB TCF](/docs/frameworks/vue/iab) turns on IAB in your policy and
  verifies the TC String.
* [IABConsentDialog](/docs/frameworks/vue/components/iab-consent-dialog) is
  the preference centre this banner opens.

# IABConsentDialog
URL: https://c15t.com/docs/frameworks/vue/components/iab-consent-dialog
Render the IAB TCF preference centre in a Vue app with IABConsentDialog, choose its first tab, and build a custom one with composables.

## Import the IAB dialog when you compose surfaces

`ConsentRoot` loads `IABConsentDialog` for you when the plugin's `iab` option
is set, the visitor's policy uses IAB TCF and preferences open. Import it only when you compose the IAB
surfaces yourself. Import it from
`c15t/vue/vue-plugin`:

```vue title="src/IabSurfaces.vue"
<script setup lang="ts">
import { IABConsentBanner, IABConsentDialog } from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

## What IABConsentDialog renders

`IABConsentDialog` is the IAB TCF preference centre. It opens while
`activeUI` is `'manager'`, the `iab` option is set, and the policy uses the
`iab` model. `ConsentRoot` loads it in place of `ConsentManager` under such
a policy.

It has two tabs. Purposes lists each purpose, stack and special feature with
consent and legitimate-interest switches. Vendors lists every vendor,
including your custom vendors, with a search field and per-vendor switches.
The footer saves the selection, or accepts or rejects everything, and writes
the TC String.

To build your own preference centre instead, read and change the selection
with `useConsentIabSelection()` and save it with `useConsentIabSave()`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`initialTab`|`'purposes' \|'vendors'`|The tab the banner asked for, else `'purposes'`|Which tab the dialog opens on.|

## Accessibility and styling

The dialog renders in `document.body` with `role="dialog"`. While blocking
it sets `aria-modal="true"`, locks scrolling and traps focus. It has a close
button. The `components['iab-dialog']` option adds attributes to parts such
as `root`, `card`, `header`, `tabsList`, `tabPanel` and `footer`, and
`components['iab-purpose-item']`, `components['iab-stack-item']` and
`components['iab-vendor-list']` reach the rows. `iabDialogHideBranding`
hides the "Secured by" tag.

## Next steps

* [IAB TCF](/docs/frameworks/vue/iab) covers vendor list loading and
  verification.
* [Composables](/docs/frameworks/vue/composables#iab-tcf) documents
  `useConsentIabSelection()` and `useConsentIabSave()`.

# Composables
URL: https://c15t.com/docs/frameworks/vue/composables
Every c15t composable for a Vue app, grouped by task, with the difference between a permission and a recorded choice.

## Import composables

Import every composable from `c15t/vue/vue-plugin`, the same entry point as
the plugin. This component reads the visitor's permission and recorded
choice, and opens preferences:

```vue title="src/ConsentStatus.vue"
<script setup lang="ts">
import {
	useConsent,
	useConsentActiveUI,
	useExplicitChoice,
} from 'c15t/vue/vue-plugin';

// May measurement code run right now?
const permissions = useConsent();
// What did the visitor decide? `null` until they accept, reject or save.
const choice = useExplicitChoice();
const activeUI = useConsentActiveUI();
</script>

<template>
	<section aria-label="Your privacy choices">
		<p v-if="choice">You saved your privacy choices.</p>
		<p v-else>You have not made a privacy choice yet.</p>
		<p>
			Measurement is
			{{ permissions.measurement ? 'allowed' : 'not allowed' }} right now.
		</p>
		<button type="button" @click="activeUI = 'manager'">
			Change your choices
		</button>
	</section>
</template>
```

Use `v-if`, not `v-show`, when optional content loads anything from a third
party. For iframes use [`ConsentGate`](/docs/frameworks/vue/components/consent-gate),
and for vendor scripts use the plugin's `scripts` option. See
[scripts](/docs/frameworks/vue/scripts).

## Where composables work

Call the composables inside `setup` of a component that renders in the app
where c15t is installed. Anywhere else they throw an error such as
`[c15t] Kernel not found`. Most return a Vue `computed`, so read them with
`.value` in `<script setup>` and without it in the template. They update
whenever the consent runtime changes.

## Permission or recorded choice

`useConsent()` and `useHasConsent()` answer "may this run now?" Under an
opt-out policy a category can be allowed before the visitor has done
anything, and Global Privacy Control can deny a category the visitor
allowed. Use them to decide whether to run code or render optional content.

`useExplicitChoice()` answers "what did the visitor decide?" It stays
`null` until the visitor accepts, rejects or saves. Use it to show the
visitor's choice or to report consent rates. Loading a page never changes
it, and dismissing a notice does not set it.

Never save a choice on the visitor's behalf because a permission is `true`.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Read consent state

|Composable|Returns|Use it to|
|--|--|--|
|`useConsent()`|Computed `Record<category, boolean>`|Read every category's current permission, such as `consent.value.marketing`.|
|`useHasConsent()`|Computed array of allowed categories|List what may run now. The array keeps its identity until a category changes.|
|`useEffectivePermissions()`|Computed permissions|The same values as `useConsent()`, read from the snapshot field.|
|`useVendorAllowed(id)`|Computed `boolean`|Check whether one vendor may run: it is declared, its category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`useExplicitChoice()`|Computed recorded choice, or `null`|Read what the visitor decided.|
|`useStoredConsent()`|Computed recorded choice, or `null`|The same value as `useExplicitChoice()`.|
|`useNoticeDismissal()`|Computed dismissal record, or `null`|Check whether the visitor dismissed a notice.|
|`usePrivacySignals()`|Computed privacy signals|Read whether Global Privacy Control was detected and applied.|
|`useConsentRestrictions()`|Computed restrictions|See why a permission is limited, for example by the policy or a privacy signal.|
|`usePolicyRule()`|Computed policy rule|Read the `model`, `prompt`, `scope` and `rights` of the visitor's policy.|
|`usePolicyResolution()`|Computed resolution|Check that a policy matched. `status` is `'matched'` when one applies.|
|`useRequestRegion()`|Computed `{ country, region }`|Read the location the policy resolved for.|

## Before the policy resolves

The plugin starts with every optional category denied and no recorded choice
read. The composables update once the browser has read the stored choice and
the policy arrives. Until then `useConsentSnapshot().value.policyPending` is
`true` and `usePolicyResolution()` reports a status other than `'matched'`,
so you can hold back UI that depends on the answer.

## Record a choice

`useConsentSave()` returns a function that records a choice and resolves to
`{ ok }` once the backend has answered. c15t applies the choice in the page
before the request, so gated scripts start without waiting for it.

|Argument|Records|
|--|--|
|`'all'`|Every category the policy covers allowed.|
|`'none'`|Every optional category denied.|
|`['measurement']`|The listed categories allowed and every other optional category denied.|

`useDismissNotice()` returns the function that dismisses a notice. It
records an acknowledgement, grants nothing and leaves earlier refusals in
place. Use it only for a policy whose prompt is `notice`.

## Open the banner or preferences

`useConsentActiveUI()` returns a writable computed. Its value is
`'banner'`, `'manager'` or `null`. Set it to `'manager'` to open
preferences, to `'banner'` to show the banner again, or to `null` to close
both. The Vue adapter uses `'manager'` where the React adapter uses
`'dialog'`. `ConsentDialogLink` does the same as setting `'manager'` and
hides itself when the policy offers no preferences.

## Change the language

`useConsentLanguage()` returns a writable computed with the language
override, or `null`. Assigning a new language code stores it and runs init
again, so c15t fetches the banner and dialog text in that language.
Assigning the current language, or `null`, does nothing.

The `language` prop on [`ConsentRoot`](/docs/frameworks/vue/components/consent-root#props)
does the same from a template binding. See
[translations](/docs/frameworks/vue/translations).

## Build a preference form

`useConsentDraft()` holds the switches of a preference form separately from
the recorded choice, so nothing is saved until the visitor clicks Save.

|Field|Type|Meaning|
|--|--|--|
|`displayedCategories`|`ComputedRef<category[]>`|The categories the policy lets the visitor choose, in the order necessary, functionality, measurement, experience, marketing.|
|`values`|`Ref<Partial<Record<category, boolean>>>`|One value per category. Bind switches to it with `v-model`; a write to `necessary` or to a category the policy does not offer snaps back.|
|`vendors`|`ComputedRef<Record<string, boolean>>`|One value per declared vendor. Change them with `setVendor(id, granted)`.|
|`isDirty`|`ComputedRef<boolean>`|`true` while any value differs from the recorded choice.|
|`isStale`|`ComputedRef<boolean>`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change.|
|`save()`|`() => Promise<{ ok: boolean }>`|Records `values` and changed vendors. Resolves `{ ok: false }` without saving while `isStale` is `true`.|
|`reset()`|`() => void`|Refills the draft from the recorded choice and the policy.|

The draft starts from the recorded choice. Before any choice, it starts
from the policy's defaults: on under an opt-out policy or for preselected
categories, otherwise off. A choice saved elsewhere updates the values the
visitor has not touched. `save()` does not close anything. Set `activeUI`
to `null` yourself after it.

## Render the actions the policy requires

|Composable|Returns|Use it to|
|--|--|--|
|`usePromptRequirement()`|Computed `{ kind }`, where `kind` is `'choice'`, `'notice'` or `'none'`|Decide whether to show a banner at all.|
|`useConsentPolicyActions(surface)`|Computed `actionGroups`, `primaryActions`, `variant`, `position`, `blocking`, `direction` and `preferenceControls`|Render the buttons a banner (`'prompt'`) or preference form (`'preferences'`) must show, in order.|
|`useHasConsentPolicy()`|Computed boolean|Check that a policy matched the visitor.|
|`useHasConsentUi()`|Computed boolean|Check that the policy owes any consent UI. Every stock surface hides while it is `false`.|
|`useHasConsentPreferences()`|Computed boolean|Check whether a preferences control should render.|

Under a notice, `actionGroups` holds `dismiss` instead of accept and
reject. `preferenceControls` lists extra buttons, `'opt-out'` or
`'preferences'`, that open preferences under a policy with those rights.

[Headless](/docs/frameworks/vue/headless) builds a complete banner and
preference form from these composables.

## IAB TCF

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentIabSelection()`|Writable computed with purpose, legitimate-interest, vendor and special-feature maps, and `preferenceCenterTab`|Read and change the visitor's IAB selection in a custom preference centre. Writing it updates gating live without saving.|
|`useConsentIabSave()`|`(input, tab?) => Promise<void>`|Save `'all'`, `'none'` or a selection. It waits for the Global Vendor List, then writes the TC String.|
|`useIabTranslations()`|Computed IAB copy|Read the IAB banner and dialog text for the visitor's language.|

## Advanced

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentSnapshot()`|`Ref<ConsentSnapshot>`|Read any snapshot field, such as `policyPending`, `vendors` or `iab`.|
|`useConsentKernel()`|The consent kernel|Call `commands.init()`, `commands.save()`, `commands.identify(user)`, subscribe with `events.on(type, listener)`, or read `getSnapshot()`.|
|`useConsentConfig()`|Computed options, merged with defaults|Read the options you passed.|
|`useConsentInit()`|Computed `{ translations, location, branding, gvl, cmpId, customVendors }`, or `undefined` before the policy resolves|Read display data from the resolved policy.|
|`useConsentComponent(name)`|Computed slot attributes|Read the `components` option for one component, to reuse it in custom markup.|

`useConsentKernel().events.on()` returns an unsubscribe function. Call it in
`onUnmounted`. For choice and permission events, prefer the `callbacks`
option, which c15t wires once for the whole app.

See [callbacks](/docs/frameworks/vue/callbacks) for the `callbacks` option.

# Callbacks
URL: https://c15t.com/docs/frameworks/vue/callbacks
Run code in a Vue app when a visitor records a consent choice, when permissions change, before a revocation reload, and when c15t reports an error.

## Register callbacks

Pass `callbacks` to the plugin. Keep them in their own file:

```ts title="src/consent-callbacks.ts"
import type { C15tVuePluginOptions } from 'c15t/vue/vue-plugin';

export const callbacks = {
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ snapshot }) => {
		console.info('Choice recorded', snapshot.explicitChoice);
	},
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies NonNullable<C15tVuePluginOptions['callbacks']>;
```

Then add them to the plugin options in `src/main.ts`:

```ts title="src/main.ts"
app.use(c15tVue, { callbacks, mode: manifest(), scripts });
```

c15t wires the callbacks once for the app, when the plugin installs. A
component does not need to be mounted for them to run.

## Available callbacks

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor clicks Accept All, Reject All or Save Settings, in the stock UI or through `useConsentSave()`.|`snapshot`, `confirmed` (the categories the action covered) and `actionAt`|
|`onPermissionsChanged`|Any effective permission changes value.|`snapshot` and `previous`, the permissions before the change|
|`onBeforeConsentRevocationReload`|A save withdraws a granted category or vendor, right before c15t reloads the page.|`preferences`, the permissions after the save|
|`onError`|A consent command fails, for example a save the backend rejects.|`error`, a message string|

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` fires only for a visitor's action. Use it to count consent
decisions or to send the choice to your own analytics.

`onPermissionsChanged` also fires when a stored choice expires, when a new
policy applies, and when a privacy signal such as Global Privacy Control
changes, with no action from the visitor. Use it to start or stop code
that depends on a permission. Do not treat it as evidence that the visitor
chose anything.

Dismissing a notice fires neither callback, because it records no choice and
changes no permission. Subscribe to it with
`useConsentKernel().events.on('notice:dismissed', listener)`.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Before a revocation reload

Removing a script tag cannot stop code that already ran, so c15t reloads the
page after a save withdraws a granted category or vendor.
`onBeforeConsentRevocationReload` runs synchronously right before that. Use
it to call a vendor's shutdown API. Avoid long work, because the reload does
not wait. Set `reloadOnConsentRevoked: false` to handle revocation yourself.

## Callbacks with a shared runtime

When you pass `runtime` to the plugin, the plugin ignores `callbacks`. Register
them where you create the runtime.

## Verify

Open the console, load the app and click **Accept All**. `onChoiceRecorded` logs
once and `onPermissionsChanged` logs the new permissions. Reload: neither logs
a new choice. Withdraw a category in preferences and save, and the
revocation callback runs before the page reloads.

# IAB TCF
URL: https://c15t.com/docs/frameworks/vue/iab
Turn on IAB TCF in a Vue app with the c15t Vue plugin's iab option, so visitors under an IAB policy get the IAB banner, preference centre and __tcfapi.

## Turn on IAB TCF

IAB TCF is off until you turn it on. Pass `iab` to the c15tVue plugin; an
empty object is enough:

```ts title="src/main.ts"
import { c15tVue, hosted } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		// Turns IAB TCF on. The CMP ID and vendor list come from `/init`.
		iab: {},
		mode: hosted(),
	})
	.mount('#app');
```

With `iab` set, `ConsentRoot` renders the IAB banner and preference centre in
place of the standard ones while the visitor's policy uses the `iab` model and
names your CMP ID, and c15t installs `__tcfapi`. Configure the CMP ID and
vendors in your Inth project, or see
[IAB TCF for a self-hosted backend](/docs/self-host/guides/iab-tcf). No extra
component or stylesheet is needed; the IAB components include their own
styles.

Without `iab`, or with `iab: false` or `iab: { enabled: false }`, IAB stays
off: no `__tcfapi` is installed and the app never loads `@c15t/iab`. The
plugin reads `iab` once, when it is installed.

If a visitor's policy uses the `iab` model and the backend sends its vendor
list while IAB is off, the app throws an `IABUnavailableError` (code
`C15T_IAB_UNAVAILABLE`). The standard banner does not handle the IAB model,
so the visitor would otherwise get no working consent UI. When the policy
arrives with `prefetch`, `app.use()` throws. When the browser resolves the
policy itself, the plugin throws the error as an uncaught error and
`ConsentRoot` renders nothing.
Set `iab`, or remove the `iab` model from the policy. A backend that answers
`gvl: null` turns IAB off for the request, and the policy runs as opt-in. See
[troubleshooting](/docs/frameworks/vue/troubleshooting#the-app-throws-iabunavailableerror).

To compose the IAB surfaces yourself, import
[`IABConsentBanner`](/docs/frameworks/vue/components/iab-consent-banner) and
[`IABConsentDialog`](/docs/frameworks/vue/components/iab-consent-dialog) and
render them in place of `ConsentRoot`. For a custom preference centre, `useConsentIabSelection()`
reads the visitor's purpose and vendor selection and `useConsentIabSave()`
writes it and the TC String.

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Set
them under the plugin's `iab` option. The vendor IDs below are placeholders;
use vendors from your list whose declarations allow each restriction.

```ts title="src/main.ts (partial)"
app.use(c15tVue, {
	iab: {
		publisherRestrictions: [
			// Vendors 10 and 755 may not use purpose 4.
			{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] },
			// Vendor 755 must use legitimate interest for purpose 7.
			{ purposeId: 7, restrictionType: 2, vendorIds: [755] },
		],
	},
	mode: hosted(),
});
```

`iab` also takes `publisherCountryCode`, a `vendors` allowlist,
`customVendors` and `cmpVersion`. Fields you leave out come from the policy:
the CMP ID, custom vendors and vendor list arrive with the policy. The CMP mounts
only while the visitor's policy uses the `iab` model.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## Vendor list loading

The browser receives a reference to the Global Vendor List with the policy.
The IAB module fetches the full list as soon as it mounts, before the visitor
clicks, and waits for it before it writes a TC String. A failed fetch leaves
the banner visible and grants nothing. Allow the list's origin, usually your
backend, in your CSP `connect-src`. See
[Content Security Policy](/docs/frameworks/vue/content-security-policy).

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Verify IAB consent

Load the app under your IAB policy and confirm the IAB banner appears. In the
browser console, `__tcfapi('getTCData', 2, console.log)` returns a TC String
after you accept or reject. If the console shows an `IABUnavailableError`
instead, `iab` is not set.

# IAB GPP
URL: https://c15t.com/docs/frameworks/vue/gpp
Turn on the IAB Global Privacy Platform API (__gpp) in a Vue app with the c15t Vue plugin's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

The `gpp` option installs `window.__gpp`, the GPP 1.1 CMP API, and keeps its
GPP string in step with the visitor's choices. Prebid.js, Google Ad Manager
and other ad tech read US privacy signals from it.

## Turn on GPP

Pass `gpp` to the Vue plugin in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		// Loads @c15t/iab/gpp and installs `__gpp` once the app mounts.
		gpp: true,
		mode: manifest(),
	})
	.mount('#app');
```

The plugin loads `@c15t/iab/gpp` when the app mounts, so apps without `gpp`
never download it. The Vue integration already depends on `@c15t/iab`;
nothing else to install. Unmounting the app removes `__gpp`.

Replace `https://your-project.inth.app` with your project's backend URL. The
GPP string follows the policy and location Inth resolves for the visitor, so
a US visitor's state comes from the backend.

If you pass the plugin a `runtime` created with `createConsentRuntime()`, the
plugin ignores `gpp`. Set `gpp` and `loadGPP: () => import('@c15t/iab/gpp')`
on that runtime instead.

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/vue/iab) as well.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/vue/content-security-policy
Allow c15t in a Vue app under a Content Security Policy, with a script nonce, the backend in connect-src, and the styles the components inject.

## What c15t adds to the page

A Vue app with c15t adds these to the page, and your policy must allow them:

|What|Directive|
|--|--|
|Requests to your backend's `/subjects`, plus `/init` with `hosted()` or `/manifest` with `manifest({ source: 'runtime' })`|`connect-src`|
|Chunks your build splits out, such as the manifest resolver and the copy for a language other than English|`script-src 'self'`|
|`<script>` elements the script loader creates for `scripts`|`script-src`|
|Scripts, frames, images and requests your vendors load|`script-src`, `frame-src`, `img-src`, `connect-src` for each vendor|
|The components' CSS, which Vite bundles with your app|`style-src`|
|The `<style id="c15t-css-vars">` element with your theme tokens, in `<head>`|`style-src`|
|Style bindings, such as the floating trigger's position, set through the CSSOM|None|

## Allow the backend

Add your backend's origin to `connect-src`. With a `manifestURL` or `geoURL`
on another origin, add that origin too. With `iab` set and an IAB TCF policy, the IAB module
fetches the Global Vendor List from the URL the policy gives, usually your
backend.

```txt title="Content-Security-Policy (partial)"
connect-src 'self' https://<your-backend-host>;
```

Use the host from your Inth project or your self-hosted backend.

## Allow scripts

The simplest policy lists each vendor's script host in `script-src`. The
[integration guide](/docs/integrations/overview) for each vendor names its
hosts.

A static Vue app is the same file for every visitor, so it cannot carry a
nonce that changes per response. If your server does generate a nonce per
response, pass it as the plugin's `nonce` option. The script loader adds it
to every `<script>` it creates, and a `nonce` on a single script takes
precedence. Scripts that a vendor script loads itself do not get the nonce.
Add `'strict-dynamic'` to `script-src` to allow them, or list their hosts.

```ts title="src/main.ts"
app.use(c15tVue, { mode: manifest(), nonce, scripts });
```

## Allow styles

The components import their CSS, which Vite adds to your app's stylesheet in
a production build. `style-src 'self'` covers it. In development, Vite injects
`<style>` elements, which need `'unsafe-inline'` in `style-src`.

The c15tVue plugin adds your theme tokens to `<head>` in an inline
`<style id="c15t-css-vars">` element. A `style-src` without
`'unsafe-inline'` blocks it, and the components fall back to the default
theme. The element's content is the same for every visitor and only changes
when you change `tokens`, so you can allow it with a hash. Copy the
`sha256-...` value from the browser's `Refused to apply inline style` console
error into `style-src`, and recompute it whenever you change `tokens`. When
you pass the plugin's `nonce` option, the element carries that nonce too.

Vue applies the components' `style` bindings, such as the floating trigger's
position, through the CSSOM. A policy does not govern CSSOM changes, so they
need no directive.

## Verify

Enforce the policy, not report-only, and load the app. The banner shows your
token colors, and the console shows no
`Refused to connect`, `Refused to load the script` or `Refused to apply inline style` error that mentions your backend, a c15t element or a vendor
you allowed. Click **Accept All**, and the vendor scripts load. The save to
`/subjects` succeeds.

# DevTools
URL: https://c15t.com/docs/frameworks/vue/components/dev-tools
Inspect consent state, the resolved policy, location, scripts and consent events in a Vue app during development with ConsentDevTools.

## Load DevTools only in development

Import `ConsentDevTools` from `c15t/vue/devtools` with a dynamic import that
runs only in development:

```vue title="src/ConsentDevTools.vue"
<script setup lang="ts">
import { defineAsyncComponent } from 'vue';

// Development builds only: the dynamic import keeps DevTools out of
// production bundles.
const DevTools = import.meta.env.DEV
	? defineAsyncComponent(() => import('c15t/vue/devtools'))
	: null;
</script>

<template>
	<DevTools v-if="DevTools" position="bottom-right" />
</template>
```

Render this component anywhere inside the app that installed
[the c15tVue plugin](/docs/frameworks/vue/plugin). `import.meta.env.DEV` is
`false` in production builds, so Vite drops the dynamic import and the panel
from your production bundle. A static `import` would ship DevTools to every
visitor even when `v-if` hides it.

## What ConsentDevTools renders

`ConsentDevTools` mounts a floating panel for the consent runtime your app
already created. It renders nothing into your component tree and mounts its
panel in `document.body`. It must render inside the app that set up c15t,
or it throws `[c15t] Kernel not found`.

|Panel|What it shows|
|--|--|
|Consents|Each category's value, with save, accept all and reject actions|
|Scripts|Your `scripts`, their loading status, and the scripts and iframes found in the page|
|Location|The resolved country and region|
|Policy|The resolved policy and presentation|
|IAB|Vendors, purposes and the TC String, under an IAB policy|
|Events|A timeline of consent changes and script events|
|Actions|Show the banner, open preferences, hide consent UI, or resolve the policy again|

Accept and reject in the Consents panel apply only to the categories the
policy covers, filtered by `consentCategories`. Necessary stays on.
`DevTools` and `C15TDevTools` are other names for the same component.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar
with a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end farthest
from the trigger's corner. The panel opens just past the toolbar, aligned
with its outer edge, and follows it when a visitor drags the toolbar to
another corner. `position` applies again once no trigger is visible.

DevTools brings its launcher back whenever the trigger is hidden, for
example while `triggerShowWhen: 'after-consent'` waits for a choice. A
production build that loads DevTools only in development shows the single
trigger button.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Corner of the toggle button.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|`'consents' \|'scripts' \|'location' \|'policy' \|'iab' \|'events' \|'actions'`|`'consents'`|Panel shown first.|
|`maxEvents`|`number`|`100`|How many events the Events panel keeps.|
|`getConsentCategories`|`() => readonly ConsentCategory[]`|`consentCategories`|Narrows the categories the Consents panel acts on. It cannot add categories outside the policy.|
|`getPresentation`|`() => ConsentPresentation \|undefined`|Your `presentation` option|Presentation the Policy panel resolves.|
|`clearRecords`|`() => void`|Clears the stored consent records|Runs when you clear records from the panel.|
|`shadow`|`boolean`|`true`|Mounts the panel inside a shadow root that carries its own stylesheet, so your page's CSS cannot restyle it. `:shadow="false"` mounts the panel in the light DOM and adds its stylesheet to `<head>`.|

Changing a prop destroys the panel and creates a new one, which clears its
event history.

## Embed the panel in your own page

`ConsentDevToolsPanel` from `c15t/vue/devtools` fills its parent element
instead of floating over the page. It has no launcher or close button and
starts open. Use it for your own debug page or another devtools host. Give
the parent a height:

```vue
<script setup lang="ts">
import { ConsentDevToolsPanel } from 'c15t/vue/devtools';
</script>

<template>
  <div style="height: 32rem">
    <ConsentDevToolsPanel default-tab="events" />
  </div>
</template>
```

It accepts `defaultTab`, `maxEvents`, `getConsentCategories`,
`getPresentation` and `clearRecords`, and must render inside the provider
that supplies the kernel.

## Verify

Run `vite` and open the app. A DevTools button appears in the corner you set.
Open it, pick the Policy panel and check the matched policy for your
location. Serve a production build with `vite build` and `vite preview`, and
confirm the DevTools button does not appear.

## Next steps

* [Troubleshooting](/docs/frameworks/vue/troubleshooting) uses DevTools to
  explain a missing banner.
* [Verify consent](/docs/guides/verify-consent) is the release checklist.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/vue/troubleshooting
Fix common c15t Vue plugin problems, from unresolved imports and a missing banner to tokens that do not apply and scripts that load twice.

## Vite fails to pre-bundle c15t's .vue files

**Check.** `vite dev` reports an error from dependency optimization for a
`.vue` file under `@c15t/vue`, or `manifest()` throws `c15t: manifest() has no backend URL`. `consentManifest()` is missing from the `plugins` array of
`vite.config.ts`.

**Fix.** Add `consentManifest()` from `c15t/vue/vite` to the `plugins` array,
next to `@vitejs/plugin-vue`, and set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`). See the
[quickstart](/docs/frameworks/vue/quickstart#add-the-vite-plugin).

## app.use() throws "pass `mode`"

**Check.** The plugin options have no `mode`. Earlier v3 alphas took
`backendURL`, `manifest`, `manifestURL` and `manifestSnapshot` on the plugin.

**Fix.** Pass `mode: manifest()`, `hosted()` or `offline()` from
`c15t/vue/vue-plugin`. Move `backendURL` into the mode, such as
`hosted({ backendURL })`, or let `consentManifest()` supply it.

## Why does the build fail to download the manifest?

**Check.** `vite build` stops with an error from `consentManifest` that
starts with the plugin's name, such as
`@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite`
for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps
going. The part in parentheses names the cause:

|Message|Cause|Fix|
|--|--|--|
|`fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error|The build cannot reach the backend|Build where the backend is reachable|
|`no response within 10 seconds`|The backend did not answer in time|Check the backend, or build where it is reachable|
|`/manifest responded 404`|The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix|Copy the backend URL exactly as Inth shows it, or set `VITE_C15T_BACKEND_URL`|
|`/manifest returned an invalid consent manifest.`|The URL answered with something other than a consent manifest, such as an HTML page|Point `backendURL` at the backend itself, not your site or a dashboard page|

A failed download never reuses an old snapshot. To deploy while the backend
is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
`undefined`, and the browser fetches the policy from the backend at runtime.

Only a build that uses `manifest()` downloads the manifest. The plugin
fetches after Vite has dropped the code the app does not use, so a `hosted()`
or `offline()` build never contacts the backend and never fails this way.

An error or warning that says `no backend URL is set` means the plugin found
no `backendURL` option and no variable. Set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass the absolute backend URL from your Inth
project. The [troubleshooting guide](/docs/guides/troubleshooting#why-does-the-build-fail-to-download-the-manifest)
lists every message.

A notice that the build `skipped the consent manifest fetch` means the backend
URL is relative, such as `/api/c15t`. Pass the absolute backend URL instead.
With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL`.

## Why is snapshot undefined?

**Check.** `snapshot` from `c15t/generated` is `undefined`, and the browser
requests `${backendURL}/manifest` on page load.

**Fix.** `snapshot` is `undefined` when Vite has no policy to serve:

* `consentManifest` is missing from `plugins` in `vite.config.ts`. Without the
  plugin, `c15t/generated` still resolves, but exports `undefined`.
* The fetch failed in `vite dev`, or in a build with
  `C15T_ON_BUILD_ERROR=runtime`. The terminal shows a `could not fetch the consent manifest` warning.
* The backend URL is relative, so the plugin skipped the fetch.
* `consentManifest({ source: 'runtime' })` is set, so the plugin never
  fetches.

Fix the cause, then restart `vite dev` or rebuild. The plugin fetches once
when Vite starts.

## app.use() fails or does nothing

**Check.** Look at where you import the plugin. `c15t/vue` is the Nuxt module
and is not a Vue plugin.

**Fix.** Import the plugin from `c15t/vue/vue-plugin`.

## A composable throws "Kernel not found"

**Check.** The component is outside the app that installed `c15tVue`, for
example in a separate `createApp()` instance, or the composable ran outside
`setup`.

**Fix.** Install the plugin on the app that renders the component, and call
composables inside `setup`.

## Why is there no banner?

**Check.** [DevTools](/docs/frameworks/vue/components/dev-tools) shows the
matched policy. With `hosted()`, find the `/init` request in the Network tab;
with `manifest({ source: 'runtime' })`, the `/manifest` request.

**Fix.** Work through these causes in order:

1. **The visitor's policy asks for no banner.** A policy with prompt `none`
   shows no banner, which is common in opt-out regions. See
   [why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).
2. **`manifest()` resolves the unknown-location policy.** Without `inputs`
   or `geoURL`, every visitor gets the policy your project assigns when the
   location is unknown. Check that rule, then rebuild.
3. **`ConsentRoot` is inside a route that unmounts.** Put it in the root
   component.
4. **The backend did not answer.** With `hosted()`, `/init` must return
   200; with a runtime manifest, `/manifest` must. A CORS error means your site's origin is missing from the
   Inth project's trusted origins. While resolution fails, c15t shows no UI and
   keeps every optional category denied.
5. **A stored choice exists.** Clear the `c15t` cookie and localStorage entry,
   or use a private window.

## The app throws IABUnavailableError

**Check.** The error has the code `C15T_IAB_UNAVAILABLE` and reads
"c15t: this visitor's policy uses IAB TCF, but `iab` is not set." The
visitor's policy uses the `iab` model and the backend sent its vendor list,
but the plugin has no `iab` option, or has `iab: false` or
`iab: { enabled: false }`. The standard banner does not handle the IAB model,
so c15t throws rather than leave the visitor with no consent UI.
`app.use()` throws when the policy arrives with `prefetch`; otherwise the
error is uncaught once the policy resolves, and `ConsentRoot` renders
nothing.

**Fix.** If the site uses IAB TCF, pass `iab` to the plugin, such as
`app.use(c15tVue, { iab: {} })`. See [IAB TCF](/docs/frameworks/vue/iab).
If it does not, remove the `iab` model from the policy for that region in
your Inth project or policy pack. A backend that answers `gvl: null` turns
IAB off for that request, and nothing throws.

## Tokens in my CSS do not apply

**Check.** The c15tVue plugin appends a `<style id="c15t-css-vars">` element to
`<head>` when you install it. The element sets every token, including the
defaults. A `:root` rule in your stylesheet for the same variable competes
with it on source order, so it may lose.

**Fix.** Set values through the plugin's `tokens` option. See
[customize](/docs/frameworks/vue/customize#set-theme-tokens).

## A script loads twice, or before consent

**Check.** Look for the vendor in both the plugin's `scripts` and a
`createScriptLoader` call.

**Fix.** Keep only `scripts`.

**Check.** Look for the vendor's own snippet in `index.html`, or SDK
initialization in your code.

**Fix.** Remove it so c15t is the only loader.

## The page flashes without the banner on a server-rendered Vue app

**Check.** c15t does not support server rendering for plain Vue.

**Fix.** Use the c15t Nuxt module. See
[server rendering without Nuxt](/docs/frameworks/vue/rendering#server-rendering-without-nuxt).

## Names from an earlier alpha are missing

**Check.** An import or component from an earlier v3 alpha fails to resolve,
such as `c15t/vue/consent-root`, `ConsentPreferencesLink` or the default
export of `c15t/vue/vite`. The v3 alphas removed names that never shipped in
a stable release, with no alias.

**Fix.** Use the current names:

|Removed|Use instead|
|--|--|
|Vue plugin options `backendURL`, `manifest`, `manifestSnapshot`, `manifestURL`, `customFetch`, `domain`|`mode`, a factory from `c15t/vue/vue-plugin` that takes them|
|The default `c15tVue` export of `c15t/vue/vite`|`consentManifest` from `c15t/vue/vite`. The Vue app plugin keeps the name `c15tVue`.|
|`c15t/vue/consent-root`, `c15t/vue/consent-widget`|Named exports from `c15t/vue/vue-plugin`|
|`ConsentPreferencesLink`, `runtime/components/consent-preferences-link.vue`|`ConsentDialogLink`, `consent-dialog-link.vue`|
|`ConsentFrame`|`ConsentGate`|
|`hosted({ url })`|`hosted({ backendURL })`, or `VITE_C15T_BACKEND_URL`|

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/astro/quickstart
Add a c15t consent banner, preference dialog and consent-gated scripts to an Astro 5, 6 or 7 site with the c15t integration and Inth, on static or server output.

## Before you start

[Create an Inth project](https://inth.com) and set it up before you touch the
code:

1. Add policy rules that cover the `measurement` category. This guide loads
   PostHog on measurement.
2. Add your site's origin to the project's trusted origins.
3. Copy the project's backend URL.

Then decide how Astro builds your pages. The integration supports both, and
[Rendering and deployment](/docs/frameworks/astro/rendering) covers mixed and
cached setups.

|Your site|Astro output|c15t mode|
|--|--|--|
|Static pages on any static host, no adapter|`output: 'static'`|`hosted()`|
|Pages rendered on each request, with a server adapter|`output: 'server'`|`manifest()`, the default|

For server output, the setup below bundles your policy into the server at
build time, the recommended production setup. Rebuild after changing policies,
translations or vendors. With static output, the browser asks Inth for the
policy on each visit.

[`examples/astro-static`](https://github.com/c15t/c15t/tree/v3/examples/astro-static)
and [`examples/astro`](https://github.com/c15t/c15t/tree/v3/examples/astro)
hold the finished code for each.

## Install the packages

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @astrojs/svelte svelte @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @astrojs/svelte svelte @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @astrojs/svelte svelte @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @astrojs/svelte svelte @c15t/integrations@alpha`|

The banner is plain `.astro` markup and ships no framework JavaScript. The
preference dialog is an island that loads when a visitor first reaches for it.
The `c15t` package includes the dialog for Svelte, React and Vue, and the
integration renders it with the one of those three your site registers.

Use the framework your site already ships, so visitors do not download a second
one for a single dialog. This guide uses Svelte. For React, install
`@astrojs/react react react-dom` instead of `@astrojs/svelte svelte` and
register `react()`. For Vue, install `@astrojs/vue vue` and register `vue()`.
With more than one of them registered, set `ui: 'react'` or `ui: 'vue'` on
`c15t()`; otherwise it uses Svelte.

## Set the backend URL

Set `PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including any
path prefix, in `.env` or wherever you build:

```sh title=".env"
PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `PUBLIC_C15T_BACKEND_URL` wins.

`c15t()` reads it from the environment, or from `.env` or `.env.local` in the
project root, when `astro.config.mjs` loads, so the config needs no
`backendURL`. The URL must be absolute.

## Configure the integration

Pick the file that matches your output. Register the framework integration
before `c15t()`.

### Static output

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t, { hosted } from 'c15t/astro';

export default defineConfig({
	integrations: [svelte(), c15t({ mode: hosted() })],
});
```

`hosted()` sends the browser straight to your Inth backend's `/init`, so no
server is needed. A static page is the same for every visitor, which means
the banner appears once the browser's `/init` request returns, not in the
first HTML.

### Server output

```js title="astro.config.mjs"
import node from '@astrojs/node';
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t from 'c15t/astro';

export default defineConfig({
	adapter: node({ mode: 'standalone' }),
	integrations: [svelte(), c15t()],
	output: 'server',
});
```

`c15t()` with no `mode` uses `manifest()`. It fetches your project's public
policy once, when `astro build` or `astro dev` starts, and embeds it in the
server build. The server resolves each visitor from that snapshot and the
request's location and language headers, so the first HTML already contains
the banner, or no banner at all for a visitor who has chosen. Consent saves
still go to Inth. [Data fetching](/docs/concepts/data-fetching) compares
this with calling the backend on every request.

`manifest()` injects one route, `/api/c15t/[...path]`, which answers
`/api/c15t/init` and `/api/c15t/manifest`, so it needs a server adapter. Use
the adapter for your host in place of `@astrojs/node`. A server-rendered page
ships only the code that saves consent; the code that resolves a policy in
the browser loads when a page needs it.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

The built server keeps the backend URL from build time, so setting
`PUBLIC_C15T_BACKEND_URL` when you start it changes nothing. Rebuild to point
at another project. To apply policy edits without rebuilding, set
`mode: manifest({ source: 'runtime' })`, with `manifest` imported from
`c15t/astro`. The server then fetches and caches the policy at runtime.

The integration writes its options into the page as JSON. `c15t()` throws if
an option holds a function, and names the option. Callbacks, vendor helpers
and anything else with a function belong in `src/c15t.client.ts`. Keep
secrets out of both.

## Register vendor scripts

Remove any existing PostHog snippet first, so PostHog loads once. Then list
the scripts in `src/c15t.client.ts`, which the integration finds on its own:

```ts title="src/c15t.client.ts"
import { posthog } from '@c15t/integrations/posthog';
import type { C15tClientOptionsExtension } from 'c15t/astro';

export default {
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
} satisfies C15tClientOptionsExtension;
```

Replace `phc_your_project_key` with your PostHog project key. PostHog waits
for measurement permission and does not fall back to cookieless capture.

Other vendors work the same way. See
[integrations](/docs/integrations/overview) for the list, and
[Scripts](/docs/frameworks/astro/scripts),
[Embeds](/docs/frameworks/astro/embeds) and
[Network blocker](/docs/frameworks/astro/network-blocker) for inline scripts,
iframes and tracking requests.

## Add the consent components to your layout

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

Wrap every page in this layout. `ConsentScript` goes in `<head>`, where it
hands the browser the server's decision and sets the color scheme before first
paint. `ConsentBanner` renders the banner, `ConsentDialog` reserves a place for
the preference dialog, and `ConsentDialogLink` is the link visitors use to
change their mind later. `ConsentScript` inlines the banner's rules into the
page, so you do not import a stylesheet.

`ClientRouter` is optional. With it, the consent runtime survives page
navigation. Without it, each page load starts the runtime again from the stored
choice.

## Type `Astro.locals.c15t`

The integration adds the type of the consent context it puts on every request
to `.astro/types.d.ts`, so TypeScript knows `Astro.locals.c15t` without an
`env.d.ts` line.

## Check that it works

Build and preview the site, then open it in a private window with DevTools open
on the Network tab:

1. Before you choose, the banner shows and there are no requests to
   `posthog.com`.
2. Select **Reject All** and reload. The banner stays closed and PostHog does
   not load.
3. Open **Privacy settings**, turn on **Analytics** (the `measurement`
   category) and select **Save Settings**. PostHog loads.
4. Turn **Analytics** off and save. The page reloads, and PostHog does not load
   again.

On server output, the page source of a first visit contains the banner markup.
On static output it does not, and the banner appears after the `/init`
request. Follow [Verify consent](/docs/guides/verify-consent) before you
ship.

## Next steps

* [Rendering and deployment](/docs/frameworks/astro/rendering) covers
  prerendered pages in a server build, cached pages with a server island, and
  offline mode for development.
* [Integration options](/docs/frameworks/astro/integration) lists every
  `c15t()` option, and [Components](/docs/frameworks/astro/components) every
  component and prop.
* [Client API](/docs/frameworks/astro/client-api) and
  [Server API](/docs/frameworks/astro/server) cover reading consent from your
  own scripts and from `Astro.locals.c15t`.
* [Customize](/docs/frameworks/astro/customize) and
  [Translations](/docs/frameworks/astro/translations) cover theme tokens, copy,
  dark mode and languages.
* [IAB TCF](/docs/frameworks/astro/iab) and
  [troubleshooting](/docs/frameworks/astro/troubleshooting).

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/astro/rendering
Choose how c15t resolves consent on an Astro site, from static output with hosted() or browser-resolved manifest() to server output with manifest(), prerendered pages, server islands, ClientRouter and offline development.

## Choose a rendering path

Where consent resolves decides what the first HTML contains. A page that is
built once and served to everyone cannot contain one visitor's consent, so the
browser finishes the job. A page rendered per request can.

|Your site|Astro setup|c15t mode|Banner in the first HTML|
|--|--|--|--|
|Static pages on any static host|`output: 'static'`, no adapter|`hosted()`|No. The browser renders it after `/init`|
|Static pages, with the policy resolved in the browser|`output: 'static'`, no adapter|`manifest({ resolve: 'browser' })`|No. The browser renders it after reading the manifest|
|Pages rendered on each request|`output: 'server'` and an adapter|`manifest()`, the default|Yes|
|A server build with some prerendered pages|`output: 'server'`, `prerender = true` on those pages|`manifest()`|Only on the request-rendered pages|
|Cached pages that still need a per-visitor banner|An adapter, and `ConsentBannerDeferred` in the layout|`manifest()`|Yes, from a server island|
|Local development and tests with no backend|Either output|`offline()`|Depends on the output|

Every path uses the same layout, client entrypoint and scripts from the
[quickstart](/docs/frameworks/astro/quickstart). Only `astro.config.mjs` and,
for cached pages, the banner component change.
[Choose your setup](/docs/concepts/choose-your-setup) explains the trade-off
across frameworks.

## Static output with `hosted()`

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t, { hosted } from 'c15t/astro';

export default defineConfig({
	integrations: [svelte(), c15t({ mode: hosted() })],
});
```

Astro builds every page once. At build time there is no visitor, so
`ConsentBanner` renders an empty, hidden placeholder. In the browser, c15t
reads the visitor's consent cookie, calls your backend's `/init` directly, and
renders the banner into the placeholder when the policy says to show one. A
returning visitor keeps their choice, because it comes from their own cookie.

The browser calls the backend from your site's origin, so that origin must be
in the Inth project's trusted origins.

The default `manifest()` does not work here. It injects an on-demand route,
and without an adapter `astro build` stops with an error that names it.

## Static output with browser resolution

`manifest({ resolve: 'browser' })` resolves the policy in the browser from
your project's manifest, with no request to the backend's `/init`:

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t, { manifest } from 'c15t/astro';

export default defineConfig({
	integrations: [svelte(), c15t({ mode: manifest({ resolve: 'browser' }) })],
});
```

The build downloads the manifest and the integration prerenders it as a
static file at `/api/c15t/manifest`, so no adapter is needed. The browser
fetches that file from your own origin, loads the resolver, and resolves the
policy. It has no request location, so without `inputs` or `geoURL` every
visitor gets the policy your project assigns when the location is unknown.
Use `hosted()` when your policy differs by region and you have no location
source. Consent saves go to the backend, so your site's origin must be in
the Inth project's trusted origins.

## Server output with `manifest()`

```js title="astro.config.mjs"
import node from '@astrojs/node';
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t from 'c15t/astro';

export default defineConfig({
	adapter: node({ mode: 'standalone' }),
	integrations: [svelte(), c15t()],
	output: 'server',
});
```

The integration registers a middleware that runs before every page. It reads
the visitor's consent cookie, location headers and Global Privacy Control
signal, resolves the policy, and stores the result in `Astro.locals.c15t`. The
components render from it, so the banner is part of the HTML and a visitor who
has already chosen gets no banner markup at all. Such a page holds one
visitor's decision, so keep it out of shared caches. See
[Server API](/docs/frameworks/astro/server#cache-server-rendered-pages-safely).

`manifest()` resolves each request on the server from your project's public
policy file. By default the build downloads that file and bundles it, so a
render never waits on the backend for the policy. With
`manifest({ source: 'runtime' })`, in `astro dev` when the fetch fails, or
with `onBuildError: 'runtime'`, the server downloads and caches the file at
runtime. The browser asks the injected `/api/c15t/init` route when it needs a
decision, and saves consent to the backend URL. A server-rendered page ships
only the code that saves consent; the code that resolves a policy loads when
a page asks again. `manifest()` needs the backend URL as `backendURL` or
`PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`); without it, the
config fails to load.
[Data fetching](/docs/concepts/data-fetching) compares this with calling
`/init` for every render.

`hosted()` also works with server output. Every server render then calls the
backend's `/init`, so each page view waits on a backend request.

### Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

`manifest()`, the default mode, bundles the manifest. The integration fetches
it when `astro build` or `astro dev` starts, then embeds it in its generated
server options. The middleware and the consent route use that same snapshot.
The browser options omit it; only `manifest({ resolve: 'browser' })` serves
it to the browser, as the prerendered `/api/c15t/manifest`. No
generated file or extra import is needed. `astro check` and `astro sync` do
not fetch, so type checks work without the backend. `astro preview` serves the
completed build and never fetches a new snapshot.

The build fetches only from an absolute upstream backend URL or
`manifestURL`, because it cannot fetch a route in the app it is still
compiling. `c15t()` without a `backendURL` reads `PUBLIC_C15T_BACKEND_URL`, then
`PUBLIC_INTH_PROJECT_URL`.
With a relative URL, `manifest({ source: 'runtime' })`,
`manifest({ snapshot })`, `hosted()` or `offline()`, the integration skips
the fetch. If the fetch fails, or no backend URL is set, `astro build` stops.
`astro dev` logs a warning instead, and the server fetches and caches the
policy at runtime. The config is read once at build time, so the built server
keeps the backend URL and the snapshot it was built with.

To let a build continue when the snapshot can't be fetched, set
`onBuildError: 'runtime'`, or build with `C15T_ON_BUILD_ERROR=runtime`:

```js title="astro.config.mjs"
c15t({ onBuildError: 'runtime' });
```

`onBuildError: 'fail'` stops `astro dev` too, and stops the build on a
relative URL.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

For policy updates without a rebuild, set `mode: manifest({ source: 'runtime' })`.
The server then fetches and caches the policy at runtime.

### Set how long a render waits for the backend

The middleware waits up to 500 ms for the policy. With a bundled manifest the
policy is already on the server, so the budget matters when the server
fetches it at runtime or uses `hosted()`. If the backend has not answered by
then, for example on a cold cache or during an outage, the page
renders without a server decision. The HTML has no banner, optional categories
are denied, and gated scripts and iframes stay blocked. The browser then asks
for the policy and shows the banner when it arrives.

Change the budget in the integration options:

```js title="astro.config.mjs (partial)"
c15t({ middleware: { timeoutMs: 800 } });
```

Set `timeoutMs: false` to wait however long the backend takes. With
`hosted()`, keep the budget above the backend's usual `/init` response time.

### Skip routes that never render consent

The middleware resolves consent for every route, including your API routes.
List routes that should not pay for that, such as health checks or webhooks.
A prefix also covers the routes below it, and `Astro.locals.c15t` stays unset
on a skipped route:

```js title="astro.config.mjs (partial)"
c15t({ middleware: { skip: ['/api/webhooks', '/healthz'] } });
```

The integration's own route under `routePrefix` is always skipped.

## Prerender pages in a server build

Add `prerender` to a page's frontmatter to build it once in a server build:

```astro title="src/pages/about.astro (partial)"
---
export const prerender = true;
---
```

The middleware sees that the page is prerendered and does not read the build's
request headers or cookies. The page then behaves like a page from a static
build. The browser reads the visitor's cookie, requests the policy from
`/api/c15t/init` and renders the banner. Other pages still render per request.

If you call `resolveConsentContext` from `c15t/astro/server` yourself, pass
`prerendered: true` only for output that every visitor shares. It drops the
request's cookie and location, so do not use it to skip the backend for one
visitor's render.

## Cache a page and render the banner per request

A page served from a CDN cache or prerendered once can still show the right
banner to each visitor. Replace `ConsentBanner` with `ConsentBannerDeferred`,
which renders the banner in an Astro server island:

```astro title="src/layouts/cached.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';
import ConsentBannerDeferred from 'c15t/astro/components/consent-banner-deferred.astro';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBannerDeferred />
		<ConsentDialog />
	</body>
</html>
```

The page HTML stays the same for everyone. The island's request carries the
visitor's cookie and location, so the middleware resolves consent for it and
the banner arrives with the visitor's own policy. Server islands need an
adapter. On a static host with no adapter, use `ConsentBanner` and let the
browser render it.

## Keep consent across `ClientRouter` navigation

With Astro's `ClientRouter`, the browser swaps pages without reloading scripts.
c15t creates one consent runtime per page load and keeps it across swaps. After
each swap it re-attaches to the new page's banner, gated scripts and dialog
triggers, applies the color scheme again, and keeps any stylesheet it linked
for the dialog. The
visitor's choice and an open dialog both carry over, and no new `/init`
request is made.

Your own scripts run once per page load, like c15t's. To update markup after a
swap, listen for `astro:page-load`. See the
[client API](/docs/frameworks/astro/client-api).

## Develop without a backend

`offline()` resolves policies in the browser and on your server with no
backend. Not recommended for production environments.

```js title="astro.config.mjs (partial)"
c15t({ mode: offline() });
```

Import `offline` from `c15t/astro`. Choices persist in the visitor's cookie and
localStorage only. There are no consent records, no hosted policies and no
visitor counts. Pass `policyRules` to `offline()` to test a specific policy.

On a prerendered page, offline mode resolves the policy at build time because
it needs no request. The banner is in the HTML but hidden, and a small inline
script shows it in the first paint to visitors with nothing stored.

## Taps before hydration

A banner in the server HTML shows before the page's JavaScript runs. A tap on
it in that gap does nothing: the button has no handler yet, so the banner
stays up and no choice is saved. The React and Vue banners hold such a tap and
replay it after hydration; the Astro banner does not.

## Check the rendering path

* **Server output:** view the page source of a first visit. It contains
  `data-testid="consent-banner-root"`. After you choose and reload, it does not.
  In DevTools Network, the browser does not request `/init` on a server-rendered
  page.
* **Static output or a prerendered page:** the page source has no banner
  markup. In DevTools Network, the browser requests `/init` from your backend
  with `hosted()`, `/api/c15t/manifest` with
  `manifest({ resolve: 'browser' })`, or `/api/c15t/init` in a server build,
  and the banner appears after it returns.
* **Server island:** the page source has no banner markup. In DevTools
  Network, a request to `/_server-islands/ConsentBanner` returns it.
* **Every path:** vendor requests stay absent until you allow their category,
  and a rejection survives a reload. See
  [Verify consent](/docs/guides/verify-consent).

# Scripts
URL: https://c15t.com/docs/frameworks/astro/scripts
Load vendor scripts and gated inline scripts on an Astro site only after the visitor allows their consent category, and stop them when consent is withdrawn.

## Register vendor scripts

The `ConsentBanner` component does not stop a `<script>` tag you already have.
Give c15t each vendor script to load instead, and remove the vendor's own
snippet so it loads once.

Vendor helpers from `@c15t/integrations` contain callbacks, and the integration
options in `astro.config.mjs` must survive JSON serialization. So register
helpers in `src/c15t.client.ts`, which the integration finds on its own, or
the module its `clientEntrypoint` option names. This list loads PostHog on
measurement:

```ts title="src/c15t.client.ts"
import { posthog } from '@c15t/integrations/posthog';
import type { C15tClientOptionsExtension } from 'c15t/astro';

export default {
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
} satisfies C15tClientOptionsExtension;
```

The integration imports that module into the page's boot script, so every page
shares one script loader. Each helper's guide under
[integrations](/docs/integrations/overview) lists its options and the requests
to expect.

## Add a script without a helper

A script with no callbacks can go straight into the integration options. Give
it an `id`, a `category`, and either a `src` or inline `textContent`:

```js title="astro.config.mjs (partial)"
c15t({
	scripts: [
		{
			id: 'example-analytics',
			category: 'measurement',
			src: 'https://analytics.example.com/script.js',
		},
	],
});
```

Scripts from `astro.config.mjs` and from the client entrypoint both load.

## What a site without scripts skips

The script loader is part of the page's boot script only when the site
configures `scripts` in `astro.config.mjs` or sets a `clientEntrypoint`, which
may add some. A site with neither never downloads it, about 4 KB gzip less on
every page. The [network blocker](./network-blocker) works the same way: it
ships in the boot script when the integration options have `networkBlocker`
rules, and loads as its own chunk when only the client entrypoint sets them.

## Gate an inline script

For a script that has to stay in the page's markup, make it inert and label it
with a category. c15t runs it once the category is allowed:

```astro title="src/pages/index.astro (partial)"
<script data-c15t-category="measurement" is:inline type="text/plain">
	document.getElementById('inline-script-status').textContent =
		'Measurement script ran';
</script>
```

Three attributes matter:

* `type="text/plain"` stops the browser from running the script.
* `data-c15t-category` names one category. An unknown name logs a warning and
  the script never runs.
* `is:inline` makes Astro ship the tag as written. Without it, Astro bundles the
  script and runs it regardless of consent.

Add `data-c15t-vendor` with a vendor slug to also hold the script while the
visitor has switched that vendor off. See
[vendor consent](/docs/frameworks/astro/vendor-consent).

Under a nonce-based Content Security Policy, where your middleware sets
`Astro.locals.c15t.nonce`, also add `nonce={Astro.locals.c15t?.nonce}` to the
tag. c15t then activates only gated tags that carry the page's nonce, and
skips the rest with a console warning. See
[put the nonce on your gated scripts](/docs/frameworks/astro/content-security-policy#put-the-nonce-on-your-gated-scripts).

c15t checks gated scripts when the page loads, after each consent change and
after each `ClientRouter` navigation, so a script on a page you navigate to
runs as soon as it is allowed. A script with `src` works the same way. For
markup you insert later from your own code, call
`activateGatedScripts(getConsent(), container)` from `c15t/astro/client`.
Under a nonce policy, give the inserted tags the nonce and pass it as a third
argument.

A script that has run cannot be undone. When the visitor withdraws consent,
c15t reloads the page, and the reloaded page leaves the script inert.

## Gate embeds and requests

An iframe loads as soon as it is in the page, so gate embeds separately. See
[Embeds](/docs/frameworks/astro/embeds) for a component that renders an iframe
only while its category is allowed, and for the iframe blocker.

To stop `fetch` and `XMLHttpRequest` calls to tracking hosts until consent,
add rules to `networkBlocker`. See
[Network blocker](/docs/frameworks/astro/network-blocker).

## Clear data when consent is withdrawn

Set `clearOnRevocation` in the integration options to remove a vendor's
cookies and storage keys when its category is withdrawn. See
[clear on revocation](/docs/frameworks/astro/clear-on-revocation) for the shape.

## Withdraw consent without reloading

By default c15t reloads the page after a save turns off a category that was
allowed, because it cannot stop code that has already run. Set
`reloadOnConsentRevoked: false` in the integration options only if every script
on the page stops itself when its category is withdrawn. Stop your own code
from the `onPermissionsChanged` callback. See
[Callbacks](/docs/frameworks/astro/callbacks).

## Check script loading

Build the site and open it in a private window with DevTools Network open:

1. Before you choose, filter for each vendor's domain. There are no requests,
   and a gated inline script has not run.
2. Allow one category from **Privacy settings**. Only that category's vendors
   load, and inline scripts gated on it run.
3. Reload. The allowed vendors load again, and the others stay absent.
4. Withdraw the category and save. The page reloads and the vendor does not
   load.

See [Verify consent](/docs/guides/verify-consent) for the full checklist.

# Embeds
URL: https://c15t.com/docs/frameworks/astro/embeds
Gate YouTube videos, maps, social posts and other iframes on an Astro site so they load only after the visitor allows their consent category, with a custom element or the c15t iframe blocker.

## Why an embed needs gating

An iframe sends requests to its host as soon as it is in the page with a
`src`, before any script can stop it. `ConsentBanner` does not block iframes
you already have. Render an embed only while its category is allowed, and
remove it when the visitor withdraws permission.

Astro has no consent gate component. Use one of these:

|Approach|Use it when|
|--|--|
|A custom element that renders the iframe|You want a placeholder with a button in place of the embed|
|The iframe blocker, with `data-category` and `data-src`|You have iframe markup to gate as it is|

## Gate an embed with a custom element

This component shows a placeholder with a preferences button until
measurement is allowed. It adds the iframe once the visitor allows
measurement, and removes it when permission is withdrawn. It also keeps the
iframe out while the visitor has switched YouTube off in
[vendor consent](/docs/frameworks/astro/vendor-consent).

The component reads `client.isVendorAllowed('youtube')`, so declare `youtube`
in the `vendors` option of `c15t()` with `category: 'measurement'`. An
undeclared vendor reads as not allowed, and the video never loads:

```astro title="src/components/consent-video.astro"
---
import { ConsentDialogLink } from 'c15t/astro/components';
---

<consent-video>
	<div data-video>
		<p>Allow measurement to load this YouTube video.</p>
	</div>
	<ConsentDialogLink>Open privacy settings</ConsentDialogLink>
</consent-video>

<script>
	import { getConsentClient } from 'c15t/astro/client';

	class ConsentVideo extends HTMLElement {
		dispose?: () => void;

		connect = () => {
			const client = getConsentClient();
			const container = this.querySelector('[data-video]');
			if (this.dispose || !client || !container) {
				return;
			}
			const render = () => {
				// Measurement is allowed and the visitor has not switched YouTube
				// off. An undeclared vendor is never allowed, so declare youtube.
				if (!client.isVendorAllowed('youtube')) {
					container.textContent =
						'Allow measurement to load this YouTube video. No video request is sent before permission.';
					return;
				}
				if (container.querySelector('iframe')) {
					return;
				}
				const frame = document.createElement('iframe');
				frame.src = 'https://www.youtube-nocookie.com/embed/czTksCF6X8Y';
				frame.title = 'YouTube video';
				frame.allowFullscreen = true;
				container.replaceChildren(frame);
			};
			render();
			this.dispose = client.subscribe(render);
		};

		connectedCallback() {
			// c15t boots from a module script, which can run after this one.
			document.addEventListener('DOMContentLoaded', this.connect, {
				once: true,
			});
			this.connect();
		}

		disconnectedCallback() {
			document.removeEventListener('DOMContentLoaded', this.connect);
			this.dispose?.();
			this.dispose = undefined;
		}
	}

	if (!customElements.get('consent-video')) {
		customElements.define('consent-video', ConsentVideo);
	}
</script>
```

Use it like any Astro component. How it works:

* The iframe does not exist in the server HTML, so nothing loads before
  consent, even before the consent runtime starts.
* `client.subscribe(render)` renders again on every consent change.
* `connectedCallback` runs again when `ClientRouter` swaps in a page that
  contains the element, so the embed works across navigation.
* The first `connect()` can run before c15t has started, so the element tries
  again on `DOMContentLoaded`.

Change the category, the iframe `src` and the placeholder text for other
embeds. The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides use the same pattern with
a reusable browser helper. [Integrations](/docs/integrations/overview) lists
the other vendors.

## Gate existing iframe markup

The consent runtime includes an iframe blocker, on by default. Mark an iframe
with a category and move its URL from `src` to `data-src`:

```html title="src/pages/contact.astro (partial)"
<iframe
  data-category="marketing"
  data-src="https://www.google.com/maps/embed?pb=..."
  title="Office location"
></iframe>
```

When the category is allowed, the blocker copies `data-src` to `src`. When it
is withdrawn, the blocker removes `src` again. `data-vendor` gates the iframe
on one vendor as well. See [vendor consent](/docs/frameworks/astro/vendor-consent).

Always use `data-src`, never `src`, for a gated iframe. The browser starts
loading a `src` from the HTML before the blocker runs, so an iframe with `src`
in the markup loads before consent.

The blocker watches the whole document, so it also gates iframes on pages you
reach with `ClientRouter`, which replaces `<body>` on each navigation.

## Gate an embed on the server

On a server-rendered page, `Astro.locals.c15t.snapshot.effectivePermissions`
tells you whether the visitor had allowed the category when the request
arrived. Rendering the iframe on the server from it works for returning
visitors. A visitor who allows the category on the page sees the embed only
after the next navigation, so pair it with the custom element, or use the
custom element alone. See [Server API](/docs/frameworks/astro/server).

## Check the embeds

1. Open the page in a private window with DevTools Network open. There is no
   request to the embed's host, and no iframe from it in the Elements panel.
2. Allow the embed's category from **Privacy settings**. The iframe appears
   and loads.
3. Reload. The iframe loads again without a new choice.
4. Withdraw the category and save. The page reloads, and the embed's host
   gets no request.

See [Verify consent](/docs/guides/verify-consent) for the full checklist.

# Network blocker
URL: https://c15t.com/docs/frameworks/astro/network-blocker
Block fetch and XMLHttpRequest calls to tracking hosts on an Astro site until the visitor allows their consent category, with c15t's network blocker rules and an onRequestBlocked handler.

## What the network blocker does

`networkBlocker` stops `fetch` and `XMLHttpRequest` calls that match a rule
until the visitor allows the rule's category. A blocked `fetch` resolves to a
`451` response, and nothing is sent. It covers requests that code already on
the page makes, such as an SDK you load yourself or a tag manager's own calls.

It does not stop `navigator.sendBeacon`, WebSockets, image pixels, `<script>`
tags or iframes. Load scripts through c15t and gate iframes as
[Scripts](/docs/frameworks/astro/scripts) and
[Embeds](/docs/frameworks/astro/embeds) describe.

## Add rules

Rules are plain data, so they can go in the integration options:

```js title="astro.config.mjs (partial)"
c15t({
	networkBlocker: {
		rules: [
			{ category: 'measurement', domain: 'google-analytics.com' },
			{
				category: 'marketing',
				domain: 'ads.example.com',
				pathIncludes: '/collect',
				methods: ['POST'],
			},
		],
	},
});
```

|Rule field|Effect|
|--|--|
|`category`|The category that must be allowed for the request to go through|
|`domain`|The host to match. It also matches every subdomain|
|`pathIncludes`|Matches only URLs whose path contains this text|
|`methods`|Matches only these HTTP methods|
|`vendor`|Also requires this vendor to be allowed, for vendor-level consent|

|Option|Default|Effect|
|--|--|--|
|`rules`|Required|The rules to apply|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Logs each blocked request to the console. Set `false` to silence it|

The blocker starts with the consent runtime, from a module script. A request
made before that, such as from an inline script at the top of `<head>`, is not
blocked.

## Log or report blocked requests

`onRequestBlocked` is a function, so it cannot go in `astro.config.mjs`. Set
`networkBlocker` in the default export of your client entrypoint instead. It
replaces the integration's `networkBlocker` completely, so repeat the rules
there:

```ts title="src/consent-client.ts (partial)"
export default {
	scripts,
	networkBlocker: {
		rules: [{ category: 'measurement', domain: 'google-analytics.com' }],
		onRequestBlocked: ({ url, rule }) => {
			console.info('Blocked until consent:', url, rule?.category);
		},
	},
} satisfies C15tClientOptionsExtension;
```

## Check the network blocker

1. Open the site in a private window with DevTools Network open, and trigger
   the code that calls a blocked host. The request does not appear, and a
   `fetch` receives a `451` response.
2. Allow the rule's category. The next request to that host goes through.
3. Withdraw the category and save. After the reload, requests to the host are
   blocked again.

# Vendor consent
URL: https://c15t.com/docs/frameworks/astro/vendor-consent
Let visitors allow a category such as marketing on an Astro site and still turn off one vendor in it, with the vendors option on the c15t() integration and the page client from c15t/astro/client.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Add `vendors` to the `c15t()` integration in `astro.config.mjs`. Each entry
uses the `vendor` slug its script already carries:

```ts title="astro.config.mjs (partial)"
vendors: [
	{
		category: 'measurement',
		description: 'Product analytics and session insights.',
		id: 'posthog',
		name: 'PostHog',
		privacyPolicyUrl: 'https://posthog.com/privacy',
	},
	{
		category: 'measurement',
		description: 'Embedded videos.',
		id: 'youtube',
		name: 'YouTube',
		privacyPolicyUrl: 'https://policies.google.com/privacy',
	},
	{
		category: 'marketing',
		description: 'Ad conversion tracking.',
		id: 'x-pixel',
		name: 'X Pixel',
		privacyPolicyUrl: 'https://x.com/en/privacy',
	},
],
```

Vendor entries are plain data, so they survive the JSON serialization the
integration options go through and can sit in `astro.config.mjs` next to
`mode`. The server also asks about the categories these vendors sit in, so a
vendor in `marketing` puts marketing in the banner decision and the
preference dialog.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

On an Astro site, two more targets take a vendor slug:

|Target|Field|
|--|--|
|Inert inline script|`data-c15t-vendor="x-pixel"` next to `data-c15t-category`|
|Your own custom element|`client.isVendorAllowed('youtube')` in its render function|

An inert tag with `data-c15t-vendor` runs once its category is allowed and the
visitor has not switched the vendor off:

```astro title="src/pages/index.astro (partial)"
<script
  is:inline
  type="text/plain"
  data-c15t-category="marketing"
  data-c15t-vendor="x-pixel"
>
  // X Pixel's base code
</script>
```

`data-c15t-vendor` does nothing without `data-c15t-category`. Under a
nonce-based Content Security Policy, the tag still needs the page's nonce. See
[gate an inline script](/docs/frameworks/astro/scripts#gate-an-inline-script).
[Embeds](/docs/frameworks/astro/embeds) covers the iframe blocker's
`data-vendor` attribute and the custom element pattern.

## What the preference dialog shows

The preference dialog lists each declared vendor under its category, with its
own switch, whichever `ui` framework renders the dialog island: React, Vue or
Svelte.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Read and record vendor choices in your own script

The page client from `getConsentClient()` in `c15t/astro/client` reads and
records vendor consent:

|Member|Returns or does|
|--|--|
|`client.getDeclaredVendors()`|The vendors from `vendors`, the backend manifest and the slugs on scripts and iframes. Empty under an IAB policy.|
|`client.getVendorChoice()`|The recorded vendor decision, whose `denied` lists the vendors the visitor switched off, or `null` before any vendor decision.|
|`client.isVendorAllowed(id)`|`true` when the vendor is declared, its category is allowed and the visitor has not switched it off.|
|`client.save({ ...categories, vendors })`|Saves the categories you pass and the vendor grants in `vendors`. Vendors you leave out keep their recorded state.|

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

The [video component](/docs/frameworks/astro/embeds#gate-an-embed-with-a-custom-element)
reads `client.isVendorAllowed('youtube')`, so it needs `youtube` in `vendors`.

Call `save()` only from a visitor's action, such as a switch in your own
form. This records marketing as allowed and X Pixel as off:

```ts title="src/scripts/x-pixel-switch.ts (partial)"
import { getConsentClient } from 'c15t/astro/client';

await getConsentClient()?.save({
	marketing: true,
	vendors: { 'x-pixel': false },
});
```

[Client API](/docs/frameworks/astro/client-api#save-consent) covers the rest
of the page client.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/astro/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns on an Astro site when that category is denied, with the clearOnRevocation option of the c15t integration.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns in the `c15t()`
integration options in `astro.config.mjs`. When that category is denied, c15t
deletes them:

```js title="astro.config.mjs (partial)"
c15t({
  clearOnRevocation: {
    measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
    marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
  },
}),
```

The value is plain data, so the integration serializes it into every page.
`clearOnRevocation` in the default export of your
[client entrypoint](/docs/frameworks/astro/integration) replaces the
integration's value. The page runtime reads it once per page load.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/astro/customize
Change the c15t banner and preference dialog on an Astro site with theme tokens, button styles, copy, dark mode, legal links and your own stylesheet order, all from the integration options.

## Choose what to change

Astro takes every customization through the `c15t()` options in
`astro.config.mjs`, and renders it on the server. The options must survive JSON
serialization, so they hold values, not functions.

|Change|Use|
|--|--|
|Brand colors, radius, type, spacing|`theme` tokens|
|Which button looks primary|`theme.consentActions`|
|Wording on every page|`i18n.messages`|
|Wording on one banner|`ConsentBanner` props|
|Light or dark surfaces|`colorScheme` and `theme.dark`|
|One part of a component|`theme.slots`, or `class` on `ConsentBanner`|
|Animation|`disableAnimation`|
|Banner position and blocking|`presentation`|
|Links to your policies|`legalLinks`, and the banner's `legalLinks` prop|
|Your own CSS from scratch|`noStyle` on the banner, or `styles: false`|

[Customization](/docs/customization/overview) explains how
these choices relate across frameworks.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## Set theme tokens

Put tokens in the integration's `theme` option:

```js title="astro.config.mjs (partial)"
c15t({
	theme: {
		colors: {
			primary: '#146b56',
			primaryHover: '#105442',
			textOnPrimary: '#ffffff',
		},
		radius: { lg: '1.25rem' },
	},
});
```

`ConsentScript` renders the tokens on the server as a
`<style id="c15t-theme">` element, so the banner and the dialog share them from
the first paint. Set hover and text colors together with a brand color, so each
button state stays readable. [Theme tokens](/docs/customization/tokens)
lists the tokens.

Put tokens in the integration options, not in the client entrypoint. The
browser does not turn tokens into CSS, so tokens in the client entrypoint's
`theme` have no effect.

## Style the banner buttons

`theme.consentActions` sets each button's `mode` and `variant`. c15t reads the
button's own key first, then `primary` for the action the policy marks as
primary, then `default`:

```js title="astro.config.mjs (partial)"
c15t({
	theme: {
		consentActions: {
			primary: { mode: 'filled' },
			customize: { mode: 'ghost', variant: 'neutral' },
		},
	},
});
```

The IAB TCF banner keeps its own button styles.

## Change the copy

For wording on every page and in the dialog, set `i18n.messages`, keyed by
language:

```js title="astro.config.mjs (partial)"
c15t({
	i18n: {
		messages: {
			en: {
				cookieBanner: {
					title: 'Cookies on this site',
					description:
						'We use cookies to measure traffic and show relevant ads.',
				},
			},
		},
	},
});
```

The server picks the visitor's language from `Accept-Language`. Set
`i18n.locale` to force one, or `detectLanguage: false` to use the default.

`i18n.messages` merges key by key with the copy for that language, so pass
only the keys you change. Setting `common.acceptAll` keeps every other label in
`common`. In `hosted()` and `manifest()` modes, the copy your backend sends is
the base, and your `i18n.messages` override it for the same language.
[Copy and translations](/docs/customization/translations) covers the message
groups.

For one banner, pass the `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` or `dismissButtonText` props
instead. [Translations](/docs/frameworks/astro/translations) covers languages
and the message keys the banner reads.

## Change the banner's shape and position

`presentation.prompt` sets the banner's shape and where it sits:

```js title="astro.config.mjs (partial)"
c15t({ presentation: { prompt: { variant: 'bar', position: 'bottom' } } });
```

`variant` is `'floating'` (default), `'bar'`, `'widget'` or `'wall'`. The policy
still decides which actions the banner must offer, and a notice never becomes a
blocking wall. [Keep behavior and appearance separate](/docs/customization/overview#keep-behavior-and-appearance-separate)
explains what presentation can and cannot change.

## Set light or dark mode

The banner and dialog turn dark when `<html>` has the `c15t-dark` class. The
integration's `colorScheme` option decides who sets it:

|Value|Behavior|
|--|--|
|`'system'` (default)|Follows `prefers-color-scheme`, including changes while the page is open|
|`'dark'`|Always adds the class|
|`'light'`|Always removes the class|
|`'none'` or `null`|Never adds or removes the class. Your site sets it|

With the first three values, `ConsentScript` sets the class before first paint,
and c15t sets it again after each `ClientRouter` navigation. Set dark colors in
`theme.dark`. [Dark mode](/docs/customization/dark-mode) explains why Astro
follows the system setting by default.

Use `'none'` when your site has its own theme switch. Toggle `c15t-dark` on
`<html>` together with your own dark class. If your theme script does not run
on `astro:after-swap`, set the class again there, because a `ClientRouter`
swap replaces the attributes of `<html>`.

## Add links to your policies

Define the links once in the integration options:

```js title="astro.config.mjs (partial)"
c15t({
	legalLinks: {
		privacyPolicy: { href: '/privacy', label: 'Privacy policy' },
		cookiePolicy: { href: '/cookies', label: 'Cookie policy' },
	},
});
```

`ConsentBanner` and `ConsentDialog` show only the ones you list in their
`legalLinks` prop, such as `legalLinks={['privacyPolicy', 'cookiePolicy']}`.
A link without a `label` reads as the translated name for its type, such as
"Privacy Policy". See
[ConsentBanner legal links](/docs/frameworks/astro/components/consent-banner#legal-links).

## Style one part of a component

`theme.slots` in the integration options adds classes or inline styles to a
named part of the banner, the IAB banner and the dialogs:

```js title="astro.config.mjs (partial)"
c15t({
	theme: {
		slots: { consentBannerCard: 'brand-card', buttonPrimary: 'brand-button' },
	},
});
```

Define the classes in a global stylesheet. `class` on `ConsentBanner` goes on
the banner root. [Component parts](/docs/customization/slots) lists the slot
keys, and [Tailwind CSS](/docs/customization/tailwind) shows the Astro setup
for Tailwind 4 and 3.

## Turn off animations

`disableAnimation` in the integration options skips the banner's entry
animation and the dialogs' enter and exit animations. The same prop on
`ConsentBanner`, `ConsentDialog`, `IABConsentBanner` or `IABConsentDialog`
overrides it for one surface. c15t's stylesheet already stops these
animations for visitors who ask for reduced motion. [Motion and animation](/docs/customization/motion) covers the duration
and easing tokens.

## Load the stylesheet yourself

`ConsentScript`, or the first consent component on a layout without it,
inlines base and configured IAB banner rules once per page as `<style>`
elements. No c15t stylesheet holds back the first paint. When a visitor
first reaches for a dialog, c15t links its rules and waits for them before
mounting the surface. Svelte also loads its primitives stylesheet. The IAB
panel's rules load only when the IAB dialog opens.

On a Tailwind CSS 3 site, the integration adds `c15t/astro/styles.css` and,
with IAB configured, `c15t/astro/iab/styles.css` to every page instead, so
your `c15t/postcss-tailwind3` build processes them.
Tailwind 3 sites need no change, but their first paint still waits for that
stylesheet.
Do not import `c15t/astro/styles.css` as well. To control the cascade layer
order yourself, set `styles: false` and import the stylesheets from your own
CSS. [Stylesheets and CSS layers](/docs/customization/stylesheets#load-astros-stylesheets-yourself)
lists the files to import.

For markup with no c15t class names at all, pass `noStyle` to `ConsentBanner`
and style its `data-testid` and `data-*` attributes.

## Check your changes

* View the page source. It contains `<style id="c15t-theme">` with your tokens.
* Open the banner and the preference dialog in light and dark mode. Both use
  your colors, and every button label is readable.
* Change the browser language and reload. The copy follows it, or stays in
  `i18n.locale` when you set one.
* Navigate with `ClientRouter`. The colors and dark mode stay the same.

# Translations
URL: https://c15t.com/docs/frameworks/astro/translations
Set the language and wording of the c15t banner and preference dialog on an Astro site with the integration's i18n option, from Accept-Language negotiation to per-language message overrides and banner props.

## How the language is chosen

On a server-rendered page, the c15t middleware picks the language for each
request, in this order:

1. `i18n.locale`, when you set it.
2. The request's `Accept-Language` header, unless `i18n.detectLanguage` is
   `false`.
3. English.

The server inlines only that language's messages into the page, so the
browser downloads one language, not the whole catalogue. The banner root
carries `lang` and `dir` for it, so right-to-left languages such as Hebrew lay
out correctly.

On a static or prerendered page there is no request at build time. The HTML
starts in `i18n.locale` or English, and the browser switches to the language
its `/init` answer returns.

c15t ships messages for Bulgarian, Chinese, Croatian, Czech, Danish, Dutch,
English, Estonian, Finnish, French, German, Greek, Gujarati, Hebrew, Hindi,
Hungarian, Icelandic, Indonesian, Irish, Italian, Latvian, Lithuanian,
Luxembourgish, Maltese, Norwegian Bokmål, Norwegian Nynorsk, Polish,
Portuguese, Romanian, Romansh, Slovak, Slovenian, Spanish, Swedish and Welsh.

## Change the wording

Set `i18n.messages` in the integration options, keyed by language:

```js title="astro.config.mjs (partial)"
c15t({
	i18n: {
		messages: {
			en: {
				common: {
					acceptAll: 'Accept all',
					rejectAll: 'Reject optional',
					customize: 'Choose cookies',
				},
				cookieBanner: {
					title: 'Cookies on this site',
					description:
						'We use cookies to measure traffic and show relevant ads.',
				},
			},
		},
	},
});
```

`i18n.messages` merges key by key with the copy for that language, so pass
only the keys you change. Setting `common.acceptAll` keeps every other label
in `common`. In hosted and manifest mode the base is the copy your backend
sends, including wording edited in your Inth project, and your messages win
for the keys they set. In offline mode the base is the stock wording.

c15t looks up messages for the exact language first, then for its primary
language, so a visitor resolved to `de-AT` gets your `de` messages when there
is no `de-AT` entry. Override every language you support. A language you
leave out keeps the backend's or the stock wording.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps backend edits visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording.

The options are serialized into the page, so messages are plain strings.
[Copy and translations](/docs/customization/translations) lists the message
groups and how to word each action.

## Messages the banner reads

|Key|Shown as|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Heading and body of a choice banner|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Heading and body of a notice|
|`common.acceptAll`, `common.rejectAll`, `common.customize`|The choice banner's buttons|
|`common.acknowledge`|The button that acknowledges a notice|
|`rights.optOut`, `rights.preferences`|"Do not sell or share my data" and "Manage preferences"|
|`common.securedBy`|The branding tag|

The preference dialog reads the `consentManagerDialog`, `consentTypes` and
`common` groups. The IAB banner and dialog read the `iab` group.

## Force one language

Set `i18n.locale` to render every page in one language, whatever the browser
asks for:

```js title="astro.config.mjs (partial)"
c15t({ i18n: { locale: 'de' } });
```

Set `i18n.detectLanguage: false` instead to ignore `Accept-Language` and use
English unless `locale` says otherwise.

## Change the copy of one banner

`ConsentBanner` props win over the messages, for that banner only:

```astro title="src/layouts/base.astro (partial)"
<ConsentBanner
  title="Your privacy"
  acceptButtonText="Allow all"
  rejectButtonText="Only necessary"
/>
```

The props are `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. They apply
in every language, so use them only on a single-language site or with values
you translate yourself. See
[ConsentBanner props](/docs/frameworks/astro/components/consent-banner#props).

## Check the translations

1. Set your browser's preferred language to German and open a
   server-rendered page in a private window. The banner is in German, and its
   root has `lang="de"`.
2. Open **Privacy settings**. The dialog is in the same language.
3. Set `i18n.locale` and reload. The banner stays in that language whatever
   the browser asks for.
4. Test your longest labels at a narrow width, as
   [Copy and translations](/docs/customization/translations#test-more-than-english)
   describes.

# Components
URL: https://c15t.com/docs/frameworks/astro/components
Every c15t Astro component, from ConsentScript and ConsentBanner to the server island banner, the preference dialog, its link and the IAB TCF surfaces, with import paths and links to each reference.

## Where the components go

Every component reads `Astro.locals.c15t`, which the integration's middleware
sets on each request. Put them in the layout that wraps every page:

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

The `c15t()` integration in `astro.config.mjs` plays the part a provider plays
in React or Vue. It holds the configuration every component reads. See
[Integration options](/docs/frameworks/astro/integration).

## Component reference

Import the components by name from `c15t/astro/components`. Astro compiles
the `.astro` files it re-exports, so a page ships only what it renders.
`ConsentBannerDeferred` is the exception: it renders a server island, which
Astro refuses to build on a site without an adapter, so import it from its
own path.

|Component|Import from|Renders|
|--|--|--|
|[`ConsentScript`](/docs/frameworks/astro/components/consent-script)|`c15t/astro/components`|Inline scripts for the boot payload and color scheme, and the theme `<style>`|
|[`ConsentBanner`](/docs/frameworks/astro/components/consent-banner)|`c15t/astro/components`|The banner, as server HTML|
|[`ConsentBannerDeferred`](/docs/frameworks/astro/components/consent-banner-deferred)|`c15t/astro/components/consent-banner-deferred.astro`|The banner, in a server island|
|[`ConsentDialog`](/docs/frameworks/astro/components/consent-dialog)|`c15t/astro/components`|An empty host for the preference dialog island|
|[`ConsentDialogLink`](/docs/frameworks/astro/components/consent-dialog-link)|`c15t/astro/components`|A button or link that opens a dialog|
|[`IABConsentBanner`](/docs/frameworks/astro/components/iab-consent-banner)|`c15t/astro/components`|The IAB TCF banner, as server HTML|
|[`IABConsentDialog`](/docs/frameworks/astro/components/iab-consent-dialog)|`c15t/astro/components`|An empty host for the IAB TCF dialog island|

## How much JavaScript each component ships

The banners and the link are plain `.astro` markup and ship no framework
JavaScript. One small shared script turns their buttons into consent actions.
The dialogs are islands in the framework the integration's `ui` option names,
and they download only when a visitor first reaches for one. See
[Dialog islands and your own islands](/docs/frameworks/astro/islands).

Astro has no floating preferences widget, consent gate component or dev tools
component. Gate embeds with the pattern in
[Embeds](/docs/frameworks/astro/embeds), and inspect consent with the
[client API](/docs/frameworks/astro/client-api) and DevTools.

## What every component needs

* The `c15t()` integration in `astro.config.mjs`, with its middleware on.
  `ConsentBanner` and `IABConsentBanner` throw when `Astro.locals.c15t` is
  missing, and the others render nothing useful without it.
* A route that the middleware does not skip. A route in `middleware.skip` has
  no `Astro.locals.c15t`.
* For the dialogs, the Astro integration of the `ui` framework, listed before
  `c15t()`.

# ConsentScript
URL: https://c15t.com/docs/frameworks/astro/components/consent-script
Put the c15t ConsentScript component in the head of an Astro layout so the browser starts with the server's consent decision, the right color scheme and your theme tokens.

## Render `ConsentScript` in the layout head

Render `ConsentScript` once in the `<head>` of the layout that wraps every
page:

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

`ConsentScript` takes no props and ships no bundled JavaScript. Everything it
renders is inline, so it works before any module script has loaded.

## What it renders

`ConsentScript` renders up to three elements from `Astro.locals.c15t`:

|Element|When|Does|
|--|--|--|
|Color-scheme `<script>`|`colorScheme` is `'system'` or `'dark'`|Sets the `c15t-dark` class on `<html>` before first paint|
|`<style id="c15t-theme">`|The integration sets `theme`|Holds the `--c15t-*` custom properties for your tokens|
|Boot payload `<script type="application/json" data-c15t-config>`|Always|Hands the browser the consent decision the server resolved|

The boot payload is a JSON data block holding the resolved consent
configuration: the policy, the visitor's stored consent and the translations
for the negotiated language. The browser starts from it, so a page rendered on
the server needs no `/init` request and the banner does not flicker. The
payload escapes `<`, so translated text cannot close the script tag.

With `colorScheme: 'light'` or `'none'`, there is no color-scheme script.
Light is the absence of the class, and `'none'` leaves the class to your site.
See [set light or dark mode](/docs/frameworks/astro/customize#set-light-or-dark-mode).

## Rendered once per request

`ConsentBanner`, `IABConsentBanner` and `ConsentScript` all need the boot
payload, and a page often contains more than one of them. The first of these
components to render on a request emits the elements. The rest emit nothing.

Keep `ConsentScript` in `<head>` even though the banner would emit the same
elements. In `<head>`, the color-scheme script runs before the browser paints
anything, so a visitor whose system is dark never sees a light banner for a
frame.

## On prerendered and skipped routes

On a prerendered page, the boot payload carries no visitor state: no stored
consent, no clock and no privacy signal. The browser reads the visitor's own
cookie instead. See
[prerender pages in a server build](/docs/frameworks/astro/rendering#prerender-pages-in-a-server-build).

On a route listed in `middleware.skip`, `Astro.locals.c15t` is unset and
`ConsentScript` renders nothing. The page then starts without a server
decision, and the browser requests one.

## Content Security Policy

The color-scheme script and the theme `<style>` are inline code. They carry
`Astro.locals.c15t.nonce` when your middleware sets it, and under Astro's
`security.csp` the integration adds their hashes to the policy. The boot
payload is a data block that the browser never runs, so a policy does not
need to allow it. See
[Content Security Policy](/docs/frameworks/astro/content-security-policy).

## Next steps

* [ConsentBanner](/docs/frameworks/astro/components/consent-banner) renders the
  same elements when `ConsentScript` is missing.
* [Integration options](/docs/frameworks/astro/integration) covers `theme` and
  `colorScheme`.
* [Server API](/docs/frameworks/astro/server) documents `buildConfigJSON`,
  `buildThemeCSS` and `buildColorSchemeScript`, the helpers behind these
  elements.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/astro/components/consent-banner
Render the c15t consent banner as server HTML on an Astro site, with props for copy, legal links and branding, the policy-driven actions, accessibility behavior and the attributes to style it.

## Add the banner to your layout

Render one `ConsentBanner` in the layout that wraps every page, after your page
content:

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

`ConsentBanner` renders on the server from `Astro.locals.c15t`. It ships no
framework JavaScript. A small shared script adds one click listener to the
document, and that listener turns the banner's buttons into consent actions.

## When the banner renders

The server renders the banner markup only when the resolved policy asks for a
banner and this visitor has not answered yet:

* A returning visitor who has chosen gets no banner markup at all.
* A rule with `prompt: 'none'` renders no banner.
* With no resolved policy, because the backend failed, timed out or matched no
  rule, the server renders a hidden placeholder. The browser renders the banner
  into it if its own `/init` request resolves a policy.

On a prerendered page, the same HTML serves every visitor, so the banner ships
hidden. A small inline script right after it shows the banner at first paint
when the visitor has no stored consent. For a visitor with a stored choice,
the consent runtime decides once it has read the cookie. In `hosted()` and
`manifest()` modes, the build cannot know the policy, so the page carries the
placeholder and the browser renders the banner after `/init`. See
[Rendering and deployment](/docs/frameworks/astro/rendering).

After a save, the browser hides the banner by setting the `hidden` attribute.
After a `ClientRouter` navigation, it shows or hides the new page's banner to
match the visitor's state.

## Props

|Prop|Type|Default|Effect|
|--|--|--|--|
|`title`|`string`|`cookieBanner.title`, or `cookieBanner.noticeTitle` under a notice|Banner heading|
|`description`|`string`|`cookieBanner.description`, or `cookieBanner.noticeDescription` under a notice|Banner body text|
|`acceptButtonText`|`string`|`common.acceptAll`|Accept button label|
|`rejectButtonText`|`string`|`common.rejectAll`|Reject button label|
|`customizeButtonText`|`string`|`common.customize`|Customize button label|
|`dismissButtonText`|`string`|`common.acknowledge`|Label of the button that acknowledges a notice|
|`legalLinks`|`('privacyPolicy' \|'cookiePolicy' \|'termsOfService')[] \|null`|None|Which links from the integration's `legalLinks` render after the description|
|`hideBranding`|`boolean`|`false`|Removes the "Secured by" tag|
|`noStyle`|`boolean`|`false`|Renders the markup without c15t's class names or button styles|
|`class`|`string`|None|Extra class on the banner root, kept with `noStyle`|
|`force`|`boolean`|`false`|Renders the banner even when the server decided to hide it, for visual tests|
|`nonce`|`string`|`Astro.locals.c15t.nonce`|Content Security Policy nonce for this banner's inline scripts and style. See [Content Security Policy](/docs/frameworks/astro/content-security-policy#allow-c15t-with-a-nonce)|

A prop wins over the translation for the visitor's language, which wins over
the English default. For wording on every page, set `i18n.messages` in the
integration instead. See [Translations](/docs/frameworks/astro/translations).

`force` does not create a policy. With no resolved policy, or under a rule that
owes no consent interface, the banner still renders nothing. On a prerendered
page, `force` also renders the banner visible.

## Actions come from the policy

The resolved policy rule decides which buttons the banner shows and in which
order. The same resolver runs for the React, Vue and Svelte banners, so a rule
produces the same actions on every framework:

* A `choice` prompt shows Reject and Accept at equal prominence, plus
  Customize when the rule offers it. Customize is the primary action by
  default.
* A `notice` prompt shows an acknowledgement button and, under an opt-out
  rule, a "Do not sell or share my data" button. The acknowledgement records
  that the visitor saw the notice. It records no consent and changes no
  permission.
* A rule that keeps preferences reachable adds a "Manage preferences" button.

Every button that opens preferences opens the preference dialog. None of them
submits an opt-out by itself.
[How consent works](/docs/concepts/how-consent-works) explains prompts, rights
and recorded choices.

## Shape and position

The integration's `presentation.prompt` option sets the banner's variant and
position for every page. The policy still decides the actions:

|Variant|Positions|Default position|
|--|--|--|
|`floating` (default)|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|`top`, `bottom`|`bottom`|
|`widget`|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|`center`|`center`|

A default corner mirrors left and right for right-to-left languages. A
position you set is never mirrored. A choice `wall` always blocks the page. A
notice never blocks, and asking for a notice `wall` falls back to `floating`.
See [change the banner's shape and position](/docs/frameworks/astro/customize#change-the-banners-shape-and-position)
and the [design gallery](/docs/customization/recipes).

The banner has no per-page variant or layout prop. Every banner on the site
shares `presentation.prompt`.

## Legal links

Define the links once in the integration's `legalLinks` option, then pick
which ones this banner shows:

```astro title="src/layouts/base.astro (partial)"
<ConsentBanner legalLinks={['privacyPolicy', 'cookiePolicy']} />
```

A key renders only when the integration defines it. Each link opens in a new
tab. A link without a `label` reads as the translated name for its type, such
as "Privacy Policy" in English or "Datenschutzerklärung" in German. Set
`label` in the integration options, such as
`{ href: '/privacy', label: 'Privacy notice' }`, to use your own wording.
[`ConsentDialog`](/docs/frameworks/astro/components/consent-dialog#props)
takes the same `legalLinks` list.

## Accessibility

* The card has `role="region"` and an `aria-label` set to the banner title.
  It leaves the page usable by keyboard and pointer.
* A blocking banner, such as a choice `wall`, has `role="dialog"` and
  `aria-modal="true"`. The browser locks page scroll, traps focus inside the
  card and shows a backdrop until the visitor answers.
* The root carries `lang` and `dir` for the translation's language, so screen
  readers pronounce the copy correctly and right-to-left text lays out
  correctly.
* Every action is a `<button type="button">`. Until the consent runtime
  starts, a click does nothing, because the page has not loaded the handler
  yet.

## Style the banner

Theme tokens and `theme.consentActions` change colors, type, radius and button
styles without touching the markup. See
[Customize](/docs/frameworks/astro/customize).

To write your own CSS, target the attributes. They stay with `noStyle`:

|Element|Attributes|
|--|--|
|Root|`data-testid="consent-banner-root"`, `data-prompt` (`choice` or `notice`), `data-model`, `data-variant`, `data-position`, `data-blocking`, `data-c15t-visible`|
|Backdrop|`data-testid="consent-banner-overlay"`, rendered only for a blocking banner|
|Card|`data-testid="consent-banner-card"`|
|Title and description|`data-testid="consent-banner-title"`, `data-testid="consent-banner-description"`|
|Footer and button groups|`data-testid="consent-banner-footer"`, `data-direction`, `data-split`, `data-fill`|
|Each action|`data-action` (`accept`, `reject`, `customize` or `dismiss`), `data-testid="consent-banner-<action>-button"`|
|Each rights button|`data-action="right"`, `data-right` (`opt-out` or `preferences`)|
|Each legal link|`data-testid="consent-banner-legal-link-<key>"`|

Keep c15t's rules loaded when you restyle the banner. The browser hides the
banner with the `hidden` attribute, and c15t's rules make `hidden` win over
the banner's `display` rule.

## Next steps

* [ConsentBannerDeferred](/docs/frameworks/astro/components/consent-banner-deferred)
  renders this banner in a server island for cached pages.
* [ConsentDialog](/docs/frameworks/astro/components/consent-dialog) is what
  Customize opens.
* [IABConsentBanner](/docs/frameworks/astro/components/iab-consent-banner)
  replaces this banner under an IAB TCF policy.

# ConsentBannerDeferred
URL: https://c15t.com/docs/frameworks/astro/components/consent-banner-deferred
Render the c15t consent banner in an Astro server island, so a cached or prerendered page still shows each visitor the banner for their own location and stored choice.

## Render the banner in a server island

Use `ConsentBannerDeferred` in place of `ConsentBanner` when the page HTML is
cached or prerendered but the banner must still come from each visitor's own
request:

```astro title="src/layouts/cached.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';
import ConsentBannerDeferred from 'c15t/astro/components/consent-banner-deferred.astro';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBannerDeferred />
		<ConsentDialog />
	</body>
</html>
```

`ConsentBannerDeferred` renders `ConsentBanner` with Astro's `server:defer`
directive. The page HTML stays the same for everyone. After the page loads,
Astro requests the island from `/_server-islands/ConsentBanner`. That request
carries the visitor's cookie and location headers, so the c15t middleware
resolves consent for it and the banner arrives with the visitor's own policy.

## When to use it

|Page|Use|
|--|--|
|Rendered on each request|`ConsentBanner`|
|Served from a CDN cache, or prerendered, on a site with a server adapter|`ConsentBannerDeferred`|
|Built by a static site with no adapter|`ConsentBanner`, which the browser renders after `/init`|

Server islands need a server adapter. A purely static build cannot answer the
island request. See
[cache a page and render the banner per request](/docs/frameworks/astro/rendering#cache-a-page-and-render-the-banner-per-request).

## Props

`ConsentBannerDeferred` passes its props to `ConsentBanner`:

|Prop|Type|Default|Effect|
|--|--|--|--|
|`title`|`string`|Translation|Banner heading|
|`description`|`string`|Translation|Banner body text|
|`acceptButtonText`|`string`|`common.acceptAll`|Accept button label|
|`rejectButtonText`|`string`|`common.rejectAll`|Reject button label|
|`customizeButtonText`|`string`|`common.customize`|Customize button label|
|`dismissButtonText`|`string`|`common.acknowledge`|Label of the button that acknowledges a notice|
|`legalLinks`|`('privacyPolicy' \|'cookiePolicy' \|'termsOfService')[] \|null`|None|Which configured legal links to show|
|`hideBranding`|`boolean`|`false`|Removes the "Secured by" tag|
|`noStyle`|`boolean`|`false`|Renders the markup without c15t's class names|
|`class`|`string`|None|Extra class on the banner root|
|`force`|`boolean`|`false`|Renders the banner even when the server decided to hide it|

Astro serializes the props of a server island for the island request, so pass
plain strings, booleans and arrays. See
[ConsentBanner](/docs/frameworks/astro/components/consent-banner#props) for
what each prop does.

`ConsentBannerDeferred` also passes the page's `Astro.locals.c15t.nonce` to
the island, so the inline code the island inserts carries the nonce the
page's policy allows. Astro's own island loader carries no nonce, so a nonce
policy from your middleware blocks the island. See
[Content Security Policy](/docs/frameworks/astro/content-security-policy#pass-the-nonce-to-consentbanner-and-consentbannerdeferred).

## Show something while the island loads

Pass a `fallback` slot. Astro shows it until the island's response replaces
it:

```astro title="src/layouts/cached.astro (partial)"
<ConsentBannerDeferred>
  <div slot="fallback" aria-hidden="true"></div>
</ConsentBannerDeferred>
```

Most sites leave the fallback empty. A visitor who has already chosen gets an
empty island response, and a placeholder the size of a banner would flash and
disappear for them.

## What stays the same

* `ConsentScript` still goes in `<head>`. On a prerendered page it inlines a
  payload with no visitor state, and the island brings the visitor's own
  decision.
* `ConsentDialog` and `ConsentDialogLink` stay in the cached layout. They
  do not depend on the visitor.
* Accessibility, attributes and styling match
  [ConsentBanner](/docs/frameworks/astro/components/consent-banner).

## Check the server island

View the page source of a first visit. It contains no banner markup. In
DevTools Network, a request to `/_server-islands/ConsentBanner` returns it.
Accept or reject, then reload: the island request returns no banner. Vendor
requests stay absent until you allow their category. See
[Verify consent](/docs/guides/verify-consent).

## Next steps

* [Rendering and deployment](/docs/frameworks/astro/rendering) compares every
  rendering path.
* [Server API](/docs/frameworks/astro/server) explains how the middleware
  resolves the island's request.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/astro/components/consent-dialog
Add the c15t preference dialog to an Astro site as an island that downloads only when a visitor opens it, and control when it loads, which framework renders it, how it opens and which legal links it shows.

## Add the dialog to your layout

Render one `ConsentDialog` in the layout that wraps every page:

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

`ConsentDialog` renders an empty host element on the server. The preference
dialog mounts into the page the first time something opens it:

* The banner's **Customize** button, or a "Manage preferences" or "Do not sell
  or share my data" button on a notice.
* A [`ConsentDialogLink`](/docs/frameworks/astro/components/consent-dialog-link).
* A link to `#c15t-preferences`, when the page loads with that hash.
* `openDialog()` from [`c15t/astro/client`](/docs/frameworks/astro/client-api#open-and-close-dialogs).

## Props

|Prop|Type|Default|Effect|
|--|--|--|--|
|`preload`|`boolean`|`false`|Downloads the dialog once the browser is idle, on every page that renders it|
|`legalLinks`|`('privacyPolicy' \|'cookiePolicy' \|'termsOfService')[] \|null`|None|Which links from the integration's `legalLinks` the dialog shows, the same list `ConsentBanner` takes|

## When the dialog downloads

A visitor who only accepts or rejects from the banner never downloads the
dialog. The download starts before the click, when the pointer moves over a
control that opens the dialog or keyboard focus reaches one. On a touch
screen, the tap itself starts it, so the first open can wait for the download.

With `preload`, the dialog downloads in the browser's first idle period, or
after two seconds in browsers without `requestIdleCallback`. Use it when the
first open must feel instant for every visitor. It costs a background download
on each page, including for visitors who never open the dialog.

To download the dialog from your own code, call `preloadDialog()` from
`c15t/astro/client`.

## Which framework renders it

The dialog is the `ConsentDialog` component of the framework that the
integration's `ui` option names:

|`ui`|Renders with|Astro integration to install|
|--|--|--|
|`'svelte'` (default)|`@c15t/svelte`|`@astrojs/svelte` and `svelte`|
|`'react'`|`c15t/react`|`@astrojs/react`, `react` and `react-dom`|
|`'vue'`|`c15t/vue`|`@astrojs/vue` and `vue`|

Pick the framework your site already ships, so visitors do not download a
second one for a single dialog. See
[Dialog islands and your own islands](/docs/frameworks/astro/islands).

## What the dialog contains

The dialog lists the categories the policy covers, each with a switch, and
offers Accept All, Reject All and Save Settings. `necessary` is always on. The dialog
follows the integration's `theme`, `presentation.preferences` and
`consentCategories`. With `vendors` declared, each category also lists its
vendors with a switch per vendor. See
[vendor consent](/docs/frameworks/astro/vendor-consent).

To link your policies from the dialog, define them in the integration's
`legalLinks` option and list the keys in the `legalLinks` prop:

```astro title="src/layouts/base.astro (partial)"
<ConsentDialog legalLinks={['privacyPolicy', 'cookiePolicy']} />
```

c15t passes the list to the Svelte, React or Vue dialog island. A key renders
only when the integration defines it. A link without a `label` reads as the
translated name for its type, such as "Privacy Policy" in English.

Save Settings, Accept All and Reject All record a choice and close the dialog. Turning
off a category that was allowed reloads the page, unless the integration sets
`reloadOnConsentRevoked: false`. See
[withdraw consent without reloading](/docs/frameworks/astro/scripts#withdraw-consent-without-reloading).

The dialog does not open while no policy is resolved, or under a rule that owes
no consent interface. An `openDialog()` call made while `/init` is still in
flight waits for the answer.

## Stylesheets

The page carries only the banner's rules. The first time a visitor reaches
for the dialog, c15t links the dialog's rules from
`@c15t/ui/styles/sheets/dialog.css`, plus the primitives stylesheet for the
Svelte dialog, and waits for them to load before the dialog paints. On a
Tailwind CSS 3 site, the dialog's rules come with `c15t/astro/styles.css` on
every page, and c15t links only the primitives stylesheet. With
`styles: false`, import `c15t/astro/styles.css` yourself, which holds the
dialog's rules too, and `c15t/astro/primitives.css` for the Svelte dialog. See
[load the stylesheet yourself](/docs/frameworks/astro/customize#load-the-stylesheet-yourself).

## Across `ClientRouter` navigation

The dialog host is part of `<body>`, which `ClientRouter` replaces. When a
visitor navigates with the dialog open, c15t mounts it again on the new page,
so it stays open. A stylesheet c15t linked for the dialog carries over to the
new page too.

## Accessibility

The dialog keeps the focus and keyboard behavior of its framework's
`ConsentDialog`. It opens as a modal dialog, and Escape closes it. Whether it
locks page scroll follows `presentation.preferences` in the integration
options. Every framework renders the same markup and labels, so the dialog
behaves the same whichever `ui` you pick.

## Next steps

* [ConsentDialogLink](/docs/frameworks/astro/components/consent-dialog-link)
  reopens the dialog from your footer.
* [IABConsentDialog](/docs/frameworks/astro/components/iab-consent-dialog) is
  the IAB TCF preference center.
* [Integration options](/docs/frameworks/astro/integration#ui) documents `ui`
  and `requireUIIntegration`.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/astro/components/consent-dialog-link
Add a footer button or link that reopens the c15t preference dialog or the IAB TCF preference center on an Astro site, with no JavaScript of its own.

## Add the link to your footer

Put one `ConsentDialogLink` in your footer, so visitors can change their
choice at any time. Its children are the label:

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

`ConsentDialogLink` renders a plain `<button>` or `<a>` with no styles of
its own. It carries `data-c15t-action="customize"`, and the same shared
listener the banner uses opens the dialog on click.

## Props

|Prop|Type|Default|Effect|
|--|--|--|--|
|`kind`|`'preferences' \|'iab'`|`'preferences'`|Which dialog to open|
|`as`|`'button' \|'a'`|`'button'`|Renders a `<button type="button">`, or an `<a href="#c15t-preferences">`|
|`class`|`string`|None|Class names for your own styles|

Use `as="a"` when your footer styles links and not buttons. The click handler
cancels the link's navigation, so the page does not jump.

## When the link is hidden

The link renders with the `hidden` attribute while there is nothing to
manage:

* No policy is resolved yet, or the backend request failed.
* The resolved rule has `prompt: 'none'` and no rights, so it owes no consent
  interface.

The browser removes `hidden` as soon as a later `/init` answer supplies a rule
that owes one, and adds it back if the rule stops owing one.

If your own CSS sets `display` on the link, keep `[hidden]` hidden too, for
example with `.footer-link[hidden] { display: none; }`.

## Open the IAB preference center

With an IAB TCF policy, set `kind="iab"`:

```astro title="src/layouts/iab.astro (partial)"
<ConsentDialogLink kind="iab">Privacy settings</ConsentDialogLink>
```

The page needs `IABConsentDialog` for `kind="iab"`, and `ConsentDialog` for
the default kind. See [IAB TCF](/docs/frameworks/astro/iab).

## Accessibility

The link is a real `<button>` or `<a>`, so it is reachable with Tab and
activates with Enter. Give it a label that says what it opens, such as
"Cookie preferences" or "Privacy settings". Keyboard focus or a hover on a
link for the preference dialog starts downloading it, so by the time the
visitor presses Enter the dialog is usually ready.

## Open a dialog from your own control

A control that is not a `ConsentDialogLink` can open the dialog with
`openDialog()` from `c15t/astro/client`. See
[open and close dialogs](/docs/frameworks/astro/client-api#open-and-close-dialogs).

## Next steps

* [ConsentDialog](/docs/frameworks/astro/components/consent-dialog) is the
  dialog this link opens.
* [Verify consent](/docs/guides/verify-consent) checks that preferences reopen
  after a choice.

# IABConsentBanner
URL: https://c15t.com/docs/frameworks/astro/components/iab-consent-banner
Render the IAB TCF 2.4 banner as server HTML on an Astro site with c15t, with the purposes, partner count and actions TCF requires, its props, accessibility and styling attributes.

## Swap in the IAB banner and dialog

Under an IAB TCF policy, replace `ConsentBanner` and `ConsentDialog` with the
IAB pair:

```astro title="src/layouts/iab.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialogLink,
	ConsentScript,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink kind="iab">Privacy settings</ConsentDialogLink>
		</footer>
		<IABConsentBanner />
		<IABConsentDialog />
	</body>
</html>
```

The integration must set `iab`. See [IAB TCF](/docs/frameworks/astro/iab) for
the CMP ID, the vendor list and publisher restrictions.

## What it renders

`IABConsentBanner` renders on the server, with no framework JavaScript:

* A title and description that name the number of partners. The partners
  count is a button that opens `IABConsentDialog` on the vendors tab.
* A list of the purposes, stacks and special features the vendor list covers,
  with "and N more" when it names only some.
* A notice about legitimate interest, and whether the choice applies to this
  site only or to a group of sites.
* Reject All and Accept All, plus a Customize button that opens the IAB
  preference center.

The banner sits in the bottom-left corner, or bottom-right for right-to-left
languages. It does not read the `presentation.prompt` variant or position.

The summary comes from the same model the React, Svelte and Vue IAB banners
read, so every framework names the same purposes.

## When it renders

The banner needs a resolved IAB policy and a vendor list, because every line
of its copy counts from the list.

* With server output, `manifest()` and `hosted()` get the vendor list through
  `/init`, and the banner is part of the first HTML.
* In `offline()` mode, set `iab.gvl` or `iab.gvlURL`, or the server has no
  list to render from.
* On a prerendered page, or while the list has not arrived, the server renders
  a hidden placeholder. The browser renders the banner into it once it has
  both the policy and the list.

A visitor who has already chosen gets no banner markup.

## Props

|Prop|Type|Default|Effect|
|--|--|--|--|
|`primaryButton`|`'accept' \|'reject' \|'customize'`|`'customize'`|Which action gets the filled button|
|`models`|`string[]`|`['iab']`|Consent models this banner responds to|
|`scrollLock`|`boolean`|From `presentation`|Makes the banner blocking, with a backdrop, scroll lock and focus trap|
|`hideBranding`|`boolean`|`false`|Removes the "Secured by" tag|
|`noStyle`|`boolean`|`false`|Renders the markup without c15t's class names|
|`class`|`string`|None|Extra class on the banner root|
|`force`|`boolean`|`false`|Renders the banner even when the server decided to hide it|

The banner's copy comes from the IAB translations for the visitor's language.
It has no copy props.

## Accessibility

* The card has `role="region"` and an `aria-label` set to the banner title.
* A blocking banner has `role="dialog"` and `aria-modal="true"`. The browser
  locks page scroll and traps focus in the card until the visitor answers.
* The partners count is a `<button>`, so keyboard users can open the vendor
  list from the description.
* The root carries `lang` and `dir` for the translation's language.

## Style the banner

The integration inlines IAB banner rules when `iab` is set. Its preference
center rules load when the IAB dialog opens. Tailwind CSS 3 uses the full
external IAB stylesheet instead. The banner keeps its own button styles and does
not read `theme.consentActions`. Theme tokens still apply.

|Element|Attributes|
|--|--|
|Root|`data-testid="iab-consent-banner-root"`, `data-position`, `data-blocking`, `data-c15t-visible`|
|Backdrop|`data-testid="iab-consent-banner-overlay"`|
|Card and footer|`data-testid="iab-consent-banner-card"`, `data-testid="iab-consent-banner-footer"`|
|Partners button|`data-testid="iab-consent-banner-partners-link"`|
|Actions|`data-action` and `data-testid="iab-consent-banner-<action>-button"`|

## Next steps

* [IABConsentDialog](/docs/frameworks/astro/components/iab-consent-dialog)
  is the preference center this banner opens.
* [IAB TCF](/docs/frameworks/astro/iab) covers configuration and testing.

# IABConsentDialog
URL: https://c15t.com/docs/frameworks/astro/components/iab-consent-dialog
Add the IAB TCF 2.4 preference center to an Astro site with c15t as an island that loads the TCF code only when a visitor opens it.

## Render the dialog next to `IABConsentBanner`

Render one `IABConsentDialog` next to `IABConsentBanner`:

```astro title="src/layouts/iab.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialogLink,
	ConsentScript,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink kind="iab">Privacy settings</ConsentDialogLink>
		</footer>
		<IABConsentBanner />
		<IABConsentDialog />
	</body>
</html>
```

`IABConsentDialog` renders an empty host element on the server. The IAB
preference center and the TCF code both load the first time something opens
it:

* The IAB banner's **Customize** button.
* The IAB banner's partners count, which opens the vendors tab.
* A `<ConsentDialogLink kind="iab">`.
* `openDialog('iab', 'vendors')` or `openDialog('iab', 'purposes')` from
  [`c15t/astro/client`](/docs/frameworks/astro/client-api#open-and-close-dialogs).

A page with IAB configured still serves a banner-only first load with no TCF
bytes.

## Props

|Prop|Type|Default|Effect|
|--|--|--|--|
|`preload`|`boolean`|`false`|Downloads the dialog once the browser is idle|

Hovering or focusing an IAB control does not start the download early, as it
does for the preference dialog. Set `preload` when the IAB preference center
must open without a wait.

## What it contains

The preference center is the IAB dialog of the framework the integration's
`ui` option names. It has tabs for purposes and vendors, per-purpose and
per-vendor controls including legitimate interest, and Accept All, Reject All
and Save Settings. Saving writes the TC String, which `__tcfapi` then reports.

Opening the dialog on a different tab than the one it shows remounts it on
that tab.

## Next steps

* [IABConsentBanner](/docs/frameworks/astro/components/iab-consent-banner)
* [IAB TCF](/docs/frameworks/astro/iab) covers the CMP ID, the vendor list and
  how to check the TC String.
* [Dialog islands and your own islands](/docs/frameworks/astro/islands)
  explains the `ui` option.

# Client API
URL: https://c15t.com/docs/frameworks/astro/client-api
Reference for c15t/astro/client on an Astro site, grouped by task, from reading permissions and recorded choices to opening dialogs, saving consent, gated scripts, the page runtime and analytics events.

## One runtime per page load

The `c15t()` integration starts one consent runtime per page load and keeps
it across `ClientRouter` navigation. Every script and island on the page
shares it. There is no provider to wrap your components in.
`c15t/astro/client` is how browser code reaches that runtime.

`getConsentClient()` returns the page's client, or `null` on the server and
before the runtime starts. The runtime starts from a module script, and module
scripts run in document order, so a script of yours can run first. Try again
on `DOMContentLoaded`, which fires after every module script has run:

```astro title="src/components/consent-video.astro"
---
import { ConsentDialogLink } from 'c15t/astro/components';
---

<consent-video>
	<div data-video>
		<p>Allow measurement to load this YouTube video.</p>
	</div>
	<ConsentDialogLink>Open privacy settings</ConsentDialogLink>
</consent-video>

<script>
	import { getConsentClient } from 'c15t/astro/client';

	class ConsentVideo extends HTMLElement {
		dispose?: () => void;

		connect = () => {
			const client = getConsentClient();
			const container = this.querySelector('[data-video]');
			if (this.dispose || !client || !container) {
				return;
			}
			const render = () => {
				// Measurement is allowed and the visitor has not switched YouTube
				// off. An undeclared vendor is never allowed, so declare youtube.
				if (!client.isVendorAllowed('youtube')) {
					container.textContent =
						'Allow measurement to load this YouTube video. No video request is sent before permission.';
					return;
				}
				if (container.querySelector('iframe')) {
					return;
				}
				const frame = document.createElement('iframe');
				frame.src = 'https://www.youtube-nocookie.com/embed/czTksCF6X8Y';
				frame.title = 'YouTube video';
				frame.allowFullscreen = true;
				container.replaceChildren(frame);
			};
			render();
			this.dispose = client.subscribe(render);
		};

		connectedCallback() {
			// c15t boots from a module script, which can run after this one.
			document.addEventListener('DOMContentLoaded', this.connect, {
				once: true,
			});
			this.connect();
		}

		disconnectedCallback() {
			document.removeEventListener('DOMContentLoaded', this.connect);
			this.dispose?.();
			this.dispose = undefined;
		}
	}

	if (!customElements.get('consent-video')) {
		customElements.define('consent-video', ConsentVideo);
	}
</script>
```

The exports that take no client, such as `getConsent()` and `openDialog()`,
look the client up for you and do nothing before it starts.

## Read a permission, not a recorded choice

A consent snapshot holds both. They answer different questions:

|Field|Answers|Use it to|
|--|--|--|
|`effectivePermissions`|May this run now?|Load a script, render an embed, send an event|
|`explicitChoice`|What did the visitor decide?|Show the visitor's choice, report consent rates|

Under an opt-out policy, `effectivePermissions.measurement` can be `true`
before the visitor has done anything, while `explicitChoice` is `null`. A
Global Privacy Control signal can turn a permission off with no recorded
choice at all. Gate code on `effectivePermissions`. See
[How consent works](/docs/concepts/how-consent-works) and the
[consent state reference](/docs/concepts/consent-state).

## Read consent

|Export|Returns|
|--|--|
|`getConsentClient()`|The page's `AstroConsentClient`, or `null`|
|`getConsent()`|The current snapshot, or `null` before the runtime starts|
|`subscribe(listener)`|An unsubscribe function. `listener` receives every new snapshot. Before the runtime starts, it returns a no-op|

The client has the same two methods, `client.getConsent()` and
`client.subscribe(listener)`, which never return `null`.

The snapshot fields you are most likely to read:

|Field|Holds|
|--|--|
|`effectivePermissions`|`true` or `false` for each category, right now|
|`explicitChoice`|The visitor's recorded decision per category, or `null`|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`, and `null` before the policy resolves|
|`model`|The policy's model: `'opt-in'`, `'opt-out'`, `'iab'` or `'none'`|
|`policyRule`|The matched rule, with its `id`, `prompt` and `rights`|
|`policyPending`|`true` while the first `/init` answer is outstanding|
|`location`|Country and region the backend resolved, or `null`|
|`translations`|The active language and its translation bundle|

A listener runs synchronously on each change. Keep it quick, and read only the
fields you need.

## Read vendor consent

When the integration declares [vendors](/docs/frameworks/astro/vendor-consent),
the client also answers per vendor:

|Member|Returns|
|--|--|
|`client.getDeclaredVendors()`|The vendors from `vendors`, the backend manifest and the slugs on scripts and iframes. Empty under an IAB policy|
|`client.getVendorChoice()`|The recorded vendor decision, whose `denied` lists the vendors the visitor switched off, or `null`|
|`client.isVendorAllowed(id)`|`true` when the vendor is declared, its category is allowed and the visitor has not switched it off|

`isVendorAllowed()` returns `false` for an id nothing declares, such as a
typo or a vendor missing from `vendors`. In development it also logs a
console warning that names the id.

## Open and close dialogs

|Member|Does|
|--|--|
|`openDialog(kind?, tab?)`|Opens `'preferences'` (default) or `'iab'`. For `'iab'`, `tab` is `'purposes'` or `'vendors'`|
|`client.closeDialog()`|Closes the open dialog. The banner comes back while the policy still owes a choice|
|`preloadDialog()`|Downloads the dialog without opening it|

`openDialog()` downloads and mounts the dialog island the first time. While
the first `/init` answer is outstanding, it waits for it, then opens nothing
if the policy owes no consent interface.

`ConsentDialogLink` needs no script. For a control you render yourself,
call `openDialog()` from its click handler:

```ts
import { openDialog } from 'c15t/astro/client';

document.querySelector('#privacy-link')?.addEventListener('click', () => {
	void openDialog();
});
```

## Save consent

|Member|Does|
|--|--|
|`client.acceptAll()`|Without IAB, saves a grant for every category in scope. Under an IAB policy, an optional category is granted only if a listed or custom vendor declares a consent purpose mapped to it after publisher restrictions apply. The CMP sets vendor and purpose consent for declared consent purposes, separate legitimate-interest signals for declared legitimate-interest purposes, and opt-ins for declared special features. The TC string records these signals. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy)|
|`client.rejectAll()`|Saves a rejection of everything except `necessary`, through the CMP under an IAB policy|
|`client.save(consents)`|Saves the categories you pass, such as `{ measurement: true }`. A `vendors` map, such as `{ vendors: { posthog: false } }`, saves vendor switches too|
|`client.identify(user)`|Links the consent record to your own user, as `{ externalId }`|

Each applies the choice in the browser at once, closes the open banner or
dialog, and returns a promise that settles when the backend has answered. A
failed request keeps the choice in the browser and retries later. See
[when a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
for which surface shows next.

Save only from a visitor's action, such as a button click. Calling
`acceptAll()` or `save()` when a page loads records a choice the visitor never
made. A save that turns off a category that was allowed reloads the page,
unless the integration sets `reloadOnConsentRevoked: false`.

Call `identify()` after your visitor signs in. `externalId` is your own user
ID. `identityProvider`, `properties` and an
[`identityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) that verifies the link are optional.

## Run gated inline scripts

`activateGatedScripts(snapshot, root?)` runs every inline script marked
`type="text/plain"` and `data-c15t-category` that the snapshot allows, inside
`root` or the whole document. A script that also carries `data-c15t-vendor`
waits until the visitor has not switched that vendor off. It returns the
number of scripts it ran.

c15t calls it after every consent change and every `ClientRouter`
navigation. Call it yourself only for markup you insert from your own code:

```ts
import { activateGatedScripts, getConsent } from 'c15t/astro/client';

const snapshot = getConsent();
if (snapshot) {
	activateGatedScripts(snapshot, container);
}
```

See [gate an inline script](/docs/frameworks/astro/scripts#gate-an-inline-script).

## Use the page runtime directly

The client exposes two properties for advanced use:

|Member|Holds|
|--|--|
|`client.runtime`|The underlying consent runtime. Pass it to a React, Vue or Svelte island. See [your own islands](/docs/frameworks/astro/islands#use-consent-in-your-own-islands)|
|`client.options`|The integration options as the browser received them|

`client.runtime.kernel.events.on(type, listener)` subscribes to individual
consent events, such as `'choice:recorded'` and `'permissions:changed'`. For
most sites, the `callbacks` in the client entrypoint are simpler. See
[Callbacks](/docs/frameworks/astro/callbacks).

Do not call `client.dispose()` in your own code. The page owns the runtime,
and a disposed runtime stops every consent surface on the page.

## Keep scripts working across `ClientRouter`

With `ClientRouter`, module scripts run once per page load, not once per
navigation. The consent runtime survives each swap, so `getConsentClient()`
keeps returning the same client and your subscriptions keep firing.

Markup your script changed is replaced on a swap. Render it again on
`astro:page-load`:

```ts
import { getConsent, subscribe } from 'c15t/astro/client';

const render = () => {
	const allowed = getConsent()?.effectivePermissions.measurement ?? false;
	document
		.querySelector('#analytics-state')
		?.replaceChildren(allowed ? 'Analytics on' : 'Analytics off');
};

subscribe(render);
document.addEventListener('astro:page-load', render);
```

A custom element, like the video component above, reconnects on its own when
the new page contains it.

## Send analytics events after consent

`createEventDispatcher` from `@c15t/integrations/events` sends your own events to
the vendors you registered, and only while their consent allows it. Pass the
same scripts and the page's `getConsent`:

```ts title="src/analytics-events.ts"
import { createEventDispatcher } from '@c15t/integrations/events';
import { getConsentClient } from 'c15t/astro/client';

import consentClient from './c15t.client';

export const trackSearch = function trackSearch(resultCount: number) {
	const client = getConsentClient();
	if (!client) {
		return;
	}
	const events = createEventDispatcher({
		getSnapshot: client.getConsent,
		scripts: consentClient.scripts ?? [],
	});
	events.track('search', { resultCount });
};
```

Events sent while consent is denied are dropped, not queued. Keep search text
and other personal data out of event properties unless you have set up their
collection on purpose.

## Advanced exports

`c15t/astro/client` also exports what the integration's page script uses:
`boot`, `attachBannerActions`, `registerDialogAdapter`,
`registerDialogSurface`, `registerDialogStyles`, `syncBannerVisibility` and
`syncSurfaceVisibility`, plus the attribute names `ACTION_ATTRIBUTE`,
`DIALOG_ATTRIBUTE` and `DIALOG_TAB_ATTRIBUTE`. The integration calls them for
you. You need them only to run c15t's client without the integration, as a
test harness does. The script loader, the network blocker and a
`consentSource` connection come from the integration's page script, so
`boot()` on its own throws when the options configure `scripts`,
`networkBlocker` or `consentSource`.

## Check the client API

* Load a page with the video component above in a fresh private window. The
  placeholder shows, and DevTools Network has no request to
  `youtube-nocookie.com`.
* Allow and deny measurement from **Privacy settings**. The video appears
  after you allow it and disappears after you withdraw it, when the page
  reloads.
* Navigate with `ClientRouter` and confirm your script still reacts. Scripts
  that change markup should listen for `astro:page-load`.

# Callbacks
URL: https://c15t.com/docs/frameworks/astro/callbacks
Run your own code on an Astro site when a visitor records a consent choice, when permissions change, before a revocation reload and on errors, with c15t callbacks in the client entrypoint.

## Where callbacks go

Callbacks are functions, and the integration options in `astro.config.mjs`
must survive JSON serialization. So callbacks go in the default export of the
module that the integration's `clientEntrypoint` names. They run in the
browser, on the page's one consent runtime.

Put them in their own module:

```ts title="src/consent-callbacks.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';

export const callbacks: C15tClientOptionsExtension['callbacks'] = {
	// Runs when the visitor selects accept, reject or save.
	onChoiceRecorded: ({ snapshot }) => {
		document.dispatchEvent(
			new CustomEvent('consent:choice', { detail: snapshot.explicitChoice })
		);
	},
	// Runs whenever a permission changes, whatever the cause.
	onPermissionsChanged: ({ previous, snapshot }) => {
		document.dispatchEvent(
			new CustomEvent('consent:permissions', {
				detail: { current: snapshot.effectivePermissions, previous },
			})
		);
	},
};
```

Then add them to the client entrypoint from the
[quickstart](/docs/frameworks/astro/quickstart):

```ts title="src/consent-client.ts (partial)"
import { callbacks } from './consent-callbacks';
import { scripts } from './scripts';

export default { callbacks, scripts } satisfies C15tClientOptionsExtension;
```

## Choose the callback

|Callback|Runs when|Receives|
|--|--|--|
|`onChoiceRecorded`|The visitor selects accept, reject or save|`{ snapshot, confirmed, actionAt }`|
|`onPermissionsChanged`|Any effective permission changes value|`{ snapshot, previous }`|
|`onBeforeConsentRevocationReload`|A save turned off a category that was allowed, just before the page reloads|`{ preferences }`|
|`onError`|c15t reports an error, such as a failed request|`{ error }`, a message string|

## `onChoiceRecorded` versus `onPermissionsChanged`

They answer different questions:

* `onChoiceRecorded` means the visitor did something. It runs once per
  accept, reject or save. `snapshot.explicitChoice` holds the recorded
  decision. Use it to report consent rates or to send a choice to your own
  systems.
* `onPermissionsChanged` means what may run has changed. It runs after a
  choice that changes a permission, and also when a policy, an expiry or a
  Global Privacy Control signal changes one. `previous` holds the permissions
  before the change, and `snapshot.effectivePermissions` holds them after.
  Use it to start or stop your own code.

Neither callback runs for a notice acknowledgement, which records no consent.
A returning visitor whose stored choice loads on page load triggers no
`onChoiceRecorded`, because loading a stored choice is not an action. On a
static or prerendered page, the browser loads that choice after the page
starts, so `onPermissionsChanged` can run on page load. Write it to handle
that.

## Stop code when consent is withdrawn

By default, c15t reloads the page after a save turns off a category that was
allowed, because it cannot stop code that has already run.
`onBeforeConsentRevocationReload` runs synchronously just before that reload.
Use it for quick work, such as calling a vendor's opt-out API. The reload does
not wait for promises.

With `reloadOnConsentRevoked: false` in the integration, there is no reload.
Stop your own code from `onPermissionsChanged` instead, and check that every
vendor on the page can stop itself. See
[withdraw consent without reloading](/docs/frameworks/astro/scripts#withdraw-consent-without-reloading).

## Listen from a script instead

Callbacks run for the whole site. A script on one page can subscribe to
changes itself with `subscribe()` from `c15t/astro/client`. For single
events, `getConsentClient()?.runtime.kernel.events.on('choice:recorded', listener)`
takes the same event names the callbacks map to. See the
[client API](/docs/frameworks/astro/client-api).

## Check your callbacks

1. Open the site in a private window and select **Accept All**.
   `onChoiceRecorded` runs once and `onPermissionsChanged` runs with
   `previous.measurement` set to `false`.
2. Reload. `onChoiceRecorded` does not run, because loading a stored choice
   is not a new action.
3. Open **Privacy settings**, turn off **Analytics** (the `measurement` category) and save.
   `onChoiceRecorded` and `onPermissionsChanged` run, and
   `onBeforeConsentRevocationReload` runs before the page reloads.

# IAB TCF
URL: https://c15t.com/docs/frameworks/astro/iab
Render the IAB TCF 2.4 banner and preference center on an Astro site with the c15t integration, and configure the CMP ID, vendor list source and publisher restrictions.

## Before you start

Use IAB TCF when your site works with advertising vendors that read a TC
String. You need:

* An Inth project whose policy for the relevant regions uses the `iab` model.
* A CMP ID. IAB Europe assigns one when a company registers as a CMP at
  [register.consensu.org/CMP](https://register.consensu.org/CMP). Every TC
  String names the CMP that wrote it, so use the ID your company registered.

The `c15t` package includes the IAB code, so there is nothing else to
install.

## Turn on IAB in the integration

Add `iab` to the integration options from the
[quickstart](/docs/frameworks/astro/quickstart):

```js title="astro.config.mjs (partial)"
c15t({ iab: { cmpId: 123 } });
```

Replace `123` with your registered CMP ID. A hosted backend can supply the CMP
ID through `/init`, so `cmpId` is optional when your Inth project has one.
The integration inlines the IAB banner's rules once per page. Its preference
center rules load before the IAB dialog opens, so there is no IAB stylesheet
request before the page's first paint. Tailwind CSS 3 sites use the full
external IAB stylesheet so the host's CSS pipeline can process it.

IAB stays off until you set `iab`. Without it, or with `iab: false` or
`enabled: false`, the page script contains no CMP code and the browser never
downloads `@c15t/iab`.

If a visitor's policy uses the `iab` model and the backend sends its vendor
list while `iab` is unset, the server render throws an `IABUnavailableError`
(code `C15T_IAB_UNAVAILABLE`). A page the browser resolves itself, such as a
prerendered one, throws it there as an uncaught error. The standard banner
does not handle the IAB model, so the visitor would otherwise get no working
consent UI. Set `iab`, or remove the `iab` model from the policy. A backend
that answers `gvl: null` turns IAB off for the request, and the policy runs
as opt-in.

|Option|Effect|
|--|--|
|`cmpId`|Your registered CMP ID|
|`cmpVersion`|The CMP version `__tcfapi` reports|
|`vendors`|Limits the vendor list to these vendor IDs|
|`publisherCountryCode`|Publisher country written into the TC String|
|`publisherRestrictions`|Restrictions written into the TC String and applied to vendors|
|`gvl`|A vendor list to use as-is, for offline mode|
|`gvlURL`|Where the server fetches the vendor list, for offline mode|
|`enabled`|Set `false` to keep the configuration but turn IAB off|

## Render the IAB banner and dialog

Replace the standard banner and dialog with the IAB pair. The footer trigger
opens the IAB preference center:

```astro title="src/layouts/iab.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialogLink,
	ConsentScript,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink kind="iab">Privacy settings</ConsentDialogLink>
		</footer>
		<IABConsentBanner />
		<IABConsentDialog />
	</body>
</html>
```

`IABConsentBanner` lists the purposes and the number of partners from the
vendor list, and renders nothing until a vendor list is available. Its
partners link opens `IABConsentDialog` on the vendors tab. See
[IABConsentBanner](/docs/frameworks/astro/components/iab-consent-banner) for props.

With server output, the layout can choose per request. When only some visitors
get an IAB policy, render the IAB pair when
`Astro.locals.c15t.snapshot.model` is `'iab'` and the standard pair otherwise.

## Where the vendor list comes from

|Mode|Vendor list source|
|--|--|
|`manifest()`|The server resolves it, and the browser reads it through the same-origin `/api/c15t/init` route|
|`hosted()`|The browser fetches it from the backend's `/init` after the page loads|
|`offline()`|The `gvl` or `gvlURL` option|

In hosted mode, the backend's `/init` must be reachable from the browser and
accept requests from your site's origin without server-only credentials. For a
private backend, put a public same-origin proxy in front of it that adds the
credentials on the server.

On a static page, the build has no vendor list, so the IAB banner appears once
the browser has one.

## Publisher restrictions

Pass `publisherRestrictions` in the `iab` options. Each entry names a
`purposeId`, a `restrictionType` and the `vendorIds` it applies to.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Check the IAB setup

Open the site in a private window from a region your IAB policy covers:

1. The IAB banner shows the purposes and a partner count. No advertising
   vendor requests appear in DevTools Network.
2. Select the partners link. The preference center opens on the vendors tab.
3. Save a choice. In the console, `__tcfapi('getTCData', 2, console.log)`
   reports a TC String, and an `euconsent-v2` cookie exists.
4. Reload. The banner stays closed and the TC String is the same.
5. Open **Privacy settings** from the footer. The IAB preference center
   opens with your saved choices.

Test the vendors' own requests as well. A category-only test does not show
that the IAB flow works.

# IAB GPP
URL: https://c15t.com/docs/frameworks/astro/gpp
Expose the IAB Global Privacy Platform API (__gpp) on an Astro site with the c15t integration's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

With `gpp` set, the c15t integration installs `window.__gpp`, the GPP 1.1
CMP API, when the page boots. It keeps the GPP string in step with the
visitor's choices. Prebid.js, Google Ad Manager and other ad tech read US
privacy signals from it.

## Turn on GPP

Add `gpp` to the integration options from the
[quickstart](/docs/frameworks/astro/quickstart):

```js title="astro.config.mjs (partial)"
c15t({ gpp: true });
```

Replace `https://your-project.inth.app` with your project's backend URL.
`gpp: true` uses the defaults. Pass an object to change them, such as
`gpp: { usFallback: 'none' }`. The [GPP options](#gpp-options) table lists
each field. All of them are plain data, so they go in `c15t({ ... })`, not in
the `clientEntrypoint` module.

The `c15t` package includes the GPP code. The browser loads it only when
`gpp` is set, so a site without GPP downloads none of it.

The GPP string follows the policy and location c15t resolves for the visitor.
With `manifest()`, the server reads a US visitor's state from the request's
geography headers; see [Geography headers](/docs/frameworks/astro/geography-headers)
to check that your host sends them. With `hosted()`, the backend's `/init`
resolves it.

The `tcfeuv2` section also needs IAB TCF. Set `iab` as described in
[IAB TCF](/docs/frameworks/astro/iab).

GPP stays off when a `consentSource` from the `clientEntrypoint` module owns
consent decisions.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Geography headers
URL: https://c15t.com/docs/frameworks/astro/geography-headers
Which request headers the c15t Astro middleware reads for the visitor's country, region, language and Global Privacy Control, how to check your host sends them, and how to test a region locally.

## Where the location comes from

On server output, the c15t middleware reads the visitor's location from the
request headers your host adds, and resolves the policy for that location.
The headers never leave your server. With `hosted()`, the middleware sends
the resolved values to your backend's `/init` as c15t override headers. With
`manifest()`, it resolves the policy itself.

On a static or prerendered page, there is no request at build time. The
browser's own `/init` request carries the location instead, and your backend
or the `/api/c15t/init` route reads it from that request.

## Which headers are read?

Within each group, the first header with a value wins:

|Input|Headers, highest precedence first|Source|
|--|--|--|
|Country|`x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country`|c15t override, Cloudflare, Vercel, CloudFront, generic|
|Region|`x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`|c15t override, Cloudflare, Vercel, generic|
|Global Privacy Control|`x-c15t-gpc`, `sec-gpc`|c15t override, browser signal|
|Language|`accept-language`|Browser|

`i18n.locale` in the integration outranks `accept-language`. GPC values count
only as `1` or `0`. Any other value is treated as absent.

When no country header has a value, the location is unknown, and your
policy's rule for an unknown location applies to every visitor.
[Policies](/docs/concepts/policies) explains rule matching.

## Check that your host sends them

c15t does not keep a list of which hosts add which headers. Check your own
deployment. Add a page that prints the inputs the middleware saw, deploy it,
and open it.

```astro title="src/pages/consent-debug.astro"
---
export const prerender = false;
const { inputs } = Astro.locals.c15t;
---

<pre>{JSON.stringify(inputs, null, 2)}</pre>
```

`country` should hold your two-letter country code. If it is missing, your
host does not add one of the headers above. Turn on the host's geolocation
headers, or put a proxy such as Cloudflare in front of the site. Remove the
page after the check.

The Node adapter behind a load balancer receives whatever headers the load
balancer forwards. AWS CloudFront's own `CloudFront-Viewer-Country` header is
not in the list. Map it to `x-c15t-country` at the edge that terminates
traffic.

## Only your edge may set `x-c15t-*` headers

`x-c15t-country`, `x-c15t-region` and `x-c15t-gpc` override the host's
headers. A visitor who sends them chooses their own policy rule. The c15t
middleware does not strip them. In production, the edge that terminates all
traffic must delete incoming `x-c15t-*` headers before anything else sets
them. Blocking direct access to your origin keeps requests on that edge, but
it does not replace the stripping, because a forwarded client header still
passes through.

The browser's own `/init` request carries the same overrides as the
`country`, `region` and `gpc` query parameters, so that a
cross-origin request needs no CORS preflight. The init route treats them like
the `x-c15t-*` headers, so strip them from `/init` requests at the same edge.

## Test a region locally

The override headers are how you test a policy without a VPN. Send them to a
server-rendered page:

```sh
curl -H 'x-c15t-country: DE' http://localhost:4321/
curl -H 'x-c15t-country: US' -H 'x-c15t-region: CA' http://localhost:4321/
curl -H 'sec-gpc: 1' http://localhost:4321/
curl -H 'accept-language: de-DE,de;q=0.9' http://localhost:4321/
```

The HTML contains the banner for that region, or none for a region whose
policy shows no banner. In a browser, a header-rewriting extension that sets
`x-c15t-country` does the same for every request, including `/init`.

With `hosted()`, `hosted({ headers: { 'x-c15t-country': 'DE' } })` pins
the country for the server and the browser `/init` requests alike. Use it only
in a development configuration.

## Check the geography

1. Deploy and open the site from two locations with different policy rules,
   for example through a VPN or your host's geo testing tools.
2. Each location gets its own banner. An opt-in region shows the banner with
   optional categories denied, and a region with no banner rule shows none.
3. Send `x-c15t-country` from outside your edge and confirm the edge removes
   it before it reaches the site.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/astro/content-security-policy
Run c15t on an Astro site under a strict Content Security Policy, with a per-request nonce from your middleware or with Astro's own hash-based CSP, and allow the consent backend and vendors.

## What c15t adds to the page

A Content Security Policy for an Astro site with c15t has to allow these:

|What|Where it comes from|Directive|
|--|--|--|
|The color-scheme script|Inline, in `<head>`, with `colorScheme` `'system'` or `'dark'`|`script-src`|
|The banner reveal script|Inline, after a banner on a prerendered page|`script-src`|
|`<style data-c15t-styles="c15t-first-paint">`, the banner's rules|Inline, in `<head>` from `ConsentScript`, or from the banner on a layout without it, unless `styles: false` or the site uses Tailwind CSS 3|`style-src`|
|`<style data-c15t-styles="c15t-iab-first-paint">`, the IAB banner's rules|Inline alongside the base rules when IAB is configured|`style-src`|
|`<style id="c15t-theme">`|Inline, when the integration sets `theme`|`style-src`|
|The page script that starts the consent runtime, and the banner's click handler|Bundled module scripts from your own origin|`script-src 'self'`|
|The dialog's stylesheet, IAB panel rules for the IAB dialog, and Svelte primitives|Stylesheets from your own origin, linked before the dialog mounts|`style-src 'self'`|
|Full base and configured IAB stylesheets on a Tailwind CSS 3 site, or the stylesheets you import with `styles: false`|Stylesheets from your own origin|`style-src 'self'`|
|Vendor `<script>` elements|Created by the script loader when a category is allowed|`script-src`, plus each vendor's hosts|
|Gated inline scripts|Your own `type="text/plain"` scripts, copied into live scripts|`script-src`|

The per-visitor boot payload is not on this list. `ConsentScript` and the
banners render it as a `<script type="application/json" data-c15t-config>`
data block. The browser never runs a data block, so a policy does not need to
allow it.

The dialog islands can render `style` attributes, for example on animated
sections. If your policy blocks style attributes, allow them with a separate
`style-src-attr 'unsafe-inline'` directive.

Choose one way to allow the inline code:

|Policy|Use it when|
|--|--|
|A nonce from your own middleware|Pages render on each request, and you set the policy header yourself|
|Astro's CSP, `security.csp`|You want Astro to write the policy, including on prerendered pages, and the site does not use `ClientRouter`|

## Allow c15t with a nonce

Set `Astro.locals.c15t.nonce` in your own middleware. The c15t middleware
runs first, with `order: 'pre'`, so `Astro.locals.c15t` exists by the time
yours runs. Generate a nonce per request, set it, render, then send the policy
header with the same nonce:

```ts title="src/middleware.ts"
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
	const nonce = crypto.randomUUID();
	if (context.locals.c15t) {
		context.locals.c15t.nonce = nonce;
	}
	const response = await next();
	response.headers.set(
		'content-security-policy',
		`script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'`
	);
	return response;
});
```

With the nonce set, every inline `<script>` and `<style>` that `ConsentScript`,
`ConsentBanner` and `IABConsentBanner` render carries it. The browser runtime
reads the nonce from the `data-c15t-config` data block and puts it on:

* The vendor scripts the script loader injects, unless a script entry sets its
  own `nonce`.
* The gated `type="text/plain"` scripts it activates.
* The stylesheet links it adds the first time a dialog opens.

### Put the nonce on your gated scripts

When the page has a nonce, c15t activates a gated `type="text/plain"` script
only if the tag carries that same nonce. Add it to each gated tag you write:

```astro title="src/pages/index.astro (partial)"
<script
  is:inline
  type="text/plain"
  data-c15t-category="measurement"
  nonce={Astro.locals.c15t?.nonce}
>
  console.log('Measurement allowed');
</script>
```

c15t skips a gated tag without the nonce, logs a console warning, marks the
tag `data-c15t-activated="untrusted"` and never tries it again. The check
exists because c15t activates a tag by creating a new `<script>`, and a policy
with `'strict-dynamic'` runs a script that trusted code creates without
checking its nonce. Without the check, a tag injected through an HTML
injection hole would run once its category was allowed.

Gated tags you insert later from your own code need the nonce too. When you
call `activateGatedScripts(snapshot, container, nonce)` from
`c15t/astro/client` for that markup, pass the page's nonce as the third
argument so the same check applies. Pages without a nonce activate every
gated tag.

A nonce only works on pages rendered on each request. A prerendered page is
built once, so every visitor would share one nonce. Use Astro's CSP for
prerendered pages.

The nonce covers what the c15t components render. Scripts and stylesheets of
your own that Astro inlines need the nonce or a hash from you.

### Pass the nonce to `ConsentBanner` and `ConsentBannerDeferred`

`ConsentBanner` reads `Astro.locals.c15t.nonce` by default. Its `nonce` prop
sets the value for that banner only.

`ConsentBannerDeferred` passes the page's nonce to its server island. The
island renders in a request of its own, but the page's policy is the one that
applies to the markup the island inserts.

Astro loads a server island with inline scripts that carry no nonce, and one
of them changes on every render. A nonce policy set from middleware therefore
blocks the loader, and the deferred banner never arrives. On pages with
`ConsentBannerDeferred`, use Astro's CSP, which hashes the loader on each
render, or render `ConsentBanner` instead.

## Allow c15t with Astro's CSP

Turn on Astro's CSP with `security.csp`, or `experimental.csp` in Astro 5:

```js title="astro.config.mjs (partial)"
export default defineConfig({
	security: { csp: true },
	integrations: [c15t()],
});
```

The c15t integration adds the hashes of the inline code it can render to that
policy, with the hash algorithm you configured:

* The color-scheme script.
* The reveal scripts of `ConsentBanner` and `IABConsentBanner`.
* Base and configured IAB banner rules, unless `styles: false` or Tailwind
  CSS 3 uses external stylesheets.
* The theme stylesheet.
* The inline `textContent` of each entry in the integration's `scripts`
  option, which the script loader injects.

You do not need `'unsafe-inline'`. Leave it out, because Astro drops the hashes
from a directive that lists it.

Some code still needs your own entry in the policy:

* Gated `type="text/plain"` scripts you write yourself. Add the hash of each
  one's text to `security.csp.scriptDirective.hashes`.
* Scripts registered from the `clientEntrypoint` module. The integration
  cannot see them when it computes the hashes, so add the hash of each inline
  one yourself. With Astro's CSP on, c15t logs a console error that names
  each inline entrypoint script the policy is missing and the hash to add.
* Vendor script hosts. Add them to `security.csp.scriptDirective.resources`,
  together with `'self'`, which a custom list no longer includes.

Astro's CSP does not support `ClientRouter`. On a site that uses it, allow the
inline code with a nonce instead.

## Allow the consent backend in `connect-src`

The browser sends consent to `${backendURL}/subjects`, and requests `/init`
when the server did not resolve the policy. Allow those origins:

|Mode|Browser requests go to|
|--|--|
|`manifest()`, the default|Your own origin for `/api/c15t/init`, and the backend origin for `/subjects`|
|`manifest({ resolve: 'browser' })`|Your own origin for `/api/c15t/manifest`, the backend origin for `/subjects`, and `geoURL` if set|
|`hosted()`|The backend origin, for `/init` and `/subjects`|
|`offline()`|No consent backend|

```txt title="Content-Security-Policy (partial)"
connect-src 'self' https://your-project.inth.app;
```

Replace `https://your-project.inth.app` with the URL from your Inth project or
your self-hosted backend. Server-side requests from the middleware and the
injected routes run in Astro and are not subject to the browser's policy.
Under an IAB TCF policy, the browser fetches the vendor list from the `/init`
route or the URL the policy names. Allow that host too.

Vendors add their own hosts to `script-src`, `connect-src`, `img-src` and
`frame-src`. Each [integration guide](/docs/integrations/overview) lists the
requests to expect.

## Check your policy

1. Load a server-rendered page with the policy enforced, not report-only, and
   open the DevTools Console. No `Refused to execute inline script` or
   `Refused to apply inline style` error appears.
2. View the page source. With a nonce policy, the color-scheme `<script>`,
   `<style id="c15t-theme">` and `<script type="application/json" data-c15t-config>` carry a `nonce` attribute that matches the
   `content-security-policy` response header. The Elements panel shows the
   attribute empty, because browsers hide a nonce's value after checking it.
3. The banner renders with your theme colors, and its buttons record a choice.
4. Open the preference dialog. It is styled, and the Console shows no
   `style-src` violation.
5. Allow a category that gates a vendor. The vendor's script loads, and no
   `connect-src` or `script-src` violation mentions its host.
6. Save a choice. The request to `/subjects` succeeds in DevTools Network.

# Islands
URL: https://c15t.com/docs/frameworks/astro/islands
Choose whether React, Vue or Svelte renders the c15t preference dialog on an Astro site, and read consent from your own framework islands through the page's shared consent runtime.

## How the dialog islands work

The c15t banner is plain `.astro` markup. The preference dialog and the IAB
TCF dialog need component state, so each one is an island in a UI framework.
The integration's `ui` option picks that framework:

|`ui`|Dialog comes from|Install|
|--|--|--|
|`'svelte'` (default)|`@c15t/svelte`, bundled with `c15t`|`@astrojs/svelte svelte`|
|`'react'`|`c15t/react`|`@astrojs/react react react-dom`|
|`'vue'`|`c15t/vue`|`@astrojs/vue vue`|

The island is not a `client:load` island. c15t mounts it into
`ConsentDialog`'s empty host the first time something opens the dialog. A
visitor who only accepts or rejects from the banner downloads no framework
code for the dialog at all.

## Pick the framework your site ships

The dialog should reuse the framework runtime visitors already download.
With `ui` unset, the integration picks the framework of the one Astro
integration among `@astrojs/svelte`, `@astrojs/react` and `@astrojs/vue` your
site registers. With none or several, it picks Svelte, whose runtime is the
smallest of the three; set `ui` yourself in that case.

Register the framework's Astro integration before `c15t()`:

```js title="astro.config.mjs (partial)"
integrations: [react(), c15t()],
```

The build stops when that integration is missing, and names the packages to
install. Only the framework you name in `ui` ends up in your build. With
`ui: 'svelte'` the build never resolves React or Vue.

A site that never opens a dialog, such as one that only shows a notice, can
set `requireUIIntegration: false` and install no framework.

## Use consent in your own islands

Your own React, Vue or Svelte islands can read consent with their adapter's
hooks. Give the adapter the page's runtime, from
`getConsentClient()?.runtime`, instead of letting it create a second one. A
second runtime would keep its own copy of consent and fall out of step with
the banner.

This React island shows whether measurement is allowed and opens the
preference dialog:

```tsx title="src/components/consent-status.tsx"
import { getConsentClient, openDialog } from 'c15t/astro/client';
import { ConsentProvider, useConsent } from 'c15t/react';

const MeasurementStatus = () => {
	const allowed = useConsent('measurement');
	return (
		<p>
			<span data-testid="measurement-status">
				Measurement is {allowed ? 'allowed' : 'not allowed'}.
			</span>{' '}
			<button
				onClick={() => {
					void openDialog();
				}}
				type="button"
			>
				Change cookie settings
			</button>
		</p>
	);
};

const ConsentStatus = () => {
	// The page's consent runtime, which the c15t integration started.
	const runtime = getConsentClient()?.runtime;
	if (!runtime) {
		return null;
	}
	return (
		// `colorScheme: null` leaves dark mode to the integration.
		<ConsentProvider options={{ colorScheme: null }} runtime={runtime}>
			<MeasurementStatus />
		</ConsentProvider>
	);
};

export default ConsentStatus;
```

Render it without server rendering, so it runs only in the browser, where the
runtime exists:

```astro title="src/pages/index.astro (partial)"
<ConsentStatus client:only="react" />
```

Three details matter:

* **Borrow the runtime.** With `runtime`, `ConsentProvider` neither starts nor
  disposes the runtime. The page owns it.
* **Pass `colorScheme: null`.** Without it, the adapter manages the
  `c15t-dark` class itself and can undo the integration's `colorScheme`.
* **Open dialogs through `c15t/astro/client`.** Call `openDialog()` to open
  preferences. An adapter's own dialog state, such as `useSetActiveUI()` in
  React, does not mount the Astro dialog island.

The island needs `c15t/react` and its Astro integration even when `ui` is
`'svelte'`. `useConsent()` reads a permission. To show the visitor's recorded
choice, read `explicitChoice` from the snapshot. See
[read a permission, not a recorded choice](/docs/frameworks/astro/client-api#read-a-permission-not-a-recorded-choice).

### Vue and Svelte islands

The Vue and Svelte adapters take the page runtime the same way:

|Framework|Pass the runtime to|With|
|--|--|--|
|React|`ConsentProvider` from `c15t/react`|`runtime={runtime}` and `options={{ colorScheme: null }}`|
|Vue|`app.use(c15tVue, …)`, with `c15tVue` from `c15t/vue/vue-plugin`|`{ runtime, colorScheme: null }`|
|Svelte|`ConsentProvider` from `@c15t/svelte`|`runtime={runtime}` and `options={{ colorScheme: null }}`|

For Vue, an island's app is set up in the `appEntrypoint` module of
`@astrojs/vue`. Install the plugin there, and only when `getConsentClient()`
returns a client, because the entrypoint also runs on the server. The Vue
components ship as `.vue` files, which Vite's dependency pre-bundling cannot
load. The integration keeps `@c15t/vue` out of pre-bundling with `ui: 'vue'`.
With another `ui`, add `vite: { optimizeDeps: { exclude: ['@c15t/vue', 'c15t'] } }`
to `astro.config.mjs` yourself.

For Svelte, install `@c15t/svelte@alpha`, because the `c15t` package has no
Svelte export.

Render Vue and Svelte islands that read consent with `client:only`, for the
same reason as the React one.

### Without a framework

A plain `<script>` or a custom element needs no adapter. Use `subscribe()`
and `getConsent()` from `c15t/astro/client`, as the
[video component](/docs/frameworks/astro/embeds) does.

## Check the islands

1. Build the site and open a page in a private window with DevTools Network
   open. Before you open the dialog, no chunk for the `ui` framework's dialog
   loads.
2. Hover **Privacy settings**. The dialog chunks download.
3. Open the dialog, turn on **Analytics** (the `measurement` category) and save. Your own island updates to
   match without a reload.
4. Toggle your system's dark mode. The banner and the dialog follow the
   integration's `colorScheme`, not your island.

# Integration options
URL: https://c15t.com/docs/frameworks/astro/integration
Reference for every option of the c15t() Astro integration, the Astro equivalent of a consent provider, from backendURL, mode and routePrefix to ui, theme, i18n, middleware and the client entrypoint.

## What the integration does

Astro islands never share a component tree, so c15t on Astro has no provider
component. The `c15t()` integration in `astro.config.mjs` takes its place. It
adds four things to your site:

* A middleware that resolves consent for each request into
  `Astro.locals.c15t`, which every component reads.
* A page script that starts one consent runtime per page load. Every script
  and island on the page shares it.
* c15t's styles: base and configured IAB banner rules inline in each page,
  and dialog rules linked before their surface mounts. On a Tailwind CSS 3
  site, the full base and configured IAB stylesheets run through your CSS
  pipeline instead.
* In `manifest()` mode, one route at `/api/c15t/[...path]` that answers
  `/api/c15t/init` and `/api/c15t/manifest`.

```js title="astro.config.mjs"
import node from '@astrojs/node';
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t from 'c15t/astro';

export default defineConfig({
	adapter: node({ mode: 'standalone' }),
	integrations: [svelte(), c15t()],
	output: 'server',
});
```

`c15t()` works with no options: the backend URL comes from
`PUBLIC_C15T_BACKEND_URL` and the mode defaults to `manifest()`. List the
Astro integration of your `ui` framework before `c15t()`. Import `c15t` and
the mode helpers from `c15t/astro`.

## Options must survive JSON

The integration serializes its options once at build time and hands the same
JSON to the middleware, the components and the browser. Functions, class
instances and other live values do not survive that, so `c15t()` throws when
an option holds a function, and names where it is. Put callbacks, vendor
helpers from `@c15t/integrations` and anything else with a function in
`src/c15t.client.ts`, the module [`clientEntrypoint`](#cliententrypoint)
names.

The options are also written into every page, so keep secrets out of them.
The backend URL is public configuration, not a secret.

## `backendURL`

Your Inth or self-hosted backend. The browser saves consent there with
`POST /subjects`, `hosted()` asks its `/init`, and `manifest()` reads
`${backendURL}/manifest`. It defaults to `PUBLIC_C15T_BACKEND_URL`, then
`PUBLIC_INTH_PROJECT_URL`, read from the environment or a `.env` file in the
project root when `astro.config.mjs` loads. A `hosted({ backendURL })` of its own wins over both.

On the server, a relative backend URL or `manifestURL`, such as `/api/self-host`,
resolves against the URL Astro gives the request, `Astro.url`. c15t does not
read `x-forwarded-host` or other forwarding headers to build it.

## `mode`

Where the visitor's policy comes from. Build it with one of the three
helpers from `c15t/astro`; they return plain data. Without `mode`, the
integration uses `manifest()`.

|Helper|Resolves consent|Needs|
|--|--|--|
|`manifest()`|On your server, from your project's public policy, downloaded during the build|A server adapter and a backend URL|
|`manifest({ source: 'runtime' })`|On your server, from the policy fetched and cached at runtime|A server adapter and a backend URL|
|`manifest({ resolve: 'browser' })`|In the browser, from the manifest|A backend URL. Works on static output: the integration prerenders `${routePrefix}/manifest`|
|`hosted()`|At your backend's `/init`, from the server on request-rendered pages and from the browser otherwise|A backend URL|
|`offline()`|In the browser and on your server, with no backend|Nothing. Not recommended for production environments.|

`manifest()` accepts:

|Field|Type|Effect|
|--|--|--|
|`source`|`'build' \|'runtime'`|`'build'`, the default, uses the snapshot the build downloaded, or fetches at runtime when the build has none. `'runtime'` always fetches at runtime.|
|`snapshot`|`ConsentManifest`|A manifest you supply, used instead of downloading one. Not combined with `source`.|
|`resolve`|`'server' \|'browser'`|Where the policy resolves. `'server'` by default.|
|`manifestURL`|`string`|Where the manifest is fetched. Defaults to `${backendURL}/manifest`.|
|`geoURL`, `inputs`|`string`, `{ country?, region? }`|The visitor's location, for `resolve: 'browser'` only.|

`hosted()` accepts:

|Field|Type|Effect|
|--|--|--|
|`backendURL`|`string`|Backend base URL, in place of the top-level `backendURL`. Absolute, or same-origin such as `/api/self-host`|
|`headers`|`Record<string, string>`|Extra headers sent with `/init` from the server and the browser. From the server, only geography, language and privacy-signal headers are sent|

`offline()` accepts `policyRules`, the rules to resolve locally. Without them
it resolves the recommended rule pack. Choices persist in the visitor's cookie
and localStorage only, and there are no consent records.

`manifest()` and `hosted()` stop `astro.config` from loading without a
backend URL, because the server would have no policy to read and the browser
nowhere to save consent. A `manifest({ snapshot })` needs none for the policy.

[Rendering and deployment](/docs/frameworks/astro/rendering) explains which
mode fits which Astro output.

## `routePrefix`

The path of the route the integration injects in `manifest()` mode:
`'/api/c15t'` by default. One catch-all, `${routePrefix}/[...path]`, answers
`${routePrefix}/init` and `${routePrefix}/manifest`. A page whose consent
changes after it loads, such as after a language change, asks it again.

The route renders on demand, so `astro build` with `manifest()` needs a server
adapter. `manifest({ resolve: 'browser' })` on static output prerenders only
`${routePrefix}/manifest`. `hosted()` and `offline()` inject nothing. Set
`routePrefix: false` to inject nothing in `manifest()` mode. The browser then
asks the backend's `/init`, not a route of your own. See
[serve the routes yourself](/docs/frameworks/astro/server#serve-the-routes-yourself).

## Consent and scripts

|Option|Type|Default|Effect|
|--|--|--|--|
|`onBuildError`|`'fail' \|'runtime'`|Unset|What a failed build-time manifest fetch does in `manifest()` mode. Unset, `astro build` stops and `astro dev` logs a warning, and the server fetches the policy at runtime. `'fail'` stops both. `'runtime'` lets both continue. A missing backend URL counts as a failed fetch. The `C15T_ON_BUILD_ERROR` environment variable overrides it. See [build-time manifests](/docs/frameworks/astro/rendering#bundle-the-manifest-during-builds).|
|`reportSessions`|`boolean`|`true`|In `manifest()` mode, reports each visitor the server resolves to the backend, so visitor counts stay complete.|
|`consentCategories`|`AllConsentNames[]`|Inferred from scripts and the policy|Categories the banner and dialog offer|
|`scripts`|`Script[]`|None|Scripts without callbacks, loaded when their category is allowed. See [Scripts](/docs/frameworks/astro/scripts)|
|`vendors`|`Vendor[]`|None|Vendors the dialog lists with their own switch inside a category. Merged with vendors from the backend manifest. See [Vendor consent](/docs/frameworks/astro/vendor-consent)|
|`networkBlocker`|`{ rules, enabled?, logBlockedRequests? } \|false`|Off|Blocks matching `fetch` and `XMLHttpRequest` calls until consent. See [Network blocker](/docs/frameworks/astro/network-blocker)|
|`clearOnRevocation`|`ClearOnRevocationConfig`|None|Cookies and storage keys to remove when a category is withdrawn|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reloads the page after a save turns off a category that was allowed|
|`storageConfig`|`StorageConfig`|`{ storageKey: 'c15t' }`|Where the choice is stored|

`storageConfig` takes `storageKey`, the cookie and localStorage name,
`crossSubdomain` to share the cookie across subdomains, `defaultDomain` to
set the cookie domain yourself, and `defaultExpiryDays`, which defaults to a
year. The server reads the same cookie name, so set it here and not only in
the browser.

## Appearance and copy

|Option|Type|Default|Effect|
|--|--|--|--|
|`theme`|`Theme`|Stock tokens|Tokens rendered on the server into `<style id="c15t-theme">`, plus `consentActions` button styles|
|`colorScheme`|`'system' \|'light' \|'dark' \|'none'`|`'system'`|Who sets the `c15t-dark` class on `<html>`|
|`presentation`|`{ prompt?, preferences? }`|Floating banner|Banner variant, position, action layout and blocking, and the dialog's blocking and default selections|
|`legalLinks`|`{ privacyPolicy?, cookiePolicy?, termsOfService? }`|None|Each an `{ href, label? }`. Without `label`, a link reads as the translated name for its type. `ConsentBanner` and `ConsentDialog` show the ones their `legalLinks` prop lists|
|`i18n`|`{ locale?, messages?, detectLanguage? }`|Negotiated from `Accept-Language`|Language and wording. See [Translations](/docs/frameworks/astro/translations)|
|`styles`|`boolean`|`true`|Inlines base and configured IAB banner rules once per page. Dialog rules load before the surface mounts; IAB panel rules load only for the IAB dialog. Tailwind CSS 3 uses the full external stylesheets. `false` delivers no styles, so you import the base and optional IAB stylesheets yourself|

[Customize](/docs/frameworks/astro/customize) shows each of these in use.

## `ui`

`ui` picks the framework that renders the preference dialog and the IAB
dialog islands: `'svelte'`, `'react'` or `'vue'`. Unset, it is the framework
of the one Astro integration among `@astrojs/svelte`, `@astrojs/react` and
`@astrojs/vue` your site registers, so the dialog reuses a runtime the site
already loads. With none or several of them registered, it is `'svelte'`.
Install that framework's Astro integration and list it before `c15t()`.

`requireUIIntegration`, default `true`, stops the build when the `ui`
framework's Astro integration is missing. Set it to `false` for a site that
never opens a dialog, such as one that only shows a notice.

See [Dialog islands and your own islands](/docs/frameworks/astro/islands).

## `iab`

IAB TCF configuration, or `false`. Takes `cmpId`, `cmpVersion`, `vendors`,
`publisherCountryCode`, `publisherRestrictions`, `gvl`, `gvlURL` and
`enabled`, all plain data. See [IAB TCF](/docs/frameworks/astro/iab) for each
field.

## `middleware`

`true` (default), `false`, or an object:

|Field|Type|Default|Effect|
|--|--|--|--|
|`enabled`|`boolean`|`true`|Registers the middleware that sets `Astro.locals.c15t`|
|`skip`|`string[]`|`[]`|Path prefixes the middleware leaves alone. `'/api'` covers `/api/health` but not `/apidocs`|
|`timeoutMs`|`number \|false`|`500`|Longest a server render waits for the policy. `false` or `Infinity` waits however long the backend takes; any other value that is not a finite, non-negative number uses the default|

The integration's own route under `routePrefix` is always skipped. On a
skipped route, `Astro.locals.c15t` is unset and `ConsentBanner` throws, so
skip only routes that render no consent components. See
[Server API](/docs/frameworks/astro/server).

## `clientEntrypoint`

A path to a module whose default export adds live values in the browser. A
relative path resolves from the project root. Unset, the integration uses
`src/c15t.client.ts`, `.js` or `.mjs` when the file exists, so the quickstart
sets nothing:

```ts title="src/c15t.client.ts"
import { posthog } from '@c15t/integrations/posthog';
import type { C15tClientOptionsExtension } from 'c15t/astro';

export default {
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
} satisfies C15tClientOptionsExtension;
```

The default export is a `C15tClientOptionsExtension` from `c15t/astro`:

|Field|Effect|
|--|--|
|`scripts`|Scripts added to the integration's `scripts`. Vendor helpers from `@c15t/integrations` go here|
|`callbacks`|`onChoiceRecorded`, `onPermissionsChanged`, `onError` and `onBeforeConsentRevocationReload`. See [Callbacks](/docs/frameworks/astro/callbacks)|
|`networkBlocker`|Replaces the integration's `networkBlocker`, so it can include `onRequestBlocked`|
|`clearOnRevocation`|Replaces the integration's `clearOnRevocation`|
|`theme`|Merged over the integration's theme for button styles. Tokens here have no effect|

The browser imports this module into the page script, so every page shares
one copy. Keep it small, because it loads on every page.

## Errors the integration raises

|Message contains|Cause|
|--|--|
|`` `mode` must be manifest(), hosted() or offline() ``|`mode` is a transport function, or not built with a helper from `c15t/astro`|
|`is a function`|A serialized option, such as a `scripts` entry from `@c15t/integrations`, holds a function. Move it to `src/c15t.client.ts`|
|`manifest() needs a backend URL`|No `backendURL`, `PUBLIC_C15T_BACKEND_URL` or `PUBLIC_INTH_PROJECT_URL`|
|`manifest({ snapshot }) still needs a backend URL`|A snapshot, but no `backendURL`, `PUBLIC_C15T_BACKEND_URL` or `PUBLIC_INTH_PROJECT_URL`. Saves go to the backend whatever `routePrefix` is|
|`hosted() needs a backend URL`|No `backendURL`, `hosted({ backendURL })`, `PUBLIC_C15T_BACKEND_URL` or `PUBLIC_INTH_PROJECT_URL`|
|`gives the server no manifest to fetch`|`backendURL: ''` without `manifest({ manifestURL })` or `manifest({ snapshot })`|
|`` `routePrefix` must be a path ``|`routePrefix` is not `false` and does not start with `/`|
|`` @c15t/astro: `routePrefix` can't be '/': a consent route at the site root would catch every page. Use a path such as '/api/c15t'. ``|`routePrefix` is `'/'`. A catch-all route at the site root would answer every page|
|`clientEntrypoint ... does not exist`|The `clientEntrypoint` path does not resolve to a file|
|`unknown ui`|`ui` is not `'svelte'`, `'react'` or `'vue'`|
|`ui: "svelte" needs @astrojs/svelte`|The `ui` framework's Astro integration is missing|
|`injects an on-demand route`|`astro build` runs in `manifest()` mode with no server adapter|
|`build-time manifests require an absolute upstream URL`|`onBuildError: 'fail'` with a relative or empty backend URL or `manifestURL`|
|`could not fetch the consent manifest`|`astro build` could not download a manifest. In `astro dev`, or with `onBuildError: 'runtime'`, the same message is a warning|
|`no backend URL is set`|The build has no backend URL to fetch from. `astro build` stops; `astro dev` warns|

[Troubleshooting](/docs/frameworks/astro/troubleshooting) has the fix for
each.

# Server API
URL: https://c15t.com/docs/frameworks/astro/server
How the c15t middleware resolves consent for each Astro request, what Astro.locals.c15t holds, the helpers in c15t/astro/server, the injected consent route, and how to cache server-rendered pages safely.

## What the middleware does

The `c15t()` integration registers a middleware with `order: 'pre'`, so it
runs before your own middleware on every route: pages, endpoints and server
islands. For each request it:

1. Reads the visitor's consent cookie.
2. Reads location, language and Global Privacy Control from the request
   headers. See [Geography headers](/docs/frameworks/astro/geography-headers).
3. Resolves the policy through the integration's `mode`.
4. Stores the result in `Astro.locals.c15t`.

The components render from `Astro.locals.c15t`, and `ConsentScript` inlines
it for the browser. A server-rendered page therefore needs no `/init` request
from the browser.

A render waits up to 500 ms for the policy. When the backend is slower, the
page renders without a server decision: no banner in the HTML, optional
categories denied, gated scripts blocked. The browser then requests the
policy itself. Change the budget with `middleware: { timeoutMs }`. See
[set how long a render waits](/docs/frameworks/astro/rendering#set-how-long-a-render-waits-for-the-backend).

On a prerendered page, the middleware reads no request headers or cookie,
because the build has no visitor. `hosted()` and `manifest()` leave the
policy for the browser. `offline()` resolves it at build time, because it
needs no request.

In `hosted()` mode the render's `/init` request carries the resolved
location, language and GPC, the `user-agent`, the mode's configured consent
headers and, while the visitor has no stored choice, the experiment arm. Over
`https` or to a loopback host it also carries the consent cookie, never the
rest of the cookie jar; over plain HTTP to any other host it carries no
cookie. The render never requests the integration's own consent route: a
backend URL that resolves to it on the request's origin renders without a
server decision.

## Type `Astro.locals.c15t`

The integration adds the type to `.astro/types.d.ts`, so no `src/env.d.ts`
line is needed.

## What `Astro.locals.c15t` holds

|Field|Holds|
|--|--|
|`snapshot`|The consent snapshot for this request, the same shape the browser's `getConsent()` returns|
|`shouldShowBanner`|Whether this request should see the banner|
|`hasPolicy`|Whether a policy rule resolved for this request|
|`hasConsentUi`|Whether that rule owes a banner or a way back to preferences|
|`prerendered`|Whether this render is shared by every visitor, as on a prerendered page|
|`inputs`|The request's `country`, `region`, `language` and `gpc` values|
|`decision`|The policy decision, when the mode produced one|
|`config`|The payload `ConsentScript` inlines for the browser|
|`options`|The integration options|
|`nonce`|The Content Security Policy nonce for this request. c15t leaves it unset. Set it from your own middleware, and the components put it on their inline scripts and styles|

On a prerendered page, `snapshot` is what a first-time visitor would get, and
`prerendered` is `true`. On a route listed in `middleware.skip`, and on the
integration's own consent route, `Astro.locals.c15t` is unset.

## Use consent in server code

Read `Astro.locals.c15t` in a page, layout or endpoint to decide what the
server renders. A layout can pick the IAB surfaces only for visitors who get
an IAB policy:

```astro title="src/layouts/page.astro (partial)"
---
import BaseLayout from './base.astro';
import IABLayout from './iab.astro';

const Layout =
  Astro.locals.c15t?.snapshot.model === 'iab' ? IABLayout : BaseLayout;
---
```

Use `snapshot.effectivePermissions` for what may run on this request, such as
an embed the server can render. Remember that a choice the visitor makes on
the page only reaches the server on the next request. Content that must
appear the moment the visitor allows it belongs in a browser script. See
[Embeds](/docs/frameworks/astro/embeds).

Do not build consent records from these values. The backend records consent
when the browser saves it.

## Cache server-rendered pages safely

A page rendered with `hosted()` or `manifest()` contains one visitor's
decision: the banner or its absence, and the boot payload with their stored
consent and location. A shared cache that stores that HTML serves it to the
next visitor.

* Do not put request-rendered pages that include c15t components in a shared
  CDN cache.
* For a page that must be cached, prerender it, or render the banner with
  [`ConsentBannerDeferred`](/docs/frameworks/astro/components/consent-banner-deferred).
  Both keep visitor state out of the cached HTML.
* The injected `/api/c15t/init` route answers with `Cache-Control: private, no-store`. Keep it out of shared caches too.
* Without a bundled manifest, the injected `/api/c15t/manifest` route passes
  the backend's `Cache-Control` and `ETag` through and answers
  `If-None-Match` with `304`, so a CDN can cache it. With one, it returns the
  build's snapshot with no cache headers.

## The injected route

In `manifest()` mode the integration injects one on-demand route,
`${routePrefix}/[...path]`, which is `/api/c15t/[...path]` by default:

|Request|Returns|
|--|--|
|`GET /api/c15t/init`|The policy for this request, resolved from the bundled or cached manifest. The browser calls it on prerendered pages, after a failed server resolution, and when a page's consent changes after it loads|
|`GET /api/c15t/manifest`|Your project's public policy file: the build's snapshot when the build bundled one, otherwise proxied from the backend with its cache headers|

The route is the consent route handler from `@c15t/core/server`, shared
with the Next.js, TanStack Start, SvelteKit and Nuxt adapters. A vendor list that cannot be loaded
fails the init request rather than answering `gvl: null`, which the browser
would read as "IAB is off". The manifest path passes upstream only a
`language` query parameter that looks like a language tag.

With a bundled manifest, the route uses the build's snapshot and never fetches
the manifest. Without one, the server keeps the manifest in memory and
refreshes it in the background.
On Cloudflare, c15t hands that refresh to the adapter's `waitUntil`, so the
request context stays alive until it finishes. The browser saves consent to
the backend URL directly, not to this route.

Change the path with `routePrefix: '/consent'`. With
`manifest({ resolve: 'browser' })` and no adapter, the integration prerenders
the route and writes only `${routePrefix}/manifest`, which the browser
fetches. `hosted()` and `offline()` inject no route.

### Serve the routes yourself

With `routePrefix: false`, the integration injects nothing and `astro build`
no longer needs an adapter for it. The browser then asks the backend's
`/init` whenever a page inits again, and never calls a route of your own at
that path. To keep `/init` on your origin, keep the injected route and move
it with `routePrefix` instead.

The handlers the injected route uses are exported as
`createConsentRouteHandlers({ options })` from `c15t/astro/server`. Mount
them yourself for other clients, or for browser resolution: with
`mode: manifest({ resolve: 'browser', manifestURL: '/api/c15t/manifest' })`,
the browser fetches the manifest from your route. `GET(request, { locals })`
dispatches by the last path segment.

## Helpers in `c15t/astro/server`

The components and the middleware are built from these helpers. Use them for
a custom middleware or your own components:

|Export|Does|
|--|--|
|`resolveConsentContext({ headers, url, options, prerendered?, timeoutMs?, fetch?, onBackgroundRevalidate? })`|Resolves the value the middleware stores on `Astro.locals.c15t`|
|`buildConfigJSON(config)`|The boot payload as JSON, for a `<script type="application/json" data-c15t-config>` data block|
|`buildConfigScript(config)`|The boot payload as a script that sets `window.__c15tAstroConfig`. The browser still reads it. It changes per visitor, so a policy can allow it only by nonce or `'unsafe-inline'`|
|`buildThemeCSS(theme)`|The CSS for `<style id="c15t-theme">`, or an empty string|
|`buildColorSchemeScript(colorScheme)`|The first-paint color-scheme script, or an empty string|
|`buildBannerRevealScript(storageConfig, testId)`|The inline script that shows a prerendered banner to visitors with nothing stored|
|`markConfigEmitted(Astro.locals)`|Claims the one boot payload per request. Returns `true` for the first caller|
|`resolvePromptModel(input)` and `resolveIABPromptModel(input)`|The copy, actions and class names of the banner and the IAB banner|
|`snapshotFromConfig(config)`|Derives a consent snapshot from a resolved configuration|

`resolveConsentContext` takes the integration options already resolved. Get
them from `Astro.locals.c15t.options`, or with `resolveOptions()` from
`c15t/astro`. Pass `prerendered: true` only for output that every visitor
shares. It drops the request's cookie and location.

To run c15t's middleware inside your own, set `middleware: false` and
register `onRequest` from `c15t/astro/middleware` with Astro's `sequence()` in
`src/middleware.ts`. Put it before anything that renders consent components.

## Check the server path

1. View the page source of a first visit on a server-rendered page. It
   contains `data-testid="consent-banner-root"` and a
   `<script type="application/json" data-c15t-config>` data block.
2. Choose, then reload. The source has no banner markup, and DevTools Network
   shows no browser request to `/init` on that page.
3. Request `/api/c15t/init` and check the `Cache-Control: private, no-store`
   response header.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/astro/troubleshooting
Fix common c15t problems on Astro sites, from build errors about adapters and UI integrations to a missing banner, scripts that run too early, unstyled dialogs and saves that fail.

## The build says manifest() needs a server adapter

**Check.** The error reads `manifest() resolves each visitor on the server and injects an on-demand route at /api/c15t/[...path]`. `manifest()` is the
default mode, and `astro build` stops when no adapter can serve its route.
Look for an adapter and server output in `astro.config.mjs`.

**Fix.** Add your host's adapter and use server output. For a static site,
set `c15t({ mode: hosted() })` or `c15t({ mode: manifest({ resolve: 'browser' }) })`.
See [Rendering and deployment](/docs/frameworks/astro/rendering).

## The config fails with "is a function"

**Check.** A serialized `c15t()` option holds a function. The error names it,
such as `c15t().scripts[0].onLoad`. A vendor helper from
`@c15t/integrations`, such as `posthog()`, returns a script with callbacks.

**Fix.** Move the option to the default export of `src/c15t.client.ts`. See
[`clientEntrypoint`](/docs/frameworks/astro/integration#cliententrypoint).

## The build says `ui` needs an Astro integration

**Check.** The preference dialog is an island in the framework that the `ui`
option names. Look in `astro.config.mjs` for that framework's Astro
integration, listed before `c15t()`.

**Fix.** Install the integration and list it before `c15t()`. For
`ui: 'svelte'`, install `@astrojs/svelte` and `svelte`. For `'react'`, install
`@astrojs/react`, `react` and `react-dom`. For `'vue'`, install `@astrojs/vue`
and `vue`. A site that only shows a notice and never opens the dialog can set
`requireUIIntegration: false` instead.

**Check.** The site registers more than one of `@astrojs/svelte`,
`@astrojs/react` and `@astrojs/vue`, and the dialog renders in Svelte.
With several registered, `ui` falls back to `'svelte'`.

**Fix.** Set `ui: 'react'` or `ui: 'vue'` to the framework your pages already
load, so visitors do not download Svelte as well.

## Consent requests go to the wrong backend

**Check.** Look at `PUBLIC_C15T_BACKEND_URL` and `PUBLIC_INTH_PROJECT_URL` in
`.env`, `.env.local` and the
build environment, and at any `backendURL` in `astro.config.mjs`, top-level or
in `hosted({ backendURL })`. One is still the placeholder
`https://your-project.inth.app`, the demo project, or a URL from another
project.

**Fix.** Replace it with your Inth project's backend URL, including any path
prefix. Astro reads the config when `astro dev` or `astro build` starts, so
restart the dev server after you change it. A built site keeps the URL from
build time, even when the config reads it from an environment variable, so
rebuild it.

## `astro build` or `astro dev` can't fetch the manifest

**Check.** In `manifest()` mode the integration downloads
`${backendURL}/manifest`, or your `manifestURL`, when `astro build` or
`astro dev` starts, and waits at most 10 seconds. When the download fails,
`astro build` stops with an error that starts with `@c15t/astro: could not fetch the consent manifest from <url> during the build`. `astro dev` logs the
same message as a warning, and the server fetches the policy at runtime. The
part in parentheses names the cause:

* `fetch failed` with a network error, or `no response within 10 seconds`:
  the build machine can't reach the backend.
* `/manifest responded 404`, or another status: the URL is not your project's
  backend. The placeholder `https://your-project.inth.app` returns 404.
* `/manifest returned an invalid consent manifest`: the URL answers, but not
  with a c15t manifest.

A relative or empty URL, such as `/api/c15t`, skips the fetch. With
`onBuildError: 'fail'`, it stops the build with `build-time manifests require an absolute upstream URL`.

A missing backend URL counts as a failed download: `astro build` stops with
`no backend URL is set`, and `astro dev` warns.

**Fix.** Set `PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`), or
`backendURL` on `c15t()`, to your
Inth project's absolute backend URL, and make sure the machine that builds
can reach it. To deploy while the backend is down, build with
`C15T_ON_BUILD_ERROR=runtime`, or set `onBuildError: 'runtime'`. To never
fetch at build time, set `mode: manifest({ source: 'runtime' })`. Either way,
the server fetches the policy at runtime.

## A component says `Astro.locals.c15t` is missing

**Check.** `ConsentBanner` and `IABConsentBanner` read the consent context that
the integration's middleware sets. Confirm that:

* `c15t()` is in the `integrations` list of `astro.config.mjs`.
* The integration does not set `middleware: false`.
* The route is not listed in `middleware.skip`.

**Fix.** Add `c15t()` to `integrations`, remove `middleware: false`, or take
the route out of `middleware.skip`.

## Why is there no banner?

**Check.** In DevTools Network, find the browser's `/init` request. Its
response, or `Astro.locals.c15t.snapshot.policyRule`, shows which policy
matched.

**Fix.** Work through these causes in order:

1. **The visitor already chose.** A saved choice hides the banner. Open a
   private window.
2. **The policy asks for no banner.** A rule whose prompt is `none`, such as
   one you set up for visitors in the United States, shows no banner.
   [Policies](/docs/concepts/policies#why-the-banner-may-be-absent) explains
   each case.
3. **The policy did not resolve.** If the browser's `/init` request failed or
   was blocked, no banner or `ConsentDialogLink` appears and optional
   categories stay denied.
4. **The page shares its HTML.** On a static or prerendered page, the banner
   appears after the `/init` request returns, not in the first HTML.

On server output, the location comes from your host's headers, such as
`cf-ipcountry` on Cloudflare or `x-vercel-ip-country` on Vercel. To test a
region locally, send `x-c15t-country` with the request. Only your own edge may
set `x-c15t-*` headers in production, because they override the host's.

## The browser's `/init` request fails with a CORS error

**Check.** With `hosted()`, the browser calls your backend directly, so the
backend must trust the site's origin. A preview deployment has its own origin.

**Fix.** Add the exact origin of the site, including the scheme and port, to
your Inth project's trusted origins. Add each preview deployment's origin too.

## The banner is missing from server HTML now and then

**Check.** The middleware waits up to 500 ms for the policy. When the backend is
slower, for example on the first request after a deploy, the page renders
without the banner and the browser shows it after its own request. This happens
when the server fetches the policy at runtime, with `hosted()`, with
`manifest({ source: 'runtime' })`, or after a build with
`onBuildError: 'runtime'` could not fetch the manifest.

**Fix.** Use `manifest()` with an absolute backend URL and let the build
reach it, so the policy ships with the build. Or raise the budget with
`middleware: { timeoutMs }`. See
[Rendering and deployment](/docs/frameworks/astro/rendering#set-how-long-a-render-waits-for-the-backend).

## The config fails with "manifest() needs a backend URL"

**Check.** The server reads the policy from `${backendURL}/manifest`, and the
browser saves consent there, so `astro.config` refuses to load without one.
`hosted()` fails the same way with `hosted() needs a backend URL`.

**Fix.** Set `PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`) in
`.env`, or pass
`c15t({ backendURL: 'https://your-project.inth.app' })` with your project's
URL in place of the placeholder. A `manifest({ snapshot })` still needs one:
the snapshot replaces the manifest download, but the consent route answers
`GET` only, so saves go to the backend.

## Options from an earlier alpha have no effect

**Check.** `astro.config.mjs` uses `hosted({ url })`,
`manifest({ backendURL, manifest })`, `endpoints` or `buildManifest`. The
integration no longer reads them, and TypeScript reports them as unknown. A
layout that imports `consent-dialog-trigger.astro` fails to resolve it.

**Fix.** Use the current names:

|Earlier|Now|
|--|--|
|`hosted({ url })`|`hosted()` with the top-level `backendURL`, or `hosted({ backendURL })`|
|`manifest({ backendURL })`|`manifest()` with the top-level `backendURL`|
|`manifest({ manifest })`|`manifest({ snapshot })`|
|`endpoints: { initPath, manifestPath }`|`routePrefix`, one catch-all for both|
|`endpoints: false`|`routePrefix: false`|
|`buildManifest: false`|`manifest({ source: 'runtime' })`|
|`buildManifest: true`|`onBuildError: 'fail'`|
|`ConsentDialogTrigger` from `consent-dialog-trigger.astro`|`ConsentDialogLink` from `c15t/astro/components`|
|`hosted({ domain })`|`hosted({ backendURL })`, or the top-level `backendURL`|
|`manifest({ reportSessions })`|The top-level `reportSessions`|
|The `c15t/astro/api/init` and `c15t/astro/api/manifest` entries, and route handlers from `c15t/astro/api`|`routePrefix`, and `createConsentRouteHandlers` and the manifest cache helpers from `c15t/astro/server`|
|`resolveTransportFactory`, `custom`, and the `C15tModeDescriptor`, `C15tHostedDescriptor`, `C15tManifestDescriptor`, `C15tOfflineDescriptor` and `C15tEndpointOptions` types|`ConsentMode` from `c15t/astro`|
|`/// <reference types="c15t/astro/middleware" />` in `src/env.d.ts`|Nothing. The integration adds the `Astro.locals.c15t` type.|

## A vendor loads before the visitor chooses

**Check.** Search your layout and any tag manager for the vendor's own snippet.

**Fix.** Remove it, so only c15t loads the vendor.

**Check.** Look at the vendor's inline script. It needs `type="text/plain"` and
`is:inline`.

**Fix.** Add the missing attribute. Without `is:inline`, Astro bundles the
script and runs it straight away.

**Check.** Read `effectivePermissions` in the snapshot. The policy may allow the
category before a choice: under an opt-out policy, measurement can be allowed
from the start.

**Fix.** None. The vendor loads because the policy allows it.
[Scripts](/docs/frameworks/astro/scripts) and
[Embeds](/docs/frameworks/astro/embeds) cover the gating options.

## A gated inline script never runs

**Check.** Open the console. c15t logs a warning for a `data-c15t-category`
value that is not a category name, and leaves that script inert.

**Fix.** Set the attribute to one category, such as `measurement`.

**Check.** Under a nonce-based Content Security Policy, c15t also skips a gated
tag that lacks the page's nonce. The console shows a warning about a script
without the page's CSP nonce, and the tag has `data-c15t-activated="untrusted"`
in the Elements panel.

**Fix.** Add `nonce={Astro.locals.c15t?.nonce}` to the tag and reload. c15t
never retries a tag it marked `untrusted`. See
[put the nonce on your gated scripts](/docs/frameworks/astro/content-security-policy#put-the-nonce-on-your-gated-scripts).

## The preference dialog opens without styles

**Check.** Look for `styles: false` in your c15t setup. With it, c15t inlines
no rules and links no stylesheet when the dialog opens. Without it, check the
Network panel for a failed request to the dialog's stylesheet, and the
console for a Content Security Policy error.

**Fix.** Import `c15t/astro/styles.css`, and `c15t/astro/primitives.css` for
the Svelte dialog, from your global stylesheet. See
[load the stylesheet yourself](/docs/frameworks/astro/customize#load-the-stylesheet-yourself).

## The banner loses its padding with Tailwind CSS

**Check.** Tailwind's preflight in the `base` layer is overriding c15t's
`components` layer. This happens when your own stylesheet names its layers
before c15t's rules do.

**Fix.** Put `components` after `base` in your first `@layer` statement, or set
`styles: false` and import `c15t/astro/styles.css` after your layer order
statement.

## The dark mode is wrong or flashes

**Check.** Find where `ConsentScript` renders. It belongs in `<head>`, so the
color scheme is set before first paint.

**Fix.** Keep `ConsentScript` in `<head>`. If your site has its own theme
switch, set `colorScheme: 'none'` and toggle `c15t-dark` on `<html>` yourself,
including after `ClientRouter` navigation. See
[set light or dark mode](/docs/frameworks/astro/customize#set-light-or-dark-mode).

## `getConsentClient()` returns `null`

**Check.** The runtime starts from a module script. Your script ran before it,
or it ran on the server.

**Fix.** Call `getConsentClient()` in the browser, and try again on
`DOMContentLoaded`. See [Client API](/docs/frameworks/astro/client-api).

## The banner shows no links to my policies

**Check.** `ConsentBanner` and `ConsentDialog` show only the legal links their
`legalLinks` prop lists, even when the integration defines them. Look for the
prop on each component.

**Fix.** Pass `legalLinks={['privacyPolicy', 'cookiePolicy']}` to each, and
define those keys in the integration's `legalLinks` option. See
[ConsentBanner legal links](/docs/frameworks/astro/components/consent-banner#legal-links).

## An iframe loads before the visitor chooses

**Check.** Look for an iframe with `src` in the HTML. It loads before any
script runs.

**Fix.** Put the URL in `data-src` with a `data-category`, or render the iframe
from a component that adds it only while the category is allowed. See
[Embeds](/docs/frameworks/astro/embeds).

## My own island is out of step with the banner, or turns dark mode off

**Check.** Your island created its own consent runtime, or its adapter is
managing the `c15t-dark` class. Look at the options the island passes to its
adapter.

**Fix.** Pass `getConsentClient()?.runtime` to the adapter as `runtime`, set
`colorScheme: null` in its options, and render the island with `client:only`.
See
[use consent in your own islands](/docs/frameworks/astro/islands#use-consent-in-your-own-islands).

## The console reports a Content Security Policy violation

**Check.** c15t renders inline scripts and a theme `<style>`. Find out whether
your site uses a nonce policy or Astro's `security.csp`.

**Fix.** Under a nonce policy, set `Astro.locals.c15t.nonce` from your own
middleware so they carry the nonce. Under Astro's `security.csp`, the
integration adds their hashes for you. A `ConsentBannerDeferred` island stays
blocked under a nonce policy, because Astro's island loader carries no nonce.
See [Content Security Policy](/docs/frameworks/astro/content-security-policy).

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/svelte/quickstart
Add a c15t cookie banner, preference dialog and consent-gated scripts to a Svelte 5 app built with Vite, with your Inth policy bundled at build time.

## Before you start

This guide is for a Svelte 5 app without SvelteKit, such as a Vite
single-page app. The browser resolves consent after the page loads, so the
banner appears after the first paint. For a banner in the server HTML, use
SvelteKit; [choose your setup](/docs/concepts/choose-your-setup) compares the
options. The `examples/svelte` app in the c15t repository is the finished
result.

The guide uses [Inth](https://inth.com) for policies and consent records.
Create an Inth project, then:

1. Set its policy rules, including the `measurement` category for the
   vendor below.
2. Add your app's origin, such as `http://localhost:5173`, to its trusted
   origins.
3. Copy the project's backend URL.

A self-hosted backend or offline mode works too; see
[other setups](#other-setups).

The setup bundles your policy into the browser bundle at build time, the
recommended production setup. Rebuild after changing policies, translations
or vendors.

## Install

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/svelte@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/svelte@alpha @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/svelte@alpha @c15t/integrations@alpha`|
|bun|`bun add @c15t/svelte@alpha @c15t/integrations@alpha`|

Svelte uses its own package, `@c15t/svelte`, which exports the components and
the `manifest()`, `hosted()` and `offline()` modes. `@c15t/integrations`
holds the vendor helpers. The `c15t` package has no Svelte entry point, so
you don't install it.

## Bundle the policy at build time

Add `consentManifest` to the plugins in `vite.config.ts`:

```ts title="vite.config.ts"
import { consentManifest } from '@c15t/svelte/vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [consentManifest(), svelte()] });
```

Set `VITE_C15T_BACKEND_URL` to your project's backend URL, including any path
prefix, in `.env` or your build environment:

```sh title=".env"
VITE_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `VITE_C15T_BACKEND_URL` wins.

`consentManifest` downloads your project's public policy from
`<backendURL>/manifest` during `vite build`, or in `vite dev` when the app
first loads it, and hands it and the backend URL to `manifest()`. A build
fetches only when the app uses `manifest()`. No file is written into your project.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

## Mount the provider

Render `ConsentProvider` around your app in `src/App.svelte`, with the
vendor scripts c15t should load:

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

The `<main>` element stands in for your app's content. `manifest()` from
`@c15t/svelte`, with no options, resolves the policy from the snapshot
`consentManifest` downloaded and saves choices to the same
`VITE_C15T_BACKEND_URL`. Vite writes the variable into the bundle at build
time, so changing it means a rebuild.

PostHog waits for measurement permission. Replace `phc_your_project_key`
with your PostHog project key. Remove any `<script>` tags or SDK imports that
already load PostHog, so c15t is the only thing that loads it.

The browser resolves the snapshot without a request when the policy does not
depend on geography, or when it knows the country and region the policy needs.
Pass them as `manifest({ inputs: { country, region } })`, for example from an
edge worker, or set `geoURL` to a same-origin route that returns them, to keep
regional resolution on the snapshot. Otherwise it calls the backend's `/init`
and uses its resolved policy and translations. Those visitors wait for a
backend round trip and can receive newer policy than the build snapshot. The
bundle carries the policy and English copy. The resolver loads as its own
chunk when the app starts, and a visitor who resolves to another language
loads that language's copy the first time it is needed.

The provider starts consent when it mounts and stops it when it unmounts, so
keep it at the root of the app.

`ConsentBanner` shows the banner when the visitor's policy asks for one.
`ConsentDialog` is the preference dialog; it loads in its own chunk after the
page, before anyone opens it. `ConsentDialogLink` is the persistent way back to
preferences. Put it where visitors look for privacy settings, such as the
footer.

There is no stylesheet to import. Each component adds the rules it uses to
`<head>` when it first renders. With Tailwind CSS 3, import
`@c15t/svelte/styles.css` yourself and pass `styles={false}` to the provider;
see [stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself).

To apply policy edits without a rebuild, pass `manifest({ source: 'runtime' })`,
which fetches the manifest from the backend when the page loads.
`manifest({ manifestURL })` fetches it from another URL, such as a CDN,
instead of using the build's snapshot. To have the backend resolve every
visitor's location, pass `hosted()`. Like `manifest()`, it reads the backend
URL from `consentManifest`, and a `hosted()` build never downloads the
manifest:

```svelte title="src/App.svelte (partial)"
<script lang="ts">
	import { ConsentProvider, hosted } from '@c15t/svelte';
</script>

<ConsentProvider mode={hosted()} {scripts}>
```

## Verify consent

Build and preview the production bundle with `vite build` and `vite preview`,
then open the app in a private window with DevTools open on the Network tab:

1. The banner appears. No requests go to PostHog yet.
2. Select **Reject All**. Reload. The banner stays closed and PostHog requests
   stay absent.
3. Select **Privacy settings**, turn on **Analytics** (the `measurement`
   category) and save. PostHog loads.
4. Turn it off and save. The page reloads and PostHog does not load.

If the banner does not appear, see [troubleshooting](/docs/frameworks/svelte/troubleshooting).
[Verify consent](/docs/guides/verify-consent) has the release checklist.

## Other setups

**Offline mode** resolves policies in the browser and keeps choices in the
browser's cookie and local storage, with no backend and no consent records. Use it for local development
and tests. Not recommended for production environments.

```ts
import { offline } from '@c15t/svelte';

const mode = offline();
```

With no arguments, `offline()` uses the recommended rules. They ask for
opt-in in Europe and unknown locations, use opt-out in US privacy states, and
show no banner where no consent law applies. Pass `offline({ policyRules })` to use your own.
[Data fetching](/docs/concepts/data-fetching#when-should-i-use-offline-mode)
explains the trade-offs.

**A self-hosted backend** uses the same setup with your own backend URL. See
[self-hosting](/docs/self-host/overview).

**Astro** can render these Svelte components as islands. Its integration uses
Svelte for the dialog by default. Pick the Astro row in
[choose your setup](/docs/concepts/choose-your-setup).

Next, [customize](/docs/frameworks/svelte/customize) the banner or read
consent in your own components with [context getters](/docs/frameworks/svelte/getters).

# Scripts
URL: https://c15t.com/docs/frameworks/svelte/scripts
Load vendor scripts, iframes and network requests in a Svelte app only after the visitor allows their consent category, and stop them when consent is withdrawn.

## Register scripts on the provider

Pass the array from `src/scripts.ts` to `ConsentProvider` as the
`scripts` prop. The [quickstart](/docs/frameworks/svelte/quickstart) sets up
this file:

```ts title="src/scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	// Loads PostHog only after the visitor allows measurement.
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

Replace the placeholder PostHog project key with your own.

The provider loads the script loader as a separate chunk, shared with the
[network blocker](./network-blocker), and only when `scripts` is not empty or
the blocker has rules, so an app with neither never downloads it. A
single-page app has no server render to link the chunk from, so the browser
requests it after your app's JavaScript has run. A SvelteKit app can preload
it from the server-rendered page; the SvelteKit scripts guide shows how.

## How registered scripts load

The provider's `scripts` prop takes an array of script configurations. Each
has a category. The loader adds a script to the page when its category becomes
allowed and removes it when the category is withdrawn. Nothing optional loads
while the policy is still resolving, or when it fails.

Helpers in `@c15t/integrations`, such as `posthog()` from `@c15t/integrations/posthog`,
return a configuration with the right category and the vendor's own consent
calls. [Integrations](/docs/integrations/overview) lists every helper. For an
SDK without a helper, write a configuration with an `id`, `category` and `src`
as shown in [building integrations](/docs/integrations/building-integrations).

Remove the vendor's original `<script>` tag, `app.html` snippet or SDK import
before you register it. A banner does not block code that loads some other
way, and a vendor loaded twice sends events twice.

The `scripts` array is read when the provider is created. Build it once, at
the top level of the component, not inside an effect.

## Script options

Helpers set these for you. For a script without a helper, write the object
yourself:

|Option|Default|Behavior|
|--|--|--|
|`id`|required|A unique name. The loader uses it to add and remove the script once.|
|`category`|required|The category or condition, such as `'measurement'` or `{ and: ['measurement', 'marketing'] }`, that must be allowed.|
|`src` or `textContent`|none|The script's URL, or inline code.|
|`callbackOnly`|`false`|Adds no `<script>` element and only runs the callbacks. Use it to switch an SDK you load yourself on and off.|
|`alwaysLoad`|`false`|Loads at once, whatever the consent state. Only for scripts that apply consent themselves, such as a tag manager with Consent Mode.|
|`persistAfterConsentRevoked`|`false`|Keeps the element after withdrawal instead of removing it.|
|`target`|`'head'`|Where the element goes: `'head'` or `'body'`.|
|`async`, `defer`, `fetchPriority`, `attributes`, `nonce`|none|Set on the `<script>` element.|
|`anonymizeId`|`true`|Gives the element a random `id`, so ad blockers do not match it by name.|
|`vendor`|none|Also waits for this vendor to be allowed, for vendor-level consent outside IAB.|
|`onBeforeLoad`, `onLoad`, `onError`, `onConsentChange`, `onDispose`|none|Lifecycle callbacks. See [callbacks](./callbacks#script-callbacks).|

## Gate embeds

Iframes are not scripts. Wrap them in `ConsentGate`, which keeps the iframe
out of the DOM until its category is allowed:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

For iframes from a CMS or Markdown, which you cannot wrap, use the iframe
blocker's `data-category` and `data-src` attributes. [Embeds](./embeds) covers
both.

## Block requests from code already on the page

The provider's `networkBlocker` option holds `fetch` and `XMLHttpRequest`
calls to the domains you list until their category is allowed. It is a
backstop for code you cannot move into `scripts`. [Network blocker](./network-blocker)
covers the rules and what it cannot stop.

## What happens when consent is withdrawn

Removing a script tag cannot stop code that already ran. So when a save
withdraws a category that was granted, the provider reloads the page after the
save request, and the new page starts with only the permitted code. Set
`reloadOnConsentRevoked: false` on the provider if you handle withdrawal
yourself, for example through a vendor's own opt-out call in
`onConsentChange`.

`ConsentGate` content unmounts without a reload. To delete first-party cookies
a vendor set, configure `clearOnRevocation`; see
[clearing data on revocation](./clear-on-revocation).

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Pass
`vendors` to the provider; helpers from `@c15t/integrations` already carry their
vendor slug. See [vendor consent](./vendor-consent).

## Verify vendor loading

Open DevTools, clear site data for your origin and reload:

1. With the banner showing, the Network panel has no requests to your vendors,
   and gated iframes are absent from the Elements panel.
2. Allow one category in preferences. Only that category's vendors load, and
   its iframes appear.
3. Reject, reload, and confirm the vendor requests stay absent.
4. Withdraw a category you allowed. The page reloads and its vendors no longer
   load.

[Verify consent](/docs/guides/verify-consent) covers automated checks.

# Embeds
URL: https://c15t.com/docs/frameworks/svelte/embeds
Keep YouTube videos, maps and other iframes out of a Svelte page until their consent category is allowed, with ConsentGate or the iframe blocker.

## Pick a way to gate the embed

A YouTube video, a map or a social post in an iframe contacts its vendor as
soon as it loads. c15t offers two ways to keep it from loading before
consent:

|Your markup|Use|Placeholder|
|--|--|--|
|A Svelte component you write|`ConsentGate` around the iframe|Built in, or your own snippet|
|HTML you do not control, such as CMS or Markdown content|The iframe blocker with `data-category` and `data-src`|None; the iframe stays empty|

Both use the visitor's effective permission for one category, and both
remove the embed again when the visitor withdraws that category.

## Wrap the iframe in ConsentGate

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

The iframe is absent from the DOM until measurement is allowed, so the
browser never requests it. The placeholder snippet replaces the built-in one
and includes a `ConsentDialogLink`, so a visitor can allow the category from
the embed's own spot. Keep `ConsentDialog` mounted for that link.
[ConsentGate](./components/consent-gate) lists its props.

Pick the category the vendor's embed needs. YouTube and maps usually fit
`measurement` or `marketing`; check what each vendor sets.

## Gate iframes you do not render

The provider's iframe blocker is on by default. It watches the page for
iframes with a `data-category` attribute:

```html
<iframe
  title="Store locations"
  data-category="functionality"
  data-src="https://www.google.com/maps/embed?pb=..."
></iframe>
```

* While the category is denied, the iframe has no `src`, so it loads nothing.
* When the category is allowed, the blocker copies `data-src` to `src`.
  Only `http` and `https` URLs are used.
* When the category is withdrawn, the blocker removes `src` again.

Iframes without `data-category` or `data-vendor` are never touched. Put
`data-src` in the HTML instead of `src`; an iframe that arrives with `src`
already starts loading before the blocker sees it. Add `data-vendor` with a
vendor slug to also keep the iframe empty while the visitor has that vendor
turned off.

The blocker has no placeholder. Style the empty iframe, or place a note and a
`ConsentDialogLink` next to it.

Pass `iframeBlocker={false}` on the provider to turn the blocker off.

## Vendor guides

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides have ready embed
configurations. [Integrations](/docs/integrations/overview) lists the rest.

## Verify the embeds

Clear site data and reload with DevTools open:

1. The Network panel has no request to the embed's host, and the Elements
   panel shows the placeholder or an iframe without `src`.
2. Allow the category in preferences. The embed loads without a page reload.
3. Withdraw the category. The embed disappears, or its iframe loses `src`.

# Network blocker
URL: https://c15t.com/docs/frameworks/svelte/network-blocker
Hold fetch and XMLHttpRequest calls to tracking domains in a Svelte app until their consent category is allowed, with the provider's networkBlocker option.

## When to use the network blocker

The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
list until their consent category is allowed. Use it as a backstop for
tracking calls from code that is already on the page, such as your own
analytics wrapper or an SDK you import. It is off until you configure it.

Load vendor SDKs through the provider's `scripts` prop first; see
[scripts](./scripts). A script that never loads sends nothing, which is
stronger than blocking its requests one by one.

## Configure the rules

Write the configuration in its own module:

```ts title="src/lib/network-blocker.ts"
import type { UseNetworkBlockerOptions } from '@c15t/svelte';

// Pass as `networkBlocker={networkBlocker}` on ConsentProvider.
export const networkBlocker: UseNetworkBlockerOptions = {
	onRequestBlocked: ({ method, url }) => {
		console.info('Blocked until consent', method, url);
	},
	rules: [
		{
			category: 'measurement',
			domain: 'google-analytics.com',
			id: 'google-analytics',
		},
		{
			category: 'marketing',
			domain: 'connect.facebook.net',
			id: 'meta-pixel',
			pathIncludes: '/signals',
		},
	],
};
```

Pass it to the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} {networkBlocker}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} {networkBlocker}>
```

The provider reads `networkBlocker` once, when it is created. Remount the
provider to change the rules.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

A blocked `fetch` resolves to a response with status `451` and the status
text `Request blocked by consent`, and nothing is sent. A blocked
`XMLHttpRequest` is aborted and fires an `error` event. Requests that match no
rule are not delayed. With `logBlockedRequests` on, the default, each blocked
request is logged with `console.warn`; `onRequestBlocked` receives
`{ method, url, rule }`.

## When blocking starts

The provider starts holding matching requests when it is created in the
browser, before its children run their own code. The blocker module loads
when the provider mounts and then decides each held request:

* While the policy is still loading, a matching request waits instead of
  failing. When the policy arrives, with the visitor's stored choice applied,
  the request is sent if its category is allowed and blocked otherwise.
* If the policy fails to load, optional categories stay denied and the
  waiting requests are blocked.
* A synchronous XHR cannot wait. Before the blocker module loads, a matching
  one throws a `NetworkError` from `send()`.

When the visitor allows a category later, new requests to its domains go
through. Requests blocked earlier are not replayed.

## What it cannot stop

The blocker sees only `fetch` and `XMLHttpRequest` calls made after the
provider is created in the browser. It cannot stop:

* Scripts that run before the provider, such as tags in `index.html` or
  `app.html` and code at the top level of modules that load first.
* Code that kept its own reference to `fetch` or `XMLHttpRequest` from before
  the provider was created.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` and `<iframe>` elements, web workers and service
  workers.
* Requests your server makes, such as from a SvelteKit `load` or endpoint.

Keep tracking calls out of that window. Send them from event handlers or
effects, not at a module's top level, and check
`getConsentManager().has('measurement')` before you call a vendor from your
own code.

## Verify the blocker

Open DevTools, clear site data for your origin and reload:

1. Before you choose, requests matching a rule do not reach the network, and
   the console logs each blocked request.
2. Allow the rule's category. New matching requests appear in the Network
   panel.
3. Reject, reload and confirm they stay blocked.

`fetch('https://www.google-analytics.com/g/collect')` in the console returns a
response with status `451` while measurement is denied.

# Vendor consent
URL: https://c15t.com/docs/frameworks/svelte/vendor-consent
Let visitors allow a category such as marketing in a Svelte app and still turn off one vendor in it, with the vendors prop on ConsentProvider and getConsentManager.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors next to the scripts in `src/scripts.ts`, using the `vendor`
slug each script already carries:

```ts title="src/scripts.ts (partial)"
import type { ConsentManagerOptions } from '@c15t/svelte';

export const vendors: NonNullable<ConsentManagerOptions['vendors']> = [
	{
		id: 'x-pixel',
		name: 'X Pixel',
		category: 'marketing',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];
```

Then pass them to `ConsentProvider` in `src/App.svelte`:

```svelte title="src/App.svelte (partial)"
<script lang="ts">
  import { scripts, vendors } from './scripts';
</script>

<ConsentProvider mode={manifest()} {scripts} {vendors}>
```

The provider reads `vendors` once, when it is created.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. For an iframe, add `data-vendor` and use
the iframe blocker; see [embeds](/docs/frameworks/svelte/embeds).

## What the preference dialog shows

`ConsentDialog` and `ConsentWidget` list each declared vendor under its
category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`getConsentManager()` stages vendor switches on the same draft as the category
switches. `selectedVendors` has one value per declared vendor,
`setSelectedVendor(id, granted)` changes one, and `saveConsents('custom')`
records the draft:

```svelte title="src/XPixelSwitch.svelte (partial)"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
</script>

<input
	type="checkbox"
	checked={consent.selectedVendors['x-pixel'] ?? true}
	onchange={(event) =>
		consent.setSelectedVendor('x-pixel', event.currentTarget.checked)}
/>
<button type="button" onclick={() => consent.saveConsents('custom')}
	>Save</button
>
```

`saveConsents('custom')` throws when the policy changed since the draft
started. `vendorChoice.denied` lists the vendors the visitor recorded as off,
and `getDisplayedVendors(category)` returns the vendors to list under one
category. [Context getters](/docs/frameworks/svelte/getters) covers the draft.

## Check whether a vendor may run

`consent.isVendorAllowed(id)` on the object from `getConsentManager()` returns
`true` while the vendor may run: it is declared, its category is allowed and
the visitor has not switched it off. Read it in markup or a `$derived` so it
updates when consent changes.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/svelte/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a Svelte app when that category is denied, with the clearOnRevocation prop on ConsentProvider.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns and pass them to
`ConsentProvider` in `src/App.svelte`. When that category is denied,
c15t deletes them:

```svelte title="src/App.svelte (partial)"
<script lang="ts">
  import type { ConsentManagerOptions } from '@c15t/svelte';

  const clearOnRevocation: ConsentManagerOptions['clearOnRevocation'] = {
    measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
    marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
  };
</script>

<ConsentProvider mode={manifest()} {scripts} {clearOnRevocation}>
```

The provider reads `clearOnRevocation` once, when it is created. For a shared
runtime, pass it to `createConsentRuntime()` instead, not to a provider that
borrows the runtime.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/svelte/customize
Change c15t's colors, shape, button styles and copy in a Svelte app with a token stylesheet, theme slots, presentation props and translations.

## Pick the right tool

|Change|Use|
|--|--|
|Brand colors, radius, type, spacing|`--c15t-*` variables in a stylesheet|
|One part of one component|`theme.slots` on the provider|
|Button styles by action|`theme.consentActions`|
|Shape, position, blocking, button order|`ConsentBanner` props or `presentation`|
|Wording and languages|`ConsentBanner` text props, or [translations](/docs/frameworks/svelte/translations)|
|Different markup|[Headless](/docs/frameworks/svelte/headless)|

[Customization](/docs/customization/overview) explains how the pieces fit
together across frameworks.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## Set brand colors and radius

Write the `--c15t-*` variables on `:root` in a stylesheet. c15t's default
tokens carry no specificity, so your rule replaces them wherever each loads:

```css title="src/consent-theme.css"
/* Load after @c15t/svelte/styles.css so these values win. */
:root {
	--c15t-primary: #6943a3;
	--c15t-primary-hover: #533285;
	--c15t-text-on-primary: #ffffff;
	--c15t-radius-lg: 18px;
}
```

```ts
import './consent-theme.css';
```

Set a hover color and a text color with the primary color, so buttons stay
readable in each state. [Theme tokens](/docs/customization/tokens) lists
every variable.

Do not put colors, radius or other tokens in the provider's `theme` prop. In
the browser, `theme` applies slots and `consentActions` only; the token values
are ignored. In development, the provider logs a warning when `theme` has
tokens and the page has no `<style id="c15t-theme">`.

If your tokens come from data at runtime, `generateThemeCSS(theme)` from
`@c15t/ui/theme` turns a theme object into the same CSS. Install
`@c15t/ui@alpha` to use it, put the result in a `<style id="c15t-theme">`
element, and expect the generator to add to your bundle. Its selectors outrank
the stock defaults, so the element works wherever it sits. They also outrank
a plain `:root` rule of your own, so if you mix both, write your overrides on
`:root:root`.

## Switch to dark tokens

The provider's `colorScheme` prop switches on the dark token set: `'dark'`
always, `'system'` when the operating system prefers dark, `'light'` never. It
toggles a `c15t-dark` class on `<html>`. Left unset, the provider copies a
`dark` class on `<html>` into `c15t-dark`, so an app with its own dark mode
toggle gets the dark tokens without the prop. Pass `null` if your app sets
`c15t-dark` itself. Override dark values under `:root.dark` and
`:root.c15t-dark` in your stylesheet. [Dark mode](/docs/customization/dark-mode)
covers a dark first paint.

## Style one part with theme slots

The provider's `theme` prop still applies slot styles in the browser. A slot
takes a class name, or `{ className, style, noStyle }`. Svelte applies a
slot's class and `style` on every stock part, including the IAB banner and
dialog:

```ts
const theme = {
	slots: {
		consentBannerCard: 'brand-banner-card',
		consentBannerTitle: 'brand-banner-title',
	},
};
```

Pass it as `theme={theme}` on `ConsentProvider`. Define the class in a
global stylesheet, or with `:global(.brand-banner-card)` in a component,
because Svelte scopes component styles. The Svelte components read these
slots:

|Component|Slots|
|--|--|
|`ConsentBanner`|`consentBanner`, `consentBannerCard`, `consentBannerHeader`, `consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`, `consentBannerFooterSubGroup`, `consentBannerRights`, `consentBannerRightLink`, `consentBannerTag`, `consentBannerOverlay`|
|`ConsentDialog`|`consentDialog`, `consentDialogCard`, `consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`, `consentDialogContent`, `consentDialogTag`|
|`ConsentWidget`|`consentWidget`, `consentWidgetFooter`, `consentWidgetFooterSubGroup`, `consentWidgetTag`|
|`ConsentDialogTrigger`|`consentDialogTrigger`, `consentDialogTriggerIcon`|
|`IABConsentBanner`|`iabConsentBanner`, `iabConsentBannerTag`, `iabConsentBannerOverlay`|
|`ConsentGate`|`consentGate`, `consentGateTitle`, `consentGateButton`|
|Buttons in every component|`buttonPrimary`, `buttonSecondary`|

Slot names are not React's `components.banner.card` keys; do not copy a React
configuration. Use slots when one part should change and tokens when a value
should change everywhere. `class` on a component, such as
`<ConsentBanner class="...">`, goes on its root.
[Component parts](/docs/customization/slots) explains the attributes each
element carries, and [Tailwind CSS](/docs/customization/tailwind) shows the
Svelte and SvelteKit setups for Tailwind 4 and 3.

## Change button styles by action

`theme.consentActions` picks each button's style by what it does, whichever
order the policy puts the buttons in:

```ts
const theme = {
	consentActions: {
		default: { variant: 'neutral', mode: 'stroke' },
		primary: { variant: 'primary', mode: 'filled' },
		reject: { variant: 'neutral', mode: 'filled' },
	},
};
```

A per-action entry overrides `primary`, which overrides `default`. The policy
decides which action is primary.

## Change the banner shape and position

Set the shape on the banner itself, or for every surface with the provider's
`presentation` prop:

```svelte
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

`blocking` adds a backdrop, locks scrolling, traps focus and stops outside
clicks from closing the banner. `layout` and `primaryButton` change the button
order and emphasis. The policy wins where they conflict. A policy that requires
a reject button keeps it, whatever the layout says.

## Change the copy

For one banner, the text props on `ConsentBanner`, such as `title` and
`rejectButtonText`, replace the copy in every mode:

```svelte
<ConsentBanner title="Your privacy" rejectButtonText="Reject optional" />
```

For site-wide copy, pass the provider's `i18n` messages. In `offline()` mode
they merge over the bundled English copy. In `hosted()` mode they merge over
the backend's copy for the same language, key by key, so keys you leave out
keep the wording from your Inth project.
[Translations](./translations) covers both, the message keys and switching
languages. [Copy and translations](/docs/customization/translations) covers
wording for each action.

## Turn off animations

`disableAnimation` on the provider turns off the banner and dialog animations,
and the same prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner` or
`IABConsentDialog` overrides it for one surface. Left unset, the provider
follows the visitor's reduced motion setting.
[Motion and animation](/docs/customization/motion) covers the duration and
easing tokens.

## Remove c15t's styles

Set `noStyle` on one component or on the provider to render the same markup
and behavior without c15t's classes. Style the `data-*` attributes and your
slot classes instead. For different markup, see the headless page.

# Translations
URL: https://c15t.com/docs/frameworks/svelte/translations
Change c15t banner and dialog copy in a Svelte app with component text props or the provider's i18n option, and switch languages at runtime.

## Where the copy comes from

The banner, dialog, widget, gate placeholder and IAB surfaces read their text
from one set of translations for the visitor's language. Which set depends on
the provider's `mode`:

|Mode|Copy comes from|Languages|
|--|--|--|
|`hosted()`|The backend's `/init` response, in the language the browser or server asked for, with the provider's `i18n` messages for that language on top|Every language the backend bundles: bg, cs, cy, da, de, el, en, es, et, fi, fr, ga, gu, he, hi, hr, hu, id, is, it, lb, lt, lv, mt, nb, nl, nn, pl, pt, rm, ro, sk, sl, sv and zh|
|`manifest()`|The manifest's translations over the base copy for the visitor's language, with the provider's `i18n` messages on top. Resolved on the server in SvelteKit, in the browser in Svelte.|English base copy is bundled; another language's base copy loads the first time a visitor needs it|
|`offline()`|The provider's `i18n` prop, merged over bundled English|English, plus any language you supply in full|

The browser bundle carries English only. Other languages arrive from the
backend, or from messages you pass.

## Change the copy for one banner

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. These props
win in every mode:

```svelte
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>
```

The props replace the text in every language, so pass values in the page's
language, or compute them from your own i18n library.

## Change the copy site-wide

Pass `i18n` to the provider. `messages` holds partial translations per
language; the keys you leave out keep c15t's copy:

```ts title="src/lib/consent-i18n.ts"
import type { I18nConfig } from '@c15t/svelte';

// Pass as `i18n={i18n}` on ConsentProvider. Messages merge over the
// bundled English copy, so list only the keys you change.
export const i18n: Partial<I18nConfig> = {
	locale: 'en',
	messages: {
		en: {
			common: { customize: 'Choose cookies', rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Your privacy on this site' },
		},
	},
};
```

`locale` selects the language the provider starts in, `en` by default.

In `hosted()` mode, the backend's copy for the visitor's language is the base,
and your `i18n` messages for that language replace it key by key. Keys you do
not list keep the backend's copy, including copy edited in your Inth project.
The same applies to the copy SvelteKit's `loadConsent` resolves on the
server. c15t picks the
messages for the exact language first, then for its primary language, so a
visitor resolved to `de-AT` gets your `de` messages when there is no `de-AT`
entry. Messages for other languages are not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps backend edits visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording. A
self-hosted backend takes `customTranslations` and `i18n` in its
[configuration](/docs/self-host/api/configuration).

In `offline()` mode, `i18n` is the only source of copy, and it applies from the
first render.

## Common message keys

|Key|Where it shows|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Choice banner heading and body.|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Notice banner heading and body.|
|`common.acceptAll`, `common.rejectAll`, `common.customize`, `common.save`|Banner and dialog buttons.|
|`common.acknowledge`|The notice's dismiss button.|
|`common.securedBy`|The "Secured by" tag.|
|`consentManagerDialog.title`, `consentManagerDialog.description`|Preference dialog heading and body.|
|`consentTypes.<category>.title`, `consentTypes.<category>.description`|A category's name and description, such as `consentTypes.measurement.title`.|
|`consentGate.title`, `consentGate.actionButton`|The `ConsentGate` placeholder. `{category}` is replaced by the category title.|

[Copy and translations](/docs/customization/translations) covers wording for
each action and testing long labels.

## Switch the language

`getConsentManager().setLanguage(code)` switches the language and resolves the
policy again, so a hosted backend returns copy in the new language and your
`i18n` messages for that language apply on top. Call it
from your language switcher's event handler. The visitor's language otherwise
comes from the `Accept-Language` header, or from `overrides.language` on the
provider.

The root of the banner, dialog and widget sets `dir` from the active
language, so right-to-left languages such as Hebrew lay out correctly.

## Verify the copy

Open the page with the browser language set to each language you support.
The banner, the dialog's category names and the gate placeholder all use that
language. Then choose a narrow window and zoom to 200%: long labels wrap
without cutting off.

# Primitives
URL: https://c15t.com/docs/frameworks/svelte/components/primitives
Build your own accessible consent dialog in Svelte with the Dialog, Switch, Tabs, Accordion and PreferenceItem primitives and the focusTrap, scrollLock and portal actions.

## When to use the primitives

The stock consent components are built from a set of unstyled, accessible
building blocks that `@c15t/svelte` also exports. Reach for them when you
build your own preference dialog or settings page with the
[headless getters](../headless) and want the same keyboard and focus behavior
as the stock dialog. For the consent state itself, use `getConsentManager()`;
the primitives know nothing about consent.

Their rules load with the stock `ConsentDialog`. A page that renders the
primitives without the stock dialog needs `@c15t/svelte/styles.css`: import it
and set `styles={false}` on the provider. Each part accepts `class` and passes
other HTML attributes to its element.

## Compound components

Import each as one object and use its parts, such as `Dialog.Root` and
`Dialog.Content`. Every part is also exported on its own.

|Component|Parts|Root props|
|--|--|--|
|`Dialog`|`Root`, `Portal`, `Backdrop`, `Positioner`, `Content`, `Title`, `Description`, `CloseTrigger`|`open` (bindable, default `false`), `closeOnEscape` (`true`), `closeOnInteractOutside` (`true`), `trapFocus` (`true`), `preventScroll` (`false`), `lazyMount` (`false`), `unmountOnExit` (`false`)|
|`Switch`|`Root`, `Control`, `Thumb`, `HiddenInput`|`checked` (bindable, default `false`), `disabled`, `type` (`'button'`)|
|`Tabs`|`Root`, `List`, `Trigger`, `Content`|`value` (bindable), `orientation` (`'horizontal'`), `loop` (`true`), `disabled`|
|`Accordion`|`Root`, `Item`, `ItemTrigger`, `ItemContent`|`type` (`'single'` or `'multiple'`, required), `value` (bindable), `collapsible` (`false`)|
|`Collapsible`|`Root`, `Trigger`, `Content`, `Indicator`|`open` (bindable, default `false`), `disabled`|
|`PreferenceItem`|`Root`, `Trigger`, `Leading`, `Header`, `Title`, `Meta`, `Auxiliary`, `Control`, `Content`|`open` (bindable, default `false`), `disabled`, `noStyle`|

`Portal` renders its children into another element, `document.body` by
default. Pass `target` as an element or a selector.

## Actions

Three Svelte actions apply the same behavior to your own elements:

|Action|Use|Parameter|
|--|--|--|
|`focusTrap`|`use:focusTrap={open}`|`true`, `false`, or `{ enabled, initialFocus }`. Keeps Tab inside the element while enabled.|
|`scrollLock`|`use:scrollLock={open}`|`boolean`. Stops the page scrolling behind the element.|
|`portal`|`use:portal` or `use:portal={'#modals'}`|An element or selector, default `body`. Moves the element there and removes it when the component unmounts.|

The banner uses these three actions; the stock dialog uses `Dialog`.

## Check your custom dialog

Open it with the keyboard only. Tab and Shift+Tab stay inside it, Escape
closes it, and focus returns to the control that opened it. Each switch
announces its name and state in a screen reader. See the
[headless page](../headless) for the consent side of a custom dialog.

# Headless
URL: https://c15t.com/docs/frameworks/svelte/headless
Replace the c15t banner or preference dialog with your own Svelte markup while the provider keeps policy, storage and script loading.

## Choose how much to replace

Try [customization](/docs/customization/overview) first: tokens, slots,
`presentation` and translations change most banners without new markup. Go
headless when you need markup the stock components cannot produce.

|Goal|Approach|
|--|--|
|Keep the markup, drop c15t's styles|Set `noStyle` on the provider or on one component, and style the `data-*` attributes and slot classes.|
|Your own banner, stock dialog|`getHeadlessConsent()` for the banner, `ConsentDialog` for preferences. This page's example.|
|Your own dialog too|Add `getConsentManager()` for the category list and the draft.|

The provider, scripts, `ConsentGate` and the stored choice work the same with
any of them. You only replace the markup.

## Build a banner with getHeadlessConsent

`getHeadlessConsent()` returns the banner and dialog state and one method per
action. Call it at the top level of a component inside
`ConsentProvider`.

This banner renders the actions the policy allows, grouped and ordered the way
the policy asks, and hides itself when no banner is due:

```svelte title="src/lib/custom-consent-banner.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Customize',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};
</script>

{#if consent.banner.isVisible}
	<section class="custom-consent-banner" aria-label="Cookie consent">
		<p>
			We use cookies to measure traffic and show ads. Choose which ones can run.
		</p>
		<!-- The policy decides which actions this visitor gets, and in what order. -->
		{#each consent.banner.actionGroups as group, index (index)}
			<div>
				{#each group as action (action)}
					<button type="button" onclick={() => consent.performAction(action)}>
						{labels[action]}
					</button>
				{/each}
			</div>
		{/each}
	</section>
{/if}

<style>
	.custom-consent-banner {
		position: fixed;
		inset: auto 1rem 1rem;
		max-width: 32rem;
		padding: 1rem;
		border: 1px solid currentColor;
		border-radius: 0.5rem;
		background: white;
	}
	.custom-consent-banner div {
		display: flex;
		gap: 0.5rem;
		margin-top: 0.5rem;
	}
</style>
```

Render it where the stock `ConsentBanner` would go. The stock dialog still
handles Customize and the preferences link, so keep `ConsentDialog`. It adds
its own rules when it opens:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import {
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		hosted,
	} from '@c15t/svelte';

	import CustomConsentBanner from '#lib/custom-consent-banner.svelte';
	import { scripts } from '#lib/scripts.js';

	let { children } = $props();

	const mode = hosted({ backendURL: 'https://your-project.inth.app' });
</script>

<ConsentProvider {mode} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<CustomConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

In a Svelte app without SvelteKit, the same markup goes in the component that
renders the provider.

|Member|Purpose|
|--|--|
|`banner.isVisible`, `dialog.isVisible`|Whether that surface is due now.|
|`banner.actionGroups`, `banner.orderedActions`|The allowed actions, grouped or flat, in the order the policy asks for.|
|`banner.requiredActions`, `banner.primaryActions`|Actions you must show, and those to emphasize.|
|`banner.variant`, `banner.position`, `banner.blocking`|The resolved shape, position and blocking behavior, if you want to follow them.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`performAction(action)`|`accept`, `reject`, `dismiss`, `save` or `customize`. Customize opens the dialog.|
|`openBanner()`, `openDialog()`, `closeUI()`|Show or hide a surface.|
|`saveCustomPreferences()`|Record the dialog's draft.|

Render from `actionGroups` or `orderedActions` rather than a fixed list. A
policy can require a reject button next to accept, or offer only a dismiss
button for a notice, and a hard-coded pair of buttons breaks those rules.

## Build your own preferences

For a custom dialog or settings page, read the category list and the unsaved
draft from `getConsentManager()`:

```svelte title="src/lib/cookie-preferences.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
	const config = $derived(consent.translationConfig);
	const copy = $derived(config.translations[config.defaultLanguage ?? 'en']);
</script>

{#if consent.draft.isStale}
	<p role="alert">The cookie policy changed. Review your choices.</p>
{/if}
<fieldset>
	<legend>Cookie preferences</legend>
	{#each consent.getDisplayedConsents() as category (category.name)}
		<label>
			<input
				type="checkbox"
				checked={consent.selectedConsents[category.name] ?? false}
				disabled={category.name === 'necessary'}
				onchange={(event) =>
					consent.setConsent(category.name, event.currentTarget.checked)}
			/>
			{copy?.consentTypes?.[category.name]?.title ?? category.name}
		</label>
	{/each}
</fieldset>
<button
	type="button"
	disabled={consent.draft.isStale}
	onclick={() => consent.saveConsents('custom')}
>
	Save preferences
</button>
```

`setConsent` changes the draft only. `saveConsents('custom')` records it. If
the policy changes while the draft is open, `consent.draft.isStale` becomes
`true` and saving throws, so the example disables Save and shows a message.
Translated titles and descriptions are in `consent.translationConfig`.
[Context getters](./getters#work-with-the-draft) covers the draft.

`@c15t/svelte` exports `Dialog`, `Switch`, `Accordion`, `PreferenceItem` and
the `focusTrap`, `scrollLock` and `portal` actions if you want accessible
building blocks for the dialog itself; see [primitives](./components/primitives).

## Verify a custom UI

Run the same checks as the stock components: reject, reload and confirm no
optional vendor requests; allow one category and confirm only its vendors
load; reopen preferences from your footer link. Test keyboard focus and a
screen reader on your markup, because c15t no longer owns it.
[Verify consent](/docs/guides/verify-consent) has the full list.

# Components
URL: https://c15t.com/docs/frameworks/svelte/components
Props and behavior of every @c15t/svelte component in a Svelte app, from ConsentProvider and ConsentBanner to ConsentGate and DevTools.

[`ConsentProvider`](./components/consent-provider) creates and starts the
consent runtime from a `mode`, such as `manifest()`. It renders no markup of
its own; every other component renders inside it.

## Every component

Import every component from `@c15t/svelte`, except the dev tools panel,
which comes from `@c15t/svelte/devtools`. Render them inside the provider:
`ConsentProvider` in a Svelte app, or `ConsentRoot`, which renders
`ConsentProvider`, in a SvelteKit root layout. A component outside it throws
`c15t: no v3 consent context`.

|Component|Renders|Page|
|--|--|--|
|`ConsentBanner`|The first-layer banner when the policy asks for one.|[ConsentBanner](./components/consent-banner)|
|`ConsentDialog`|The preference dialog, loaded on first use.|[ConsentDialog](./components/consent-dialog)|
|`ConsentWidget`|The preference controls inline, for a settings page.|[ConsentWidget](./components/consent-widget)|
|`ConsentDialogLink`|An unstyled button that opens preferences, for your footer.|[ConsentDialogLink](./components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens preferences.|[ConsentDialogTrigger](./components/consent-dialog-trigger)|
|`ConsentGate`|Its children only while a category is allowed.|[ConsentGate](./components/consent-gate)|
|`ConsentButton`|A button that accepts, rejects, saves or opens preferences.|[ConsentButton](./components/consent-button)|
|`IABConsentBanner`|The IAB TCF banner, for visitors under an IAB policy.|[IABConsentBanner](./components/iab-consent-banner)|
|`IABConsentDialog`|The IAB TCF preference center.|[IABConsentDialog](./components/iab-consent-dialog)|
|`ConsentDevTools`|A development panel for the consent state.|[Dev tools](./components/dev-tools)|
|`Dialog`, `Switch`, `Tabs` and others|Unstyled building blocks for your own UI.|[Primitives](./components/primitives)|

`DevTools` and `C15TDevTools` are aliases for `ConsentDevTools`.

## Styles

There is no stylesheet to import. Each stock component adds the rules it
uses to `<head>` as a `<style>` element, once per page, before its own
elements render. On a server-rendered SvelteKit page, `c15tHandle` writes the
banner's rules into the HTML, so the banner is styled before hydration. The
dialog's rules, including the primitives', load with the dialog's code.

The IAB TCF banner and dialog also add their own rules. The IAB dialog adds
its rules when it opens, and includes the base rules it needs when rendered
without a banner. Pages without IAB components do not load the IAB sheets.

To run the stylesheet through Tailwind CSS 3 or put it in a named cascade
layer, set `styles={false}` on the provider and import
`@c15t/svelte/styles.css`. With IAB TCF, also import
`@c15t/svelte/iab/styles.css` after the base stylesheet;
[stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when.

## When components render nothing

Every consent surface stays hidden until a policy resolves for the visitor,
and again when the resolved policy asks for no prompt and grants no way to
change preferences. A missing banner or link is usually a policy result, not
a rendering bug. See
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

## Shared props

Several props mean the same thing on every component:

|Prop|Behavior|
|--|--|
|`noStyle`|Renders the same markup and behavior without c15t's classes. Set it on the provider for every component, or on one component.|
|`class`|Adds your class to the component's root element.|
|`hideBranding`|Hides the "Secured by" tag on the banner, dialog and widget.|
|`models`|The policy models a surface renders for: `opt-in`, `opt-out`, `iab` and `none`.|
|`legalLinks`|Which of the provider's legal links a banner or dialog shows, or `null` for none.|

Theme slots style one part of one component; [customize](./customize) lists
them.

# ConsentProvider
URL: https://c15t.com/docs/frameworks/svelte/components/consent-provider
Mount ConsentProvider at the root of a Svelte app to start c15t, with every prop, its default, and which options update after mount.

## Mount the provider

Render `ConsentProvider` once, around your whole app, in the component
you pass to `mount()`:

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

`mode` is the only required prop. Here `manifest()` resolves the policy from
the snapshot the build bundled and saves choices to your Inth project, as set
up in the [quickstart](../quickstart). `manifest({ source: 'runtime' })`
fetches the manifest when the page loads instead, and `hosted()` asks the
backend's `/init`. Both read the backend URL from `consentManifest`, or take
`backendURL`. Import every mode from
`@c15t/svelte`. The consent components render inside
the provider; your app's own components can sit anywhere inside it too, so
they can call the [context getters](../getters).

In a Svelte app without SvelteKit the browser resolves the policy after the
page loads, so the banner appears after the first paint. Optional categories
stay denied until then.

## Props

Pass each option as a top-level prop, or group them in `options`. When both
set the same option, the top-level prop wins. The `ConsentManagerOptions` type
from `@c15t/svelte` lists every option. SvelteKit's `ConsentRoot` takes the
same props, except that `state` replaces `mode` and `prefetch`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`mode`|`manifest()`, `hosted()`, `offline()` or `custom()` result, all from `@c15t/svelte`|required|Where policies come from and where choices are saved. Read once; remount the provider to change it. `ConsentRoot` builds it from `state`, or takes a `custom()` transport as `mode`.|
|`prefetch`|`ConsentState`|none|Server-resolved state, such as the result of `resolveConsent`. With a resolved policy in it, the first render already knows whether to show the banner, and the browser skips its own policy request. `ConsentRoot` passes it from `state`. Read once.|
|`scripts`|`Script[]`|none|Vendor scripts that load when their category is allowed. Updates after mount: new scripts go to the loader. See [scripts](../scripts).|
|`consentCategories`|`AllConsentNames[]`|the policy's categories|Categories the preference UI offers, within the policy's scope. Updates after mount.|
|`theme`|`Theme`|none|Slot classes and `consentActions` button styles. Design tokens in it are not applied in the browser. Updates after mount.|
|`presentation`|`ConsentPresentation`|the policy's defaults|Banner and dialog shape, position, button layout and blocking for every component. Updates after mount.|
|`legalLinks`|`LegalLinks`|none|Privacy policy, cookie policy and terms links shown in the banner and dialog. Updates after mount.|
|`i18n`|`Partial<I18nConfig>`|bundled English|Copy overrides per language. They win key by key over the backend's copy for the same language; see [translations](../translations). Read once.|
|`colorScheme`|`'light'`, `'dark'`, `'system'` or `null`|none|Toggles the `c15t-dark` class on `<html>`. `null` or unset leaves `<html>` alone. Updates after mount.|
|`noStyle`|`boolean`|`false`|Renders every component without c15t's classes. A component's own `noStyle` wins.|
|`disableAnimation`|`boolean`|follows `prefers-reduced-motion`|Turns off enter and exit transitions.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Defaults for the banner and dialog. `blocking` on a component sets both.|
|`preloadDialog`|`'idle'` or `'intent'`|`'idle'`|When `ConsentDialog` starts loading before its first open. See [ConsentDialog](./consent-dialog).|
|`networkBlocker`|options or `false`|off|Holds `fetch` and XHR requests to listed domains until their category is allowed. Updates after mount: new rules and `enabled` apply, and `false` removes the blocker. The blocker loads on demand. See [network blocker](../network-blocker).|
|`iframeBlocker`|`{ disableAutomaticBlocking?: boolean }` or `false`|on|Gates iframes that carry `data-category`. Updates after mount: `false` removes the blocker and a new `disableAutomaticBlocking` rebuilds it. See [embeds](../embeds).|
|`iab`|`ProviderIABOptions` or `false`|off|IAB TCF settings. Read once. See [IAB TCF](../iab).|
|`callbacks`|`ConsentProviderCallbacks`|none|`onChoiceRecorded`, `onPermissionsChanged`, `onError` and `onBeforeConsentRevocationReload`. The latest functions are called. See [callbacks](../callbacks).|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reloads the page after a save withdraws a category or vendor that was granted.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|Forces the location, language or Global Privacy Control signal the policy resolves for. A change after mount resolves the policy again.|
|`user`|`User`|none|Identity sent with the policy request and every saved choice, so the choice is linked to your user ID. A different user after mount is identified with the backend; the user you mount with is not identified separately.|
|`storageConfig`|`StorageConfig`|cookie and key `c15t`|Names and lifetime of the stored choice. Read once. On SvelteKit, pass the same name as `cookieName` to the server helpers.|
|`persistence`|`boolean` or options|`true`|`false` keeps choices in memory only. Read once.|
|`clearOnRevocation`|`ClearOnRevocationConfig`|off|Deletes first-party cookies and storage entries when their category is withdrawn. Loads on demand. See [clearing data on revocation](../clear-on-revocation). Read once.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. See [vendor consent](../vendor-consent). Updates after mount: a new list replaces the declared vendors.|
|`nonce`|`string`|none|Content Security Policy nonce for the `<script>` elements the script loader adds. See [Content Security Policy](../content-security-policy). Read when the loader starts.|
|`enabled`|`boolean`|`true`|`false` grants every category, hides all consent UI and skips `/init`. Updates after mount: turning it off renders a separate permissive state and keeps the visitor's stored choice for when it is turned back on.|
|`runtime`|`ConsentRuntime`|none|A runtime you created with `createConsentRuntime()`. See [share one runtime](#share-one-runtime).|
|`options`|`ConsentManagerOptions`|none|The same options as one object.|
|`children`|`Snippet`|none|Your app. The provider renders no markup of its own.|

"Read once" options are read when the provider is created. Changing them later
has no effect until the provider remounts, and outside production a change to
`mode`, `i18n` or `experiment` logs a warning. Options that update after mount
are compared with their previous values, so a new `options` object that only
changes `theme` sends no request. The provider has no `policyRules`
option. For local policy rules, pass `offline({ policyRules })` as `mode`.

## What the provider does when it mounts

The provider creates the consent runtime while the component initializes, on
the server and in the browser. Creating it has no side effects, so the server
can render the banner from `prefetch`. In the browser, `onMount` starts the
runtime:

1. It reads the stored choice from the cookie and local storage.
2. It starts the script loader, the iframe blocker and, if configured, the
   network blocker and the IAB TCF add-on.
3. It resolves the policy with its `mode`, unless `prefetch` already holds
   one.

When the provider unmounts, it stops all of them. Keep one provider at the root of the app, so it stays mounted across
navigation and every component can reach it.

With `networkBlocker`, matching requests are held from the moment the provider
is created in the browser, before its children run their own code, until the
blocker decides them.

## Share one runtime

Pass `runtime` when two component trees that cannot share Svelte context need
the same consent state. Create it with `createConsentRuntime()` from
`@c15t/svelte`, pass it to each provider, and call `runtime.start()` and
`runtime.dispose()` yourself. A provider never starts or disposes a runtime it
did not create. Options that build the runtime, such as `mode`, `scripts` and
`callbacks`, come from your `createConsentRuntime()` call; display options such
as `theme` and `noStyle` still apply per provider.

## Verify the provider

Open the page in a private window with DevTools open:

1. The banner appears once the policy resolves. `window.c15t` in the console
   shows `pkg: '@c15t/svelte'`.
2. The Network panel shows the request your mode makes: none for
   `manifest()` with a bundled snapshot, one `/init` for `hosted()`, and
   none when the page came with a server-resolved state.
3. A component that calls `getConsentManager()` renders without the
   `c15t: no v3 consent context` error.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/svelte/components/consent-banner
Show the c15t cookie banner in a Svelte app with ConsentBanner, and set its variant, position, button layout, copy, accessibility and styling hooks.

## Render the banner

Render `ConsentBanner` once, inside `ConsentProvider`, next to
`ConsentDialog` so its Customize button has a dialog to open:

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

The banner decides for itself whether to show. You do not wrap it in a
condition.

## Change the shape

`variant` and `position` set the shape for one banner. The provider's
`presentation` prop sets them for every surface; a prop on `ConsentBanner`
wins. This banner is a full-width bar along the bottom edge:

```svelte title="src/lib/cookie-banner.svelte"
<script lang="ts">
	import { ConsentBanner } from '@c15t/svelte';
</script>

<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

A notice defaults to `bar` and a choice prompt to `floating`. A position that
does not fit the variant falls back to the variant's default and logs a
warning in development. When the page's text direction is right to left and
you set no position, a corner position flips to the other side.

The [design gallery](/docs/customization/recipes) has more banner designs
with tested Svelte code.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating'`, `'bar'`, `'widget'` or `'wall'`|from the policy|Shape of the banner.|
|`position`|see the table above|the variant's default|Where the banner sits.|
|`blocking`|`boolean`|`false`|Adds a backdrop, locks scrolling, traps focus and ignores outside clicks. `wall` is always blocking; a notice never is.|
|`layout`|array of `'accept'`, `'reject'`, `'customize'`, `'dismiss'` or nested groups|from the policy|Button order and grouping, such as `[['reject', 'accept'], 'customize']`.|
|`primaryButton`|one action or an array|from the policy|Which buttons get the primary style.|
|`title`, `description`|`string`|translated copy|Replace the heading and body for this banner.|
|`acceptButtonText`, `rejectButtonText`, `customizeButtonText`, `dismissButtonText`|`string`|translated copy|Replace one button label for this banner.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description. `null` shows none.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab']`|Policy models this banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes, keeping markup and behavior.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The policy wins where it conflicts with `layout` or `primaryButton`. A policy
that requires a reject button next to accept keeps it, whatever the layout
says. For copy used across the site, use the provider's `i18n` or your
backend's translations; see [translations](../translations).

## When the banner shows

`ConsentBanner` renders when all of these are true:

* A policy has resolved for the visitor and it asks for a prompt.
* The visitor has not chosen yet, or the policy asks them to choose again.
* The active surface is the banner, not the dialog or nothing.
* The policy's model is in `models`.

A visitor in a region without a consent law, or one who already chose, gets
no banner. That is a policy result; see
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

A choice prompt shows Accept, Reject and Customize, in the order the policy
asks for. A notice, such as an opt-out policy that only informs, shows a
dismiss button and its own title and description from the `noticeTitle` and
`noticeDescription` translations. Dismissing a notice records the dismissal,
not a grant.

When the policy grants visitor rights, such as opting out of sale, the banner
shows each one as a text button that opens the preference dialog.

Accept and Reject record the choice and close the banner in the same task.
The backend request runs after; a failed request is retried and does not
reopen the banner. Customize opens `ConsentDialog`, so render the dialog too.

## Accessibility

* The banner card is a `region` labelled by the banner title. With `blocking`,
  it becomes a `dialog` with `aria-modal="true"`, and focus stays inside it
  until the visitor chooses.
* The title is an `h2`. Buttons are `<button type="button">` with their
  visible text as the accessible name.
* The banner does not move focus when it appears, unless focus trapping is on.
  Visitors reach it with Tab.
* With `prefers-reduced-motion`, the banner appears and leaves without a
  transition.
* The root sets `dir` from the active language, so right-to-left copy lays out
  correctly.

## Style the banner

`ConsentBanner` reads these theme slots from the provider's `theme` prop:
`consentBanner`, `consentBannerCard`, `consentBannerHeader`,
`consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`,
`consentBannerFooterSubGroup`, `consentBannerRights` and
`consentBannerRightLink`. [Customize](../customize) shows how to pass them.

The root element carries `data-testid="consent-banner-root"` and these
attributes for CSS and tests:

|Attribute|Value|
|--|--|
|`data-prompt`|`choice` or `notice`|
|`data-model`|`opt-in`, `opt-out` or `iab`|
|`data-variant`|the resolved variant|
|`data-position`|the resolved position|
|`data-blocking`|`true` when blocking|

Each button carries `data-action` with `accept`, `reject`, `customize` or
`dismiss`.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/svelte/components/consent-dialog
Add the c15t preference dialog to a Svelte app with ConsentDialog, including how it loads on first use, its props, keyboard behavior and theme slots.

## Render the dialog

Render `ConsentDialog` once, inside `ConsentProvider`. The banner's
Customize button and `ConsentDialogLink` open it:

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

## How the dialog loads

`ConsentDialog` is not part of the first page load. The component you render
is a small loader; the dialog itself is a separate chunk that it imports:

* In browser idle time after the page's `load` event, while a button that
  opens the dialog is mounted. Those buttons are the banner's Customize button,
  `ConsentDialogLink`, `ConsentDialogTrigger`, the `ConsentGate` placeholder
  and `ConsentButton` with `action="open-consent-dialog"`.
* When such a button is hovered or focused.
* At the latest, when the dialog opens.

Set the provider's `preloadDialog` to `'intent'` to skip the idle load and
load only on hover, focus or open. Idle loading is also skipped when the
browser asks to save data, on 2G connections and offline. Every
`ConsentDialog` on the page shares one import. If the import fails, the
surface the dialog replaced comes back, and the next hover, focus or open
retries. The dialog's CSS travels with that chunk and goes into `<head>`
before the dialog renders. With `styles={false}`, it comes from your imported
`@c15t/svelte/styles.css`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself. While `open` is `true`, the dialog stays open, even after Escape.|
|`showTrigger`|`boolean` or trigger props|`false`|Renders a floating `ConsentDialogTrigger` with the dialog. Pass an object for `defaultPosition`, `persistPosition`, `showWhen`, `size`, `ariaLabel`, `noStyle` and `class`.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab', 'none']`|Policy models the dialog opens for. `none` is included so a policy with no prompt but a right to change preferences still opens it.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the dialog content.|

`ConsentDialog` has no text props. Its title and description come from the
`consentManagerDialog` translations; see [translations](../translations).

With `showTrigger`, the dialog loads when it mounts, because the trigger needs
it at once. The trigger appears right after hydration. To keep a trigger in
server HTML, render `ConsentDialogTrigger` next to the dialog instead.

## What the dialog contains

The dialog renders the heading, the description with legal links, and a
[`ConsentWidget`](./consent-widget) with one switch per category and the save
buttons the policy allows. Categories come from the provider's
`consentCategories`, limited to the policy's scope. `necessary` is always on
and cannot be switched off.

Switches change an unsaved draft. The save button records the draft; the
accept and reject buttons record every category at once. The dialog closes in the same task
the choice is recorded. If the policy changes while the dialog is open, the
widget shows an alert and asks the visitor to review before saving.

## Open and close the dialog

Anything that sets the active surface to `'dialog'` opens it: the banner's
Customize button, `ConsentDialogLink`, `ConsentDialogTrigger`,
`getConsentManager().setActiveUI('dialog')` or
`getHeadlessConsent().openDialog()`.

Escape closes the dialog. Clicks outside it do not, so a visitor cannot lose
unsaved switches by accident. Closing without saving records nothing. If the
policy still owes a choice, the banner comes back.

With the `open` prop set, your component owns visibility. Escape then moves
the active surface off `'dialog'`, to `'banner'` while a choice is still owed
or `'none'` otherwise, and the dialog stays mounted until you set `open` to
`false`. Watch `getConsentManager().activeUI` to close it.

## Accessibility

* The dialog content is labelled by its title (`aria-labelledby`) and
  described by its description (`aria-describedby`).
* While the dialog is blocking, which is the default, focus is trapped inside
  it and the page behind does not scroll. The provider's `presentation` can
  turn blocking off for the dialog.
* Each category switch is a `switch` role labelled with the category title.
* The root sets `dir` from the active language.

## Style the dialog

`ConsentDialog` reads these theme slots: `consentDialog`, `consentDialogCard`,
`consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`,
`consentDialogContent` and `consentDialogTag`. The widget inside it reads the
`ConsentWidget` slots. The content element carries
`data-testid="consent-dialog-root"` and `data-blocking="true"` while
blocking.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/svelte/components/consent-widget
Put c15t's category switches inline on a Svelte privacy settings page with ConsentWidget, and how its draft, vendors and stale-policy alert behave.

## Put preferences on a page

`ConsentWidget` renders the preference controls inline: one switch per
category, an expandable description for each, and the save buttons the policy
allows. It is the same widget `ConsentDialog` shows, without the dialog
around it. Use it for a privacy settings page:

```svelte title="src/routes/privacy/+page.svelte"
<script lang="ts">
	import { ConsentWidget } from '@c15t/svelte';
</script>

<h1>Privacy settings</h1>
<p>Choose which optional cookies this site may use.</p>
<!-- The category switches and save buttons, inline on the page. -->
<ConsentWidget />
```

Render the page inside `ConsentProvider`. The widget works without
`ConsentDialog`, but keep the dialog mounted elsewhere if the banner's
Customize button should also work.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Shows the "Secured by" tag when `false`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

`ConsentWidget` renders nothing until a policy resolves and asks for consent
UI. Then it lists the provider's `consentCategories`, limited to the policy's
scope, with `necessary` always on and disabled.

Each switch starts from the visitor's recorded choice. Before a choice, a
switch is on under an opt-out policy or for a category the policy preselects,
and off otherwise. Moving a switch changes an unsaved draft
that every consent component on the page shares. The save button records the
draft; the accept and reject buttons record every category at once.

A category with declared vendors lists them under its description, each with
its own switch, so a visitor can allow a category and still turn one vendor
off. Under an IAB policy, vendor rows are not shown.

If the policy changes while the visitor has unsaved changes, the widget shows
an alert with a **Review preferences** button. Saving the stale draft fails
until the visitor reviews it, so a choice made under the old policy is never
recorded under the new one.

## Accessibility

* Each category switch has the `switch` role and the category title as its
  accessible name.
* Each category heading is a button with `aria-expanded` that opens its
  description. Opening one closes the others.
* The stale-policy message uses `role="alert"`, so screen readers announce it.

## Style the widget

`ConsentWidget` reads the `consentWidget` and `consentWidgetFooter` theme
slots. The root carries `data-testid="consent-widget-root"`, and each
category row carries `data-testid="consent-widget-accordion-item-<category>"`.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/svelte/components/consent-dialog-link
Let visitors reopen c15t preferences from a Svelte footer with ConsentDialogLink, an unstyled button that renders only when the policy offers preferences.

## Reopen preferences from your footer

`ConsentDialogLink` is an unstyled button that opens the preference dialog.
Put it where your site keeps its legal links, so preferences stay reachable
after the banner closes:

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

It needs `ConsentDialog` mounted in the same provider. Inside a
`ConsentGate` placeholder it gives visitors a way to allow a blocked embed:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

## Props

`ConsentDialogLink` takes its label as children and passes every other
attribute, such as `class`, `id` or `aria-describedby`, to the `<button>` it
renders.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`children`|`Snippet`|required|The visible label, such as "Privacy settings".|
|`noStyle`|`boolean`|`true`|Unstyled by default so it matches your footer links. Set `false` for c15t's button style.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it opening.|
|any button attribute|||Passed to the `<button>`.|

There is no `asChild`. To style it like your links, give it the same class,
and reset the button's border, background and padding in that class.

## Behavior

* The link renders only when the policy offers a way to change preferences:
  a prompt or a visitor right. Visitors in a
  region with no consent law and no rights see no link.
* A click sets the active surface to `'dialog'`. It needs a mounted
  `ConsentDialog` in the same provider to show anything.
* It starts loading the dialog chunk in browser idle time while mounted, and
  on hover or focus. See [ConsentDialog](./consent-dialog#how-the-dialog-loads).

## Accessibility

The link is a `<button type="button">`, so keyboard users reach it with Tab
and activate it with Enter or Space. Its accessible name is its text. Keep the
text specific, such as "Privacy settings" or "Cookie preferences", rather
than "Click here".

## Style the link

The button carries `data-testid="consent-dialog-link"` and
`data-c15t-rights` with the rights the policy grants, separated by spaces.
Style it with your own class; with `noStyle` on, c15t adds no classes.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/svelte/components/consent-dialog-trigger
Add a floating, draggable privacy button to a Svelte app with ConsentDialogTrigger, and set its corner, size, saved position, accessible name and callbacks.

## Add a floating privacy button

`ConsentDialogTrigger` is a small round button, fixed to a corner of the
viewport, that opens the preference dialog. It keeps preferences one click
away on every page without a footer link. Render it next to `ConsentDialog`:

```svelte title="src/lib/privacy-trigger.svelte"
<script lang="ts">
	import { ConsentDialog, ConsentDialogTrigger } from '@c15t/svelte';
</script>

<!-- A floating button in the bottom-left corner that opens preferences.
     Visitors can drag it to another corner; c15t remembers where. -->
<ConsentDialogTrigger defaultPosition="bottom-left" size="sm" />
<ConsentDialog />
```

Render the component inside `ConsentProvider`. `ConsentDialog`'s
`showTrigger` prop renders the same button for you, but only after the dialog
chunk loads; a separate `ConsentDialogTrigger` is part of the page from the
first render.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`defaultPosition`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner it starts in.|
|`persistPosition`|`boolean`|`true`|Remembers the corner a visitor drags it to, in local storage.|
|`showWhen`|`'always'` or `'never'`|`'always'`|`'never'` hides it.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name. Translate it yourself; it does not come from `i18n`.|
|`noStyle`|`boolean`|`false`|Drops c15t's classes, including the fixed positioning.|
|`class`|`string`|none|Extra class on the button.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it.|
|`onPositionChange`|`(corner) => void`|none|Runs after a drag moves it to another corner.|

## Behavior

* The button renders only when the policy offers a way to change preferences,
  and hides while the dialog is open.
* Visitors can drag it. On release it snaps to the nearest corner in the
  direction of the drag. A drag does not open the dialog; a click does.
* The icon follows the project's branding.
* It is rendered into `document.body`, so a parent's `overflow` or
  `transform` does not clip it.
* It starts loading the dialog chunk in idle time and on hover or focus, like
  the other buttons that open the dialog.
* While `ConsentDevTools` is mounted, it becomes a two-button toolbar: the
  preferences button stays in the corner and a DevTools button sits beside it.
  The DevTools panel opens next to the toolbar instead of from its own
  launcher. See [DevTools](./dev-tools).

## Accessibility

The trigger is a `<button type="button">` with `aria-label`, since it shows
only an icon. Keep the label in the page's language by passing `ariaLabel`.
Dragging needs a pointer; keyboard users activate it with Enter or Space and
cannot move it, so pick a `defaultPosition` that does not cover your own
controls.

## Style the trigger

The button carries `data-testid="consent-dialog-trigger"`,
`data-c15t-trigger="true"` and `data-c15t-rights`. Its colors come from the
`--c15t-*` tokens; [theme tokens](/docs/customization/tokens) lists them.

# ConsentGate
URL: https://c15t.com/docs/frameworks/svelte/components/consent-gate
Keep a YouTube video or map out of a Svelte page until its consent category is allowed with ConsentGate, and replace its placeholder.

## Gate an embed behind consent

`ConsentGate` mounts its children only while one category is allowed, and
shows a placeholder otherwise. Wrap any iframe or widget that sets cookies or
contacts a vendor when it loads:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

Render the component inside `ConsentProvider`, with `ConsentDialog`
mounted so the placeholder's link has a dialog to open. [Embeds](../embeds)
covers iframes you cannot wrap, such as those from a CMS.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The category whose permission the content needs, such as `'measurement'` or `'marketing'`.|
|`children`|`Snippet`|none|The gated content. It is not in the DOM until the category is allowed.|
|`placeholder`|`Snippet`|built-in placeholder|Shown while the category is denied.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes from the built-in placeholder.|
|`class`|`string`|none|Class on the wrapper `<div>` that stays in the page in every state.|

## Behavior

`ConsentGate` renders a `<div>` wrapper. Inside it, it renders the children
while the visitor's effective permission for `category` is granted, and the
placeholder otherwise. The permission is the same value as
`getConsentManager().has(category)`. It can be granted before the visitor
chooses, under an opt-out policy, and a recorded grant can be overridden by a
privacy signal such as Global Privacy Control.

* While the category is denied, the children are absent from the DOM, so an
  iframe inside sends no request.
* When the visitor allows the category, the children mount. No reload.
* When the visitor withdraws it, the children unmount and the embed stops.
* Until the component has mounted in the browser, the wrapper is empty. The
  server HTML never contains the children or the placeholder, and the browser
  fills the wrapper one frame after mount.

The built-in placeholder shows `Accept {category} consent to view this content.`
and a button labelled `Enable {category} consent`, with the category's
translated title in place of `{category}`. The copy comes from the
`consentGate.title` and `consentGate.actionButton` translations. The button opens the
preference dialog; it does not grant the category, so mount `ConsentDialog`
in the same provider.

`ConsentGate` does not add its category to the preference dialog. Keep the
category in your policy's scope, and in `consentCategories` if you set that
prop.

## Accessibility

The built-in placeholder is plain text and a `<button>`, so it works without
the embed. Give the iframe a descriptive `title`, and give visitors who
decline another way to the content, such as a link to the video's page or a
store address next to the map. A category the policy blocks cannot be allowed
from preferences.

## Style the placeholder

Set `class` on `ConsentGate` to size the wrapper to the embed, for example an
`aspect-ratio` for a video, so the page does not shift when the embed
replaces the placeholder.

To restyle the built-in placeholder, set the `consentGate` slot for the card,
`consentGateTitle` and `consentGateButton` in the provider's `theme.slots`.
`consentGateButton` applies on top of `buttonPrimary`:

```ts
const theme = {
	slots: {
		consentGate: 'brand-gate',
		consentGateButton: { className: 'brand-gate-button' },
	},
};
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`. For a different design, pass your own
`placeholder` snippet.

# ConsentButton
URL: https://c15t.com/docs/frameworks/svelte/components/consent-button
Accept, reject, save or open preferences from your own Svelte markup with ConsentButton, and what each action records.

## Put consent actions on your own pages

`ConsentButton` is a button that performs one consent action, styled like the
banner's buttons. Use it on a cookie policy page, an onboarding step or
anywhere visitors should accept, reject or open preferences outside the
banner:

```svelte title="src/lib/cookie-choices.svelte"
<script lang="ts">
	import { ConsentButton, ConsentDialog } from '@c15t/svelte';
</script>

<section aria-labelledby="cookie-choices">
	<h2 id="cookie-choices">Cookie choices</h2>
	<ConsentButton action="accept-consent" variant="primary" mode="filled">
		Accept all
	</ConsentButton>
	<ConsentButton action="reject-consent">Reject optional</ConsentButton>
	<ConsentButton action="open-consent-dialog" mode="ghost">
		Choose cookies
	</ConsentButton>
</section>
<ConsentDialog />
```

Render it inside `ConsentProvider`. A button with
`action="open-consent-dialog"` needs a mounted `ConsentDialog`.

## Props

`ConsentButton` also passes any `<button>` attribute through, such as `id`,
`disabled` or `aria-describedby`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`action`|see below|required|What the click does.|
|`category`|`AllConsentNames`|none|The category `set-consent` switches on.|
|`variant`|`'primary'` or `'neutral'`|`'neutral'`|Color emphasis.|
|`mode`|`'filled'`, `'stroke'`, `'lighter'` or `'ghost'`|`'stroke'`|Fill style.|
|`size`|`'medium'`, `'small'`, `'xsmall'` or `'xxsmall'`|`'small'`|Button size.|
|`closeConsentBanner`, `closeConsentDialog`|`boolean`|`false`|Close both surfaces after `dismiss-notice`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs first. Call `event.preventDefault()` to skip the action.|
|`children`|`Snippet`|none|The label.|

|`action`|Effect|
|--|--|
|`accept-consent`|Records every category in scope as allowed.|
|`reject-consent`|Records only `necessary`, rejecting the rest.|
|`custom-consent`|Records the current draft, as the dialog's save button does.|
|`dismiss-notice`|Records that the visitor dismissed a notice. Not a grant.|
|`open-consent-dialog`|Opens the preference dialog.|
|`set-consent`|Switches `category` on in the unsaved draft. Nothing is recorded until a save.|

## Behavior

Accept, reject and save record the choice in the same task as the click, and
the banner or dialog that showed closes. The backend request runs after. A
failed request is reported through the provider's `onError` callback and
retried; the click handler does not throw. A save refused because the policy
changed keeps the dialog open for review.

A button with `open-consent-dialog` starts loading the dialog chunk in idle
time while mounted, and on hover or focus.

## Accessibility

`ConsentButton` renders `<button type="button">` with its children as the
accessible name. Write labels that say what happens: "Accept all" records a
choice, "Choose cookies" opens preferences. Do not label a notice dismissal
"Accept". [Copy and translations](/docs/customization/translations#write-labels-that-describe-the-action)
has more guidance.

## Style the button

The button uses c15t's button classes and the `buttonPrimary` or
`buttonSecondary` theme slot, by `variant`. It carries `data-variant`,
`data-mode` and `data-size` for CSS. With `noStyle`, it renders with only
your `class` and none of those attributes.

# IABConsentBanner
URL: https://c15t.com/docs/frameworks/svelte/components/iab-consent-banner
Show the IAB TCF 2.4 first-layer banner to visitors under an IAB policy in a Svelte app with IABConsentBanner, its props and behavior.

## Show the TCF banner

`IABConsentBanner` is the first layer of the IAB TCF 2.4 consent flow. It
lists the purposes, special features and number of vendors from the Global
Vendor List, and offers Accept All, Reject All and Customize. It renders only
for visitors whose resolved policy uses the `iab` model, so render it next to
the standard `ConsentBanner`, which covers everyone else:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

Turn IAB on with the provider's `iab` prop first; [IAB TCF](../iab) covers the
CMP ID, the vendor list and the provider options.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'accept'`, `'reject'` or `'customize'`|`'customize'`|Which button gets the primary style.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models the banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The banner has no text props. Its copy comes from the IAB translations, in the
visitor's language.

## Behavior

* The banner stays hidden until an IAB policy resolves and the vendor list is
  available. Forcing it does not create either.
* Accept All and Reject All record the visitor's TCF choice and write the TC
  String. The banner closes as soon as the click is handled. It comes back
  only if nothing could be recorded, such as when the vendor list failed to
  load, so the visitor can try again. A failed backend request never reopens
  it.
* Customize opens `IABConsentDialog`, so render it too. The partners link in
  the description opens the dialog on the vendors tab.
* The `__tcfapi` function is available once the TCF add-on loads, whether or
  not the banner is showing, so vendor scripts can read the TC String.

## Accessibility

The banner card is a `region` labelled with the banner title. When focus
trapping is on, through `trapFocus` or a blocking presentation, it becomes a
`dialog` with `aria-modal="true"`. The title is an `h2`, and every control is
a native `<button>`.

## Style the banner

`IABConsentBanner` reads the `iabConsentBanner` theme slot and needs
`@c15t/svelte/iab/styles.css`, loaded after `@c15t/svelte/styles.css`, with
`styles={false}` on the provider.
Buttons carry `data-testid="iab-consent-banner-accept-button"`,
`iab-consent-banner-reject-button` and `iab-consent-banner-customize-button`.

# IABConsentDialog
URL: https://c15t.com/docs/frameworks/svelte/components/iab-consent-dialog
Show the IAB TCF 2.4 preference center with purposes, features and vendors in a Svelte app with IABConsentDialog.

## Show the TCF preference center

`IABConsentDialog` is the IAB TCF 2.4 preference center. It has two tabs:
purposes, with stacks, special features and legitimate interest objections,
and vendors, with each vendor's purposes, data retention and privacy policy.
Render it next to `IABConsentBanner`; the banner's Customize button opens it:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself.|
|`initialTab`|`'purposes'` or `'vendors'`|`'purposes'`|The tab it opens on, for example from a "See our partners" link.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models it opens for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

* It opens when the active surface is `'dialog'` under an IAB policy, the
  same state `ConsentDialog` uses for other policies. Opening preferences
  from `ConsentDialogLink` therefore shows this dialog to IAB visitors and
  `ConsentDialog` to everyone else.
* Switches change purpose consent, legitimate interest, special feature
  opt-ins and vendor consent in the TCF state. Save writes a new TC String.
* It needs the Global Vendor List. While the list loads,
  `getConsentManager().iab.isLoadingGVL` is `true`.

## Accessibility

The preference center is a `dialog` labelled with its title, with a close
button labelled from the `common.close` translation. Escape closes it. While
it is blocking, which is the default, focus stays inside it and the page does
not scroll. The purposes and vendors tabs are keyboard-operable tabs.

## Style the dialog

It needs `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css`, with
`styles={false}` on the provider. The root carries
`data-testid="iab-consent-dialog-root"`.

# Context getters
URL: https://c15t.com/docs/frameworks/svelte/getters
Reference for every @c15t/svelte context getter in a Svelte app, from reading permissions and recorded choices to saving, the draft, IAB state and kernel events.

## Where getters work

Svelte has no consent hooks or stores. `@c15t/svelte` exports context getters
instead. Call one at the top level of a component's `<script>`, inside
`ConsentProvider`, and read its properties in markup or in `$derived`.
The properties read the provider's `$state`, so the component updates when
consent changes.

A getter uses Svelte's `getContext`, so it throws when you call it:

* in an event handler, an effect or a timer,
* in a component rendered outside the provider,
* in a plain `.ts` module.

Call it once at the top level and keep the returned object; its methods work
from event handlers later. The same getters are exported from
`@c15t/svelte/headless`.

|Getter|Returns|Use it to|
|--|--|--|
|`getConsentManager()`|`ConsentManagerState`|Read permissions and choices, and record choices. Start here.|
|`getHeadlessConsent()`|Surface state and actions|Build your own banner. See [headless](./headless).|
|`getIAB()`|`SvelteIABState` or `null`|Read or change IAB TCF consent.|
|`getConsentKernel()`|`ConsentKernel`|Subscribe to raw events or call low-level commands.|
|`getSnapshot()`|`ConsentSnapshot`|Read the full kernel snapshot once.|

## Read a permission or a recorded choice

A permission answers "may this run now?" A recorded choice answers "what did
the visitor decide?" They differ. Under an opt-out policy a category can be
allowed before the visitor chooses anything, and Global Privacy Control can
deny a category the visitor allowed. Load scripts and render optional
features from permissions; use the recorded choice only to show or report
what the visitor decided.

```svelte title="src/lib/consent-status.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	// Call getters at the top level of the component, inside the provider.
	const consent = getConsentManager();

	// A permission: may measurement code run now?
	const measurementAllowed = $derived(consent.has('measurement'));
	// A recorded choice: what did the visitor decide? `null` until they choose.
	const measurementChoice = $derived(
		consent.explicitChoice?.categories.measurement?.value
	);
</script>

<dl>
	<dt>Measurement may run</dt>
	<dd data-testid="measurement-permission">
		{measurementAllowed ? 'Yes' : 'No'}
	</dd>
	<dt>Visitor's measurement choice</dt>
	<dd data-testid="measurement-choice">
		{measurementChoice === undefined
			? 'Not chosen'
			: measurementChoice
				? 'Allowed'
				: 'Denied'}
	</dd>
</dl>
```

Before the visitor chooses, this component shows "No" and "Not chosen".
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

|Property or method|Answers|
|--|--|
|`has(condition)`|Whether a category, or a condition such as `{ and: ['measurement', 'marketing'] }` or `{ or: [...] }`, is allowed now.|
|`effectivePermissions`|Every category's permission, such as `effectivePermissions.measurement`.|
|`explicitChoice`|The visitor's recorded choice, or `null` before they choose. `explicitChoice.categories.measurement.value` is one category's answer.|
|`noticeDismissal`|Whether and when a notice was dismissed. Dismissing a notice is not consent.|
|`privacySignals`|Signals from the browser, such as `privacySignals.gpc.detected`.|
|`restrictions`|Per category, the reasons a recorded grant is overridden, such as GPC.|
|`vendorChoice`, `selectedVendors`|Recorded and draft grants for individual vendors outside IAB.|

## Read the policy and the UI state

|Property|Value|
|--|--|
|`hasPolicy`|`true` once a policy resolved for the visitor. Optional categories stay denied until then.|
|`policyPending`|`true` while the policy request is in flight.|
|`policyRule`|The resolved rule: `model`, `prompt`, `scope`, `rights` and more.|
|`resolution`|The resolution outcome, with `status` of `matched`, `failed` or another state.|
|`model`|`'opt-in'`, `'opt-out'`, `'iab'` or `'none'`.|
|`promptRequirement`|Whether the visitor owes a choice, a notice acknowledgement or nothing.|
|`hasConsentUi`|Whether the policy calls for any consent surface.|
|`hasConsentPreferences`|Whether a way back to preferences should show. `ConsentDialogLink` renders on this.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`location`|The country and region the policy resolved for.|
|`overrides`|The forced country, region, language or GPC value, if any.|
|`consentCategories`, `consentTypes`|The categories the preference UI offers, as names and as full definitions.|
|`translationConfig`, `translations`|The active copy and language.|
|`legalLinks`, `presentation`|The provider's `legalLinks` and `presentation` props.|
|`user`, `subject`|The identified user and the backend's subject for this visitor.|

## Record a choice

Call the methods from event handlers. Save methods return a promise.

```svelte title="src/lib/privacy-controls.svelte"
<script lang="ts">
	import { ConsentDialog, getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();

	// Record one category from your own button. setConsent changes the draft;
	// saveConsents('custom') records it.
	const allowAnalytics = async () => {
		consent.setConsent('measurement', true);
		await consent.saveConsents('custom');
	};
</script>

<button type="button" onclick={() => consent.setActiveUI('dialog')}>
	Privacy settings
</button>
<button type="button" onclick={allowAnalytics}> Allow analytics </button>
<ConsentDialog />
```

Clicking **Allow analytics** records measurement as allowed and leaves the
other categories as they were. **Privacy settings** opens the dialog.

|Method|Effect|
|--|--|
|`setActiveUI(surface)`|`'dialog'` opens preferences, `'banner'` shows the banner, `'none'` closes the open surface. Closing preferences brings the banner back while the policy still owes a choice. Records nothing.|
|`setConsent(category, value)`|Changes one category in the unsaved draft. `setSelectedConsent` is the same method.|
|`setSelectedVendor(vendorId, granted)`|Changes one vendor in the draft. Ignored for undeclared or disabled vendors.|
|`saveConsents('custom')`|Records the draft. Throws when the policy changed since the draft started; see [the draft](#work-with-the-draft).|
|`saveConsents('all')`|Records every category in scope as allowed.|
|`saveConsents('necessary')`|Records only `necessary`, rejecting the rest.|
|`dismissNotice()`|Records that the visitor dismissed a notice. Only works while a notice is due.|
|`setLanguage(code)`|Switches the language and resolves the policy again for it.|
|`getDisplayedConsents()`|The categories to render in your own preference UI.|
|`getDisplayedVendors(category)`|The vendors to list under one category. Empty under an IAB policy.|
|`isVendorAllowed(vendorId)`|`true` while a declared vendor's category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`subscribeToConsentChanges(listener)`|Calls `listener` with the permissions after every snapshot change. Returns an unsubscribe function.|

A save updates permissions in the same task, so registered scripts and
`ConsentGate` react before the backend request finishes. A failed request is
kept and retried; it does not undo the choice, and the provider's `onError`
callback reports it. When a save withdraws a category that was granted, the
provider reloads the page by default so code that already ran is gone. Set
`reloadOnConsentRevoked={false}` on the provider to handle that yourself.

Only call save methods from a visitor's action. Saving on page load records a
choice the visitor never made.

## Work with the draft

`consent.draft` is the unsaved state every preference surface on the page
shares: the dialog, `ConsentWidget` and your own UI.

|Member|Behavior|
|--|--|
|`values`|Each category's draft value. Starts from the recorded choice, or from the policy's defaults before a choice. A choice saved elsewhere moves the values the visitor has not touched. Categories outside `consentCategories` read `false`. `selectedConsents` is the same object.|
|`vendors`|Each declared vendor's draft grant.|
|`isStale`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change. A draft with no unsaved change follows the policy and is never stale.|
|`set(category, value)`, `setVendor(id, granted)`|The same as `setConsent` and `setSelectedVendor`.|
|`reset()`|Discards unsaved changes.|

The draft's code loads with the first preference surface, so a page that
only shows the banner does not ship it. `ConsentWidget` and `ConsentDialog`
bring it with them, and their switches render seeded on the first render,
on the server too. Headless code that reads or writes the draft without
either one starts the load itself: until it lands, `values` and `vendors`
are empty objects and `isStale` is `false`, and they update reactively once
it does. Writes made before then apply in order, `draft.reset()` drops
them, and `saveConsents('custom')` waits for the draft before it records.

When `isStale` is `true`, `saveConsents('custom')` throws "The policy changed.
Review your preferences before saving." Show the visitor the current
categories, call `draft.reset()`, and let them save again.

## Read and change IAB TCF consent

`getConsentManager().iab` is the live IAB state, or `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it; read `.iab` on
the manager for values that update.

|Member|Value or effect|
|--|--|
|`config.enabled`, `config.cmpId`|Whether the add-on is on, and the CMP ID.|
|`gvl`, `isLoadingGVL`|The Global Vendor List, and whether it is still loading.|
|`purposeConsents`, `vendorConsents`, `specialFeatureOptIns`|The visitor's TCF choices, staged or saved.|
|`tcString`|The saved TC String, or `null`.|
|`nonIABVendors`|Custom vendors outside the IAB list.|
|`acceptAll()`, `rejectAll()`|Accept All sets vendor and purpose consent for declared consent purposes, separate vendor and purpose legitimate-interest signals for declared legitimate-interest purposes, and opt-ins for declared special features. Reject All clears these signals.|
|`setPurposeConsent(id, value)`, `setPurposeLegitimateInterest(id, value)`|Change one purpose.|
|`setVendorConsent(id, value)`, `setVendorLegitimateInterest(id, value)`|Change one vendor.|
|`setSpecialFeatureOptIn(id, value)`|Change one special feature.|
|`save()`|Writes the TC String and records the choice.|
|`preferenceCenterTab`, `setPreferenceCenterTab(tab)`|The tab `IABConsentDialog` shows.|

Until the TCF add-on finishes loading, the action methods queue and replay.
See [IAB TCF](./iab) for setup.

## Listen to consent events

`getConsentKernel()` returns the consent kernel behind the provider. Its
`events.on(type, listener)` subscribes to one event and returns an
unsubscribe function. Subscribe in `$effect` so Svelte removes the listener
when the component unmounts:

```svelte title="src/lib/consent-events.svelte"
<script lang="ts">
	import { getConsentKernel } from '@c15t/svelte';

	// Read the kernel at the top level; subscribe in an effect so the
	// listener is removed when the component unmounts.
	const kernel = getConsentKernel();
	let lastRecorded = $state<string | null>(null);

	$effect(() =>
		kernel.events.on('choice:recorded', ({ snapshot }) => {
			const { measurement } = snapshot.effectivePermissions;
			lastRecorded = measurement ? 'measurement allowed' : 'measurement denied';
		})
	);
</script>

<p data-testid="last-recorded">
	{lastRecorded ?? 'No choice recorded on this page yet'}
</p>
```

`choice:recorded` fires for an explicit accept, reject or save.
`permissions:changed` fires for any change to what may run. For callbacks that
cover the whole app, use the provider's `callbacks` prop instead; see
[callbacks](./callbacks).

The kernel also has `subscribe(listener)`, which runs on every snapshot
change, `getSnapshot()`, and `commands` for `init()`, `save()`,
`dismissNotice()` and `identify()`. Prefer the manager's methods; they keep
the draft and the open surface in step, which the raw commands do not.
`getSnapshot()` from `@c15t/svelte` returns the snapshot at the moment you
call it and does not update.

## Other exports

|Export|Purpose|
|--|--|
|`manifest()`|The `mode` that resolves the policy in the browser from the manifest `consentManifest()` downloaded.|
|`hosted({ backendURL })`|The `mode` that asks an Inth or self-hosted backend's `/init` for every visitor.|
|`offline({ policyRules })`|The `mode` that resolves policies in the browser with no backend. Not recommended for production environments.|
|`custom(transport)`|The `mode` for your own transport.|
|`createConsentRuntime(options)`|Creates a runtime to share between providers, through their `runtime` prop.|
|`resolveConsentPresentation(input)`|Resolves the banner or dialog shape and actions a policy asks for, as `getHeadlessConsent()` does.|
|`defaultTranslationConfig`, `mergeTranslationConfigs`, `prepareTranslationConfig`, `detectBrowserLanguage`|Translation helpers.|

# Callbacks
URL: https://c15t.com/docs/frameworks/svelte/callbacks
Run your own code in a Svelte app when a visitor records a choice or permissions change, with onChoiceRecorded, onPermissionsChanged and script callbacks.

## Pick the right callback

Run your own code when consent changes through the provider's `callbacks`
prop, a script's own callbacks, or a kernel event in one component:

|You want to|Use|
|--|--|
|Send a choice to your analytics or CRM when the visitor makes one|`callbacks.onChoiceRecorded`|
|Start or stop your own code when what may run changes|`callbacks.onPermissionsChanged`|
|Report failed backend requests|`callbacks.onError`|
|Show a message or flush data before a withdrawal reloads the page|`callbacks.onBeforeConsentRevocationReload`|
|Call a vendor's own consent API after its script loads|The script's `onConsentChange`|
|React to consent inside one component|`getConsentKernel().events.on()` or the manager's properties|

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only when the visitor accepts, rejects or saves.
`onPermissionsChanged` runs whenever effective permissions change, whatever
the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|Policy resolves under opt-out and allows categories before a choice|No|Yes|
|Global Privacy Control overrides a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent records and audit trails, because it fires
only for a visitor's action. Use `onPermissionsChanged` to start or stop code,
because it covers every way a permission changes. Never treat
`onPermissionsChanged` as proof that the visitor agreed to something.

## Pass callbacks to the provider

```ts title="src/lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from '@c15t/svelte';

// Pass as `callbacks={callbacks}` on ConsentProvider.
export const callbacks: ConsentProviderCallbacks = {
	// Runs just before c15t reloads the page after a withdrawal.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// An explicit accept, reject or save. Never runs for defaults, expiry,
	// policy changes or privacy signals.
	onChoiceRecorded: ({ snapshot, confirmed }) => {
		console.info('Visitor chose', snapshot.explicitChoice, confirmed);
	},
	// A failed command, such as an /init request that could not reach the
	// backend.
	onError: ({ error }) => {
		console.warn('c15t error', error);
	},
	// Any change to what may run, whatever caused it.
	onPermissionsChanged: ({ snapshot, previous }) => {
		console.info('Permissions', previous, '->', snapshot.effectivePermissions);
	},
};
```

Pass the object as `callbacks={callbacks}` on `ConsentProvider`. The
provider reads it once, when it is created. Keep the functions in a module or
in the component that renders the provider; on SvelteKit, not in a server
load, because a load cannot send functions to the browser.

|Callback|Payload|
|--|--|
|`onChoiceRecorded`|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time.|
|`onPermissionsChanged`|`snapshot`, the state after the change; `previous`, the permissions before it.|
|`onError`|`error`, a message string.|
|`onBeforeConsentRevocationReload`|`preferences`, the permissions after the withdrawal.|

Callbacks run after c15t updates its own state, so `snapshot` and
`getConsentManager()` already hold the new values. Visitor actions happen in
the browser, so in practice that is where the callbacks run.

`onBeforeConsentRevocationReload` runs synchronously right before the reload.
Keep it short; the page is about to unload. It does not run when you set
`reloadOnConsentRevoked={false}`.

## Script callbacks

Each entry in `scripts` takes its own callbacks:

|Callback|Runs|
|--|--|
|`onBeforeLoad`|Before the loader adds the script.|
|`onLoad`|When the script loaded.|
|`onError`|When the script failed to load.|
|`onConsentChange`|When consent changes after the script loaded. Use it to call the vendor's own consent API.|
|`onDispose`|When the configuration is removed or the provider unmounts.|

Helpers from `@c15t/integrations` already set these for their vendor.
[Building integrations](/docs/integrations/building-integrations) shows how to
write them.

## Listen inside one component

For a component that shows or reacts to consent, subscribe to a kernel event
in `$effect`, so the listener goes away with the component. The
[context getters](./getters#listen-to-consent-events) page has the example.
For values you render, read the manager's properties instead; they update the
component without a listener.

## Verify the callbacks

Open the console, clear site data and reload:

1. Accept in the banner. `onChoiceRecorded` and `onPermissionsChanged` both
   log.
2. Dismiss a notice, if your policy shows one. Neither logs.
3. Withdraw a category you allowed. `onBeforeConsentRevocationReload` logs,
   then the page reloads.

# IAB TCF
URL: https://c15t.com/docs/frameworks/svelte/iab
Turn on the IAB TCF 2.4 banner and preference center in a Svelte app with IABConsentBanner, IABConsentDialog and the provider's iab option.

## Before you turn on IAB TCF

Use IAB TCF when your ad partners require a TC String. It needs an IAB policy
in your Inth project and a CMP ID. IAB Europe assigns a CMP ID to a company
when it registers as a CMP
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your visitors' consent to someone else. Example CMP IDs in c15t demos are not
production configuration.

`@c15t/svelte` loads the TCF add-on from `@c15t/iab`, which it installs as a
dependency. The add-on is a separate chunk that apps without IAB never
download.

## Add the IAB components

Turn IAB on with the provider's `iab` prop, keeping your existing mode or `state`,
`scripts` and other props. `registeredCmpId` stands for the number IAB Europe
assigned to your company. The standard and IAB components add their styles
automatically:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} iab={{ cmpId: registeredCmpId }}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} iab={{ cmpId: registeredCmpId }}>
```

Then render `IABConsentBanner` and `IABConsentDialog` next to the standard
components.
The standard components cover visitors whose policy is not IAB, such as those
outside Europe:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

The IAB banner adds its first-paint rules before its elements render. The
IAB dialog adds its rules when it opens, including the base rules it needs
when rendered without a banner. Each sheet appears once per page. On a
server-rendered SvelteKit page, `c15tHandle` writes the rendered components'
rules into `<head>` before hydration.

To run the CSS through Tailwind CSS 3 or put it in a named cascade layer,
set `styles={false}` on the provider and import
`@c15t/svelte/styles.css` followed by `@c15t/svelte/iab/styles.css`.
[Stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when to use that option.

|`iab` option|Purpose|
|--|--|
|`cmpId`|Your registered CMP ID. A hosted backend can supply it instead.|
|`vendors`|Limit the Global Vendor List to these vendor IDs.|
|`customVendors`|Vendors outside the IAB list, with their purposes and data use.|
|`publisherRestrictions`|Override how vendors may use a purpose. See below.|
|`publisherCountryCode`|Your country, written into the TC String.|
|`gvl`, `gvlURL`|Supply the vendor list, or change where it is fetched from.|
|`enabled`|`false` keeps the configuration but leaves the add-on unmounted.|

Pass `iab={false}`, or omit it, to leave IAB off. If a visitor's policy
then uses the `iab` model and the backend sends its vendor list, the
provider throws an `IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`) while
rendering, on the server and in the browser: the standard banner does not
handle the IAB model, so the visitor would otherwise get no working consent
UI. Set `iab`, or remove the `iab` model from the policy. A backend that
answers `gvl: null` turns IAB off for the request, and the policy runs as
opt-in.

[IABConsentBanner](./components/iab-consent-banner) and
[IABConsentDialog](./components/iab-consent-dialog) list each component's
props.

`IABConsentBanner` and `IABConsentDialog` stay hidden until an IAB policy resolves for the visitor. Forcing the
dialog open does not create a policy or a vendor list, so check the policy
resolution and the vendor list request before changing how they render.

## Read the TCF state

`getConsentManager().iab` holds the live IAB state: the vendor list, purpose
and vendor consents, `isLoadingGVL`, and the actions `acceptAll()`,
`rejectAll()`, `setPurposeConsent()`, `setVendorConsent()`,
`setSpecialFeatureOptIn()` and `save()`. It is `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it.
[Context getters](./getters#read-and-change-iab-tcf-consent) lists every
member.

For a custom IAB banner, `@c15t/svelte/headless` exports
`getIABBannerDisplayItems`, `processGVLData` and `getIABTranslations`.

## Restrict how vendors use a purpose

Pass publisher restrictions in the provider's `iab` option as
`publisherRestrictions`, for example
`[{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] }]` to stop vendors
10 and 755 using purpose 4. Use vendors from your own list whose declarations
allow each restriction.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Verify the TCF flow

Accept, reject and save purpose and vendor choices, then check in the console
that `__tcfapi('getTCData', 2, console.log)` returns a TC String that matches
what you chose. Reload and confirm it persists. Check the vendors' actual
requests too; a category banner test does not show that the IAB flow works.

# IAB GPP
URL: https://c15t.com/docs/frameworks/svelte/gpp
Expose the IAB Global Privacy Platform API (__gpp) from a Svelte app with the provider's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

The provider's `gpp` option installs `window.__gpp`, the GPP 1.1 CMP API, and
keeps its GPP string in step with the visitor's choices. Prebid.js, Google Ad
Manager and other ad tech read US privacy signals from it.

## Turn on GPP

Add `gpp` to the provider in `src/App.svelte`, keeping your existing `mode`,
`scripts` and other props:

```svelte title="src/App.svelte"
<ConsentProvider mode={manifest()} {scripts} gpp>
```

`gpp` on its own uses the defaults. Pass an object to change them, such as
`gpp={{ usFallback: 'none' }}`; the options are listed below. Omit `gpp`, or
pass `gpp={false}`, to leave it off.

`@c15t/svelte` loads the GPP code from `@c15t/iab/gpp`, which it installs as a
dependency. It is a separate chunk that apps without `gpp` never download.
The provider installs `__gpp` once that chunk arrives and removes it when the
provider unmounts.

The US section follows the policy and location your Inth project resolves for
the visitor. With `offline()` mode, pass the location yourself, for example
`overrides={{ country: 'US', region: 'CA' }}`.

The TCF EU section needs IAB TCF as well. Set it up with
[IAB TCF](/docs/frameworks/svelte/iab).

If you pass your own `runtime` to the provider, the provider does not add GPP.
Set `gpp` and `loadGPP: () => import('@c15t/iab/gpp')` in that runtime's
`createConsentRuntime()` call instead.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/svelte/content-security-policy
Write a Content Security Policy for a Svelte app using c15t, with the hosts to allow, the provider's nonce option and what c15t injects.

## Set the policy where you host the app

A Svelte app built with Vite has no server of its own, so the policy comes
from your host or CDN as a `Content-Security-Policy` header, or from a
`<meta http-equiv="Content-Security-Policy">` tag in `index.html`. Test it
against `vite build` and `vite preview`. The dev server injects CSS through
`<style>` elements, so a strict policy breaks `vite dev` even when production
works.

A static host serves the same file to everyone and cannot put a fresh nonce
in each response, so allow each vendor's script host in `script-src` instead
of relying on the provider's `nonce`.

In a Svelte app without server rendering, Svelte sets every `style` value
through the DOM, which a policy does not block, so c15t needs no
`'unsafe-inline'` for style attributes.

c15t's components add their rules to `<head>` as `<style>` elements, and a
`style-src` without `'unsafe-inline'` blocks those. A static host has no
nonce to give the provider, so set `styles={false}` on
`ConsentProvider` and import `@c15t/svelte/styles.css` from your
entry module. `'self'` covers that stylesheet.

## What c15t adds to the page

A Content Security Policy has to allow each thing c15t or your vendors put on
the page:

|c15t does|Directive|Allow|
|--|--|--|
|Requests the policy from `/init` and saves choices to `/subjects`|`connect-src`|Your backend's origin. `'self'` covers a same-origin route such as `/api/c15t`.|
|Adds a `<script>` element for each allowed entry in `scripts`|`script-src`|Each vendor's script host, or the provider's `nonce`.|
|Lets vendor scripts load more scripts, pixels and requests|`script-src`, `img-src`, `connect-src`|The hosts each vendor documents.|
|Sets `src` on gated iframes, or mounts `ConsentGate` children|`frame-src`|Each embed's host, such as `https://www.youtube-nocookie.com`.|
|Adds its rules to `<head>` as `<style>` elements|`style-src`|The provider's `nonce`. With `styles={false}` and an imported `@c15t/svelte/styles.css`, `'self'`.|
|Fetches the Global Vendor List under an IAB policy|`connect-src`|The vendor list host the policy names, when it is not your own origin.|

The dev tools panel attaches a stylesheet to its shadow root. Keep the panel
out of production builds, as its page describes, and a production policy
does not need to allow it.

## Stamp a nonce on vendor scripts

If your server creates a nonce for each response and puts it in the
`Content-Security-Policy` header as `'nonce-<value>'`, pass the same value to
the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} nonce={cspNonce}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} nonce={cspNonce}>
```

The script loader then sets that nonce on every `<script>` it adds, for both
`src` and inline `textContent` scripts. A `nonce` on one `scripts` entry wins
for that script. The components put it on the `<style>` elements they add.
The provider reads `nonce` once, when it is created.

The nonce covers only the elements c15t creates. A script that a vendor's
script loads by itself does not get it; allow that host in `script-src`, or
add `'strict-dynamic'` so scripts loaded by a trusted script are trusted too.
With `'strict-dynamic'`, browsers ignore host allowlists in `script-src`, so
every script on the page needs the nonce or a hash.

## Verify the policy

Enforce the policy, not report-only, and open the console with site data
cleared:

1. The banner renders with its styles, and no `Refused to` message mentions a
   c15t element, a `<style data-c15t-styles>` element or
   `@c15t/svelte/styles.css`. Open the preference dialog and check again.
2. Allow a category. Its vendor scripts load, and none are refused. A refused
   script from a vendor's own host means that host is missing from
   `script-src`.
3. Save a choice. The request to `/subjects` succeeds; a `connect-src`
   violation means the backend's origin is missing.
4. Allow the category of a gated embed. It loads; a `frame-src` violation
   names the host to add.

# DevTools
URL: https://c15t.com/docs/frameworks/svelte/components/dev-tools
Inspect consent, scripts, location and events in a Svelte app with ConsentDevTools from @c15t/svelte/devtools, loaded only in development.

## Add the panel in development

Render `ConsentDevTools` inside `ConsentProvider`, and load it only in
development. Vite sets `import.meta.env.DEV` to `true` in `vite dev` and to
`false` in a production build, which then drops the import:

```svelte title="src/lib/ConsentDevTools.svelte"
<script lang="ts">
	const devTools = import.meta.env.DEV ? import('@c15t/svelte/devtools') : null;
</script>

{#if devTools}
	{#await devTools then { ConsentDevTools }}
		<ConsentDevTools />
	{/await}
{/if}
```

Render `<ConsentDevTools />` from that file anywhere inside the provider. The
export is also available as `DevTools` and `C15TDevTools`.

## What the panel shows

The panel is a floating inspector for the provider's consent runtime. Its
tabs:

|Tab|Shows|
|--|--|
|`consents`|Effective permissions and the recorded choice per category, with switches to stage and save a test choice.|
|`scripts`|Each registered script and its loading state.|
|`location`|The country, region and language the policy resolved for, with overrides to test another location.|
|`policy`|The resolved policy rule, its model, prompt, scope and rights.|
|`iab`|The TCF state, when IAB is on.|
|`events`|The consent runtime's events and script lifecycle events.|
|`actions`|Buttons to open the banner or dialog, reset the draft, clear stored records and resolve the policy again.|

Clearing records from the panel deletes the stored choice through the
provider's storage settings, so a custom `storageConfig` is respected.
Location overrides from the panel change the current page only.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|Corner of the panel's toggle.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|one of the tabs above|`'consents'`|The tab it opens on.|
|`maxEvents`|`number`|`100`|How many events the `events` tab keeps.|
|`getConsentCategories`|`() => AllConsentNames[]`|the provider's categories|Categories the `consents` tab lists.|
|`getPresentation`|`() => ConsentPresentation`|the provider's `presentation`|Presentation used for the panel's diagnostics.|
|`clearRecords`|`() => void`|the provider's own|Replaces what the clear action does.|
|`shadow`|`boolean`|`true`|`false` mounts the panel without a shadow root.|

By default the panel renders inside a shadow root with its own stylesheet,
so your CSS does not restyle it and its CSS does not leak into the page.
`shadow={false}` mounts the panel in the light DOM instead and puts its
stylesheet in `<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar with
a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end of the
toolbar farthest from its corner. The panel opens just past the toolbar,
aligned with its outer edge, and follows it when a visitor drags the toolbar
to another corner. `position` applies again once no trigger is visible. The
trigger that `ConsentDialog`'s `showTrigger` prop renders behaves the same
way.

DevTools brings its launcher back whenever no trigger is visible, for example
with `showWhen="never"` or while the dialog is open. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

## Keep it out of production

The panel can clear consent and change the location the policy resolves for.
Render it in development only. Importing `@c15t/svelte/devtools` statically
puts the panel in every bundle that imports the file, so import it
dynamically behind a development check, as the example above does.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/svelte/troubleshooting
Fix a Vite build that cannot fetch the c15t manifest, a missing bundled policy, a missing banner, a wrong backend URL, ignored theme colors and vendors that load before consent in a Svelte app.

## The build or dev server fails fetching the manifest

**Check.** `vite build` and `vite dev` download the policy through the
`consentManifest` plugin in `vite.config.ts`. `vite build` stops with an
error that starts with `@c15t/svelte/vite: could not fetch the consent manifest`, and `vite dev` logs it as a warning. The part in parentheses names
the cause:

|Error|Cause|
|--|--|
|`/manifest responded 404`|The backend URL is wrong, or still the `https://your-project.inth.app` placeholder.|
|`no backend URL is set`|Neither the `backendURL` option nor `VITE_C15T_BACKEND_URL` (or `VITE_INTH_PROJECT_URL`) is set, or it is empty. `vite build` stops; `vite dev` warns.|
|`skipped the consent manifest fetch` (a notice)|The backend URL is relative. With `onBuildError: 'fail'`, this is the error `build-time manifests require an absolute upstream URL`.|
|`/manifest returned an invalid consent manifest.`|The URL answers, but not with a c15t v3 manifest.|
|`fetch failed` or `no response within 10 seconds`|The machine running the command cannot reach the backend.|

**Fix.** Set `VITE_C15T_BACKEND_URL` (or `VITE_INTH_PROJECT_URL`) to your
project's absolute backend URL where the command runs, in `.env` or the CI environment, and make sure that
machine can reach the backend. To deploy while it is down, build with
`C15T_ON_BUILD_ERROR=runtime`.

## The browser fetches the manifest at runtime

**Check.** With `manifest()`, the browser requests `<backendURL>/manifest` on
page load instead of resolving from a bundled policy. The build had no policy
to bundle: `consentManifest` is missing from `plugins` in `vite.config.ts`,
the fetch failed in `vite dev` or in a build with
`C15T_ON_BUILD_ERROR=runtime`, or the backend URL is relative. Without the
plugin and without a `backendURL` option, `manifest()` has no backend URL at
all and throws when it runs.

**Fix.** Add the plugin or fix the cause from the
[fetch errors](#the-build-or-dev-server-fails-fetching-the-manifest), then
restart `vite dev` or rebuild. A build fetches once, and `vite dev` fetches
the first time the app loads the policy.

## Consent requests go to the wrong backend

**Check.** Look at `VITE_C15T_BACKEND_URL` and `VITE_INTH_PROJECT_URL` in
`.env`, `.env.local` and the build environment, and at any `backendURL` in `vite.config.ts` or
`src/App.svelte`. One still has the demo project, the placeholder
`https://your-project.inth.app`, or a URL from another project. Vite writes
`VITE_C15T_BACKEND_URL` into the bundle at build time, so changing it later
does nothing until you rebuild.

**Fix.** Set `VITE_C15T_BACKEND_URL` (or `VITE_INTH_PROJECT_URL`) to your
Inth project's backend URL, including any path prefix, and rebuild. The project must also list your app's
origin as trusted.

## The banner appears after the page

**Check.** In a Svelte app without a server, the browser resolves the policy
after the page loads, then shows the banner. That is expected. Optional
categories stay denied until the policy resolves.

**Fix.** For a banner in the first HTML, the page has to be server-rendered;
SvelteKit does that. See [choose your setup](/docs/concepts/choose-your-setup).

## Why is there no banner?

**Check.** Read `getConsentManager().policyRule.prompt` and `.location`, or open
DevTools. In the Network panel, find the `/init` request.

**Fix.** Work through these causes in order:

1. **The policy asks for no prompt.** Visitors in regions without a consent
   law, and opt-out policies with no prompt, get no banner. See
   [why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).
2. **A choice is already stored.** Clear site data for your origin, or use the
   DevTools panel, and reload.
3. **The backend request failed.** A CORS error means your site's origin is
   not in the Inth project's trusted origins. A 404 means the backend URL is
   wrong. While the request fails, optional categories stay denied and no
   banner shows.
4. **The component is outside the provider.** `ConsentBanner` must render
   inside `ConsentProvider`; outside it, Svelte throws
   `c15t: no v3 consent context`.

## Svelte throws "no v3 consent context"

**Check.** A getter or component ran without a `ConsentProvider` above
it.

**Fix.** Move it inside the provider.

**Check.** Look for a getter called in an event handler or effect. Getters use
Svelte's `getContext`.

**Fix.** Call getters at the top level of a component's `<script>`.

**Check.** If the provider is there, check that the app resolves one copy of
`@c15t/svelte`. Two copies create two separate contexts.

**Fix.** Make the app resolve a single copy of `@c15t/svelte`.

## Theme colors are ignored

**Check.** The provider's `theme` prop applies slot styles and `consentActions`
only. Colors, radius, typography and other tokens in `theme` are not turned
into CSS in the browser, and in development the provider logs a warning about
it.

**Fix.** Set the `--c15t-*` variables on `:root` in a stylesheet, or render
`generateThemeCSS()` output as `<style id="c15t-theme">`. The customize page
shows both.

**Check.** If your values still lose, inspect the element. A generated theme
uses `:root:root`, so it beats your own `:root` rule.

**Fix.** Write your rule on `:root:root` too, or move the value into the theme.

## The dialog or banner has no styles

**Check.** Look in `<head>` for `<style data-c15t-styles>` elements, and in
the console for a Content Security Policy error. On a server-rendered
SvelteKit page, check that `src/hooks.server.ts` exports `c15tHandle`.

**Fix.**

* No c15t `<style>` element: the provider sets `styles={false}` or
  `noStyle`. With `styles={false}`, import `@c15t/svelte/styles.css` once,
  in the component that renders the provider or in your global stylesheet.
* The SvelteKit banner is unstyled until hydration: add `c15tHandle` from
  `@c15t/svelte/kit` to `src/hooks.server.ts`, or set `styles={false}` and
  import `@c15t/svelte/styles.css`.
* The console reports a blocked inline style: pass the provider a `nonce`, or
  set `styles={false}` and import the stylesheet. The Content Security Policy
  page covers both.
* IAB TCF surfaces are unstyled with automatic styles disabled: import
  `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css` together. With
  automatic styles enabled, check the policy and IAB configuration, the
  provider's `noStyle` option, and CSP errors.

## A vendor loads before consent, or twice

**Check.** The vendor is still loaded some other way: a `<script>` tag in
`index.html` or `app.html`, a tag manager, or an SDK import in your code. Check
the Network panel with site data cleared; nothing from the vendor should load
before you allow its category.

**Fix.** Remove the other loader and keep only the `scripts` registration.

## The page reloads after saving

**Check.** When a save withdraws a category that was granted, the provider
reloads the page so code that already ran is gone. This is expected.

**Fix.** Set `reloadOnConsentRevoked: false` on the provider only if every
registered vendor stops itself through its consent API.

## Names from an earlier alpha are missing

**Check.** An import from an earlier v3 alpha fails, such as
`ConsentManagerProvider`, `Frame` or `consentManifest({ outputFile })`.
`@c15t/svelte` was not public in v2, so the alphas renamed these with no
alias.

**Fix.** Use the current names:

|Removed|Use instead|
|--|--|
|`ConsentManagerProvider`|`ConsentProvider`|
|`Frame`|`ConsentGate`|
|`hosted({ url })`|`hosted()` with `VITE_C15T_BACKEND_URL`, or `hosted({ backendURL })`|
|`ConsentManifestOptions`, `consentManifest({ outputFile })`|Removed. `consentManifest()` serves the snapshot as `c15t/generated`.|

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI. [Verify
consent](/docs/guides/verify-consent) lists the checks to run before release.

# Quickstart
URL: https://c15t.com/docs/frameworks/sveltekit/quickstart
Bundle your c15t policy into a SvelteKit server at build time, resolve consent in the root layout load so the banner is in the server HTML, then hydrate ConsentRoot with consent-gated scripts and a preferences link.

## Before you start

This guide sets up a server-rendered SvelteKit app. The root layout's server
`load` resolves each visitor's consent before the page renders, so the banner
is part of the first HTML and a returning visitor's choice applies from the
first paint. For prerendered pages, a static site or SPA mode, follow this
guide and then [rendering and deployment](/docs/frameworks/sveltekit/rendering).
The `examples/sveltekit` app in the c15t repository is the finished result.

`@c15t/svelte` supports SvelteKit 2.63 and later, including SvelteKit 3,
with Svelte 5. The examples use SvelteKit 3. On SvelteKit 2, keep the adapter
in `svelte.config.js` instead of passing it to `sveltekit()`.

The guide uses [Inth](https://inth.com) for policies and consent records.
Create an Inth project, then:

1. Set its policy rules, including the `measurement` category for the
   vendor below.
2. Add your app's origin, such as `http://localhost:5173`, to its trusted
   origins.
3. Copy the project's backend URL. The build downloads the policy from it and
   the browser saves choices to it.

A self-hosted backend works the same way with your own URL; see
[self-hosting](/docs/self-host/overview).

The setup bundles your policy into the server at build time, the recommended
production setup. Rebuild after changing policies, translations or vendors.

## Install

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/svelte@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/svelte@alpha @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/svelte@alpha @c15t/integrations@alpha`|
|bun|`bun add @c15t/svelte@alpha @c15t/integrations@alpha`|

SvelteKit uses `@c15t/svelte`: components from `@c15t/svelte`, server
helpers from `@c15t/svelte/kit` and the Vite plugin from `@c15t/svelte/vite`.
The `c15t` package has no Svelte entry point, so you don't install it.

## Set the backend URL

Set `PUBLIC_C15T_BACKEND_URL` to your project's backend URL, including any
path prefix, in `.env` or your host's build environment:

```sh title=".env"
PUBLIC_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `PUBLIC_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `PUBLIC_C15T_BACKEND_URL` wins.

The example app's `.env` points at `https://example-inth.inth.app`, a demo
project. The build reads the variable, and the server and the browser use the
value the build read, so rebuild after you change it.

## Bundle the policy at build time

Add `consentManifest` to the plugins in `vite.config.ts`:

```ts title="vite.config.ts"
import { consentManifest } from '@c15t/svelte/vite';
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), sveltekit({ adapter: adapter() })],
});
```

`consentManifest` downloads your project's public policy from
`<backendURL>/manifest` during `vite build`, and in `vite dev` the first time
the server loads it. The policy stays on the server:
the browser bundle never gets it. No file is written into your project. In a
build, the plugin also lets `c15tHandle`, added below, preload the script
loader on pages that register scripts.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, fetch the policy at runtime instead;
see [fetch the manifest at runtime](/docs/frameworks/sveltekit/rendering#fetch-the-manifest-at-runtime).

## Add the server hook

`c15tHandle` holds the consent config and reads the consent cookie, location
headers and Global Privacy Control once per request. It stores them on
`event.locals.c15t` for `loadConsent` and any other load or endpoint that
needs them. It also writes a server-rendered banner's rules into the HTML
`<head>` as `<style>` elements, so the banner is styled before hydration
without a stylesheet request. Add it to `src/hooks.server.ts`:

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle();
```

With no options, the mode is `manifest()`: the server resolves each visitor
from the bundled policy. [Rendering and deployment](/docs/frameworks/sveltekit/rendering)
covers `hosted()`, `offline()` and the other options.

Type `event.locals.c15t` with one line in `src/app.d.ts`:

```ts title="src/app.d.ts"
/// <reference types="@c15t/svelte/kit/locals" />
```

## Resolve consent in the root layout load

Export `loadConsent` as the root layout's server load:

```ts title="src/routes/+layout.server.ts"
export { loadConsent as load } from '@c15t/svelte/kit';
```

`loadConsent` resolves the visitor's policy from the bundled snapshot with
the inputs `c15tHandle` read, and returns `{ consent }`, a plain,
serializable object for `ConsentRoot`. Rendering a page makes no policy
request to the backend. `loadConsent` never throws. If resolution takes
longer than 500 ms, it returns the stored choice without a policy, and the
browser resolves the policy after hydration.

While SvelteKit prerenders pages at build time, `loadConsent` returns no
visitor's consent and no policy, because a prerendered page goes to every
visitor. It reads SvelteKit's `building` flag itself.
[Prerender some pages](/docs/frameworks/sveltekit/rendering#prerender-some-pages)
covers how the browser resolves consent there.

## Render ConsentRoot in the root layout

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

Pass `data.consent` through unchanged. `ConsentRoot` starts from it, so the
server and the browser render the same banner and the browser makes no second
request for the policy. A page the server resolved ships no resolver, policy
rules or snapshot to the browser.

PostHog waits for measurement permission. Replace `phc_your_project_key`
with your PostHog project key. Remove any `<script>` tags in `src/app.html` or
SDK imports that already load PostHog, so c15t is the only thing that loads
it. Create `scripts` in the layout component, not in `+layout.server.ts`:
they hold functions, which a server load cannot send to the browser.

`ConsentBanner` shows the banner when the policy asks for one.
`ConsentDialog` is the preference dialog; it loads in its own chunk after the
page, before anyone opens it. `ConsentDialogLink` is the persistent way back to
preferences. Put it where visitors look for privacy settings, such as the
footer. There is no stylesheet to import: the components bring their own
rules, and the server hook writes the banner's into the HTML.

Keep `ConsentRoot` in the root layout so it stays mounted across client-side
navigation.

## Verify consent

Build the app with `vite build` and serve the production build with
`vite preview`, then open it in a private window with DevTools open:

1. View the page source. It contains `data-testid="consent-banner-root"`, so
   the banner is in the server HTML, and `<head>` holds a
   `<style data-c15t-styles>` element with its rules.
2. In the Network panel, no requests go to PostHog.
3. Select **Reject All** and reload. The page source no longer contains the
   banner, and PostHog requests stay absent.
4. Select **Privacy settings**, turn on **Analytics** (the `measurement`
   category) and save. PostHog loads.
5. Turn it off and save. The page reloads and PostHog does not load.
6. Navigate to another route and back. The choice holds without a new banner.

If the build fails or the banner is missing from the page source, see
[troubleshooting](/docs/frameworks/sveltekit/troubleshooting).
[Verify consent](/docs/guides/verify-consent) has the release checklist.

## Next steps

* [Rendering and deployment](/docs/frameworks/sveltekit/rendering): runtime
  policy fetching, prerendered pages, static sites, SPA mode and edge adapters.
* [Customize](/docs/frameworks/sveltekit/customize): brand colors rendered on
  the server, slots and copy.
* [Scripts and embeds](/docs/frameworks/sveltekit/scripts): more vendors,
  gated iframes and network blocking.
* [Context getters](/docs/frameworks/sveltekit/getters): read consent in your
  own components.

# Rendering and deployment
URL: https://c15t.com/docs/frameworks/sveltekit/rendering
Use the recommended build-time manifest for SvelteKit server rendering, choose runtime fetching for policy updates without a rebuild, and handle prerendered pages, static sites and SPA mode.

## Pick a rendering path

`c15tHandle()` in `src/hooks.server.ts` holds the config for the whole app.
Its `mode` option decides where each visitor's policy comes from. Import the
modes from `@c15t/svelte/kit`: they are plain data, which `loadConsent`
sends to the browser.

|Your app|Where consent resolves|`c15tHandle()` options|
|--|--|--|
|Server-rendered pages, recommended|Root layout load, from a build-time manifest|None. See the [quickstart](/docs/frameworks/sveltekit/quickstart).|
|Policy changes must apply without a rebuild|Root layout load, from a manifest fetched at runtime|`mode: manifest({ source: 'runtime' })`. See [fetch the manifest at runtime](#fetch-the-manifest-at-runtime).|
|Backend resolves every visit|Root layout load calls the backend's `/init`|`mode: hosted()`. See [ask the backend on every request](#ask-the-backend-on-every-request).|
|A server app with some prerendered pages|Server for most pages, the browser on prerendered ones|`routePrefix: '/api/c15t'` and a consent route. See [prerender some pages](#prerender-some-pages).|
|A fully static site with `adapter-static`|The browser|`mode: hosted()`. See [build a static site](#build-a-static-site).|
|SPA mode, `ssr = false`|The browser|See [use SPA mode](#use-spa-mode).|

Every path uses the same root layout: `loadConsent` as the server load and
`ConsentRoot` with `state={data.consent}`. The quickstart's code is the
`examples/sveltekit` app in the c15t repository.
[Data fetching](/docs/concepts/data-fetching) compares `/init`, the manifest
and browser resolution in general.

## Bundle the manifest during builds

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

The [quickstart](/docs/frameworks/sveltekit/quickstart) sets this up across
these files:

|File|Role|
|--|--|
|`vite.config.ts`|`consentManifest` from `@c15t/svelte/vite` fetches the policy.|
|`src/hooks.server.ts`|`c15tHandle()`, whose default mode, `manifest()`, resolves from the fetched policy.|
|`src/routes/+layout.server.ts`|`export { loadConsent as load }` resolves each visitor.|
|`src/routes/+layout.svelte`|`ConsentRoot state={data.consent}` renders the result.|

The plugin's position in `plugins` does not matter. It fetches the policy
once Vite has resolved its config, before anything compiles. Without a
`backendURL` option, it reads `PUBLIC_C15T_BACKEND_URL`, then
`PUBLIC_INTH_PROJECT_URL`, from the environment or `.env`.

The plugin detects the `sveltekit()` plugin and keeps the snapshot on the
server. `loadConsent` and `createConsentRoute()` read it without an import.
The browser bundle never holds it: `ConsentRoot` gets the resolved policy
from `loadConsent` instead.

Static hosts follow [build a static site](/docs/frameworks/sveltekit/rendering#build-a-static-site)
instead.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

On SvelteKit 3, `svelte-kit sync` resolves the Vite config, so it runs the
plugin and fetches the policy too, following the same rules when the fetch
fails. SvelteKit 2.68 also runs the plugin during `svelte-kit sync`, but logs
a failed fetch and continues.

To apply policy edits without a rebuild, set
`c15tHandle({ mode: manifest({ source: 'runtime' }) })` and follow
[fetch the manifest at runtime](/docs/frameworks/sveltekit/rendering#fetch-the-manifest-at-runtime).
To have the backend resolve every visit instead, set
`c15tHandle({ mode: hosted() })`. The layout load then calls the backend's
`/init`, and so does the browser on pages the server did not resolve.

## Fetch the manifest at runtime

Use runtime manifest fetching when policy updates must apply without a
rebuild. Your server downloads the project's public policy manifest, caches
it, and resolves each visitor locally. Consent saves still go to the backend,
directly or through the
[consent proxy](#save-consent-through-your-own-origin).

```ts title="src/hooks.server.ts"
import { c15tHandle, manifest } from '@c15t/svelte/kit';

export const handle = c15tHandle({ mode: manifest({ source: 'runtime' }) });
```

Keep `consentManifest` in `vite.config.ts`: it supplies the backend URL. Set
`consentManifest({ onBuildError: 'runtime' })` so a build does not depend on
the backend, or pass `c15tHandle({ backendURL })`. `loadConsent` fetches
`${backendURL}/manifest`, or the URL in `manifest({ manifestURL })`.

The server caches the manifest in memory for as long as its `s-maxage`
allows. After that, within the backend's `stale-while-revalidate` window, it
serves the stale copy while it refreshes in the background. Past that window,
the next request waits for a fresh copy, up to the 500 ms budget of
`loadConsent`. It also reports each resolved visit to the backend so Inth
still counts visitors it never served `/init` to.

Pass the absolute Inth URL as `backendURL`. A relative URL, such as
`/api/self-host` for a backend mounted in your app, is fetched with
`event.fetch` inside the app and is never resolved against the request's
`Host` header. One that points back at the consent route makes the route
fetch itself.

## Ask the backend on every request

`mode: hosted()` sends every server render to the backend's `/init`, which
resolves the visitor's location itself. The browser asks the same `/init` on
pages the server did not resolve:

```ts title="src/hooks.server.ts"
import { c15tHandle, hosted } from '@c15t/svelte/kit';

export const handle = c15tHandle({ mode: hosted() });
```

`hosted()` reads the backend URL from `consentManifest`, or takes
`hosted({ backendURL })`. The request to `/init` carries the resolved
location, language and GPC, the `user-agent` and, over `https` or to a
loopback host, the consent cookie alone. Every render waits on the backend,
up to 500 ms. `consentManifest` still downloads the manifest during the
build; set `onBuildError: 'runtime'` if a backend outage should not stop the
build.

## Serve the consent route

A page the server resolved needs no route. The browser needs one only when it
resolves consent itself, such as on a prerendered page, and you want it to
ask your own origin instead of the backend. Add a catch-all route at
`src/routes/api/c15t/[...path]/+server.ts`:

```ts title="src/routes/api/c15t/[...path]/+server.ts"
import { createConsentRoute } from '@c15t/svelte/kit';

// GET /api/c15t/init resolves the visitor from the bundled policy, and
// GET /api/c15t/manifest serves it. Other methods are not handled: the
// browser saves consent to the backend URL directly. Pair it with
// `c15tHandle({ routePrefix: '/api/c15t' })`.
export const { GET } = createConsentRoute();
```

Tell the handle where it is, so `loadConsent` passes the prefix to the
browser:

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle({ routePrefix: '/api/c15t' });
```

`createConsentRoute()` returns `GET`, which serves two paths:

|Request|Response|
|--|--|
|`GET /api/c15t/init`|The visitor's resolved policy, like the backend's `/init`. `Cache-Control: private, no-store`.|
|`GET /api/c15t/manifest`|The manifest, with the backend's `Cache-Control` and `ETag`. Answers `If-None-Match` with `304`.|

The route resolves from the snapshot `consentManifest` downloaded and reads
the backend URL from it, so it needs no options. It also reads what you pass
to `c15tHandle()`: a `snapshot`, a `backendURL`, and the mode's own
`backendURL` or `manifestURL`. Set them once, on the handle. Options you pass
to `createConsentRoute()` win.

This route file exports `GET` only, so a `POST` or `PATCH` to `/api/c15t`
gets a `405`. Consent saves go to the backend URL directly, unless you turn
on the proxy described in
[save consent through your own origin](#save-consent-through-your-own-origin).

### Save consent through your own origin

To keep every consent request on your site's origin, pass `proxy: true` and
export the write handlers from the same catch-all route:

```ts title="src/routes/api/c15t/[...path]/+server.ts"
import { createConsentRoute } from '@c15t/svelte/kit';

export const { GET, POST, PATCH, PUT, DELETE, OPTIONS } = createConsentRoute({
	proxy: true,
});
```

Then point saves at the route:

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle({
	backendURL: '/api/c15t',
	routePrefix: '/api/c15t',
});
```

The route skips a handle `backendURL` that points at itself, and forwards to
the backend URL `consentManifest` read from `PUBLIC_C15T_BACKEND_URL` or
`PUBLIC_INTH_PROJECT_URL`. To
forward somewhere else, pass `createConsentRoute({ backendURL, proxy: true })`.
With the proxy on, `GET`
still resolves `init` and `manifest` in the process, and the handlers forward
other requests to `backendURL`. They forward only
`subjects`, `subjects/:id`, `init`, `manifest`, `health`, `status` and any
extra paths you list in `proxy: { paths }`, and answer anything else with
`404`. Cookies go upstream only when `proxy: { cookieNames }` names them. The visitor's address comes from
`event.getClientAddress()`, and `x-forwarded-host` and `x-forwarded-proto`
come from `event.url`, so configure your adapter's address header if it runs
behind a proxy. The proxy forwards to `backendURL`, never to a `manifestURL`.
An absolute URL is fetched over the network. A relative one, such as a route
elsewhere in your app, is fetched with `event.fetch` inside the app and is
never resolved against the request's `Host` header.

### Keep background work alive after the response

The route and `loadConsent` use only `fetch`, so they run on Node and edge
adapters alike. Some runtimes stop work once a response is sent, which would
cut off the background manifest refresh and the visit report. When the
adapter exposes `event.platform.context.waitUntil`, c15t registers that work
there automatically. Netlify does, as do Cloudflare and Vercel edge on
SvelteKit 2.

SvelteKit 3's Cloudflare adapter no longer puts `waitUntil` on
`event.platform`, and its Vercel adapter has no edge runtime. On those, pass
the platform's own `waitUntil` as `onBackgroundRevalidate`:

```ts title="src/routes/api/c15t/[...path]/+server.ts (partial)"
import { createConsentRoute } from '@c15t/svelte/kit';
import { waitUntil } from 'cloudflare:workers'; // Vercel: '@vercel/functions'

export const { GET } = createConsentRoute({
	onBackgroundRevalidate: (promise) => waitUntil(promise),
});
```

Without it, those runtimes can cut the refresh and the visit report short.
Requests keep getting the cached manifest, but it can stay stale for longer,
and the backend misses those visits.

`loadConsent` takes the same option when you call it from your own `load`
instead of exporting it directly:

```ts title="src/routes/+layout.server.ts"
import { loadConsent } from '@c15t/svelte/kit';
import { waitUntil } from 'cloudflare:workers';

export const load = (event) =>
	loadConsent(event, {
		onBackgroundRevalidate: (promise) => waitUntil(promise),
	});
```

`loadConsent` uses `event.platform.context.waitUntil` when available and
this callback otherwise. The framework-free `resolveConsent` helper also
accepts `onBackgroundRevalidate`; it has no event from which to find a
platform hook.

## Resolve request context once with c15tHandle

The quickstart installs `c15tHandle` in `src/hooks.server.ts`. It holds the
consent config for the app and reads the consent cookie and headers once per
request for every load and endpoint:

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle();
```

It stores the result on `event.locals.c15t`, which `loadConsent` reuses, and
rewrites the location headers into one normalized form. Compose it with your
own handles through `sequence(c15tHandle(), yourHandle)` from
`@sveltejs/kit/hooks`.

|Option|Default|What it does|
|--|--|--|
|`mode`|`manifest()`|How `loadConsent` resolves the visitor: `manifest()`, `hosted()` or `offline()` from `@c15t/svelte/kit`.|
|`routePrefix`|none|Where [`createConsentRoute()`](#serve-the-consent-route) is mounted, such as `/api/c15t`. Without it, the browser asks the backend's `/init` when it resolves consent itself.|
|`backendURL`|The URL `consentManifest` read from `PUBLIC_C15T_BACKEND_URL` or `PUBLIC_INTH_PROJECT_URL`|The backend. `hosted({ backendURL })` wins.|
|`snapshot`|The manifest `consentManifest` downloaded|A manifest of your own to resolve with.|
|`cookieName`|`c15t`|The consent cookie. Match the provider's `storageConfig.storageKey`.|
|`country`, `region`, `language`|from headers|Forces one input for every request.|

`c15tHandle` also writes a server-rendered banner's rules into the HTML
`<head>` as `<style>` elements, so the banner is styled before hydration.
Without it, a server-rendered banner shows unstyled until the page hydrates,
unless `ConsentRoot` sets `styles={false}` and the app imports
`@c15t/svelte/styles.css`.

Type `event.locals.c15t` in `src/app.d.ts`:

```ts title="src/app.d.ts"
/// <reference types="@c15t/svelte/kit/locals" />
```

Options passed to one `loadConsent` call, such as `country`, override the
handle's values for that call. Without the handle, `loadConsent` resolves
with `manifest()` and reads the request itself.

## Prerender some pages

A prerendered page is built once and sent to every visitor, so it cannot
contain one visitor's consent. SvelteKit runs the root layout load while it
builds those pages. `loadConsent` and `c15tHandle` read SvelteKit's
`building` flag, so they return no visitor's consent and no policy then, and
make no backend request. Prerendering a page needs only the page option:

```ts title="src/routes/about/+page.ts"
// Build this page once as static HTML. While SvelteKit prerenders,
// `loadConsent` returns no visitor's consent, so the browser resolves it
// here.
export const prerender = true;
```

On a prerendered page the HTML has no banner. After hydration the browser
resolves the policy, then shows the banner or applies the stored choice.
Optional categories stay denied until then. Server-rendered pages in the same
app keep the banner in their HTML.

Where the browser asks depends on the handle:

* With [`routePrefix` and the consent route](#serve-the-consent-route), it
  asks your own `/api/c15t/init`, which resolves from the bundled snapshot.
* Without them, it asks the backend's `/init`.

## Build a static site

With `adapter-static`, every page is prerendered and no server runs after the
build. Set the option in the root layout:

```ts title="src/routes/+layout.ts"
export const prerender = true;
```

The browser resolves consent on every page. Server routes such as
`/api/c15t` do not exist after a static build, so it has to ask the backend
directly. Starting from the quickstart, set `hosted()` as the mode and keep
the rest:

```ts title="src/hooks.server.ts"
import { c15tHandle, hosted } from '@c15t/svelte/kit';

export const handle = c15tHandle({ mode: hosted() });
```

The hook and `loadConsent` still run while SvelteKit prerenders, and return
no visitor's consent. The browser then calls the backend's `/init`, and the
backend resolves the visitor's location. Leave out `routePrefix` and the
consent route. On a static host, the backend URL must be the absolute Inth
URL, and the backend must allow your site's origin.

## Use SPA mode

With `export const ssr = false` in the root `+layout.ts` and a server
adapter, the quickstart works unchanged. The root layout's server load still
runs for each navigation, so `ConsentRoot` starts from a resolved policy;
there is no server HTML, so the banner appears once the page has rendered in
the browser.

With a static SPA fallback page and no server, no server load runs. Delete
`+layout.server.ts` and the c15t handle, and render `ConsentProvider` with a
browser mode in `+layout.svelte`:

```svelte title="src/routes/+layout.svelte (partial)"
<script lang="ts">
	import { ConsentProvider, hosted } from '@c15t/svelte';
	import { PUBLIC_C15T_BACKEND_URL } from '$env/static/public';

	const mode = hosted({ backendURL: PUBLIC_C15T_BACKEND_URL });
</script>

<ConsentProvider {mode} {scripts}>
```

The browser resolves consent through the backend's `/init`.
`ConsentProvider` takes the same props as `ConsentRoot`, with `mode` in place
of `state`.

## Taps before hydration

A banner in the server HTML shows before the page's JavaScript runs. A tap on
it in that gap does nothing: the button has no handler yet, so the banner
stays up and no choice is saved. The React and Vue banners hold such a tap and
replay it after hydration; the SvelteKit banner does not.

## Resolve consent in other server code

`resolveConsent` from `@c15t/svelte/server` does what `loadConsent` does
without a SvelteKit event, for endpoints or code outside a load:

```ts
import { resolveConsent } from '@c15t/svelte/server';

const state = await resolveConsent({
	backendURL: 'https://your-project.inth.app',
	headers: request.headers,
});
```

It never throws. When the backend fails or takes longer than `timeoutMs`,
500 ms by default, it returns the stored choice without a policy. Pass
`manifest` to resolve from a manifest you hold instead of calling `/init`. In a load, use `loadConsent`, which
reads the request and the handle's config from the event.
Import `@c15t/svelte/kit` and `@c15t/svelte/server` only from server files
such as `+layout.server.ts`, `+server.ts` and `hooks.server.ts`; imported into
a component they add server code to the browser bundle.

# Scripts
URL: https://c15t.com/docs/frameworks/sveltekit/scripts
Load vendor scripts, iframes and network requests in a SvelteKit app only after the visitor allows their consent category, and stop them when consent is withdrawn.

## Register scripts in the root layout

Pass the array from `src/lib/scripts.ts` to `ConsentRoot`
as the `scripts` prop in `src/routes/+layout.svelte`. The
[quickstart](/docs/frameworks/sveltekit/quickstart) sets up both files:

```ts title="src/lib/scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	// Loads PostHog only after the visitor allows measurement.
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

Create the scripts in the layout component, not in `+layout.server.ts`. Script
configurations hold functions, which a server load cannot send to the
browser. Scripts load only in the browser, after hydration, so they never
appear in server HTML.

## Preload the script loader

The provider loads the script loader only on pages whose `scripts` array is
not empty or that have [network blocker](./network-blocker) rules. The loader
and the blocker share one separate chunk. Pages with neither never download
it. On a page with either, the browser would otherwise request the chunk after
the app's JavaScript has run, and a returning visitor's consented scripts and
held requests would wait for that extra request.

`consentManifest()` from `@c15t/svelte/vite`, already in `vite.config.ts`
from the quickstart, lets `c15tHandle` link the chunk from the page's
`<head>` with `<link rel="modulepreload">`. It does this whenever the
`sveltekit()` plugin is present; there is nothing else to add.

SvelteKit builds the server before the client, so the server cannot know the
chunk's file name. After the client build, `consentManifest()` writes the chunk URL
into the server output, before SvelteKit prerenders pages and before the
adapter copies the build. Then `c15tHandle` adds one link to every page whose
provider has scripts or blocker rules, prerendered pages included. The link
carries the provider's `nonce`, or else the nonce SvelteKit put on its own
scripts. It asks for low priority (`fetchpriority="low"`): the
runtime needs the chunk only after hydration, so the browser fetches your
app's own chunks first. It does nothing in `vite dev`.

Without the plugin, or without `c15tHandle` in `hooks.server.ts`, scripts
still load, one request later.

## How registered scripts load

The provider's `scripts` prop takes an array of script configurations. Each
has a category. The loader adds a script to the page when its category becomes
allowed and removes it when the category is withdrawn. Nothing optional loads
while the policy is still resolving, or when it fails.

Helpers in `@c15t/integrations`, such as `posthog()` from `@c15t/integrations/posthog`,
return a configuration with the right category and the vendor's own consent
calls. [Integrations](/docs/integrations/overview) lists every helper. For an
SDK without a helper, write a configuration with an `id`, `category` and `src`
as shown in [building integrations](/docs/integrations/building-integrations).

Remove the vendor's original `<script>` tag, `app.html` snippet or SDK import
before you register it. A banner does not block code that loads some other
way, and a vendor loaded twice sends events twice.

The `scripts` array is read when the provider is created. Build it once, at
the top level of the component, not inside an effect.

## Script options

Helpers set these for you. For a script without a helper, write the object
yourself:

|Option|Default|Behavior|
|--|--|--|
|`id`|required|A unique name. The loader uses it to add and remove the script once.|
|`category`|required|The category or condition, such as `'measurement'` or `{ and: ['measurement', 'marketing'] }`, that must be allowed.|
|`src` or `textContent`|none|The script's URL, or inline code.|
|`callbackOnly`|`false`|Adds no `<script>` element and only runs the callbacks. Use it to switch an SDK you load yourself on and off.|
|`alwaysLoad`|`false`|Loads at once, whatever the consent state. Only for scripts that apply consent themselves, such as a tag manager with Consent Mode.|
|`persistAfterConsentRevoked`|`false`|Keeps the element after withdrawal instead of removing it.|
|`target`|`'head'`|Where the element goes: `'head'` or `'body'`.|
|`async`, `defer`, `fetchPriority`, `attributes`, `nonce`|none|Set on the `<script>` element.|
|`anonymizeId`|`true`|Gives the element a random `id`, so ad blockers do not match it by name.|
|`vendor`|none|Also waits for this vendor to be allowed, for vendor-level consent outside IAB.|
|`onBeforeLoad`, `onLoad`, `onError`, `onConsentChange`, `onDispose`|none|Lifecycle callbacks. See [callbacks](./callbacks#script-callbacks).|

## Gate embeds

Iframes are not scripts. Wrap them in `ConsentGate`, which keeps the iframe
out of the DOM until its category is allowed:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

For iframes from a CMS or Markdown, which you cannot wrap, use the iframe
blocker's `data-category` and `data-src` attributes. [Embeds](./embeds) covers
both.

## Block requests from code already on the page

The provider's `networkBlocker` option holds `fetch` and `XMLHttpRequest`
calls to the domains you list until their category is allowed. It is a
backstop for code you cannot move into `scripts`. [Network blocker](./network-blocker)
covers the rules and what it cannot stop.

## What happens when consent is withdrawn

Removing a script tag cannot stop code that already ran. So when a save
withdraws a category that was granted, the provider reloads the page after the
save request, and the new page starts with only the permitted code. Set
`reloadOnConsentRevoked: false` on the provider if you handle withdrawal
yourself, for example through a vendor's own opt-out call in
`onConsentChange`.

`ConsentGate` content unmounts without a reload. To delete first-party cookies
a vendor set, configure `clearOnRevocation`; see
[clearing data on revocation](./clear-on-revocation).

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Pass
`vendors` to the provider; helpers from `@c15t/integrations` already carry their
vendor slug. See [vendor consent](./vendor-consent).

## Verify vendor loading

Open DevTools, clear site data for your origin and reload:

1. With the banner showing, the Network panel has no requests to your vendors,
   and gated iframes are absent from the Elements panel.
2. Allow one category in preferences. Only that category's vendors load, and
   its iframes appear.
3. Reject, reload, and confirm the vendor requests stay absent.
4. Withdraw a category you allowed. The page reloads and its vendors no longer
   load.

[Verify consent](/docs/guides/verify-consent) covers automated checks.

# Embeds
URL: https://c15t.com/docs/frameworks/sveltekit/embeds
Keep YouTube videos, maps and other iframes out of SvelteKit server HTML and the browser until their consent category is allowed.

## Pick a way to gate the embed

A YouTube video, a map or a social post in an iframe contacts its vendor as
soon as it loads. c15t offers two ways to keep it from loading before
consent:

|Your markup|Use|Placeholder|
|--|--|--|
|A Svelte component you write|`ConsentGate` around the iframe|Built in, or your own snippet|
|HTML you do not control, such as CMS or Markdown content|The iframe blocker with `data-category` and `data-src`|None; the iframe stays empty|

Both use the visitor's effective permission for one category, and both
remove the embed again when the visitor withdraws that category.

## Wrap the iframe in ConsentGate

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

The iframe is absent from the DOM until measurement is allowed, so the
browser never requests it. The placeholder snippet replaces the built-in one
and includes a `ConsentDialogLink`, so a visitor can allow the category from
the embed's own spot. Keep `ConsentDialog` mounted for that link.
[ConsentGate](./components/consent-gate) lists its props.

Pick the category the vendor's embed needs. YouTube and maps usually fit
`measurement` or `marketing`; check what each vendor sets.

## Gate iframes you do not render

The provider's iframe blocker is on by default. It watches the page for
iframes with a `data-category` attribute:

```html
<iframe
  title="Store locations"
  data-category="functionality"
  data-src="https://www.google.com/maps/embed?pb=..."
></iframe>
```

* While the category is denied, the iframe has no `src`, so it loads nothing.
* When the category is allowed, the blocker copies `data-src` to `src`.
  Only `http` and `https` URLs are used.
* When the category is withdrawn, the blocker removes `src` again.

Iframes without `data-category` or `data-vendor` are never touched. Put
`data-src` in the HTML instead of `src`; an iframe that arrives with `src`
already starts loading before the blocker sees it. Add `data-vendor` with a
vendor slug to also keep the iframe empty while the visitor has that vendor
turned off.

The blocker has no placeholder. Style the empty iframe, or place a note and a
`ConsentDialogLink` next to it.

Pass `iframeBlocker={false}` on the provider to turn the blocker off.

## Vendor guides

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides have ready embed
configurations. [Integrations](/docs/integrations/overview) lists the rest.

## Verify the embeds

Clear site data and reload with DevTools open:

1. The Network panel has no request to the embed's host, and the Elements
   panel shows the placeholder or an iframe without `src`.
2. Allow the category in preferences. The embed loads without a page reload.
3. Withdraw the category. The embed disappears, or its iframe loses `src`.

## Embeds in server HTML

`ConsentGate` renders an empty wrapper on the server, so a gated embed is
never in the server HTML, whatever the visitor chose. It appears in the
browser after hydration. An iframe with `data-category` and `data-src` is in
the server HTML without `src`, so it loads nothing until the iframe blocker
starts in the browser and finds its category allowed.

# Network blocker
URL: https://c15t.com/docs/frameworks/sveltekit/network-blocker
Hold browser fetch and XMLHttpRequest calls to tracking domains in a SvelteKit app until their consent category is allowed, with the networkBlocker option.

## When to use the network blocker

The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
list until their consent category is allowed. Use it as a backstop for
tracking calls from code that is already on the page, such as your own
analytics wrapper or an SDK you import. It is off until you configure it.

Load vendor SDKs through the provider's `scripts` prop first; see
[scripts](./scripts). A script that never loads sends nothing, which is
stronger than blocking its requests one by one.

## Configure the rules

Write the configuration in its own module:

```ts title="src/lib/network-blocker.ts"
import type { UseNetworkBlockerOptions } from '@c15t/svelte';

// Pass as `networkBlocker={networkBlocker}` on ConsentProvider.
export const networkBlocker: UseNetworkBlockerOptions = {
	onRequestBlocked: ({ method, url }) => {
		console.info('Blocked until consent', method, url);
	},
	rules: [
		{
			category: 'measurement',
			domain: 'google-analytics.com',
			id: 'google-analytics',
		},
		{
			category: 'marketing',
			domain: 'connect.facebook.net',
			id: 'meta-pixel',
			pathIncludes: '/signals',
		},
	],
};
```

Pass it to the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} {networkBlocker}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} {networkBlocker}>
```

The provider reads `networkBlocker` once, when it is created. Remount the
provider to change the rules.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

A blocked `fetch` resolves to a response with status `451` and the status
text `Request blocked by consent`, and nothing is sent. A blocked
`XMLHttpRequest` is aborted and fires an `error` event. Requests that match no
rule are not delayed. With `logBlockedRequests` on, the default, each blocked
request is logged with `console.warn`; `onRequestBlocked` receives
`{ method, url, rule }`.

## When blocking starts

The provider starts holding matching requests when it is created in the
browser, before its children run their own code. The blocker module loads
when the provider mounts and then decides each held request:

* While the policy is still loading, a matching request waits instead of
  failing. When the policy arrives, with the visitor's stored choice applied,
  the request is sent if its category is allowed and blocked otherwise.
* If the policy fails to load, optional categories stay denied and the
  waiting requests are blocked.
* A synchronous XHR cannot wait. Before the blocker module loads, a matching
  one throws a `NetworkError` from `send()`.

When the visitor allows a category later, new requests to its domains go
through. Requests blocked earlier are not replayed.

## What it cannot stop

The blocker sees only `fetch` and `XMLHttpRequest` calls made after the
provider is created in the browser. It cannot stop:

* Scripts that run before the provider, such as tags in `index.html` or
  `app.html` and code at the top level of modules that load first.
* Code that kept its own reference to `fetch` or `XMLHttpRequest` from before
  the provider was created.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` and `<iframe>` elements, web workers and service
  workers.
* Requests your server makes, such as from a SvelteKit `load` or endpoint.

Keep tracking calls out of that window. Send them from event handlers or
effects, not at a module's top level, and check
`getConsentManager().has('measurement')` before you call a vendor from your
own code.

## Verify the blocker

Open DevTools, clear site data for your origin and reload:

1. Before you choose, requests matching a rule do not reach the network, and
   the console logs each blocked request.
2. Allow the rule's category. New matching requests appear in the Network
   panel.
3. Reject, reload and confirm they stay blocked.

`fetch('https://www.google-analytics.com/g/collect')` in the console returns a
response with status `451` while measurement is denied.

## Preload the blocker

The blocker shares a separate chunk with the script loader. The chunk loads
only on pages with `networkBlocker` rules or `scripts`, and matching requests
wait until it has loaded. `consentManifest()` lets `c15tHandle` link the
chunk from the page's `<head>`, so the browser fetches it with the app's own
code.
[Preload the script loader](./scripts#preload-the-script-loader) shows the
setup.

## Server requests are not blocked

The network blocker runs in the browser. A `fetch` in a SvelteKit `load`,
`+server.ts` or `hooks.server.ts` is never blocked, even when the visitor has
denied the category. If server code sends data to a vendor, check the
visitor's stored choice yourself before it does; `event.locals.c15t.config`
from [`c15tHandle`](./server-api#c15thandle) holds it.

# Vendor consent
URL: https://c15t.com/docs/frameworks/sveltekit/vendor-consent
Let visitors allow a category such as marketing in a SvelteKit app and still turn off one vendor in it, with the vendors prop on ConsentRoot and getConsentManager.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

Declare the vendors in the root layout, using the `vendor` slug each script
already carries, and pass them to `ConsentRoot`:

```svelte title="src/routes/+layout.svelte (partial)"
<script lang="ts">
  import type { ConsentManagerOptions } from '@c15t/svelte';

  const vendors: NonNullable<ConsentManagerOptions['vendors']> = [
    {
      id: 'x-pixel',
      name: 'X Pixel',
      category: 'marketing',
      privacyPolicyUrl: 'https://x.com/privacy',
    },
  ];
</script>

<ConsentRoot state={data.consent} {scripts} {vendors}>
```

The provider reads `vendors` once, when it is created.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

`ConsentGate` checks a category only. For an iframe, add `data-vendor` and use
the iframe blocker; see [embeds](/docs/frameworks/sveltekit/embeds).

## What the preference dialog shows

`ConsentDialog` and `ConsentWidget` list each declared vendor under its
category, with its own switch.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Build your own vendor switch

`getConsentManager()` stages vendor switches on the same draft as the category
switches. `selectedVendors` has one value per declared vendor,
`setSelectedVendor(id, granted)` changes one, and `saveConsents('custom')`
records the draft:

```svelte title="src/lib/x-pixel-switch.svelte (partial)"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
</script>

<input
	type="checkbox"
	checked={consent.selectedVendors['x-pixel'] ?? true}
	onchange={(event) =>
		consent.setSelectedVendor('x-pixel', event.currentTarget.checked)}
/>
<button type="button" onclick={() => consent.saveConsents('custom')}
	>Save</button
>
```

`saveConsents('custom')` throws when the policy changed since the draft
started. `vendorChoice.denied` lists the vendors the visitor recorded as off,
and `getDisplayedVendors(category)` returns the vendors to list under one
category. [Context getters](/docs/frameworks/sveltekit/getters) covers the draft.

## Check whether a vendor may run

`consent.isVendorAllowed(id)` on the object from `getConsentManager()` returns
`true` while the vendor may run: it is declared, its category is allowed and
the visitor has not switched it off. Read it in markup or a `$derived` so it
updates when consent changes.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/sveltekit/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a SvelteKit app when that category is denied, with the clearOnRevocation prop on ConsentRoot.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns and pass them to
`ConsentRoot` in `src/routes/+layout.svelte`. When that category is denied,
c15t deletes them:

```svelte title="src/routes/+layout.svelte (partial)"
<script lang="ts">
	import type { ConsentManagerOptions } from '@c15t/svelte';

	const clearOnRevocation: ConsentManagerOptions['clearOnRevocation'] = {
		measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
		marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
	};
</script>

<ConsentRoot state={data.consent} {scripts} {clearOnRevocation}>
```

The provider reads `clearOnRevocation` once, when it is created. Cleanup runs
in the browser only, never during server rendering. For a shared
runtime, pass it to `createConsentRuntime()` instead, not to a provider that
borrows the runtime.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/sveltekit/customize
Render c15t brand colors on the SvelteKit server with generateThemeCSS, and change slots, button styles, banner shape and copy.

## Pick the right tool

|Change|Use|
|--|--|
|Brand colors, radius, type, spacing|`generateThemeCSS()` in a server load, or `--c15t-*` variables in a stylesheet|
|One part of one component|`theme.slots` on the provider|
|Button styles by action|`theme.consentActions`|
|Shape, position, blocking, button order|`ConsentBanner` props or `presentation`|
|Wording and languages|`ConsentBanner` text props, or [translations](/docs/frameworks/sveltekit/translations)|
|Different markup|[Headless](/docs/frameworks/sveltekit/headless)|

[Customization](/docs/customization/overview) explains how the pieces fit
together across frameworks.

See the [design gallery](/docs/customization/recipes) for five banner designs,
from a bottom bar to a fully custom one, with tested code for this framework.

## Render brand tokens on the server

The provider's `theme` prop does not turn colors, radius or other tokens into
CSS in the browser. Generate the CSS on the server instead, so the first paint
already uses your brand. Install `@c15t/ui`, which has the generator:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/ui@alpha`|
|pnpm|`pnpm add @c15t/ui@alpha`|
|yarn|`yarn add @c15t/ui@alpha`|
|bun|`bun add @c15t/ui@alpha`|

Put the theme in a module under `src/lib/server`. SvelteKit refuses to import
server-only modules into browser code, so the generator never reaches the bundle:

```ts title="src/lib/server/consent-theme.ts"
import { generateThemeCSS } from '@c15t/ui/theme';

// Modules in a `server` directory never reach the browser, so the theme
// generator stays on the server. The CSS is generated once, when the server
// starts.
export const themeCSS = generateThemeCSS({
	colors: {
		primary: '#6943a3',
		primaryHover: '#533285',
		textOnPrimary: '#ffffff',
	},
	radius: { lg: '18px' },
});
```

Return the CSS from a layout load. If your root `+layout.server.ts` already
exports `loadConsent` from the quickstart, call it from your own `load` and
return `themeCSS` next to its `consent`, as in
`({ ...(await loadConsent(event)), themeCSS })`. A separate layout looks like
this:

```ts title="src/routes/+layout.server.ts"
import { themeCSS } from '#lib/server/consent-theme.js';

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = () => ({ themeCSS });
```

Render it in `<svelte:head>` in the layout:

```svelte title="src/routes/+layout.svelte"
<svelte:head>
	<!-- generateThemeCSS escapes `<`, so its output is safe in a style element. -->
	{@html `<style id="c15t-theme">${data.themeCSS}</style>`}
</svelte:head>
```

SvelteKit writes `<svelte:head>` content before its stylesheet links, and
`c15tHandle` adds c15t's default rules at the end of `<head>`. The
`generateThemeCSS` selectors are more specific than those defaults, so the
theme still wins. Keep the `c15t-theme` id. In development, the provider logs a warning when its
`theme` prop has tokens and the page has no `<style id="c15t-theme">`. `generateThemeCSS` escapes `<`,
so its output is safe inside a `<style>` element.

`generateThemeCSS` fills in what you leave out, such as a readable text color
for your primary color. Pass a color scheme as its second argument,
`'dark'` or `'system'`, to include dark tokens. Keep slot styles and
`consentActions` in the provider's `theme` prop; the server CSS covers tokens
only. [Theme tokens](/docs/customization/tokens) lists every token.

### Use a stylesheet instead

For fixed brand values you can skip the generator. Write the `--c15t-*`
variables on `:root` in a stylesheet and import it in the root layout:

```css title="src/consent-theme.css"
/* Load after @c15t/svelte/styles.css so these values win. */
:root {
	--c15t-primary: #6943a3;
	--c15t-primary-hover: #533285;
	--c15t-text-on-primary: #ffffff;
	--c15t-radius-lg: 18px;
}
```

Set the hover and text colors yourself; a stylesheet does not derive them.

Pick one of the two for each token. `generateThemeCSS` output outranks a plain
`:root` rule, so a `--c15t-*` value you set on `:root` loses to the generated
theme wherever the two overlap. To override a generated value from your
stylesheet, write the rule on `:root:root`, or move the value into the theme.

## Switch to dark tokens

The provider's `colorScheme` prop switches on the dark token set: `'dark'`
always, `'system'` when the operating system prefers dark, `'light'` never. It
toggles a `c15t-dark` class on `<html>`. Left unset, the provider copies a
`dark` class on `<html>` into `c15t-dark`, so an app with its own dark mode
toggle gets the dark tokens without the prop. Pass `null` if your app sets
`c15t-dark` itself. Override dark values under `:root.dark` and
`:root.c15t-dark` in your stylesheet. [Dark mode](/docs/customization/dark-mode)
covers a dark first paint.

## Style one part with theme slots

The provider's `theme` prop still applies slot styles in the browser. A slot
takes a class name, or `{ className, style, noStyle }`. Svelte applies a
slot's class and `style` on every stock part, including the IAB banner and
dialog:

```ts
const theme = {
	slots: {
		consentBannerCard: 'brand-banner-card',
		consentBannerTitle: 'brand-banner-title',
	},
};
```

Pass it as `theme={theme}` on `ConsentProvider`. Define the class in a
global stylesheet, or with `:global(.brand-banner-card)` in a component,
because Svelte scopes component styles. The Svelte components read these
slots:

|Component|Slots|
|--|--|
|`ConsentBanner`|`consentBanner`, `consentBannerCard`, `consentBannerHeader`, `consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`, `consentBannerFooterSubGroup`, `consentBannerRights`, `consentBannerRightLink`, `consentBannerTag`, `consentBannerOverlay`|
|`ConsentDialog`|`consentDialog`, `consentDialogCard`, `consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`, `consentDialogContent`, `consentDialogTag`|
|`ConsentWidget`|`consentWidget`, `consentWidgetFooter`, `consentWidgetFooterSubGroup`, `consentWidgetTag`|
|`ConsentDialogTrigger`|`consentDialogTrigger`, `consentDialogTriggerIcon`|
|`IABConsentBanner`|`iabConsentBanner`, `iabConsentBannerTag`, `iabConsentBannerOverlay`|
|`ConsentGate`|`consentGate`, `consentGateTitle`, `consentGateButton`|
|Buttons in every component|`buttonPrimary`, `buttonSecondary`|

Slot names are not React's `components.banner.card` keys; do not copy a React
configuration. Use slots when one part should change and tokens when a value
should change everywhere. `class` on a component, such as
`<ConsentBanner class="...">`, goes on its root.
[Component parts](/docs/customization/slots) explains the attributes each
element carries, and [Tailwind CSS](/docs/customization/tailwind) shows the
Svelte and SvelteKit setups for Tailwind 4 and 3.

## Change button styles by action

`theme.consentActions` picks each button's style by what it does, whichever
order the policy puts the buttons in:

```ts
const theme = {
	consentActions: {
		default: { variant: 'neutral', mode: 'stroke' },
		primary: { variant: 'primary', mode: 'filled' },
		reject: { variant: 'neutral', mode: 'filled' },
	},
};
```

A per-action entry overrides `primary`, which overrides `default`. The policy
decides which action is primary.

## Change the banner shape and position

Set the shape on the banner itself, or for every surface with the provider's
`presentation` prop:

```svelte
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

`blocking` adds a backdrop, locks scrolling, traps focus and stops outside
clicks from closing the banner. `layout` and `primaryButton` change the button
order and emphasis. The policy wins where they conflict. A policy that requires
a reject button keeps it, whatever the layout says.

## Change the copy

For one banner, the text props on `ConsentBanner`, such as `title` and
`rejectButtonText`, replace the copy in every mode:

```svelte
<ConsentBanner title="Your privacy" rejectButtonText="Reject optional" />
```

For site-wide copy, pass the provider's `i18n` messages. In `offline()` mode
they merge over the bundled English copy. In `hosted()` mode they merge over
the backend's copy for the same language, key by key, so keys you leave out
keep the wording from your Inth project.
[Translations](./translations) covers both, the message keys and switching
languages. [Copy and translations](/docs/customization/translations) covers
wording for each action.

## Turn off animations

`disableAnimation` on the provider turns off the banner and dialog animations,
and the same prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner` or
`IABConsentDialog` overrides it for one surface. Left unset, the provider
follows the visitor's reduced motion setting.
[Motion and animation](/docs/customization/motion) covers the duration and
easing tokens.

## Remove c15t's styles

Set `noStyle` on one component or on the provider to render the same markup
and behavior without c15t's classes. Style the `data-*` attributes and your
slot classes instead. For different markup, see the headless page.

# Translations
URL: https://c15t.com/docs/frameworks/sveltekit/translations
Change c15t banner and dialog copy in a SvelteKit app, where the server-resolved consent carries the translations for the request's language.

## Where the copy comes from

The banner, dialog, widget, gate placeholder and IAB surfaces read their text
from one set of translations for the visitor's language. Which set depends on
the provider's `mode`:

|Mode|Copy comes from|Languages|
|--|--|--|
|`hosted()`|The backend's `/init` response, in the language the browser or server asked for, with the provider's `i18n` messages for that language on top|Every language the backend bundles: bg, cs, cy, da, de, el, en, es, et, fi, fr, ga, gu, he, hi, hr, hu, id, is, it, lb, lt, lv, mt, nb, nl, nn, pl, pt, rm, ro, sk, sl, sv and zh|
|`manifest()`|The manifest's translations over the base copy for the visitor's language, with the provider's `i18n` messages on top. Resolved on the server in SvelteKit, in the browser in Svelte.|English base copy is bundled; another language's base copy loads the first time a visitor needs it|
|`offline()`|The provider's `i18n` prop, merged over bundled English|English, plus any language you supply in full|

The browser bundle carries English only. Other languages arrive from the
backend, or from messages you pass.

## Change the copy for one banner

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. These props
win in every mode:

```svelte
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>
```

The props replace the text in every language, so pass values in the page's
language, or compute them from your own i18n library.

## Change the copy site-wide

Pass `i18n` to the provider. `messages` holds partial translations per
language; the keys you leave out keep c15t's copy:

```ts title="src/lib/consent-i18n.ts"
import type { I18nConfig } from '@c15t/svelte';

// Pass as `i18n={i18n}` on ConsentProvider. Messages merge over the
// bundled English copy, so list only the keys you change.
export const i18n: Partial<I18nConfig> = {
	locale: 'en',
	messages: {
		en: {
			common: { customize: 'Choose cookies', rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Your privacy on this site' },
		},
	},
};
```

`locale` selects the language the provider starts in, `en` by default.

In `hosted()` mode, the backend's copy for the visitor's language is the base,
and your `i18n` messages for that language replace it key by key. Keys you do
not list keep the backend's copy, including copy edited in your Inth project.
The same applies to the copy SvelteKit's `loadConsent` resolves on the
server. c15t picks the
messages for the exact language first, then for its primary language, so a
visitor resolved to `de-AT` gets your `de` messages when there is no `de-AT`
entry. Messages for other languages are not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps backend edits visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording. A
self-hosted backend takes `customTranslations` and `i18n` in its
[configuration](/docs/self-host/api/configuration).

In `offline()` mode, `i18n` is the only source of copy, and it applies from the
first render.

## Common message keys

|Key|Where it shows|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Choice banner heading and body.|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Notice banner heading and body.|
|`common.acceptAll`, `common.rejectAll`, `common.customize`, `common.save`|Banner and dialog buttons.|
|`common.acknowledge`|The notice's dismiss button.|
|`common.securedBy`|The "Secured by" tag.|
|`consentManagerDialog.title`, `consentManagerDialog.description`|Preference dialog heading and body.|
|`consentTypes.<category>.title`, `consentTypes.<category>.description`|A category's name and description, such as `consentTypes.measurement.title`.|
|`consentGate.title`, `consentGate.actionButton`|The `ConsentGate` placeholder. `{category}` is replaced by the category title.|

[Copy and translations](/docs/customization/translations) covers wording for
each action and testing long labels.

## Switch the language

`getConsentManager().setLanguage(code)` switches the language and resolves the
policy again, so a hosted backend returns copy in the new language and your
`i18n` messages for that language apply on top. Call it
from your language switcher's event handler. The visitor's language otherwise
comes from the `Accept-Language` header, or from `overrides.language` on the
provider.

The root of the banner, dialog and widget sets `dir` from the active
language, so right-to-left languages such as Hebrew lay out correctly.

## Verify the copy

Open the page with the browser language set to each language you support.
The banner, the dialog's category names and the gate placeholder all use that
language. Then choose a narrow window and zoom to 200%: long labels wrap
without cutting off.

## Language on the server

`loadConsent` resolves the language from the request's `Accept-Language`
header and returns the copy for it in `consent`, so the server HTML
is already in the visitor's language. Pass `language` to `loadConsent` or
`c15tHandle` to force one, for example from a `/de/` route prefix. The
provider applies its `i18n` messages for that language over the
server-resolved copy, so the server HTML already shows your overrides.

# Primitives
URL: https://c15t.com/docs/frameworks/sveltekit/components/primitives
Build your own accessible consent dialog in SvelteKit with the Dialog, Switch, Tabs, Accordion and PreferenceItem primitives and the focusTrap, scrollLock and portal actions.

## When to use the primitives

The stock consent components are built from a set of unstyled, accessible
building blocks that `@c15t/svelte` also exports. Reach for them when you
build your own preference dialog or settings page with the
[headless getters](../headless) and want the same keyboard and focus behavior
as the stock dialog. For the consent state itself, use `getConsentManager()`;
the primitives know nothing about consent.

Their rules load with the stock `ConsentDialog`. A page that renders the
primitives without the stock dialog needs `@c15t/svelte/styles.css`: import it
and set `styles={false}` on the provider. Each part accepts `class` and passes
other HTML attributes to its element.

## Compound components

Import each as one object and use its parts, such as `Dialog.Root` and
`Dialog.Content`. Every part is also exported on its own.

|Component|Parts|Root props|
|--|--|--|
|`Dialog`|`Root`, `Portal`, `Backdrop`, `Positioner`, `Content`, `Title`, `Description`, `CloseTrigger`|`open` (bindable, default `false`), `closeOnEscape` (`true`), `closeOnInteractOutside` (`true`), `trapFocus` (`true`), `preventScroll` (`false`), `lazyMount` (`false`), `unmountOnExit` (`false`)|
|`Switch`|`Root`, `Control`, `Thumb`, `HiddenInput`|`checked` (bindable, default `false`), `disabled`, `type` (`'button'`)|
|`Tabs`|`Root`, `List`, `Trigger`, `Content`|`value` (bindable), `orientation` (`'horizontal'`), `loop` (`true`), `disabled`|
|`Accordion`|`Root`, `Item`, `ItemTrigger`, `ItemContent`|`type` (`'single'` or `'multiple'`, required), `value` (bindable), `collapsible` (`false`)|
|`Collapsible`|`Root`, `Trigger`, `Content`, `Indicator`|`open` (bindable, default `false`), `disabled`|
|`PreferenceItem`|`Root`, `Trigger`, `Leading`, `Header`, `Title`, `Meta`, `Auxiliary`, `Control`, `Content`|`open` (bindable, default `false`), `disabled`, `noStyle`|

`Portal` renders its children into another element, `document.body` by
default. Pass `target` as an element or a selector.

## Actions

Three Svelte actions apply the same behavior to your own elements:

|Action|Use|Parameter|
|--|--|--|
|`focusTrap`|`use:focusTrap={open}`|`true`, `false`, or `{ enabled, initialFocus }`. Keeps Tab inside the element while enabled.|
|`scrollLock`|`use:scrollLock={open}`|`boolean`. Stops the page scrolling behind the element.|
|`portal`|`use:portal` or `use:portal={'#modals'}`|An element or selector, default `body`. Moves the element there and removes it when the component unmounts.|

The banner uses these three actions; the stock dialog uses `Dialog`.

## Check your custom dialog

Open it with the keyboard only. Tab and Shift+Tab stay inside it, Escape
closes it, and focus returns to the control that opened it. Each switch
announces its name and state in a screen reader. See the
[headless page](../headless) for the consent side of a custom dialog.

# Headless
URL: https://c15t.com/docs/frameworks/sveltekit/headless
Replace the c15t banner or preference dialog with your own markup in a SvelteKit app while the provider keeps policy, storage and script loading.

## Choose how much to replace

Try [customization](/docs/customization/overview) first: tokens, slots,
`presentation` and translations change most banners without new markup. Go
headless when you need markup the stock components cannot produce.

|Goal|Approach|
|--|--|
|Keep the markup, drop c15t's styles|Set `noStyle` on the provider or on one component, and style the `data-*` attributes and slot classes.|
|Your own banner, stock dialog|`getHeadlessConsent()` for the banner, `ConsentDialog` for preferences. This page's example.|
|Your own dialog too|Add `getConsentManager()` for the category list and the draft.|

The provider, scripts, `ConsentGate` and the stored choice work the same with
any of them. You only replace the markup.

## Build a banner with getHeadlessConsent

`getHeadlessConsent()` returns the banner and dialog state and one method per
action. Call it at the top level of a component inside
`ConsentProvider`.

This banner renders the actions the policy allows, grouped and ordered the way
the policy asks, and hides itself when no banner is due:

```svelte title="src/lib/custom-consent-banner.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Customize',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};
</script>

{#if consent.banner.isVisible}
	<section class="custom-consent-banner" aria-label="Cookie consent">
		<p>
			We use cookies to measure traffic and show ads. Choose which ones can run.
		</p>
		<!-- The policy decides which actions this visitor gets, and in what order. -->
		{#each consent.banner.actionGroups as group, index (index)}
			<div>
				{#each group as action (action)}
					<button type="button" onclick={() => consent.performAction(action)}>
						{labels[action]}
					</button>
				{/each}
			</div>
		{/each}
	</section>
{/if}

<style>
	.custom-consent-banner {
		position: fixed;
		inset: auto 1rem 1rem;
		max-width: 32rem;
		padding: 1rem;
		border: 1px solid currentColor;
		border-radius: 0.5rem;
		background: white;
	}
	.custom-consent-banner div {
		display: flex;
		gap: 0.5rem;
		margin-top: 0.5rem;
	}
</style>
```

Render it where the stock `ConsentBanner` would go. The stock dialog still
handles Customize and the preferences link, so keep `ConsentDialog`. It adds
its own rules when it opens:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import {
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		hosted,
	} from '@c15t/svelte';

	import CustomConsentBanner from '#lib/custom-consent-banner.svelte';
	import { scripts } from '#lib/scripts.js';

	let { children } = $props();

	const mode = hosted({ backendURL: 'https://your-project.inth.app' });
</script>

<ConsentProvider {mode} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<CustomConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

In a Svelte app without SvelteKit, the same markup goes in the component that
renders the provider.

|Member|Purpose|
|--|--|
|`banner.isVisible`, `dialog.isVisible`|Whether that surface is due now.|
|`banner.actionGroups`, `banner.orderedActions`|The allowed actions, grouped or flat, in the order the policy asks for.|
|`banner.requiredActions`, `banner.primaryActions`|Actions you must show, and those to emphasize.|
|`banner.variant`, `banner.position`, `banner.blocking`|The resolved shape, position and blocking behavior, if you want to follow them.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`performAction(action)`|`accept`, `reject`, `dismiss`, `save` or `customize`. Customize opens the dialog.|
|`openBanner()`, `openDialog()`, `closeUI()`|Show or hide a surface.|
|`saveCustomPreferences()`|Record the dialog's draft.|

Render from `actionGroups` or `orderedActions` rather than a fixed list. A
policy can require a reject button next to accept, or offer only a dismiss
button for a notice, and a hard-coded pair of buttons breaks those rules.

## Build your own preferences

For a custom dialog or settings page, read the category list and the unsaved
draft from `getConsentManager()`:

```svelte title="src/lib/cookie-preferences.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
	const config = $derived(consent.translationConfig);
	const copy = $derived(config.translations[config.defaultLanguage ?? 'en']);
</script>

{#if consent.draft.isStale}
	<p role="alert">The cookie policy changed. Review your choices.</p>
{/if}
<fieldset>
	<legend>Cookie preferences</legend>
	{#each consent.getDisplayedConsents() as category (category.name)}
		<label>
			<input
				type="checkbox"
				checked={consent.selectedConsents[category.name] ?? false}
				disabled={category.name === 'necessary'}
				onchange={(event) =>
					consent.setConsent(category.name, event.currentTarget.checked)}
			/>
			{copy?.consentTypes?.[category.name]?.title ?? category.name}
		</label>
	{/each}
</fieldset>
<button
	type="button"
	disabled={consent.draft.isStale}
	onclick={() => consent.saveConsents('custom')}
>
	Save preferences
</button>
```

`setConsent` changes the draft only. `saveConsents('custom')` records it. If
the policy changes while the draft is open, `consent.draft.isStale` becomes
`true` and saving throws, so the example disables Save and shows a message.
Translated titles and descriptions are in `consent.translationConfig`.
[Context getters](./getters#work-with-the-draft) covers the draft.

`@c15t/svelte` exports `Dialog`, `Switch`, `Accordion`, `PreferenceItem` and
the `focusTrap`, `scrollLock` and `portal` actions if you want accessible
building blocks for the dialog itself; see [primitives](./components/primitives).

## Verify a custom UI

Run the same checks as the stock components: reject, reload and confirm no
optional vendor requests; allow one category and confirm only its vendors
load; reopen preferences from your footer link. Test keyboard focus and a
screen reader on your markup, because c15t no longer owns it.
[Verify consent](/docs/guides/verify-consent) has the full list.

# Components
URL: https://c15t.com/docs/frameworks/sveltekit/components
Props and behavior of every @c15t/svelte component in a SvelteKit app, from ConsentRoot and ConsentBanner to ConsentGate and DevTools.

[`ConsentRoot`](./components/consent-root) renders `ConsentProvider` from
the state `loadConsent` returned, so the banner is in the server HTML. Mount
it once, in the root `+layout.svelte`; every other component renders inside
it.

## Every component

Import every component from `@c15t/svelte`, except the dev tools panel,
which comes from `@c15t/svelte/devtools`. Render them inside the provider:
`ConsentProvider` in a Svelte app, or `ConsentRoot`, which renders
`ConsentProvider`, in a SvelteKit root layout. A component outside it throws
`c15t: no v3 consent context`.

|Component|Renders|Page|
|--|--|--|
|`ConsentBanner`|The first-layer banner when the policy asks for one.|[ConsentBanner](./components/consent-banner)|
|`ConsentDialog`|The preference dialog, loaded on first use.|[ConsentDialog](./components/consent-dialog)|
|`ConsentWidget`|The preference controls inline, for a settings page.|[ConsentWidget](./components/consent-widget)|
|`ConsentDialogLink`|An unstyled button that opens preferences, for your footer.|[ConsentDialogLink](./components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens preferences.|[ConsentDialogTrigger](./components/consent-dialog-trigger)|
|`ConsentGate`|Its children only while a category is allowed.|[ConsentGate](./components/consent-gate)|
|`ConsentButton`|A button that accepts, rejects, saves or opens preferences.|[ConsentButton](./components/consent-button)|
|`IABConsentBanner`|The IAB TCF banner, for visitors under an IAB policy.|[IABConsentBanner](./components/iab-consent-banner)|
|`IABConsentDialog`|The IAB TCF preference center.|[IABConsentDialog](./components/iab-consent-dialog)|
|`ConsentDevTools`|A development panel for the consent state.|[Dev tools](./components/dev-tools)|
|`Dialog`, `Switch`, `Tabs` and others|Unstyled building blocks for your own UI.|[Primitives](./components/primitives)|

`DevTools` and `C15TDevTools` are aliases for `ConsentDevTools`.

## Styles

There is no stylesheet to import. Each stock component adds the rules it
uses to `<head>` as a `<style>` element, once per page, before its own
elements render. On a server-rendered SvelteKit page, `c15tHandle` writes the
banner's rules into the HTML, so the banner is styled before hydration. The
dialog's rules, including the primitives', load with the dialog's code.

The IAB TCF banner and dialog also add their own rules. The IAB dialog adds
its rules when it opens, and includes the base rules it needs when rendered
without a banner. Pages without IAB components do not load the IAB sheets.

To run the stylesheet through Tailwind CSS 3 or put it in a named cascade
layer, set `styles={false}` on the provider and import
`@c15t/svelte/styles.css`. With IAB TCF, also import
`@c15t/svelte/iab/styles.css` after the base stylesheet;
[stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when.

## When components render nothing

Every consent surface stays hidden until a policy resolves for the visitor,
and again when the resolved policy asks for no prompt and grants no way to
change preferences. A missing banner or link is usually a policy result, not
a rendering bug. See
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

## Shared props

Several props mean the same thing on every component:

|Prop|Behavior|
|--|--|
|`noStyle`|Renders the same markup and behavior without c15t's classes. Set it on the provider for every component, or on one component.|
|`class`|Adds your class to the component's root element.|
|`hideBranding`|Hides the "Secured by" tag on the banner, dialog and widget.|
|`models`|The policy models a surface renders for: `opt-in`, `opt-out`, `iab` and `none`.|
|`legalLinks`|Which of the provider's legal links a banner or dialog shows, or `null` for none.|

Theme slots style one part of one component; [customize](./customize) lists
them.

# ConsentRoot
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-root
Mount ConsentRoot in a SvelteKit root layout with the state loadConsent returns, so the banner is in the first HTML, with every prop and its default.

## Mount ConsentRoot in the root layout

Export `loadConsent` as the root layout's server load, then pass its
`consent` to `ConsentRoot` as `state`:

```ts title="src/routes/+layout.server.ts"
export { loadConsent as load } from '@c15t/svelte/kit';
```

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

Pass `data.consent` through unchanged. It holds the visitor's
server-resolved consent, the mode `c15tHandle()` was given, the backend URL
and the consent route's prefix. `ConsentRoot` renders `ConsentProvider` from
it, on the server and in the browser, so both render the same banner and the
browser makes no second policy request. The [quickstart](../quickstart)
explains `c15tHandle` and `loadConsent`.

`ConsentRoot` turns the mode into a transport that loads each policy path
only when it runs. A page the server resolved ships a small transport that
saves choices, and no resolver, policy rules, snapshot or other languages.
The code to resolve the policy again in the browser, such as after a
language change or on a prerendered page, loads when it is needed.

To use a transport of your own, pass `custom()` from `@c15t/svelte` as
`ConsentRoot`'s `mode` prop. `c15tHandle()` takes only data modes.

Keep the provider in the root `+layout.svelte`. A layout stays mounted across
client-side navigation, so the runtime, the loaded scripts and the dialog
survive page changes. A provider in a page component would start again on
every navigation.

Create `scripts` and `callbacks` in the layout component, not in
`+layout.server.ts`. They hold functions, which a server load cannot send to
the browser.

## Props

Pass each option as a top-level prop, or group them in `options`. When both
set the same option, the top-level prop wins. The `ConsentManagerOptions` type
from `@c15t/svelte` lists every option. SvelteKit's `ConsentRoot` takes the
same props, except that `state` replaces `mode` and `prefetch`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`mode`|`manifest()`, `hosted()`, `offline()` or `custom()` result, all from `@c15t/svelte`|required|Where policies come from and where choices are saved. Read once; remount the provider to change it. `ConsentRoot` builds it from `state`, or takes a `custom()` transport as `mode`.|
|`prefetch`|`ConsentState`|none|Server-resolved state, such as the result of `resolveConsent`. With a resolved policy in it, the first render already knows whether to show the banner, and the browser skips its own policy request. `ConsentRoot` passes it from `state`. Read once.|
|`scripts`|`Script[]`|none|Vendor scripts that load when their category is allowed. Updates after mount: new scripts go to the loader. See [scripts](../scripts).|
|`consentCategories`|`AllConsentNames[]`|the policy's categories|Categories the preference UI offers, within the policy's scope. Updates after mount.|
|`theme`|`Theme`|none|Slot classes and `consentActions` button styles. Design tokens in it are not applied in the browser. Updates after mount.|
|`presentation`|`ConsentPresentation`|the policy's defaults|Banner and dialog shape, position, button layout and blocking for every component. Updates after mount.|
|`legalLinks`|`LegalLinks`|none|Privacy policy, cookie policy and terms links shown in the banner and dialog. Updates after mount.|
|`i18n`|`Partial<I18nConfig>`|bundled English|Copy overrides per language. They win key by key over the backend's copy for the same language; see [translations](../translations). Read once.|
|`colorScheme`|`'light'`, `'dark'`, `'system'` or `null`|none|Toggles the `c15t-dark` class on `<html>`. `null` or unset leaves `<html>` alone. Updates after mount.|
|`noStyle`|`boolean`|`false`|Renders every component without c15t's classes. A component's own `noStyle` wins.|
|`disableAnimation`|`boolean`|follows `prefers-reduced-motion`|Turns off enter and exit transitions.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Defaults for the banner and dialog. `blocking` on a component sets both.|
|`preloadDialog`|`'idle'` or `'intent'`|`'idle'`|When `ConsentDialog` starts loading before its first open. See [ConsentDialog](./consent-dialog).|
|`networkBlocker`|options or `false`|off|Holds `fetch` and XHR requests to listed domains until their category is allowed. Updates after mount: new rules and `enabled` apply, and `false` removes the blocker. The blocker loads on demand. See [network blocker](../network-blocker).|
|`iframeBlocker`|`{ disableAutomaticBlocking?: boolean }` or `false`|on|Gates iframes that carry `data-category`. Updates after mount: `false` removes the blocker and a new `disableAutomaticBlocking` rebuilds it. See [embeds](../embeds).|
|`iab`|`ProviderIABOptions` or `false`|off|IAB TCF settings. Read once. See [IAB TCF](../iab).|
|`callbacks`|`ConsentProviderCallbacks`|none|`onChoiceRecorded`, `onPermissionsChanged`, `onError` and `onBeforeConsentRevocationReload`. The latest functions are called. See [callbacks](../callbacks).|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reloads the page after a save withdraws a category or vendor that was granted.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|Forces the location, language or Global Privacy Control signal the policy resolves for. A change after mount resolves the policy again.|
|`user`|`User`|none|Identity sent with the policy request and every saved choice, so the choice is linked to your user ID. A different user after mount is identified with the backend; the user you mount with is not identified separately.|
|`storageConfig`|`StorageConfig`|cookie and key `c15t`|Names and lifetime of the stored choice. Read once. On SvelteKit, pass the same name as `cookieName` to the server helpers.|
|`persistence`|`boolean` or options|`true`|`false` keeps choices in memory only. Read once.|
|`clearOnRevocation`|`ClearOnRevocationConfig`|off|Deletes first-party cookies and storage entries when their category is withdrawn. Loads on demand. See [clearing data on revocation](../clear-on-revocation). Read once.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. See [vendor consent](../vendor-consent). Updates after mount: a new list replaces the declared vendors.|
|`nonce`|`string`|none|Content Security Policy nonce for the `<script>` elements the script loader adds. See [Content Security Policy](../content-security-policy). Read when the loader starts.|
|`enabled`|`boolean`|`true`|`false` grants every category, hides all consent UI and skips `/init`. Updates after mount: turning it off renders a separate permissive state and keeps the visitor's stored choice for when it is turned back on.|
|`runtime`|`ConsentRuntime`|none|A runtime you created with `createConsentRuntime()`. See [share one runtime](#share-one-runtime).|
|`options`|`ConsentManagerOptions`|none|The same options as one object.|
|`children`|`Snippet`|none|Your app. The provider renders no markup of its own.|

"Read once" options are read when the provider is created. Changing them later
has no effect until the provider remounts, and outside production a change to
`mode`, `i18n` or `experiment` logs a warning. Options that update after mount
are compared with their previous values, so a new `options` object that only
changes `theme` sends no request. The provider has no `policyRules`
option. For local policy rules, pass `offline({ policyRules })` as `mode`.

## What the provider does when it mounts

The provider creates the consent runtime while the component initializes, on
the server and in the browser. Creating it has no side effects, so the server
can render the banner from `prefetch`. In the browser, `onMount` starts the
runtime:

1. It reads the stored choice from the cookie and local storage.
2. It starts the script loader, the iframe blocker and, if configured, the
   network blocker and the IAB TCF add-on.
3. It resolves the policy with its `mode`, unless `prefetch` already holds
   one.

When the provider unmounts, it stops all of them. Keep one provider at the root of the app, so it stays mounted across
navigation and every component can reach it.

With `networkBlocker`, matching requests are held from the moment the provider
is created in the browser, before its children run their own code, until the
blocker decides them.

## Share one runtime

Pass `runtime` when two component trees that cannot share Svelte context need
the same consent state. Create it with `createConsentRuntime()` from
`@c15t/svelte`, pass it to each provider, and call `runtime.start()` and
`runtime.dispose()` yourself. A provider never starts or disposes a runtime it
did not create. Options that build the runtime, such as `mode`, `scripts` and
`callbacks`, come from your `createConsentRuntime()` call; display options such
as `theme` and `noStyle` still apply per provider.

## Verify the provider

Open the page in a private window with DevTools open:

1. The banner appears once the policy resolves. `window.c15t` in the console
   shows `pkg: '@c15t/svelte'`.
2. The Network panel shows the request your mode makes: none for
   `manifest()` with a bundled snapshot, one `/init` for `hosted()`, and
   none when the page came with a server-resolved state.
3. A component that calls `getConsentManager()` renders without the
   `c15t: no v3 consent context` error.

# ConsentBanner
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-banner
Show the c15t cookie banner in SvelteKit server HTML with ConsentBanner, and set its variant, position, button layout, copy, accessibility and styling hooks.

## Render the banner

Render `ConsentBanner` once, in the root layout inside
`ConsentRoot`, next to `ConsentDialog`:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

The banner decides for itself whether to show. You do not wrap it in a
condition.

## Banner in the server HTML

When `ConsentRoot`'s `state` holds a resolved policy, SvelteKit renders the
banner into the page's HTML. It is visible at first paint, and a returning
visitor's choice applies before hydration. The entry transition runs once, at
first paint; hydration does not replay it.

The banner is not in the HTML when the page was prerendered, when
`loadConsent` fell back after a slow or failed backend, or when the visitor
already chose. The browser then shows it after hydration if it is due.
[Troubleshooting](../troubleshooting#why-is-the-banner-missing-from-the-server-html)
covers each case.

## Change the shape

`variant` and `position` set the shape for one banner. The provider's
`presentation` prop sets them for every surface; a prop on `ConsentBanner`
wins. This banner is a full-width bar along the bottom edge:

```svelte title="src/lib/cookie-banner.svelte"
<script lang="ts">
	import { ConsentBanner } from '@c15t/svelte';
</script>

<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

A notice defaults to `bar` and a choice prompt to `floating`. A position that
does not fit the variant falls back to the variant's default and logs a
warning in development. When the page's text direction is right to left and
you set no position, a corner position flips to the other side.

The [design gallery](/docs/customization/recipes) has more banner designs
with tested Svelte code.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating'`, `'bar'`, `'widget'` or `'wall'`|from the policy|Shape of the banner.|
|`position`|see the table above|the variant's default|Where the banner sits.|
|`blocking`|`boolean`|`false`|Adds a backdrop, locks scrolling, traps focus and ignores outside clicks. `wall` is always blocking; a notice never is.|
|`layout`|array of `'accept'`, `'reject'`, `'customize'`, `'dismiss'` or nested groups|from the policy|Button order and grouping, such as `[['reject', 'accept'], 'customize']`.|
|`primaryButton`|one action or an array|from the policy|Which buttons get the primary style.|
|`title`, `description`|`string`|translated copy|Replace the heading and body for this banner.|
|`acceptButtonText`, `rejectButtonText`, `customizeButtonText`, `dismissButtonText`|`string`|translated copy|Replace one button label for this banner.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description. `null` shows none.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab']`|Policy models this banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes, keeping markup and behavior.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The policy wins where it conflicts with `layout` or `primaryButton`. A policy
that requires a reject button next to accept keeps it, whatever the layout
says. For copy used across the site, use the provider's `i18n` or your
backend's translations; see [translations](../translations).

## When the banner shows

`ConsentBanner` renders when all of these are true:

* A policy has resolved for the visitor and it asks for a prompt.
* The visitor has not chosen yet, or the policy asks them to choose again.
* The active surface is the banner, not the dialog or nothing.
* The policy's model is in `models`.

A visitor in a region without a consent law, or one who already chose, gets
no banner. That is a policy result; see
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

A choice prompt shows Accept, Reject and Customize, in the order the policy
asks for. A notice, such as an opt-out policy that only informs, shows a
dismiss button and its own title and description from the `noticeTitle` and
`noticeDescription` translations. Dismissing a notice records the dismissal,
not a grant.

When the policy grants visitor rights, such as opting out of sale, the banner
shows each one as a text button that opens the preference dialog.

Accept and Reject record the choice and close the banner in the same task.
The backend request runs after; a failed request is retried and does not
reopen the banner. Customize opens `ConsentDialog`, so render the dialog too.

## Accessibility

* The banner card is a `region` labelled by the banner title. With `blocking`,
  it becomes a `dialog` with `aria-modal="true"`, and focus stays inside it
  until the visitor chooses.
* The title is an `h2`. Buttons are `<button type="button">` with their
  visible text as the accessible name.
* The banner does not move focus when it appears, unless focus trapping is on.
  Visitors reach it with Tab.
* With `prefers-reduced-motion`, the banner appears and leaves without a
  transition.
* The root sets `dir` from the active language, so right-to-left copy lays out
  correctly.

## Style the banner

`ConsentBanner` reads these theme slots from the provider's `theme` prop:
`consentBanner`, `consentBannerCard`, `consentBannerHeader`,
`consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`,
`consentBannerFooterSubGroup`, `consentBannerRights` and
`consentBannerRightLink`. [Customize](../customize) shows how to pass them.

The root element carries `data-testid="consent-banner-root"` and these
attributes for CSS and tests:

|Attribute|Value|
|--|--|
|`data-prompt`|`choice` or `notice`|
|`data-model`|`opt-in`, `opt-out` or `iab`|
|`data-variant`|the resolved variant|
|`data-position`|the resolved position|
|`data-blocking`|`true` when blocking|

Each button carries `data-action` with `accept`, `reject`, `customize` or
`dismiss`.

# ConsentDialog
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog
Add the c15t preference dialog to a SvelteKit root layout with ConsentDialog, including how it loads after hydration, its props, keyboard behavior and theme slots.

## Render the dialog

Render `ConsentDialog` once, in the root layout inside
`ConsentRoot`. The banner's Customize button and
`ConsentDialogLink` open it:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

`ConsentDialog` is never in the server HTML. It loads in the browser after
hydration, before anyone opens it, so a server-rendered page does not carry
its markup or script.

## How the dialog loads

`ConsentDialog` is not part of the first page load. The component you render
is a small loader; the dialog itself is a separate chunk that it imports:

* In browser idle time after the page's `load` event, while a button that
  opens the dialog is mounted. Those buttons are the banner's Customize button,
  `ConsentDialogLink`, `ConsentDialogTrigger`, the `ConsentGate` placeholder
  and `ConsentButton` with `action="open-consent-dialog"`.
* When such a button is hovered or focused.
* At the latest, when the dialog opens.

Set the provider's `preloadDialog` to `'intent'` to skip the idle load and
load only on hover, focus or open. Idle loading is also skipped when the
browser asks to save data, on 2G connections and offline. Every
`ConsentDialog` on the page shares one import. If the import fails, the
surface the dialog replaced comes back, and the next hover, focus or open
retries. The dialog's CSS travels with that chunk and goes into `<head>`
before the dialog renders. With `styles={false}`, it comes from your imported
`@c15t/svelte/styles.css`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself. While `open` is `true`, the dialog stays open, even after Escape.|
|`showTrigger`|`boolean` or trigger props|`false`|Renders a floating `ConsentDialogTrigger` with the dialog. Pass an object for `defaultPosition`, `persistPosition`, `showWhen`, `size`, `ariaLabel`, `noStyle` and `class`.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab', 'none']`|Policy models the dialog opens for. `none` is included so a policy with no prompt but a right to change preferences still opens it.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the dialog content.|

`ConsentDialog` has no text props. Its title and description come from the
`consentManagerDialog` translations; see [translations](../translations).

With `showTrigger`, the dialog loads when it mounts, because the trigger needs
it at once. The trigger appears right after hydration. To keep a trigger in
server HTML, render `ConsentDialogTrigger` next to the dialog instead.

## What the dialog contains

The dialog renders the heading, the description with legal links, and a
[`ConsentWidget`](./consent-widget) with one switch per category and the save
buttons the policy allows. Categories come from the provider's
`consentCategories`, limited to the policy's scope. `necessary` is always on
and cannot be switched off.

Switches change an unsaved draft. The save button records the draft; the
accept and reject buttons record every category at once. The dialog closes in the same task
the choice is recorded. If the policy changes while the dialog is open, the
widget shows an alert and asks the visitor to review before saving.

## Open and close the dialog

Anything that sets the active surface to `'dialog'` opens it: the banner's
Customize button, `ConsentDialogLink`, `ConsentDialogTrigger`,
`getConsentManager().setActiveUI('dialog')` or
`getHeadlessConsent().openDialog()`.

Escape closes the dialog. Clicks outside it do not, so a visitor cannot lose
unsaved switches by accident. Closing without saving records nothing. If the
policy still owes a choice, the banner comes back.

With the `open` prop set, your component owns visibility. Escape then moves
the active surface off `'dialog'`, to `'banner'` while a choice is still owed
or `'none'` otherwise, and the dialog stays mounted until you set `open` to
`false`. Watch `getConsentManager().activeUI` to close it.

## Accessibility

* The dialog content is labelled by its title (`aria-labelledby`) and
  described by its description (`aria-describedby`).
* While the dialog is blocking, which is the default, focus is trapped inside
  it and the page behind does not scroll. The provider's `presentation` can
  turn blocking off for the dialog.
* Each category switch is a `switch` role labelled with the category title.
* The root sets `dir` from the active language.

## Style the dialog

`ConsentDialog` reads these theme slots: `consentDialog`, `consentDialogCard`,
`consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`,
`consentDialogContent` and `consentDialogTag`. The widget inside it reads the
`ConsentWidget` slots. The content element carries
`data-testid="consent-dialog-root"` and `data-blocking="true"` while
blocking.

# ConsentWidget
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-widget
Put c15t's category switches inline on a SvelteKit privacy settings route with ConsentWidget, and how its draft, vendors and stale-policy alert behave.

## Put preferences on a page

`ConsentWidget` renders the preference controls inline: one switch per
category, an expandable description for each, and the save buttons the policy
allows. It is the same widget `ConsentDialog` shows, without the dialog
around it. Use it for a privacy settings page:

```svelte title="src/routes/privacy/+page.svelte"
<script lang="ts">
	import { ConsentWidget } from '@c15t/svelte';
</script>

<h1>Privacy settings</h1>
<p>Choose which optional cookies this site may use.</p>
<!-- The category switches and save buttons, inline on the page. -->
<ConsentWidget />
```

Render the page inside `ConsentProvider`. The widget works without
`ConsentDialog`, but keep the dialog mounted elsewhere if the banner's
Customize button should also work.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Shows the "Secured by" tag when `false`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

`ConsentWidget` renders nothing until a policy resolves and asks for consent
UI. Then it lists the provider's `consentCategories`, limited to the policy's
scope, with `necessary` always on and disabled.

Each switch starts from the visitor's recorded choice. Before a choice, a
switch is on under an opt-out policy or for a category the policy preselects,
and off otherwise. Moving a switch changes an unsaved draft
that every consent component on the page shares. The save button records the
draft; the accept and reject buttons record every category at once.

A category with declared vendors lists them under its description, each with
its own switch, so a visitor can allow a category and still turn one vendor
off. Under an IAB policy, vendor rows are not shown.

If the policy changes while the visitor has unsaved changes, the widget shows
an alert with a **Review preferences** button. Saving the stale draft fails
until the visitor reviews it, so a choice made under the old policy is never
recorded under the new one.

## Accessibility

* Each category switch has the `switch` role and the category title as its
  accessible name.
* Each category heading is a button with `aria-expanded` that opens its
  description. Opening one closes the others.
* The stale-policy message uses `role="alert"`, so screen readers announce it.

## Style the widget

`ConsentWidget` reads the `consentWidget` and `consentWidgetFooter` theme
slots. The root carries `data-testid="consent-widget-root"`, and each
category row carries `data-testid="consent-widget-accordion-item-<category>"`.

## Widget in the server HTML

With server-resolved consent from the root layout, the widget renders into the
route's HTML with the visitor's stored choices. Without one, it appears after
hydration once the policy resolves. The page title in the example is
`src/routes/privacy/+page.svelte`; any route under the root layout works.

# ConsentDialogLink
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog-link
Let visitors reopen c15t preferences from a SvelteKit layout footer with ConsentDialogLink, rendered in server HTML when the policy offers preferences.

## Reopen preferences from your footer

`ConsentDialogLink` is an unstyled button that opens the preference dialog.
Put it in the root layout's footer, so it is on every page:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

It needs `ConsentDialog` mounted in the same provider. With server-resolved
consent, the link is in the server HTML. Without one, such as on a
prerendered page, it appears after hydration once the policy resolves.

## Props

`ConsentDialogLink` takes its label as children and passes every other
attribute, such as `class`, `id` or `aria-describedby`, to the `<button>` it
renders.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`children`|`Snippet`|required|The visible label, such as "Privacy settings".|
|`noStyle`|`boolean`|`true`|Unstyled by default so it matches your footer links. Set `false` for c15t's button style.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it opening.|
|any button attribute|||Passed to the `<button>`.|

There is no `asChild`. To style it like your links, give it the same class,
and reset the button's border, background and padding in that class.

## Behavior

* The link renders only when the policy offers a way to change preferences:
  a prompt or a visitor right. Visitors in a
  region with no consent law and no rights see no link.
* A click sets the active surface to `'dialog'`. It needs a mounted
  `ConsentDialog` in the same provider to show anything.
* It starts loading the dialog chunk in browser idle time while mounted, and
  on hover or focus. See [ConsentDialog](./consent-dialog#how-the-dialog-loads).

## Accessibility

The link is a `<button type="button">`, so keyboard users reach it with Tab
and activate it with Enter or Space. Its accessible name is its text. Keep the
text specific, such as "Privacy settings" or "Cookie preferences", rather
than "Click here".

## Style the link

The button carries `data-testid="consent-dialog-link"` and
`data-c15t-rights` with the rights the policy grants, separated by spaces.
Style it with your own class; with `noStyle` on, c15t adds no classes.

# ConsentDialogTrigger
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-dialog-trigger
Add a floating, draggable privacy button to a SvelteKit layout with ConsentDialogTrigger, and set its corner, size, saved position, accessible name and callbacks.

## Add a floating privacy button

`ConsentDialogTrigger` is a small round button, fixed to a corner of the
viewport, that opens the preference dialog. It keeps preferences one click
away on every page without a footer link. Render it next to `ConsentDialog`:

```svelte title="src/lib/privacy-trigger.svelte"
<script lang="ts">
	import { ConsentDialog, ConsentDialogTrigger } from '@c15t/svelte';
</script>

<!-- A floating button in the bottom-left corner that opens preferences.
     Visitors can drag it to another corner; c15t remembers where. -->
<ConsentDialogTrigger defaultPosition="bottom-left" size="sm" />
<ConsentDialog />
```

Render the component inside `ConsentProvider`. `ConsentDialog`'s
`showTrigger` prop renders the same button for you, but only after the dialog
chunk loads; a separate `ConsentDialogTrigger` is part of the page from the
first render.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`defaultPosition`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner it starts in.|
|`persistPosition`|`boolean`|`true`|Remembers the corner a visitor drags it to, in local storage.|
|`showWhen`|`'always'` or `'never'`|`'always'`|`'never'` hides it.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name. Translate it yourself; it does not come from `i18n`.|
|`noStyle`|`boolean`|`false`|Drops c15t's classes, including the fixed positioning.|
|`class`|`string`|none|Extra class on the button.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it.|
|`onPositionChange`|`(corner) => void`|none|Runs after a drag moves it to another corner.|

## Behavior

* The button renders only when the policy offers a way to change preferences,
  and hides while the dialog is open.
* Visitors can drag it. On release it snaps to the nearest corner in the
  direction of the drag. A drag does not open the dialog; a click does.
* The icon follows the project's branding.
* It is rendered into `document.body`, so a parent's `overflow` or
  `transform` does not clip it.
* It starts loading the dialog chunk in idle time and on hover or focus, like
  the other buttons that open the dialog.
* While `ConsentDevTools` is mounted, it becomes a two-button toolbar: the
  preferences button stays in the corner and a DevTools button sits beside it.
  The DevTools panel opens next to the toolbar instead of from its own
  launcher. See [DevTools](./dev-tools).

## Accessibility

The trigger is a `<button type="button">` with `aria-label`, since it shows
only an icon. Keep the label in the page's language by passing `ariaLabel`.
Dragging needs a pointer; keyboard users activate it with Enter or Space and
cannot move it, so pick a `defaultPosition` that does not cover your own
controls.

## Style the trigger

The button carries `data-testid="consent-dialog-trigger"`,
`data-c15t-trigger="true"` and `data-c15t-rights`. Its colors come from the
`--c15t-*` tokens; [theme tokens](/docs/customization/tokens) lists them.

## Trigger in the server HTML

Rendered in the root layout with server-resolved consent, the trigger is in the
server HTML at its default corner. After hydration it moves to
`document.body` and, if the visitor dragged it on an earlier visit, to the
saved corner.

# ConsentGate
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-gate
Keep a YouTube video or map out of SvelteKit server HTML until its consent category is allowed with ConsentGate, and replace its placeholder.

## Gate an embed behind consent

`ConsentGate` mounts its children only while one category is allowed, and
shows a placeholder otherwise. Wrap any iframe or widget that sets cookies or
contacts a vendor when it loads. Save it as its own component, for example
in `src/lib`, and render it from any route:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

`ConsentDialog` must be mounted in the root layout so the placeholder's link
has a dialog to open. [Embeds](../embeds) covers iframes you cannot wrap.

## The gate on the server

`ConsentGate` renders an empty wrapper on the server, even when the visitor's
stored choice allows the category. The embed and the placeholder both appear
in the browser one frame after hydration. So an embed never reaches a cached
or prerendered page, and a visitor who has not allowed it never requests it.
Size the wrapper with `class` to avoid a layout shift.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The category whose permission the content needs, such as `'measurement'` or `'marketing'`.|
|`children`|`Snippet`|none|The gated content. It is not in the DOM until the category is allowed.|
|`placeholder`|`Snippet`|built-in placeholder|Shown while the category is denied.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes from the built-in placeholder.|
|`class`|`string`|none|Class on the wrapper `<div>` that stays in the page in every state.|

## Behavior

`ConsentGate` renders a `<div>` wrapper. Inside it, it renders the children
while the visitor's effective permission for `category` is granted, and the
placeholder otherwise. The permission is the same value as
`getConsentManager().has(category)`. It can be granted before the visitor
chooses, under an opt-out policy, and a recorded grant can be overridden by a
privacy signal such as Global Privacy Control.

* While the category is denied, the children are absent from the DOM, so an
  iframe inside sends no request.
* When the visitor allows the category, the children mount. No reload.
* When the visitor withdraws it, the children unmount and the embed stops.
* Until the component has mounted in the browser, the wrapper is empty. The
  server HTML never contains the children or the placeholder, and the browser
  fills the wrapper one frame after mount.

The built-in placeholder shows `Accept {category} consent to view this content.`
and a button labelled `Enable {category} consent`, with the category's
translated title in place of `{category}`. The copy comes from the
`consentGate.title` and `consentGate.actionButton` translations. The button opens the
preference dialog; it does not grant the category, so mount `ConsentDialog`
in the same provider.

`ConsentGate` does not add its category to the preference dialog. Keep the
category in your policy's scope, and in `consentCategories` if you set that
prop.

## Accessibility

The built-in placeholder is plain text and a `<button>`, so it works without
the embed. Give the iframe a descriptive `title`, and give visitors who
decline another way to the content, such as a link to the video's page or a
store address next to the map. A category the policy blocks cannot be allowed
from preferences.

## Style the placeholder

Set `class` on `ConsentGate` to size the wrapper to the embed, for example an
`aspect-ratio` for a video, so the page does not shift when the embed
replaces the placeholder.

To restyle the built-in placeholder, set the `consentGate` slot for the card,
`consentGateTitle` and `consentGateButton` in the provider's `theme.slots`.
`consentGateButton` applies on top of `buttonPrimary`:

```ts
const theme = {
	slots: {
		consentGate: 'brand-gate',
		consentGateButton: { className: 'brand-gate-button' },
	},
};
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`. For a different design, pass your own
`placeholder` snippet.

# ConsentButton
URL: https://c15t.com/docs/frameworks/sveltekit/components/consent-button
Accept, reject, save or open preferences from SvelteKit pages with ConsentButton, and what each action records.

## Put consent actions on your own pages

`ConsentButton` is a button that performs one consent action, styled like the
banner's buttons. Use it on a cookie policy page, an onboarding step or
anywhere visitors should accept, reject or open preferences outside the
banner:

```svelte title="src/lib/cookie-choices.svelte"
<script lang="ts">
	import { ConsentButton, ConsentDialog } from '@c15t/svelte';
</script>

<section aria-labelledby="cookie-choices">
	<h2 id="cookie-choices">Cookie choices</h2>
	<ConsentButton action="accept-consent" variant="primary" mode="filled">
		Accept all
	</ConsentButton>
	<ConsentButton action="reject-consent">Reject optional</ConsentButton>
	<ConsentButton action="open-consent-dialog" mode="ghost">
		Choose cookies
	</ConsentButton>
</section>
<ConsentDialog />
```

Render it inside `ConsentProvider`. A button with
`action="open-consent-dialog"` needs a mounted `ConsentDialog`.

## Props

`ConsentButton` also passes any `<button>` attribute through, such as `id`,
`disabled` or `aria-describedby`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`action`|see below|required|What the click does.|
|`category`|`AllConsentNames`|none|The category `set-consent` switches on.|
|`variant`|`'primary'` or `'neutral'`|`'neutral'`|Color emphasis.|
|`mode`|`'filled'`, `'stroke'`, `'lighter'` or `'ghost'`|`'stroke'`|Fill style.|
|`size`|`'medium'`, `'small'`, `'xsmall'` or `'xxsmall'`|`'small'`|Button size.|
|`closeConsentBanner`, `closeConsentDialog`|`boolean`|`false`|Close both surfaces after `dismiss-notice`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs first. Call `event.preventDefault()` to skip the action.|
|`children`|`Snippet`|none|The label.|

|`action`|Effect|
|--|--|
|`accept-consent`|Records every category in scope as allowed.|
|`reject-consent`|Records only `necessary`, rejecting the rest.|
|`custom-consent`|Records the current draft, as the dialog's save button does.|
|`dismiss-notice`|Records that the visitor dismissed a notice. Not a grant.|
|`open-consent-dialog`|Opens the preference dialog.|
|`set-consent`|Switches `category` on in the unsaved draft. Nothing is recorded until a save.|

## Behavior

Accept, reject and save record the choice in the same task as the click, and
the banner or dialog that showed closes. The backend request runs after. A
failed request is reported through the provider's `onError` callback and
retried; the click handler does not throw. A save refused because the policy
changed keeps the dialog open for review.

A button with `open-consent-dialog` starts loading the dialog chunk in idle
time while mounted, and on hover or focus.

## Accessibility

`ConsentButton` renders `<button type="button">` with its children as the
accessible name. Write labels that say what happens: "Accept all" records a
choice, "Choose cookies" opens preferences. Do not label a notice dismissal
"Accept". [Copy and translations](/docs/customization/translations#write-labels-that-describe-the-action)
has more guidance.

## Style the button

The button uses c15t's button classes and the `buttonPrimary` or
`buttonSecondary` theme slot, by `variant`. It carries `data-variant`,
`data-mode` and `data-size` for CSS. With `noStyle`, it renders with only
your `class` and none of those attributes.

# IABConsentBanner
URL: https://c15t.com/docs/frameworks/sveltekit/components/iab-consent-banner
Show the IAB TCF 2.4 first-layer banner to visitors under an IAB policy in a SvelteKit app with IABConsentBanner, its props and behavior.

## Show the TCF banner

`IABConsentBanner` is the first layer of the IAB TCF 2.4 consent flow. It
lists the purposes, special features and number of vendors from the Global
Vendor List, and offers Accept All, Reject All and Customize. It renders only
for visitors whose resolved policy uses the `iab` model, so render it next to
the standard `ConsentBanner`, which covers everyone else:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

Turn IAB on with the provider's `iab` prop first; [IAB TCF](../iab) covers the
CMP ID, the vendor list and the provider options.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'accept'`, `'reject'` or `'customize'`|`'customize'`|Which button gets the primary style.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models the banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The banner has no text props. Its copy comes from the IAB translations, in the
visitor's language.

## Behavior

* The banner stays hidden until an IAB policy resolves and the vendor list is
  available. Forcing it does not create either.
* Accept All and Reject All record the visitor's TCF choice and write the TC
  String. The banner closes as soon as the click is handled. It comes back
  only if nothing could be recorded, such as when the vendor list failed to
  load, so the visitor can try again. A failed backend request never reopens
  it.
* Customize opens `IABConsentDialog`, so render it too. The partners link in
  the description opens the dialog on the vendors tab.
* The `__tcfapi` function is available once the TCF add-on loads, whether or
  not the banner is showing, so vendor scripts can read the TC String.

## Accessibility

The banner card is a `region` labelled with the banner title. When focus
trapping is on, through `trapFocus` or a blocking presentation, it becomes a
`dialog` with `aria-modal="true"`. The title is an `h2`, and every control is
a native `<button>`.

## Style the banner

`IABConsentBanner` reads the `iabConsentBanner` theme slot and needs
`@c15t/svelte/iab/styles.css`, loaded after `@c15t/svelte/styles.css`, with
`styles={false}` on the provider.
Buttons carry `data-testid="iab-consent-banner-accept-button"`,
`iab-consent-banner-reject-button` and `iab-consent-banner-customize-button`.

## IAB banner in the server HTML

With a server-resolved IAB policy in `ConsentRoot`'s `state`, `IABConsentBanner` renders
into the server HTML. The browser then fetches the Global Vendor List from the
route the server names. [IAB TCF](../iab#iab-on-the-server) covers the server
side.

# IABConsentDialog
URL: https://c15t.com/docs/frameworks/sveltekit/components/iab-consent-dialog
Show the IAB TCF 2.4 preference center with purposes, features and vendors in a SvelteKit app with IABConsentDialog.

## Show the TCF preference center

`IABConsentDialog` is the IAB TCF 2.4 preference center. It has two tabs:
purposes, with stacks, special features and legitimate interest objections,
and vendors, with each vendor's purposes, data retention and privacy policy.
Render it next to `IABConsentBanner`; the banner's Customize button opens it:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself.|
|`initialTab`|`'purposes'` or `'vendors'`|`'purposes'`|The tab it opens on, for example from a "See our partners" link.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models it opens for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

* It opens when the active surface is `'dialog'` under an IAB policy, the
  same state `ConsentDialog` uses for other policies. Opening preferences
  from `ConsentDialogLink` therefore shows this dialog to IAB visitors and
  `ConsentDialog` to everyone else.
* Switches change purpose consent, legitimate interest, special feature
  opt-ins and vendor consent in the TCF state. Save writes a new TC String.
* It needs the Global Vendor List. While the list loads,
  `getConsentManager().iab.isLoadingGVL` is `true`.

## Accessibility

The preference center is a `dialog` labelled with its title, with a close
button labelled from the `common.close` translation. Escape closes it. While
it is blocking, which is the default, focus stays inside it and the page does
not scroll. The purposes and vendors tabs are keyboard-operable tabs.

## Style the dialog

It needs `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css`, with
`styles={false}` on the provider. The root carries
`data-testid="iab-consent-dialog-root"`.

# Context getters
URL: https://c15t.com/docs/frameworks/sveltekit/getters
Reference for every @c15t/svelte context getter in SvelteKit components, from reading permissions and recorded choices to saving, the draft, IAB state and events.

## Where getters work

Svelte has no consent hooks or stores. `@c15t/svelte` exports context getters
instead. Call one at the top level of a component's `<script>`, inside
`ConsentProvider`, and read its properties in markup or in `$derived`.
The properties read the provider's `$state`, so the component updates when
consent changes.

A getter uses Svelte's `getContext`, so it throws when you call it:

* in an event handler, an effect or a timer,
* in a component rendered outside the provider,
* in a plain `.ts` module.

Call it once at the top level and keep the returned object; its methods work
from event handlers later. The same getters are exported from
`@c15t/svelte/headless`.

|Getter|Returns|Use it to|
|--|--|--|
|`getConsentManager()`|`ConsentManagerState`|Read permissions and choices, and record choices. Start here.|
|`getHeadlessConsent()`|Surface state and actions|Build your own banner. See [headless](./headless).|
|`getIAB()`|`SvelteIABState` or `null`|Read or change IAB TCF consent.|
|`getConsentKernel()`|`ConsentKernel`|Subscribe to raw events or call low-level commands.|
|`getSnapshot()`|`ConsentSnapshot`|Read the full kernel snapshot once.|

## Read a permission or a recorded choice

A permission answers "may this run now?" A recorded choice answers "what did
the visitor decide?" They differ. Under an opt-out policy a category can be
allowed before the visitor chooses anything, and Global Privacy Control can
deny a category the visitor allowed. Load scripts and render optional
features from permissions; use the recorded choice only to show or report
what the visitor decided.

```svelte title="src/lib/consent-status.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	// Call getters at the top level of the component, inside the provider.
	const consent = getConsentManager();

	// A permission: may measurement code run now?
	const measurementAllowed = $derived(consent.has('measurement'));
	// A recorded choice: what did the visitor decide? `null` until they choose.
	const measurementChoice = $derived(
		consent.explicitChoice?.categories.measurement?.value
	);
</script>

<dl>
	<dt>Measurement may run</dt>
	<dd data-testid="measurement-permission">
		{measurementAllowed ? 'Yes' : 'No'}
	</dd>
	<dt>Visitor's measurement choice</dt>
	<dd data-testid="measurement-choice">
		{measurementChoice === undefined
			? 'Not chosen'
			: measurementChoice
				? 'Allowed'
				: 'Denied'}
	</dd>
</dl>
```

Before the visitor chooses, this component shows "No" and "Not chosen".
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

|Property or method|Answers|
|--|--|
|`has(condition)`|Whether a category, or a condition such as `{ and: ['measurement', 'marketing'] }` or `{ or: [...] }`, is allowed now.|
|`effectivePermissions`|Every category's permission, such as `effectivePermissions.measurement`.|
|`explicitChoice`|The visitor's recorded choice, or `null` before they choose. `explicitChoice.categories.measurement.value` is one category's answer.|
|`noticeDismissal`|Whether and when a notice was dismissed. Dismissing a notice is not consent.|
|`privacySignals`|Signals from the browser, such as `privacySignals.gpc.detected`.|
|`restrictions`|Per category, the reasons a recorded grant is overridden, such as GPC.|
|`vendorChoice`, `selectedVendors`|Recorded and draft grants for individual vendors outside IAB.|

## Read the policy and the UI state

|Property|Value|
|--|--|
|`hasPolicy`|`true` once a policy resolved for the visitor. Optional categories stay denied until then.|
|`policyPending`|`true` while the policy request is in flight.|
|`policyRule`|The resolved rule: `model`, `prompt`, `scope`, `rights` and more.|
|`resolution`|The resolution outcome, with `status` of `matched`, `failed` or another state.|
|`model`|`'opt-in'`, `'opt-out'`, `'iab'` or `'none'`.|
|`promptRequirement`|Whether the visitor owes a choice, a notice acknowledgement or nothing.|
|`hasConsentUi`|Whether the policy calls for any consent surface.|
|`hasConsentPreferences`|Whether a way back to preferences should show. `ConsentDialogLink` renders on this.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`location`|The country and region the policy resolved for.|
|`overrides`|The forced country, region, language or GPC value, if any.|
|`consentCategories`, `consentTypes`|The categories the preference UI offers, as names and as full definitions.|
|`translationConfig`, `translations`|The active copy and language.|
|`legalLinks`, `presentation`|The provider's `legalLinks` and `presentation` props.|
|`user`, `subject`|The identified user and the backend's subject for this visitor.|

## Record a choice

Call the methods from event handlers. Save methods return a promise.

```svelte title="src/lib/privacy-controls.svelte"
<script lang="ts">
	import { ConsentDialog, getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();

	// Record one category from your own button. setConsent changes the draft;
	// saveConsents('custom') records it.
	const allowAnalytics = async () => {
		consent.setConsent('measurement', true);
		await consent.saveConsents('custom');
	};
</script>

<button type="button" onclick={() => consent.setActiveUI('dialog')}>
	Privacy settings
</button>
<button type="button" onclick={allowAnalytics}> Allow analytics </button>
<ConsentDialog />
```

Clicking **Allow analytics** records measurement as allowed and leaves the
other categories as they were. **Privacy settings** opens the dialog.

|Method|Effect|
|--|--|
|`setActiveUI(surface)`|`'dialog'` opens preferences, `'banner'` shows the banner, `'none'` closes the open surface. Closing preferences brings the banner back while the policy still owes a choice. Records nothing.|
|`setConsent(category, value)`|Changes one category in the unsaved draft. `setSelectedConsent` is the same method.|
|`setSelectedVendor(vendorId, granted)`|Changes one vendor in the draft. Ignored for undeclared or disabled vendors.|
|`saveConsents('custom')`|Records the draft. Throws when the policy changed since the draft started; see [the draft](#work-with-the-draft).|
|`saveConsents('all')`|Records every category in scope as allowed.|
|`saveConsents('necessary')`|Records only `necessary`, rejecting the rest.|
|`dismissNotice()`|Records that the visitor dismissed a notice. Only works while a notice is due.|
|`setLanguage(code)`|Switches the language and resolves the policy again for it.|
|`getDisplayedConsents()`|The categories to render in your own preference UI.|
|`getDisplayedVendors(category)`|The vendors to list under one category. Empty under an IAB policy.|
|`isVendorAllowed(vendorId)`|`true` while a declared vendor's category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`subscribeToConsentChanges(listener)`|Calls `listener` with the permissions after every snapshot change. Returns an unsubscribe function.|

A save updates permissions in the same task, so registered scripts and
`ConsentGate` react before the backend request finishes. A failed request is
kept and retried; it does not undo the choice, and the provider's `onError`
callback reports it. When a save withdraws a category that was granted, the
provider reloads the page by default so code that already ran is gone. Set
`reloadOnConsentRevoked={false}` on the provider to handle that yourself.

Only call save methods from a visitor's action. Saving on page load records a
choice the visitor never made.

## Work with the draft

`consent.draft` is the unsaved state every preference surface on the page
shares: the dialog, `ConsentWidget` and your own UI.

|Member|Behavior|
|--|--|
|`values`|Each category's draft value. Starts from the recorded choice, or from the policy's defaults before a choice. A choice saved elsewhere moves the values the visitor has not touched. Categories outside `consentCategories` read `false`. `selectedConsents` is the same object.|
|`vendors`|Each declared vendor's draft grant.|
|`isStale`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change. A draft with no unsaved change follows the policy and is never stale.|
|`set(category, value)`, `setVendor(id, granted)`|The same as `setConsent` and `setSelectedVendor`.|
|`reset()`|Discards unsaved changes.|

The draft's code loads with the first preference surface, so a page that
only shows the banner does not ship it. `ConsentWidget` and `ConsentDialog`
bring it with them, and their switches render seeded on the first render,
on the server too. Headless code that reads or writes the draft without
either one starts the load itself: until it lands, `values` and `vendors`
are empty objects and `isStale` is `false`, and they update reactively once
it does. Writes made before then apply in order, `draft.reset()` drops
them, and `saveConsents('custom')` waits for the draft before it records.

When `isStale` is `true`, `saveConsents('custom')` throws "The policy changed.
Review your preferences before saving." Show the visitor the current
categories, call `draft.reset()`, and let them save again.

## Read and change IAB TCF consent

`getConsentManager().iab` is the live IAB state, or `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it; read `.iab` on
the manager for values that update.

|Member|Value or effect|
|--|--|
|`config.enabled`, `config.cmpId`|Whether the add-on is on, and the CMP ID.|
|`gvl`, `isLoadingGVL`|The Global Vendor List, and whether it is still loading.|
|`purposeConsents`, `vendorConsents`, `specialFeatureOptIns`|The visitor's TCF choices, staged or saved.|
|`tcString`|The saved TC String, or `null`.|
|`nonIABVendors`|Custom vendors outside the IAB list.|
|`acceptAll()`, `rejectAll()`|Accept All sets vendor and purpose consent for declared consent purposes, separate vendor and purpose legitimate-interest signals for declared legitimate-interest purposes, and opt-ins for declared special features. Reject All clears these signals.|
|`setPurposeConsent(id, value)`, `setPurposeLegitimateInterest(id, value)`|Change one purpose.|
|`setVendorConsent(id, value)`, `setVendorLegitimateInterest(id, value)`|Change one vendor.|
|`setSpecialFeatureOptIn(id, value)`|Change one special feature.|
|`save()`|Writes the TC String and records the choice.|
|`preferenceCenterTab`, `setPreferenceCenterTab(tab)`|The tab `IABConsentDialog` shows.|

Until the TCF add-on finishes loading, the action methods queue and replay.
See [IAB TCF](./iab) for setup.

## Listen to consent events

`getConsentKernel()` returns the consent kernel behind the provider. Its
`events.on(type, listener)` subscribes to one event and returns an
unsubscribe function. Subscribe in `$effect` so Svelte removes the listener
when the component unmounts:

```svelte title="src/lib/consent-events.svelte"
<script lang="ts">
	import { getConsentKernel } from '@c15t/svelte';

	// Read the kernel at the top level; subscribe in an effect so the
	// listener is removed when the component unmounts.
	const kernel = getConsentKernel();
	let lastRecorded = $state<string | null>(null);

	$effect(() =>
		kernel.events.on('choice:recorded', ({ snapshot }) => {
			const { measurement } = snapshot.effectivePermissions;
			lastRecorded = measurement ? 'measurement allowed' : 'measurement denied';
		})
	);
</script>

<p data-testid="last-recorded">
	{lastRecorded ?? 'No choice recorded on this page yet'}
</p>
```

`choice:recorded` fires for an explicit accept, reject or save.
`permissions:changed` fires for any change to what may run. For callbacks that
cover the whole app, use the provider's `callbacks` prop instead; see
[callbacks](./callbacks).

The kernel also has `subscribe(listener)`, which runs on every snapshot
change, `getSnapshot()`, and `commands` for `init()`, `save()`,
`dismissNotice()` and `identify()`. Prefer the manager's methods; they keep
the draft and the open surface in step, which the raw commands do not.
`getSnapshot()` from `@c15t/svelte` returns the snapshot at the moment you
call it and does not update.

## Other exports

|Export|Purpose|
|--|--|
|`manifest()`|The `mode` that resolves the policy in the browser from the manifest `consentManifest()` downloaded.|
|`hosted({ backendURL })`|The `mode` that asks an Inth or self-hosted backend's `/init` for every visitor.|
|`offline({ policyRules })`|The `mode` that resolves policies in the browser with no backend. Not recommended for production environments.|
|`custom(transport)`|The `mode` for your own transport.|
|`createConsentRuntime(options)`|Creates a runtime to share between providers, through their `runtime` prop.|
|`resolveConsentPresentation(input)`|Resolves the banner or dialog shape and actions a policy asks for, as `getHeadlessConsent()` does.|
|`defaultTranslationConfig`, `mergeTranslationConfigs`, `prepareTranslationConfig`, `detectBrowserLanguage`|Translation helpers.|

## Read consent on the server

Getters run in components. On the server there is no provider, only the
state `loadConsent` returns, or `event.locals.c15t.config` when `c15tHandle`
is installed. That state is the input the provider starts from. It holds the
stored records, the request's location and GPC, and the resolved policy when
the backend answered. It holds no computed permissions, so gate vendors in the browser
through `scripts` and the getters on this page.
[Rendering and deployment](/docs/frameworks/sveltekit/rendering#resolve-request-context-once-with-c15thandle)
covers `c15tHandle`.

# Callbacks
URL: https://c15t.com/docs/frameworks/sveltekit/callbacks
Run your own code in a SvelteKit app when a visitor records a choice or permissions change, with onChoiceRecorded, onPermissionsChanged and script callbacks.

## Pick the right callback

Run your own code when consent changes through the provider's `callbacks`
prop, a script's own callbacks, or a kernel event in one component:

|You want to|Use|
|--|--|
|Send a choice to your analytics or CRM when the visitor makes one|`callbacks.onChoiceRecorded`|
|Start or stop your own code when what may run changes|`callbacks.onPermissionsChanged`|
|Report failed backend requests|`callbacks.onError`|
|Show a message or flush data before a withdrawal reloads the page|`callbacks.onBeforeConsentRevocationReload`|
|Call a vendor's own consent API after its script loads|The script's `onConsentChange`|
|React to consent inside one component|`getConsentKernel().events.on()` or the manager's properties|

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only when the visitor accepts, rejects or saves.
`onPermissionsChanged` runs whenever effective permissions change, whatever
the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|Policy resolves under opt-out and allows categories before a choice|No|Yes|
|Global Privacy Control overrides a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent records and audit trails, because it fires
only for a visitor's action. Use `onPermissionsChanged` to start or stop code,
because it covers every way a permission changes. Never treat
`onPermissionsChanged` as proof that the visitor agreed to something.

## Pass callbacks to the provider

```ts title="src/lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from '@c15t/svelte';

// Pass as `callbacks={callbacks}` on ConsentProvider.
export const callbacks: ConsentProviderCallbacks = {
	// Runs just before c15t reloads the page after a withdrawal.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// An explicit accept, reject or save. Never runs for defaults, expiry,
	// policy changes or privacy signals.
	onChoiceRecorded: ({ snapshot, confirmed }) => {
		console.info('Visitor chose', snapshot.explicitChoice, confirmed);
	},
	// A failed command, such as an /init request that could not reach the
	// backend.
	onError: ({ error }) => {
		console.warn('c15t error', error);
	},
	// Any change to what may run, whatever caused it.
	onPermissionsChanged: ({ snapshot, previous }) => {
		console.info('Permissions', previous, '->', snapshot.effectivePermissions);
	},
};
```

Pass the object as `callbacks={callbacks}` on `ConsentProvider`. The
provider reads it once, when it is created. Keep the functions in a module or
in the component that renders the provider; on SvelteKit, not in a server
load, because a load cannot send functions to the browser.

|Callback|Payload|
|--|--|
|`onChoiceRecorded`|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time.|
|`onPermissionsChanged`|`snapshot`, the state after the change; `previous`, the permissions before it.|
|`onError`|`error`, a message string.|
|`onBeforeConsentRevocationReload`|`preferences`, the permissions after the withdrawal.|

Callbacks run after c15t updates its own state, so `snapshot` and
`getConsentManager()` already hold the new values. Visitor actions happen in
the browser, so in practice that is where the callbacks run.

`onBeforeConsentRevocationReload` runs synchronously right before the reload.
Keep it short; the page is about to unload. It does not run when you set
`reloadOnConsentRevoked={false}`.

## Script callbacks

Each entry in `scripts` takes its own callbacks:

|Callback|Runs|
|--|--|
|`onBeforeLoad`|Before the loader adds the script.|
|`onLoad`|When the script loaded.|
|`onError`|When the script failed to load.|
|`onConsentChange`|When consent changes after the script loaded. Use it to call the vendor's own consent API.|
|`onDispose`|When the configuration is removed or the provider unmounts.|

Helpers from `@c15t/integrations` already set these for their vendor.
[Building integrations](/docs/integrations/building-integrations) shows how to
write them.

## Listen inside one component

For a component that shows or reacts to consent, subscribe to a kernel event
in `$effect`, so the listener goes away with the component. The
[context getters](./getters#listen-to-consent-events) page has the example.
For values you render, read the manager's properties instead; they update the
component without a listener.

## Verify the callbacks

Open the console, clear site data and reload:

1. Accept in the banner. `onChoiceRecorded` and `onPermissionsChanged` both
   log.
2. Dismiss a notice, if your policy shows one. Neither logs.
3. Withdraw a category you allowed. `onBeforeConsentRevocationReload` logs,
   then the page reloads.

# IAB TCF
URL: https://c15t.com/docs/frameworks/sveltekit/iab
Turn on the IAB TCF 2.4 banner and preference center in a SvelteKit app with IABConsentBanner, IABConsentDialog and the provider's iab option.

## Before you turn on IAB TCF

Use IAB TCF when your ad partners require a TC String. It needs an IAB policy
in your Inth project and a CMP ID. IAB Europe assigns a CMP ID to a company
when it registers as a CMP
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your visitors' consent to someone else. Example CMP IDs in c15t demos are not
production configuration.

`@c15t/svelte` loads the TCF add-on from `@c15t/iab`, which it installs as a
dependency. The add-on is a separate chunk that apps without IAB never
download.

## Add the IAB components

Turn IAB on with the provider's `iab` prop, keeping your existing mode or `state`,
`scripts` and other props. `registeredCmpId` stands for the number IAB Europe
assigned to your company. The standard and IAB components add their styles
automatically:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} iab={{ cmpId: registeredCmpId }}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} iab={{ cmpId: registeredCmpId }}>
```

Then render `IABConsentBanner` and `IABConsentDialog` next to the standard
components.
The standard components cover visitors whose policy is not IAB, such as those
outside Europe:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

The IAB banner adds its first-paint rules before its elements render. The
IAB dialog adds its rules when it opens, including the base rules it needs
when rendered without a banner. Each sheet appears once per page. On a
server-rendered SvelteKit page, `c15tHandle` writes the rendered components'
rules into `<head>` before hydration.

To run the CSS through Tailwind CSS 3 or put it in a named cascade layer,
set `styles={false}` on the provider and import
`@c15t/svelte/styles.css` followed by `@c15t/svelte/iab/styles.css`.
[Stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when to use that option.

|`iab` option|Purpose|
|--|--|
|`cmpId`|Your registered CMP ID. A hosted backend can supply it instead.|
|`vendors`|Limit the Global Vendor List to these vendor IDs.|
|`customVendors`|Vendors outside the IAB list, with their purposes and data use.|
|`publisherRestrictions`|Override how vendors may use a purpose. See below.|
|`publisherCountryCode`|Your country, written into the TC String.|
|`gvl`, `gvlURL`|Supply the vendor list, or change where it is fetched from.|
|`enabled`|`false` keeps the configuration but leaves the add-on unmounted.|

Pass `iab={false}`, or omit it, to leave IAB off. If a visitor's policy
then uses the `iab` model and the backend sends its vendor list, the
provider throws an `IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`) while
rendering, on the server and in the browser: the standard banner does not
handle the IAB model, so the visitor would otherwise get no working consent
UI. Set `iab`, or remove the `iab` model from the policy. A backend that
answers `gvl: null` turns IAB off for the request, and the policy runs as
opt-in.

[IABConsentBanner](./components/iab-consent-banner) and
[IABConsentDialog](./components/iab-consent-dialog) list each component's
props.

`IABConsentBanner` and `IABConsentDialog` stay hidden until an IAB policy resolves for the visitor. Forcing the
dialog open does not create a policy or a vendor list, so check the policy
resolution and the vendor list request before changing how they render.

## Read the TCF state

`getConsentManager().iab` holds the live IAB state: the vendor list, purpose
and vendor consents, `isLoadingGVL`, and the actions `acceptAll()`,
`rejectAll()`, `setPurposeConsent()`, `setVendorConsent()`,
`setSpecialFeatureOptIn()` and `save()`. It is `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it.
[Context getters](./getters#read-and-change-iab-tcf-consent) lists every
member.

For a custom IAB banner, `@c15t/svelte/headless` exports
`getIABBannerDisplayItems`, `processGVLData` and `getIABTranslations`.

## Restrict how vendors use a purpose

Pass publisher restrictions in the provider's `iab` option as
`publisherRestrictions`, for example
`[{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] }]` to stop vendors
10 and 755 using purpose 4. Use vendors from your own list whose declarations
allow each restriction.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Verify the TCF flow

Accept, reject and save purpose and vendor choices, then check in the console
that `__tcfapi('getTCData', 2, console.log)` returns a TC String that matches
what you chose. Reload and confirm it persists. Check the vendors' actual
requests too; a category banner test does not show that the IAB flow works.

## IAB on the server

`loadConsent` and the consent route know about IAB policies. With a
server-resolved IAB policy, the IAB banner can render in the server HTML, and
the browser fetches the Global Vendor List from the route the server names.
Pass `fetchGvl` to `createConsentRoute` to change how the consent route
fetches the vendor list.

Keep [`c15tHandle`](./rendering#resolve-request-context-once-with-c15thandle) in your server hooks. It
reads the rendered IAB components' stylesheet markers and writes the rules
into `<head>`, so the server banner is styled before hydration without a
stylesheet request. The injected styles use the provider's `nonce`, or the
nonce SvelteKit put on its scripts. The browser reuses those styles and
adds the dialog's rules with the same nonce when it opens. See
[Content Security Policy](./content-security-policy#allow-c15ts-style-elements)
for nonce and prerendered-page requirements.

# IAB GPP
URL: https://c15t.com/docs/frameworks/sveltekit/gpp
Expose the IAB Global Privacy Platform API (__gpp) from a SvelteKit app with the provider's gpp option, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

The provider's `gpp` option installs `window.__gpp`, the GPP 1.1 CMP API, and
keeps its GPP string in step with the visitor's choices. Prebid.js, Google Ad
Manager and other ad tech read US privacy signals from it.

## Turn on GPP

Add `gpp` to `ConsentRoot` in your root layout, keeping your existing `state`
and other props:

```svelte title="src/routes/+layout.svelte"
<ConsentRoot state={data.consent} {scripts} gpp>
```

`gpp` on its own uses the defaults. Pass an object to change them, such as
`gpp={{ usFallback: 'none' }}`; the options are listed below. Omit `gpp`, or
pass `gpp={false}`, to leave it off.

`@c15t/svelte` loads the GPP code from `@c15t/iab/gpp`, which it installs as a
dependency. It is a separate chunk that apps without `gpp` never download.
`__gpp` exists only in the browser: the server render does not install it.
The provider installs it once the chunk arrives and removes it when the
provider unmounts.

The US section follows the policy the server resolved for the visitor, so the
visitor's state comes from the request headers `loadConsent` reads. See
[Geography headers](/docs/frameworks/sveltekit/geography-headers) for which
headers carry the region and how to test another location.

The TCF EU section needs IAB TCF as well. Set it up with
[IAB TCF](/docs/frameworks/sveltekit/iab).

If the root layout passes its own `runtime` to the provider, the provider does
not add GPP. Set `gpp` and `loadGPP: () => import('@c15t/iab/gpp')` in that
runtime's `createConsentRuntime()` call instead.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Geography headers
URL: https://c15t.com/docs/frameworks/sveltekit/geography-headers
Which request headers SvelteKit's c15t helpers read for country, region, language and Global Privacy Control, how to trust them, and how to test another location.

## Why location matters

Your consent policy picks a rule by the visitor's country and region: opt-in
in Europe, opt-out in US states with privacy laws, no banner where no law
applies. On SvelteKit, the server helpers read that location from request
headers your host or CDN adds. If no header arrives, the policy resolves with
its rule for an unknown location.

## Which headers are read

`loadConsent`, `c15tHandle`, the manifest route and `resolveConsent` read the
same headers, in this order. The first one present wins.

|Input|Headers, highest priority first|
|--|--|
|Country|`x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country`|
|Region|`x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`|
|Language|`accept-language`, negotiated by quality value to a primary tag such as `de`|
|Global Privacy Control|`x-c15t-gpc`, `sec-gpc`; only `1` and `0` count|

Vercel adds its country and region headers on every request. Cloudflare adds
`cf-ipcountry`; for `cf-region-code`, turn on Cloudflare's visitor location
headers. On another host, or a Node server without a CDN, set `x-c15t-country`
and `x-c15t-region` at your proxy from whatever location data it has.

With a build-time snapshot, as in the quickstart, `loadConsent` resolves the
policy in the server process from these inputs and makes no policy request.
In `hosted()` mode, it sends the resolved inputs to the backend's `/init` as
`x-c15t-country`, `x-c15t-region`, `accept-language` and `sec-gpc`, along
with `user-agent`. It adds the visitor IP as `x-forwarded-for` only with
`trustForwardedHeaders: true`. It never forwards `forwarded`,
`x-forwarded-host` or `x-forwarded-proto`; with that option it reads them to
resolve a relative `backendURL`. When the backend is a route in your own
app, it passes the same headers through `event.fetch`, which forwards only
cookies and authorization by itself.

## Resolve the inputs once per request

`c15tHandle` in `src/hooks.server.ts` reads the headers once, stores the
inputs on `event.locals.c15t.inputs`, and rewrites the request's headers to
the normalized `x-c15t-country`, `x-c15t-region`, `accept-language` and
`sec-gpc`. Later loads, endpoints and proxied backend calls then see one
form, whichever CDN header carried the value:

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle();
```

[Server API](./server-api#c15thandle) lists its options.

## Trust the headers

The `x-c15t-*` headers always win, and a browser can send them. A visitor who
sets `x-c15t-country: US` gets the policy for the United States. That changes
only their own banner, not anyone else's, but if you need the policy to
follow your CDN's location, remove incoming `x-c15t-*` headers at your edge
before the request reaches SvelteKit.

`cf-ipcountry` and the Vercel headers are set by the platform and cannot be
forged through it. Behind your own proxy, make sure it overwrites the country
headers rather than passing a client's value through.

The consent route fetches a relative `backendURL` through `event.fetch` and
never resolves it against the request, so a forged `Host` or
`x-forwarded-host` header cannot send its requests elsewhere. `loadConsent`
resolves a relative `backendURL` against `event.url`. With its default
`event.fetch`, the call stays in-process. With your own `fetch`, it goes to the
origin of `event.url`. `adapter-node` builds that origin from `paths.origin`
in SvelteKit 3 (the `ORIGIN` variable in SvelteKit 2), or from its
`PROTOCOL_HEADER` and `HOST_HEADER` settings; with none of them, it takes the
host from the `Host` header. SvelteKit 3's `adapter-node` ignores `ORIGIN`
without a warning, so move it to `paths.origin` when you upgrade. A forged `x-forwarded-host` changes
neither unless you set `trustForwardedHeaders`. See
[Server API](./server-api#loadconsent).

## Force a location

Pass `country`, `region` or `language` to force an input:

* On `c15tHandle({ country: 'DE' })`, for every request, such as a site that
  serves one country.
* On one `loadConsent(event, { country: 'DE' })` call, from a layout's own
  `load`, such as a `/de/` section.

A per-call value wins over the handle's. The browser's provider takes
`overrides={{ country, region, language, gpc }}` for the same purpose after
hydration.

## Test another location

Send the override header with a request and look for the banner in the HTML:

```sh
curl -s -H 'x-c15t-country: DE' http://localhost:5173/ | grep -c consent-banner-root
curl -s -H 'x-c15t-country: US' -H 'x-c15t-region: CA' http://localhost:5173/ | grep -c consent-banner-root
curl -s -H 'Sec-GPC: 1' -H 'x-c15t-country: US' -H 'x-c15t-region: CA' http://localhost:5173/
```

The first request prints `1` under a policy that asks Europe for opt-in. What
the others print depends on your policy's rules for California. In the
browser, the dev tools panel's location tab changes the location for the
current page without a request header.

## Verify

1. On your deployed site, open DevTools and check the document request's
   headers for your CDN's country header.
2. View the page source. The banner is in the HTML for a location that needs
   one, and absent for one that does not.
3. With the dev tools panel, confirm the resolved country and policy match
   where you are.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/sveltekit/content-security-policy
Write a Content Security Policy for a SvelteKit app using c15t with SvelteKit's csp option, covering vendor hosts, c15t's style elements, the server-rendered theme style and style attributes.

## Configure csp

SvelteKit writes the `Content-Security-Policy` header when you set its `csp`
option. In SvelteKit 3 that option goes to the `sveltekit()` plugin in
`vite.config.ts`. SvelteKit adds nonces or hashes to its own inline scripts.
Add the hosts c15t and your vendors need to the directives:

```ts title="vite.config.ts (partial)"
export default defineConfig({
	plugins: [
		sveltekit({
			csp: {
				mode: 'auto',
				directives: {
					'connect-src': ['self', 'https://your-project.inth.app'],
					'frame-src': ['https://www.youtube-nocookie.com'],
					'script-src': ['self', 'https://<vendor-script-host>'],
				},
			},
		}),
	],
});
```

On SvelteKit 2, set the same `csp` object as `kit.csp` in `svelte.config.js`.

Replace `https://your-project.inth.app` with the backend URL from your Inth
project, and list each vendor's script host.

SvelteKit does not pass the nonce it generates to your components, so the
provider's `nonce` prop cannot reuse it. Allow vendor hosts in `script-src`
instead. Host sources still apply next to SvelteKit's nonces, as long as the
list has no `'strict-dynamic'`.

The `<link rel="modulepreload">` tag that `c15tHandle` adds for the script
loader and network blocker chunk takes the nonce SvelteKit put on its own
scripts, unless the provider has a `nonce` of its own. The chunk is on your
own origin, so `'self'` covers it too.

## Allow c15t's style elements

c15t's components add their rules as `<style>` elements. On a server-rendered
page, `c15tHandle` writes the banner's rules into the HTML `<head>` with the
provider's `nonce`, or else the nonce SvelteKit put on its own scripts, so a
nonce-based policy admits them. A prerendered page under `mode: 'auto'` gets
hashes instead of nonces, so there is no nonce for `c15tHandle` to copy.

The standard and IAB dialogs and other components that first render in the
browser use the provider's `nonce`, or inherit the nonce from an existing
c15t style or a page script. Your `style-src` must allow that nonce.

For a prerendered page, or when your policy does not allow those nonces, set
`styles={false}` on `ConsentRoot` and import
`@c15t/svelte/styles.css` in your root layout. With IAB TCF, also import
`@c15t/svelte/iab/styles.css` after it. `'self'` covers those stylesheets.

## Allow the generated theme

The `<style id="c15t-theme">` element from
[customize](./customize#render-brand-tokens-on-the-server) is inline CSS that
you render with `{@html}`. SvelteKit's `csp` option adds no nonce or hash to it, so a
`style-src` without `'unsafe-inline'` blocks it and the banner falls back to
the stock colors. Either add the SHA-256 hash of the element's text to
`style-src`, which stays fixed while the theme does not change, or switch to
[a stylesheet](./customize#use-a-stylesheet-instead), which `'self'` covers.
Browsers ignore `'unsafe-inline'` in a list that also has a nonce or hash, so
adding it does not help under `mode: 'nonce'` or `'auto'`.

## Style attributes in server HTML

In the browser, Svelte sets `style` values through the DOM, which a policy
does not block. Server-rendered HTML is different. A `style` attribute in the
HTML is inline style, and `style-src` without `'unsafe-inline'` blocks it.
c15t renders `style` attributes for theme slot `style` values and for the
position of `ConsentDialogTrigger`. Svelte does not set them again during
hydration, so a blocked value stays unapplied.

Use class names in theme slots instead of `style` objects, or allow style
attributes with a separate `style-src-attr 'unsafe-inline'` directive.

## Server requests

`loadConsent`, `c15tHandle` and the manifest route call the backend from your
server, which the browser's policy does not govern. Only the browser's own
requests, such as saving a choice, need the backend in `connect-src`. With
the [consent proxy](./rendering#save-consent-through-your-own-origin), those
go to your own origin and `'self'` covers them.

## What c15t adds to the page

A Content Security Policy has to allow each thing c15t or your vendors put on
the page:

|c15t does|Directive|Allow|
|--|--|--|
|Requests the policy from `/init` and saves choices to `/subjects`|`connect-src`|Your backend's origin. `'self'` covers a same-origin route such as `/api/c15t`.|
|Adds a `<script>` element for each allowed entry in `scripts`|`script-src`|Each vendor's script host, or the provider's `nonce`.|
|Lets vendor scripts load more scripts, pixels and requests|`script-src`, `img-src`, `connect-src`|The hosts each vendor documents.|
|Sets `src` on gated iframes, or mounts `ConsentGate` children|`frame-src`|Each embed's host, such as `https://www.youtube-nocookie.com`.|
|Adds its rules to `<head>` as `<style>` elements|`style-src`|The provider's `nonce`. With `styles={false}` and an imported `@c15t/svelte/styles.css`, `'self'`.|
|Fetches the Global Vendor List under an IAB policy|`connect-src`|The vendor list host the policy names, when it is not your own origin.|

The dev tools panel attaches a stylesheet to its shadow root. Keep the panel
out of production builds, as its page describes, and a production policy
does not need to allow it.

## Stamp a nonce on vendor scripts

If your server creates a nonce for each response and puts it in the
`Content-Security-Policy` header as `'nonce-<value>'`, pass the same value to
the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} nonce={cspNonce}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} nonce={cspNonce}>
```

The script loader then sets that nonce on every `<script>` it adds, for both
`src` and inline `textContent` scripts. A `nonce` on one `scripts` entry wins
for that script. The components put it on the `<style>` elements they add.
The provider reads `nonce` once, when it is created.

The nonce covers only the elements c15t creates. A script that a vendor's
script loads by itself does not get it; allow that host in `script-src`, or
add `'strict-dynamic'` so scripts loaded by a trusted script are trusted too.
With `'strict-dynamic'`, browsers ignore host allowlists in `script-src`, so
every script on the page needs the nonce or a hash.

## Verify the policy

Enforce the policy, not report-only, and open the console with site data
cleared:

1. The banner renders with its styles, and no `Refused to` message mentions a
   c15t element, a `<style data-c15t-styles>` element or
   `@c15t/svelte/styles.css`. Open the preference dialog and check again.
2. Allow a category. Its vendor scripts load, and none are refused. A refused
   script from a vendor's own host means that host is missing from
   `script-src`.
3. Save a choice. The request to `/subjects` succeeds; a `connect-src`
   violation means the backend's origin is missing.
4. Allow the category of a gated embed. It loads; a `frame-src` violation
   names the host to add.

# Server API
URL: https://c15t.com/docs/frameworks/sveltekit/server-api
Reference for c15tHandle, loadConsent, createConsentRoute and resolveConsent from @c15t/svelte/kit and @c15t/svelte/server, with every option and default.

## Import server helpers only in server files

`@c15t/svelte/kit` holds the SvelteKit helpers and `@c15t/svelte/server` the
framework-free `resolveConsent`. Import them from `hooks.server.ts`,
`+layout.server.ts`, `+page.server.ts` and `+server.ts` only. Imported into a
component, they add the manifest resolver and every bundled translation to
the browser bundle. Components import from `@c15t/svelte`.

|Export|From|Use it in|Page|
|--|--|--|--|
|`c15tHandle(options)`|`@c15t/svelte/kit`|`hooks.server.ts`|[c15tHandle](#c15thandle)|
|`loadConsent`|`@c15t/svelte/kit`|`+layout.server.ts`, as `load`|[loadConsent](#loadconsent)|
|`createConsentRoute(options)`|`@c15t/svelte/kit`|`+server.ts`|[createConsentRoute](#createconsentroute)|
|`manifest()`, `hosted()`, `offline()`|`@c15t/svelte/kit`|`hooks.server.ts`, as `c15tHandle({ mode })`|[Rendering](./rendering#pick-a-rendering-path)|
|`resolveConsent(options)`|`@c15t/svelte/server`|Any server code|[resolveConsent](#resolveconsent)|
|`consentManifest(options)`|`@c15t/svelte/vite`|`vite.config.ts`|[consentManifest](#consentmanifest)|

The modes from `@c15t/svelte/kit` return plain data that reaches the browser
through `loadConsent`. `@c15t/svelte/server` re-exports the browser
transports `hosted`, `offline` and `custom` from `@c15t/core`, for code that
builds a provider itself.

## c15tHandle

`c15tHandle(options?)` returns a SvelteKit `Handle` that holds the consent
config for the app. Register it in `src/hooks.server.ts`. For every request
it:

1. reads the location, language and GPC inputs from the headers,
2. writes them back as `x-c15t-country`, `x-c15t-region`, `accept-language`
   and `sec-gpc`, so later code sees one normalized form,
3. reads the consent cookie,
4. stores the result and its own options on `event.locals.c15t`,
5. writes a server-rendered banner's styles into the page `<head>`, and
6. on pages whose provider has `scripts` or network blocker rules, links
   the chunk that holds both with `<link rel="modulepreload">`, once
   `consentManifest()` has written its URL into the build.

While SvelteKit prerenders, the handle reads no cookie or headers: the page
goes to every visitor.

|Option|Type|Default|Behavior|
|--|--|--|--|
|`mode`|`ConsentMode`|`manifest()`|How `loadConsent` resolves the visitor. `manifest()`, `hosted()` or `offline()` from `@c15t/svelte/kit`. A `custom()` transport throws; pass it to `ConsentRoot`'s `mode` prop instead.|
|`routePrefix`|`string`|none|Where `createConsentRoute()` is mounted, such as `/api/c15t`. The browser then resolves consent on pages the server did not, through that route. Without it, the browser asks the backend's `/init`. `'/'` throws `` @c15t/svelte: `routePrefix` can't be '/': a consent route at the site root would catch every page. Use a path such as '/api/c15t'. `` when the hook is created.|
|`backendURL`|`string`|the URL `consentManifest()` read|The backend. Consent saves go here. A `hosted({ backendURL })` mode's own URL wins.|
|`snapshot`|`ConsentManifest`|the manifest `consentManifest()` downloaded|A manifest to resolve with. `createConsentRoute()` reads it too.|
|`cookieName`|`string`|`c15t`|The consent cookie. Match the provider's `storageConfig.storageKey`.|
|`country`, `region`, `language`|`string`|from headers|Forces the input for every request.|

`event.locals.c15t` has this shape, exported as `C15tLocals`:

|Field|Value|
|--|--|
|`config`|The `ConsentState` from the cookie and request inputs, without a resolved policy.|
|`inputs`|`{ country?, region?, language?, gpc? }` for this request.|
|`mode`|The handle's mode, as data.|
|`backendURL`, `routePrefix`, `snapshot`, `cookieName`|The handle's options, when you passed them.|
|`shared`|`true` while SvelteKit prerenders.|

Some runtimes refuse to change request headers. The handle then skips step
2, and `event.locals.c15t.inputs` still carries the values. Compose it with
your own handles through `sequence()` from `@sveltejs/kit/hooks`. Type
`event.locals.c15t` by adding
`/// <reference types="@c15t/svelte/kit/locals" />` to `src/app.d.ts`.

## loadConsent

`loadConsent(event, options?)` returns `Promise<{ consent }>`. Export it as
the root layout's `load`, and pass `data.consent` to `ConsentRoot` as
`state`:

```ts title="src/routes/+layout.server.ts"
export { loadConsent as load } from '@c15t/svelte/kit';
```

It reads the consent cookie, the location and language headers and Global
Privacy Control, then resolves the policy with the handle's `mode`:

|Mode|How it resolves|
|--|--|
|`manifest()`|From the snapshot `consentManifest()` downloaded, or the handle's `snapshot`, with this visitor's inputs. No policy request.|
|`manifest({ source: 'runtime' })`|From the manifest at `${backendURL}/manifest`, or `manifestURL`, fetched and cached in memory.|
|`manifest({ resolve: 'browser' })`|Reads the cookie only. The browser resolves the policy.|
|`hosted()`|Calls the backend's `/init`.|
|`offline()`|From the mode's `policyRules`, or c15t's recommended rules.|

`consent` holds the resolved state, the mode as data, the backend URL and the
handle's `routePrefix`. It is plain, serializable data; pass it to
`ConsentRoot` unchanged.

While SvelteKit prerenders, `loadConsent` reads its `building` flag and
returns no stored consent, clock, GPC signal or policy, and makes no backend
request. Any stored records in the page would stop the browser reading the
visitor's own cookie, and a build-time clock would age every record against
it. The browser resolves the visitor after hydration.

To pass options, call it from your own `load`:

```ts title="src/routes/+layout.server.ts"
import { loadConsent } from '@c15t/svelte/kit';

export const load = (event) => loadConsent(event, { timeoutMs: 1000 });
```

|Option|Type|Default|Behavior|
|--|--|--|--|
|`timeoutMs`|`number` or `false`|`500`|Longest wait for the backend or the manifest, in milliseconds. `false` or `Infinity` waits as long as it takes; any other value that is not a finite, non-negative number uses the default.|
|`reportSessions`|`boolean`|`true`|With a manifest, reports each resolved visit to an absolute backend URL through `/sessions`.|
|`onBackgroundRevalidate`|`(promise, event) => void`|platform hook when available|Keeps session reports and unfinished requests alive after the response. `event.platform.context.waitUntil` takes precedence; this callback is the fallback. See [keep background work alive](./rendering#keep-background-work-alive-after-the-response).|
|`cookieName`|`string`|the handle's, or `c15t`|The consent cookie. Match the provider's `storageConfig.storageKey`.|
|`country`, `region`, `language`|`string`|from the handle or headers|Forces one input for this call.|
|`forwardHeaders`|`string[]`|none|Extra request headers to send to the backend's `/init`, only over `https`, to a loopback host, or in-process. `cookie`, `forwarded` and `x-forwarded-*` cannot be named.|
|`trustForwardedHeaders`|`boolean`|`false`|Resolves a relative backend URL against the request's forwarding headers instead of `event.url`, and sends the visitor IP to the backend as `x-forwarded-for`.|
|`fetch`|`typeof fetch`|global `fetch`|The fetch for a backend on another origin. A URL on the request's own origin always goes through `event.fetch`. A custom fetch keeps the vendor list inline.|

`loadConsent` resolves a relative backend URL against `event.url`. Any URL
on the request's own origin, relative or absolute, is called with
`event.fetch`, so SvelteKit answers it in-process and the request never
leaves the server. A client's `x-forwarded-host` does not change it.
`adapter-node` builds that origin from `paths.origin` in SvelteKit 3 (the
`ORIGIN` variable in SvelteKit 2), or from its `PROTOCOL_HEADER` and
`HOST_HEADER` settings. SvelteKit 3's `adapter-node` ignores `ORIGIN` without
a warning; move it to `paths.origin` when you upgrade.
`trustForwardedHeaders: true` resolves against the forwarding headers
instead. Set it only when your proxy overwrites those headers.

In `hosted()` mode, the backend's `/init` gets the resolved location,
language and GPC, the `user-agent` and, while the visitor has no stored
choice, the experiment arm. A backend on another origin, over `https` or a
loopback host, also gets the consent cookie (`cookieName`, never the rest of
the cookie jar) and any `forwardHeaders`. Nothing identifying crosses plain
HTTP to a remote host.

`loadConsent` never throws. When the backend fails, answers with an error or
takes longer than `timeoutMs`, it returns the stored choice without a policy.
The page then renders without a banner in the HTML, optional categories stay
denied, and the browser resolves the policy after hydration. A manifest fetch
that runs out of time keeps running in the background and fills the manifest
cache for the next request.

When `c15tHandle` ran for the request, `loadConsent` reuses the inputs it
normalized. Passing `country`, `region` or `language` makes it read the
headers again for that call.

## createConsentRoute

`createConsentRoute(options?)` returns the request handlers for the consent
route. Export them from a catch-all route such as
`src/routes/api/c15t/[...path]/+server.ts`, and set
`c15tHandle({ routePrefix: '/api/c15t' })` so the browser uses it. Only pages
the server did not resolve, such as prerendered ones, need it. The route
reads the snapshot, backend URL and mode `c15tHandle()` stored on
`event.locals.c15t`, so you set them once, on the handle. Options you pass to
the route win.

```ts title="src/routes/api/c15t/[...path]/+server.ts"
import { createConsentRoute } from '@c15t/svelte/kit';

// GET /api/c15t/init resolves the visitor from the bundled policy, and
// GET /api/c15t/manifest serves it. Other methods are not handled: the
// browser saves consent to the backend URL directly. Pair it with
// `c15tHandle({ routePrefix: '/api/c15t' })`.
export const { GET } = createConsentRoute();
```

|Returned|Serves|
|--|--|
|`GET`|`init` below the rest parameter: the visitor's resolved policy, like the backend's `/init`, with `Cache-Control: private, no-store`. Under an IAB policy it also serves the Global Vendor List. `manifest`: the manifest, with the backend's `Cache-Control` and `ETag`, answering `If-None-Match` with `304`. Any other path is forwarded with `proxy` on and answers `404` without it.|

With `proxy` on, it also returns `POST`, `PATCH`, `PUT`, `DELETE` and
`OPTIONS`, which forward writes to the backend.

|Option|Type|Default|Behavior|
|--|--|--|--|
|`backendURL`|`string`|the handle's: a `hosted()` mode's `backendURL`, then `c15tHandle({ backendURL })`, then the URL `consentManifest()` read from `PUBLIC_C15T_BACKEND_URL` or `PUBLIC_INTH_PROJECT_URL`|The backend's base URL, absolute or `/`-relative. The manifest is at `<backendURL>/manifest` when there is no snapshot. A handle `backendURL` that points at this route, as in the proxy setup, is skipped.|
|`manifestURL`|`string`|the handle's `manifest({ manifestURL })`|A manifest URL of its own, such as a CDN. Wins over `backendURL`. Absolute or `/`-relative.|
|`snapshot`|`ConsentManifest`|the handle's: the mode's `snapshot`, then `c15tHandle({ snapshot })`, then the manifest `consentManifest()` downloaded|A manifest to resolve with.|
|`proxy`|`true` or `{ paths?, cookieNames? }`|off|Forwards consent writes to `backendURL`. See [save consent through your own origin](./rendering#save-consent-through-your-own-origin).|
|`reportSessions`|`boolean`|`true`|Reports each resolved visit to the backend's `/sessions`, so Inth counts visitors it never served `/init` to.|
|`onBackgroundRevalidate`|`(promise, event) => void`|`event.platform.context.waitUntil`, when the adapter provides it|Keeps background manifest refreshes and session reports alive on runtimes that stop work after the response. SvelteKit 3's Cloudflare and Vercel adapters provide none; see [keep background work alive](./rendering#keep-background-work-alive-after-the-response).|
|`fetchGvl`|`({ reference, language, fetch }) => Promise<GlobalVendorList \|null>`|the shared server cache, with a five-second deadline|Fetches the Global Vendor List under an IAB policy. A rejection fails the init request instead of answering `gvl: null`.|
|`fetch`|`typeof fetch`|global `fetch`|The fetch used for an absolute `backendURL` or `manifestURL`, and for the vendor list.|

An absolute `backendURL` or `manifestURL` is fetched over the network with
`fetch`. A `/`-relative one, such as `/api/self-host` for a backend mounted in
your app, names a route in this app. The handlers request it through
`event.fetch`, which SvelteKit answers in-process, so it is never resolved
against `event.url` or the request's `Host` header. The proxy forwards to a
relative `backendURL` the same way. Do not point it at the route the handlers
serve, such as `/api/c15t`, or the route requests itself. The route skips a
`c15tHandle()` `backendURL` that names its own path for this reason. A relative
`backendURL` also turns off session reports, which need an absolute backend.

With runtime fetching, the manifest is cached in memory per server process
for as long as its `s-maxage` allows. After that, within the backend's
`stale-while-revalidate` window, the handlers serve the stale copy while it
refreshes in the background. Past that window, the next request waits for a
fresh copy.
The `manifest` handler passes upstream only a `language` query parameter that
looks like a language tag; the visitor's other parameters never reach the
backend. When the manifest cannot be read and `backendURL` is set, `init` asks
the backend's own `/init`, which covers backends without `/manifest`.

These handlers are built on the consent route handler in `@c15t/core/server`,
shared with the Next.js, TanStack Start, Astro and Nuxt adapters. `init`
answers with `x-c15t-policy-contract: 1`. A browser that declares another
policy contract gets a failed `unsupported-contract` resolution, and a
resolution that did not match carries no snapshot token, vendor list, CMP ID
or custom vendors.

## resolveConsent

`resolveConsent(options)` from `@c15t/svelte/server` does what `loadConsent`
does without a SvelteKit event. Pass `snapshot` to resolve a build-time snapshot
with each visitor's request inputs.

|Option|Type|Default|Behavior|
|--|--|--|--|
|`headers`|`Headers`|required|The incoming request's headers.|
|`backendURL`|`string`|none|Calls `<backendURL>/init` when no snapshot is supplied. With `snapshot`, an absolute URL receives session reports. Without either, only the cookie and headers are read. A relative URL resolves against `requestURL`, or the `host` header when there is none.|
|`snapshot`|`ConsentManifest`|none|Build-time snapshot, such as `snapshot` from `c15t/generated`. Resolves locally using this visitor's inputs and takes precedence over backend policy fetching.|
|`reportSessions`|`boolean`|`true`|Reports manifest resolutions to an absolute `backendURL`. Set `false` to skip reports. Hosted `/init` already counts the visitor.|
|`onBackgroundRevalidate`|`(promise) => void`|none|Pass the host's `waitUntil` to keep session reports alive after a serverless response.|
|`requestURL`|`string` or `URL`|none|The URL the framework resolved the request under, such as SvelteKit's `event.url`. `loadConsent` passes it for you.|
|`trustForwardedHeaders`|`boolean`|`false`|Resolves a relative `backendURL` against `forwarded`, `x-forwarded-host` and `x-forwarded-proto`, and sends the visitor IP to the backend as `x-forwarded-for`.|
|`cookieName`|`string`|`c15t`|The consent cookie.|
|`cookieHeader`|`string` or `null`|`headers.get('cookie')`|A cookie header to read instead.|
|`country`, `region`, `language`|`string`|from headers|Forces one input.|
|`forwardHeaders`|`string[]`|none|Extra headers to send to `/init`, under the same rule as `loadConsent`.|
|`fetch`|`typeof fetch`|global `fetch`|The fetch for `/init`, session reports and IAB vendor lists.|
|`timeoutMs`|`number` or `false`|`500`|Longest wait for `/init`, in milliseconds, with the same rule as `loadConsent`.|
|`now`|`number`|the current time|The request time, shared with the browser.|

It never throws; a failed or slow call returns the stored choice without a
policy.

## consentManifest

`consentManifest(options)` from `@c15t/svelte/vite` returns the Vite plugins
that download `<backendURL>/manifest` during the build. `loadConsent`,
`createConsentRoute()` and `manifest()` from `@c15t/svelte` read the result
without an import. The plugin writes no file into your project.

|Option|Type|Default|Behavior|
|--|--|--|--|
|`backendURL`|`string`|`PUBLIC_C15T_BACKEND_URL`, then `VITE_C15T_BACKEND_URL`, then `PUBLIC_INTH_PROJECT_URL`, then `VITE_INTH_PROJECT_URL`|Absolute `http` or `https` backend URL. The plugin appends `/manifest`.|
|`onBuildError`|`'fail' \|'runtime'`|Unset|What a failed fetch does. Unset, `vite build` stops and `vite dev` logs a warning. A missing backend URL counts as a failed fetch. The `C15T_ON_BUILD_ERROR` environment variable overrides it.|

The plugin detects `sveltekit()` and keeps the snapshot on the server: the
browser bundle never holds it. A Svelte app without SvelteKit gets it in the
browser, for `manifest()`. The backend URL is public and reaches both.

The plugin fetches once Vite has resolved its config: for `vite build`,
`vite dev` and, on SvelteKit 3, `svelte-kit sync`. `vite preview` does not
run it. The fetch waits at most 10 seconds. When it fails, `vite build` stops.
`vite dev` logs a warning instead, and `loadConsent` fetches the policy at
runtime. In a SvelteKit build the plugin also writes the URL of the chunk
that holds the script loader and the network blocker, which `c15tHandle`
preloads.

Server code that needs the manifest itself, such as a `resolveConsent` call,
imports `snapshot` and `backendURL` from `@c15t/core/generated`. Without the
plugin, that module still resolves and exports `undefined` for both. It ships
its own types, so `svelte-check` passes on a fresh checkout without running
Vite first.

## ConsentState

`resolveConsent` and `event.locals.c15t.config` return a `ConsentState`:
plain, serializable data a load can return. It holds the stored records, the request's location,
language and GPC, the resolved policy and translations when the backend
answered, and the IAB state for an IAB policy. It holds no computed
permissions. Pass it on unchanged; do not build one yourself or edit its
fields.

# DevTools
URL: https://c15t.com/docs/frameworks/sveltekit/components/dev-tools
Inspect consent, scripts, location and events in a SvelteKit app with ConsentDevTools, imported only when $app/env reports development.

## Add the panel in development

Render `ConsentDevTools` inside `ConsentRoot`, and load it only in
development. `dev` from `$app/env` (`$app/environment` on SvelteKit 2) is `true` in `vite dev` and
`false` in a production build, which then drops the import:

```svelte title="src/lib/consent-dev-tools.svelte"
<script lang="ts">
	import { dev } from '$app/env';

	// Import the panel only in development, so production bundles never
	// download it.
	const devTools = dev ? import('@c15t/svelte/devtools') : null;
</script>

{#if devTools}
	{#await devTools then { ConsentDevTools }}
		<ConsentDevTools />
	{/await}
{/if}
```

Render `<ConsentDevTools />` from that file in the root layout or any page.
The panel mounts in the browser only; it is never part of server HTML.

## What the panel shows

The panel is a floating inspector for the provider's consent runtime. Its
tabs:

|Tab|Shows|
|--|--|
|`consents`|Effective permissions and the recorded choice per category, with switches to stage and save a test choice.|
|`scripts`|Each registered script and its loading state.|
|`location`|The country, region and language the policy resolved for, with overrides to test another location.|
|`policy`|The resolved policy rule, its model, prompt, scope and rights.|
|`iab`|The TCF state, when IAB is on.|
|`events`|The consent runtime's events and script lifecycle events.|
|`actions`|Buttons to open the banner or dialog, reset the draft, clear stored records and resolve the policy again.|

Clearing records from the panel deletes the stored choice through the
provider's storage settings, so a custom `storageConfig` is respected.
Location overrides from the panel change the current page only.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|Corner of the panel's toggle.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|one of the tabs above|`'consents'`|The tab it opens on.|
|`maxEvents`|`number`|`100`|How many events the `events` tab keeps.|
|`getConsentCategories`|`() => AllConsentNames[]`|the provider's categories|Categories the `consents` tab lists.|
|`getPresentation`|`() => ConsentPresentation`|the provider's `presentation`|Presentation used for the panel's diagnostics.|
|`clearRecords`|`() => void`|the provider's own|Replaces what the clear action does.|
|`shadow`|`boolean`|`true`|`false` mounts the panel without a shadow root.|

By default the panel renders inside a shadow root with its own stylesheet,
so your CSS does not restyle it and its CSS does not leak into the page.
`shadow={false}` mounts the panel in the light DOM instead and puts its
stylesheet in `<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar with
a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end of the
toolbar farthest from its corner. The panel opens just past the toolbar,
aligned with its outer edge, and follows it when a visitor drags the toolbar
to another corner. `position` applies again once no trigger is visible. The
trigger that `ConsentDialog`'s `showTrigger` prop renders behaves the same
way.

DevTools brings its launcher back whenever no trigger is visible, for example
with `showWhen="never"` or while the dialog is open. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

## Keep it out of production

The panel can clear consent and change the location the policy resolves for.
Render it in development only. Importing `@c15t/svelte/devtools` statically
puts the panel in every bundle that imports the file, so import it
dynamically behind a development check, as the example above does.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/sveltekit/troubleshooting
Fix a SvelteKit build that cannot fetch the c15t manifest, a missing bundled policy, a banner missing from server HTML, failed saves through the consent route, a wrong backend URL and ignored theme colors.

## The build, dev server or type check fails fetching the manifest

**Check.** `vite build`, `vite dev` and, on SvelteKit 3, `svelte-kit sync`
download the policy through the `consentManifest` plugin in `vite.config.ts`.
`vite build` stops with an error that starts with `@c15t/svelte/vite: could not fetch the consent manifest`, and `vite dev` logs it as a warning. The part
in parentheses names the cause:

|Error|Cause|
|--|--|
|`/manifest responded 404`|The backend URL is wrong, or still the `https://your-project.inth.app` placeholder.|
|`no backend URL is set`|Neither the `backendURL` option nor `PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`) is set, or it is empty. `vite build` stops; `vite dev` warns.|
|`skipped the consent manifest fetch` (a notice)|The backend URL is relative, such as `/api/c15t`. With `onBuildError: 'fail'`, this is the error `build-time manifests require an absolute upstream URL`.|
|`/manifest returned an invalid consent manifest.`|The URL answers, but not with a c15t v3 manifest.|
|`fetch failed` or `no response within 10 seconds`|The machine running the command cannot reach the backend.|

**Fix.** Set `PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`) to your
project's absolute backend URL where the command runs, in `.env` or the CI environment. The plugin reads it
when `vite.config.ts` passes no `backendURL`. Make sure the build machine can
reach the backend. To deploy while it is down, build with
`C15T_ON_BUILD_ERROR=runtime`.
A `check-types` script that starts with `svelte-kit sync` needs the backend
too.

## The server fetches the manifest at runtime

**Check.** With the default `manifest()` mode, the server log shows a
manifest request to the backend, or a page waits on it after a cold start.
The build had no policy to bundle: `consentManifest` is missing from
`plugins` in `vite.config.ts`, the fetch failed in `vite dev` or in a build
with `C15T_ON_BUILD_ERROR=runtime`, or the backend URL is relative.

**Fix.** Add the plugin or fix the cause from the
[fetch errors](#the-build-dev-server-or-type-check-fails-fetching-the-manifest),
then restart `vite dev` or rebuild. A build fetches once, and `vite dev`
fetches the first time the server loads the policy.
Until then, the server fetches and caches the policy at runtime.

## Why is the banner missing from the server HTML?

**Check.** View the page source and search for `consent-banner-root`.

**Fix.** If the banner only appears after hydration, work through these causes
in order:

1. **`ConsentRoot` has no server state.** Check that the root
   `+layout.server.ts` exports `loadConsent` as `load` and that
   `+layout.svelte` passes `state={data.consent}`. With
   `manifest({ resolve: 'browser' })` or `offline()`, the browser resolves
   the policy by design.
2. **`loadConsent` fell back.** It returns the stored choice without a policy
   when resolution fails or takes longer than `timeoutMs`, 500 ms by default.
   Check the server logs. With runtime fetching or `hosted()`, check the
   backend's response time, and raise `timeoutMs` if it is slow.
3. **The page is prerendered.** Prerendered pages never carry a visitor's
   consent. See
   [prerender some pages](/docs/frameworks/sveltekit/rendering#prerender-some-pages).
4. **No banner is due.** The policy for the visitor's location may ask for no
   prompt, or the visitor already chose. Clear site data and check the policy.

## The banner flashes, or the stored choice is ignored on the server

**Check.** The server reads the choice from the `c15t` cookie. Look for a
changed `storageConfig.storageKey` on the provider. Without a matching cookie
name, the server reads nothing and renders the banner for every visitor.

**Fix.** Pass the same name as `cookieName` to `loadConsent` or `c15tHandle`.

**Check.** Look at what the layout passes to `ConsentRoot`. Rebuilding
`data.consent` from booleans loses the policy and the stored record.

**Fix.** Pass `data.consent` to `ConsentRoot` unchanged.

## Saving fails with 405 from /api/c15t

**Check.** `c15tHandle({ backendURL: '/api/c15t' })` sends saves to the
consent route, but the route does not forward writes. A route file that
exports only `GET` still answers a save with `405`.

**Fix.** Pass `proxy: true` to `createConsentRoute` and export
`POST`, `PATCH`, `PUT`, `DELETE` and `OPTIONS` next to `GET` from the
catch-all route. See
[save consent through your own origin](/docs/frameworks/sveltekit/rendering#save-consent-through-your-own-origin).

## The consent route times out or calls itself

**Check.** `createConsentRoute` needs the backend's URL. It reads it from
`c15tHandle()` and then `consentManifest` unless you pass `backendURL`, and
skips a handle `backendURL` that points at the route itself. A relative
`backendURL` passed to the route names a route in your own app, which the
handlers call in-process; if it points at `/api/c15t`, the route requests
itself.

**Fix.** Pass the Inth URL as `createConsentRoute({ backendURL })`, or leave
it unset so the route uses `PUBLIC_C15T_BACKEND_URL` or
`PUBLIC_INTH_PROJECT_URL`.

## Consent requests go to the wrong backend

**Check.** Look at `PUBLIC_C15T_BACKEND_URL` and `PUBLIC_INTH_PROJECT_URL` in
`.env`, `.env.local` and the build environment, and at any `backendURL` in `vite.config.ts`,
`src/hooks.server.ts` and a `hosted({ backendURL })` mode. One still has the
demo project, the placeholder `https://your-project.inth.app`, or a URL from
another project. The build reads the variable, so the URL for the policy and
for saves is fixed when you build, and setting it when the built app starts
changes nothing.

**Fix.** Set `PUBLIC_C15T_BACKEND_URL` (or `PUBLIC_INTH_PROJECT_URL`) to your
Inth project's backend URL, including any path prefix, for the build and for the running app, then
rebuild. The policy and saves need the same backend.

## Your own `:root` token rules are ignored

**Check.** A theme from `generateThemeCSS()` uses `:root:root`, which outranks a
plain `:root` rule wherever each one sits in the page. If you also set
`--c15t-*` variables on `:root` in a stylesheet, the generated theme wins for
every token both set.

**Fix.** Move those values into the theme, or write the rule on `:root:root`.
See [customize](/docs/frameworks/sveltekit/customize).

## Server code ends up in the browser bundle

**Check.** Look for imports of `@c15t/svelte/kit` or `@c15t/svelte/server` in
components. They are for server files: `hooks.server.ts`,
`+layout.server.ts`, `+page.server.ts` and `+server.ts`. Imported from a
component, they pull the manifest resolver and every bundled translation into
the browser bundle.

**Fix.** Import the components from `@c15t/svelte` in components, and set
the mode on `c15tHandle()` in `hooks.server.ts`.

## c15tHandle() throws on `custom()`

**Check.** `c15tHandle({ mode })` received `custom()`. The error reads
"c15tHandle() takes manifest(), hosted() or offline() from @c15t/svelte/kit".
The handle's mode must be data that can reach the browser, and a custom
transport is code.

**Fix.** Pass the `custom()` transport to `ConsentRoot`'s `mode` prop, and
keep the handle's `mode` for one of the data modes from `@c15t/svelte/kit`.

## Names from an earlier alpha are missing

**Check.** An import or option from an earlier v3 alpha fails, such as
`createSvelteKitConsentRouteHandlers`, `c15tPreload` or
`loadConsent(event, { backendURL })`. `@c15t/svelte` was not public in v2, so
the alphas renamed these with no alias.

**Fix.** Use the current names:

|Removed|Use instead|
|--|--|
|`ConsentManagerProvider` with `prefetch={...}`|`<ConsentRoot state={data.consent}>`|
|`Frame`|`ConsentGate`|
|`createSvelteKitConsentRouteHandlers`|`createConsentRoute`|
|`c15tPreload`|Part of `consentManifest()` from `@c15t/svelte/vite`|
|`ConsentManifestOptions`, `consentManifest({ outputFile })`|Removed|
|`loadConsent(event, { backendURL, manifest, initRoute, shared })` returning `prefetch`|`c15tHandle({ mode, routePrefix, snapshot, backendURL })` in `src/hooks.server.ts`, and `export { loadConsent as load }`, which returns `{ consent }`|
|`resolveConsent({ manifest })` from `@c15t/svelte/server`|`resolveConsent({ snapshot })`|

## Why is there no banner?

**Check.** Read `getConsentManager().policyRule.prompt` and `.location`, or open
DevTools. In the Network panel, find the `/init` request.

**Fix.** Work through these causes in order:

1. **The policy asks for no prompt.** Visitors in regions without a consent
   law, and opt-out policies with no prompt, get no banner. See
   [why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).
2. **A choice is already stored.** Clear site data for your origin, or use the
   DevTools panel, and reload.
3. **The backend request failed.** A CORS error means your site's origin is
   not in the Inth project's trusted origins. A 404 means the backend URL is
   wrong. While the request fails, optional categories stay denied and no
   banner shows.
4. **The component is outside the provider.** `ConsentBanner` must render
   inside `ConsentProvider`; outside it, Svelte throws
   `c15t: no v3 consent context`.

## Svelte throws "no v3 consent context"

**Check.** A getter or component ran without a `ConsentProvider` above
it.

**Fix.** Move it inside the provider.

**Check.** Look for a getter called in an event handler or effect. Getters use
Svelte's `getContext`.

**Fix.** Call getters at the top level of a component's `<script>`.

**Check.** If the provider is there, check that the app resolves one copy of
`@c15t/svelte`. Two copies create two separate contexts.

**Fix.** Make the app resolve a single copy of `@c15t/svelte`.

## Theme colors are ignored

**Check.** The provider's `theme` prop applies slot styles and `consentActions`
only. Colors, radius, typography and other tokens in `theme` are not turned
into CSS in the browser, and in development the provider logs a warning about
it.

**Fix.** Set the `--c15t-*` variables on `:root` in a stylesheet, or render
`generateThemeCSS()` output as `<style id="c15t-theme">`. The customize page
shows both.

**Check.** If your values still lose, inspect the element. A generated theme
uses `:root:root`, so it beats your own `:root` rule.

**Fix.** Write your rule on `:root:root` too, or move the value into the theme.

## The dialog or banner has no styles

**Check.** Look in `<head>` for `<style data-c15t-styles>` elements, and in
the console for a Content Security Policy error. On a server-rendered
SvelteKit page, check that `src/hooks.server.ts` exports `c15tHandle`.

**Fix.**

* No c15t `<style>` element: the provider sets `styles={false}` or
  `noStyle`. With `styles={false}`, import `@c15t/svelte/styles.css` once,
  in the component that renders the provider or in your global stylesheet.
* The SvelteKit banner is unstyled until hydration: add `c15tHandle` from
  `@c15t/svelte/kit` to `src/hooks.server.ts`, or set `styles={false}` and
  import `@c15t/svelte/styles.css`.
* The console reports a blocked inline style: pass the provider a `nonce`, or
  set `styles={false}` and import the stylesheet. The Content Security Policy
  page covers both.
* IAB TCF surfaces are unstyled with automatic styles disabled: import
  `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css` together. With
  automatic styles enabled, check the policy and IAB configuration, the
  provider's `noStyle` option, and CSP errors.

## A vendor loads before consent, or twice

**Check.** The vendor is still loaded some other way: a `<script>` tag in
`index.html` or `app.html`, a tag manager, or an SDK import in your code. Check
the Network panel with site data cleared; nothing from the vendor should load
before you allow its category.

**Fix.** Remove the other loader and keep only the `scripts` registration.

## The page reloads after saving

**Check.** When a save withdraws a category that was granted, the provider
reloads the page so code that already ran is gone. This is expected.

**Fix.** Set `reloadOnConsentRevoked: false` on the provider only if every
registered vendor stops itself through its consent API.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI. [Verify
consent](/docs/guides/verify-consent) lists the checks to run before release.

# Quickstart
URL: https://c15t.com/docs/frameworks/html/quickstart
Add the c15t banner, preferences and script gating to a plain HTML site, CMS theme, page builder or static site generator with one script tag and no build step.

## Connect Inth

[Create an Inth project](https://inth.com), set its policy rules, add your
site's origin to its trusted origins, and copy the project's backend URL. The
URL is public configuration. It ends up in your page's HTML, which is expected.

This guide loads `@c15t/browser` from your Inth project with a `<script>`
tag. The tag brings the banner, the preference dialog, stored choices and
script gating. There is nothing to install or build. If your site has a bundler, the same
package is available as an ES module; [choose your setup](/docs/concepts/choose-your-setup)
lists both paths.

## Add the script tag

Paste this tag into the `<head>` of every page.
Replace `https://your-project.inth.app` with the URL from your Inth project,
and keep `/c15t.js` on the end.

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.js"
	defer
></script>
```

Inth serves the hosted bundle with your project's backend URL already
configured, so the tag needs no `data-backend-url`. `defer` lets the page keep
parsing while the script downloads. When it runs, the tag resolves the
visitor's policy through Inth's `/init`, then shows the banner if the policy
asks for one.
A returning visitor who already chose sees no banner. Attributes from the
[attribute reference](/docs/frameworks/html/attributes-and-api), such as
`data-language`, still work on this tag.

`c15t.js` keeps the stock UI and consent behavior while excluding offline
policy presets, offline resolution and manifest transport code. `/init`
returns the policy resolved for this visitor.

### Where to paste it

The tag belongs in the shared `<head>` that every page renders, such as a WordPress
child theme's `header.php`, Webflow's head code setting, Shopify's
`layout/theme.liquid`, or your static site generator's base layout.
[Install on your platform](/docs/frameworks/html/platforms) gives the exact
place for each platform, and what to check in caching plugins and tag
managers.

A page without the tag has no consent state, and its vendor scripts follow
their own rules. Check a few pages from different templates after you publish.

## Gate your vendor scripts

The tag only controls scripts it knows about. Change each vendor tag's `type`
to `text/plain` and name its category in `data-c15t-category`. The browser
ignores a `text/plain` script, so the vendor stays off until c15t sees
permission for that category and runs the script.

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	src="/posthog.js"
></script>
```

The PostHog tag loads the vendor's snippet from a file on your site. Save the
snippet from your PostHog project settings as that file. A vendor snippet you
paste inline works the same way: keep it inside the tag and change the tag's
`type` and category.

Remove the original, active copy of each vendor tag, including copies a theme
setting or another plugin adds. Use `measurement` for analytics and
`marketing` for ads and pixels. [Consent categories](/docs/concepts/consent-categories)
lists all five. [Gated scripts](/docs/frameworks/html/components/gated-script)
covers load order, and [scripts](/docs/frameworks/html/scripts) covers
callbacks and what happens when a visitor withdraws permission.

## Gate embeds

Move an iframe's URL from `src` to `data-src` and add `data-category`. c15t
sets `src` once the category is allowed and removes it again if the visitor
withdraws permission.

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

Without a `src`, the iframe loads nothing. Show a placeholder next to it with
CSS, such as `iframe:not([src]) { display: none; }` and a message that links to
privacy settings. [Embeds](/docs/frameworks/html/embeds) has the full
placeholder markup.

## Add a privacy settings link

Visitors need a way to change their choice after the banner closes. A link to
`#c15t-preferences` opens the preference dialog, with no JavaScript on your
page:

```html title="index.html"
<a href="#c15t-preferences">Privacy settings</a>
```

Put it in the footer of every page. A button with
`data-c15t-action="customize"` does the same, and `data-trigger` on the script
tag adds a [floating button](/docs/frameworks/html/components/trigger)
instead. [Components](/docs/frameworks/html/components) lists every surface
and page hook.

## Check it works

Open the site in a private window with the browser's developer tools open on
the Network tab.

1. Before you choose, filter for `posthog`. There are no requests, and the
   YouTube iframe has no `src`.
2. Click **Reject All** and reload. The banner stays closed and the PostHog
   requests stay absent.
3. Open **Privacy settings**, turn on **Analytics** (the `measurement` category) and save. PostHog's
   `array.js` and the YouTube player load.
4. Open **Privacy settings** again and turn **Analytics** off. The page reloads,
   and PostHog and YouTube do not load again.

If no banner appears, the policy for your location may not ask for one. See
[troubleshooting](/docs/frameworks/html/troubleshooting). Run the full
[verification checklist](/docs/guides/verify-consent) before you ship.

## Other ways to run the tag

* **Offline mode.** Load `c15t.offline.js` from a CDN, without
  `data-backend-url`, and c15t resolves the policy in the browser from
  `data-policy-rules` or its recommended rules. The browser does not know
  the visitor's country, so without `data-country` every visitor gets the
  strict opt-in fallback. Choices stay in that browser and there are no
  consent records. Not recommended for production environments.
* **A self-hosted backend.** A [self-hosted c15t backend](/docs/self-host/overview)
  serves the hosted bundle at `/c15t.js` with its backend URL already
  configured, so the tag needs only a `src`:
  `<script src="https://consent.example.com/c15t.js" defer></script>`, with
  your backend's origin in place of `consent.example.com`.
* **From a CDN.** Load a pinned version from jsDelivr. Use `c15t.js` with
  `data-backend-url` for hosted mode:
  `<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@<version>/dist/c15t.js" data-backend-url="https://your-project.inth.app" defer></script>`.
  For offline mode, use `dist/c15t.offline.js` without `data-backend-url`.
  Replace `<version>` with the exact version listed on
  [npm](https://www.npmjs.com/package/@c15t/browser?activeTab=versions).
  `@alpha` loads the newest v3 prerelease, so a new release can change your
  banner without a deploy.
* **Manifest mode.** Use the `@c15t/browser` ES module for manifest mode
  with the stock UI, or `c15t.headless.js` with your own UI. These clients can
  fetch or inline the backend's cacheable policy manifest. The IAB script
  also supports manifest mode for IAB policies. See
  [modes](/docs/frameworks/html/attributes-and-api#choose-a-mode).

## Next steps

* [Customize the banner](/docs/frameworks/html/customize).
* Read the [attributes](/docs/frameworks/html/attributes-and-api) and
  [window.c15t API](/docs/frameworks/html/api) references.
* Add [translations](/docs/frameworks/html/translations).

# Install on your platform
URL: https://c15t.com/docs/frameworks/html/platforms
Where to paste the c15t script tag, gated vendor snippets and the privacy settings link in WordPress, Webflow, Shopify, Squarespace, Wix, Framer, Ghost, Hugo, Eleventy and Jekyll.

## What every platform needs

Whatever builds your pages, three pieces go in three places:

|Piece|Where it goes|
|--|--|
|The c15t script tag from the [quickstart](/docs/frameworks/html/quickstart#add-the-script-tag)|The shared `<head>` every page renders.|
|Each vendor snippet, changed to `type="text/plain"`|Wherever the vendor told you to paste it. Remove the original copy.|
|A link to `#c15t-preferences`|The footer or legal menu every page renders.|

The tag must be on every page. A page without it has no consent state, and its
vendor scripts follow their own rules. After you publish, check a page from
each template your site uses, such as the home page, a blog post and a
product page.

## WordPress

Add the tag to your child theme's `header.php`, right before `</head>`. Edits
to a parent theme are lost when it updates. A block theme without
`header.php` can print the tag from the child theme's `functions.php`:

```php
add_action('wp_head', function () {
  echo '<script src="https://your-project.inth.app/c15t.js" defer></script>';
}, 1);
```

Priority `1` prints the tag before other plugins' head output. Replace the
backend URL with your Inth project's URL.

Plugins that add analytics or pixels for you, such as a site stats plugin or
a marketing integration, print active tags you cannot change to
`text/plain`. Turn off that plugin's tracking output and paste the vendor's
snippet as a gated tag instead, or keep the plugin and hold its requests with
a [network blocker](/docs/frameworks/html/network-blocker) rule.

Add the privacy settings link as a custom link in your footer menu, with the
URL `#c15t-preferences`.

## Webflow

Paste the tag in Site settings, Custom code, Head code. Paste gated vendor
snippets there too, or in an Embed element for one page. Put the
`#c15t-preferences` link in your footer component. Publish the site after each
change; custom code does not run in the Designer.

## Shopify

Edit your theme's code and paste the tag in `layout/theme.liquid`, before
`</head>`. Put the privacy settings link in the footer menu with the URL
`#c15t-preferences`. Checkout pages do not render `theme.liquid`, so the tag
does not run there.

Apps that install tracking tags add them outside your theme. Check the page
source for each vendor after you install c15t, and turn off an app's own
tracking where it offers a setting.

## Squarespace

Paste the tag in the Code Injection page's Header field. Code injection is not
available on every plan. Add a footer link with the URL `#c15t-preferences`.

## Wix

Add the tag as custom code in your site settings, placed in the head and
loaded on all pages. Custom code needs a site plan with a connected domain.
Add a footer link to `#c15t-preferences`.

## Framer

Paste the tag in your site settings' custom code, in the section for the start
or end of `<head>`. Add a link with the URL `#c15t-preferences` in your
footer. Publish to see it on the live site.

## Ghost

Paste the tag in Settings, Code injection, Site header. Add a navigation item
with the URL `#c15t-preferences` to the secondary navigation, which most
themes render in the footer.

## Hugo

Add the tag to the template that renders `<head>`, usually
`layouts/_default/baseof.html` or a head partial. Copy a theme's file into
your own `layouts/` directory before editing it, so a theme update does not
overwrite your change.

## Eleventy

Add the tag to the base layout in your `_includes` directory that every page
extends.

## Jekyll

Add the tag to `_includes/head.html` or `_layouts/default.html`. Copy a
theme's file into your site before editing it.

## Plain HTML and server includes

Add the tag to each page's `<head>`, or to the shared header include your
server uses.

## Tag managers

Do not load the c15t tag from Google Tag Manager or another tag manager. The
tag manager runs its own tags before c15t could decide anything, and it is a
vendor that needs consent itself. Load c15t directly in `<head>`, then gate the
tag manager's snippet like any other vendor. [Scripts](/docs/frameworks/html/scripts#google-consent-mode-and-tag-managers)
covers Google Consent Mode.

## Caching and optimization plugins

Plugins and CDN features that combine, defer or delay scripts can rewrite a
gated tag's `type`, move it, or delay the c15t tag until the first click. Any
of these breaks gating. Exclude the c15t tag, `c15t.js`, and every tag with
`data-c15t-category` from script optimization. Then check the page source of
the published site. Each gated tag still has `type="text/plain"` before a
choice.

A full-page cache is safe. The tag reads the visitor's choice in the browser,
so every visitor can get the same cached HTML.

## Check it works

On the published site, open a page from each template in a private window
with the Network tab open.

1. The banner appears, and filtering for each vendor's domain shows no
   request before a choice.
2. Click **Reject All** and open another page. The banner stays closed.
3. Click the footer's privacy settings link. The preference dialog opens.
4. View the page source. There is one c15t tag, and every vendor snippet is
   `type="text/plain"`.

# Scripts
URL: https://c15t.com/docs/frameworks/html/scripts
Hold vendor scripts on a plain HTML page until the visitor allows their category, load scripts with callbacks, handle withdrawal and clear vendor cookies with the c15t script tag and no build step.

## Choose how to gate a script

The c15t script tag has two ways to hold a vendor script until its category is
allowed:

|Form|Use it when|
|--|--|
|A `<script type="text/plain" data-c15t-category>` tag in your HTML|You paste a vendor snippet into a theme, a CMS field or a page builder. No JavaScript of your own.|
|A `scripts` entry in a queued `config` call|You need a callback after the vendor loads, on an error, or when consent changes.|

Both wait for the same permission and both add their category to the
preference dialog. Iframes use `data-src` instead; see
[embeds](/docs/frameworks/html/embeds). Requests your own code sends with
`fetch` use the [network blocker](/docs/frameworks/html/network-blocker).

## Gate a pasted snippet

Change the vendor's tag to `type="text/plain"` and add
`data-c15t-category`:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
<script type="text/plain" data-c15t-category="marketing" src="https://vendor.example/tag.js"></script>
```

On a page whose c15t tag has a nonce, add the same `nonce` to each gated tag,
or c15t skips it. See
[gated tags on a page with a nonce](/docs/frameworks/html/components/gated-script#gated-tags-on-a-page-with-a-nonce).
The [quickstart](/docs/frameworks/html/quickstart#gate-your-vendor-scripts)
shows this with PostHog. [Gated scripts](/docs/frameworks/html/components/gated-script)
covers load order, copied attributes and tags added after load.

## What happens when a visitor withdraws permission

A script that has run cannot be stopped. When a visitor turns off a category
they had allowed, c15t saves the choice and reloads the page. The new page
starts with the vendor tag inert again. Allowing a category never reloads.

To handle withdrawal yourself, for example by calling a vendor's opt-out
function, set `reloadOnConsentRevoked: false` in `config`. Then c15t does not
reload and the vendor code that already ran keeps running until the next page
load. `callbacks.onBeforeConsentRevocationReload` runs right before the
reload, if you need to flush something first. See
[events and callbacks](/docs/frameworks/html/callbacks).

## Load a script with callbacks

List the script under `scripts` in a queued `config` call before the tag:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    scripts: [
      {
        id: 'analytics',
        src: 'https://analytics.example/sdk.js',
        category: 'measurement',
        onLoad: () => window.analytics.track('page_view'),
        onConsentChange: ({ hasConsent }) => {
          if (!hasConsent) window.analytics.optOut();
        },
      },
    ],
  }]);
</script>
```

`analytics.track` and `analytics.optOut` stand for your vendor's own API.
c15t adds the script to `<head>` once measurement is allowed, and removes the
element again when the visitor withdraws it.

|Field|What it does|
|--|--|
|`id`|A unique, stable name for the script. Required.|
|`category`|The category it needs, such as `'measurement'`. Required. It also accepts a condition such as `{ and: ['measurement', 'marketing'] }`.|
|`src` or `textContent`|The URL to load, or inline code to run. One is required unless `callbackOnly` is set.|
|`callbackOnly`|Add no element. Only run the callbacks, for a vendor that is already on the page.|
|`alwaysLoad`|Load whatever the consent state. Use it only for tags that manage consent themselves.|
|`persistAfterConsentRevoked`|Keep the element on the page after withdrawal.|
|`target`|`'head'` (default) or `'body'`.|
|`async`, `defer`, `nonce`, `fetchPriority`, `attributes`|Attributes for the created `<script>` element. Without its own `nonce`, the script gets the c15t tag's nonce.|
|`anonymizeId`|Give the element a random `id` so blockers cannot match it by name. On by default.|
|`vendor`|A vendor ID for vendor-level consent. See [vendor consent](/docs/frameworks/html/vendor-consent).|
|`onBeforeLoad`, `onLoad`, `onError`|Run before a load attempt, after the script loads, or when it fails.|
|`onConsentChange`|Run each time the script's consent changes. The argument has `hasConsent` and `consents`.|
|`onDispose`|Run when the script is removed from the configuration or c15t is disposed.|

Every callback receives the script's `id`, the created element's
`elementId`, `hasConsent`, the current `consents`, and the `element` when
there is one.

For a plain vendor snippet, the `text/plain` tag is simpler and works in any
CMS field that accepts HTML. The vendor helpers in `@c15t/integrations`, such as
the PostHog and Google tag helpers, are ES modules that need a bundler. On a
plain HTML page, paste the vendor's own snippet into a `text/plain` tag.

## Clear cookies when permission is withdrawn

Gating stops new requests but does not delete what a vendor already stored.
Add `clearOnRevocation` to the config to delete named cookies and storage keys
when their category is denied. See
[clear on revocation](/docs/frameworks/html/clear-on-revocation).

## Google Consent Mode and tag managers

The script tag does not send Google Consent Mode signals. The Google tag and
Google Tag Manager helpers in `@c15t/integrations` do, but they need a bundler. On
a plain HTML page, gate Google's snippet like any other vendor. Google then
loads only after consent, so it sends nothing before a choice.
[Gated scripts](/docs/frameworks/html/components/gated-script#load-order)
shows the GA4 snippet with its two tags in the right order.

If you need Consent Mode instead, load Google's snippet ungated and send the
signals yourself. Put this before Google's tags:

```html
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() { dataLayer.push(arguments); }
  gtag('consent', 'default', {
    analytics_storage: 'denied',
    ad_storage: 'denied',
    ad_user_data: 'denied',
    ad_personalization: 'denied',
  });
  window.c15t = window.c15t || [];
  c15t.push(['on', 'consent', (snapshot) => {
    const allowed = snapshot.effectivePermissions;
    const state = (granted) => (granted ? 'granted' : 'denied');
    gtag('consent', 'update', {
      analytics_storage: state(allowed.measurement),
      ad_storage: state(allowed.marketing),
      ad_user_data: state(allowed.marketing),
      ad_personalization: state(allowed.marketing),
    });
  }]);
</script>
```

With Consent Mode, Google receives requests before a choice, marked as denied.
Decide which behavior your policy needs before you pick one.

The vendor guides under [integrations](/docs/integrations/overview) have an
HTML tab with the no-build setup.

## Check it works

Open the page in a private window with the Network tab open.

1. Filter for each vendor's domain. Nothing loads before a choice.
2. Allow one category. Only that category's vendors load, and each `onLoad`
   runs.
3. Turn the category off again. The page reloads and the vendor stays absent.

# Embeds
URL: https://c15t.com/docs/frameworks/html/embeds
Hold YouTube videos, maps and other iframes on a plain HTML page until their consent category is allowed with data-src and data-category, show a placeholder, and configure the c15t iframe blocker.

## Gate an iframe

Move the iframe's URL from `src` to `data-src` and name its category in
`data-category`. The c15t script tag gives the iframe its `src` once the
category is allowed:

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

An iframe with no `src` loads nothing, so the vendor gets no request and sets
no cookie until the visitor allows the category. Give every embed a `title`
that says what it shows.

## Attributes

|Attribute|What it does|
|--|--|
|`data-src`|The embed's URL. c15t moves it to `src` when the gate opens. Only `http:` and `https:` URLs load. A relative URL resolves against the page.|
|`data-category`|One category name. An unknown name logs a warning and keeps the iframe blocked.|
|`data-vendor`|Optional vendor ID for vendor-level consent. The iframe also stays blocked while the visitor has turned that vendor off. See [vendor consent](/docs/frameworks/html/vendor-consent).|
|`data-c15t-paused`|Set by c15t when it took away a `src` the iframe already had. Do not set it yourself.|

Iframes without `data-category` or `data-vendor` are left alone.

## Show a placeholder

c15t does not draw anything in place of a blocked iframe. Put your own message
next to it and hide it once the iframe has a `src`:

```html
<div class="embed">
  <iframe data-src="…" data-category="measurement" title="YouTube video"></iframe>
  <div class="placeholder">
    <p>Allow measurement to load this YouTube video.</p>
    <a href="#c15t-preferences">Choose video permissions</a>
  </div>
</div>
```

```css
.embed iframe:not([src]) { display: none; }
.embed iframe[src] + .placeholder { display: none; }
```

The `#c15t-preferences` link opens the preference dialog, where the visitor
can allow the category. See [preferences link](/docs/frameworks/html/components/preferences-link).

## What happens on withdrawal

When a visitor turns the category off, c15t removes the iframe's `src` and puts
the URL back in `data-src`, which unloads the embed. The page also reloads by
default, as it does for scripts.

An iframe written with a normal `src` and a `data-category` starts loading
before c15t runs, then c15t removes the `src`. The vendor already got its
request, so always use `data-src`.

## Iframes added later

c15t watches the whole document. An iframe that a page builder, a CMS widget
or your own script adds later is gated the moment it appears, and so is an
iframe whose `data-category` changes. This keeps working when a client router
such as Turbo replaces `<body>` on navigation, and when the c15t tag runs in
`<head>` before `<body>` exists.

## Configure the iframe blocker

The iframe blocker is on by default in every `@c15t/browser` build. Set
`iframeBlocker` in a queued `config` call to change it:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', { iframeBlocker: false }]);
</script>
```

|Value|Effect|
|--|--|
|omitted or `{}`|Gate every iframe with `data-category` or `data-vendor`, including ones added later.|
|`{ disableAutomaticBlocking: true }`|Do not scan or watch the page. c15t sets or removes a `src` only when you call `c15t.processIframes()`. See [check iframes yourself](#check-iframes-yourself).|
|`false`|Turn the blocker off. `data-src` iframes never load.|

The categories on gated iframes are added to the preference dialog, as they
are for gated scripts.

## Check iframes yourself

With `iframeBlocker: { disableAutomaticBlocking: true }`, c15t leaves iframes
alone until your page calls `c15t.processIframes()`. Each call pauses gated
iframes, those with `data-category` or `data-vendor`, that consent does not
allow, and restores the ones it does. Call it after the policy resolves, after
you add iframes, and after consent changes:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', { iframeBlocker: { disableAutomaticBlocking: true } }]);
  c15t.push(['processIframes']);
  c15t.push(['on', 'consent', () => c15t.processIframes()]);
</script>
```

A queued `processIframes` runs once the policy has resolved, so
`c15t.push(['processIframes'])` is safe before and after the tag loads. With
automatic blocking on, c15t does this by itself and you do not need to call
it.

## Vendor embeds

The [integration guides](/docs/integrations/overview) have an HTML tab for
YouTube, Google Maps and other embeds, with the category each one needs. The
`youtube-nocookie.com` player still contacts Google when it loads, so gate it
like any other embed.

## Check it works

Open the page in a private window with the Network tab open.

1. Before you choose, the iframe has no `src` in the Elements panel and there
   is no request to the embed's host. The placeholder shows.
2. Allow the category. The iframe gets its `src`, the embed loads and the
   placeholder hides.
3. Open preferences and turn the category off. The page reloads and the embed
   stays unloaded.

# Network blocker
URL: https://c15t.com/docs/frameworks/html/network-blocker
Hold fetch and XMLHttpRequest calls from a plain HTML page until their consent category is allowed, with network blocker rules queued on the c15t script tag.

## When you need it

Some code sends data with `fetch` or `XMLHttpRequest` from a place you cannot
change into a `text/plain` tag, such as a theme's bundled script, a plugin, or your own
code that runs before consent. A network blocker rule holds those requests
until the rule's category is allowed. Script tags and iframes do not need it;
gate those with [gated scripts](/docs/frameworks/html/components/gated-script)
and [embeds](/docs/frameworks/html/embeds).

## Add rules

Queue a `config` call with `networkBlocker` before the script tag:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    networkBlocker: {
      rules: [
        { id: 'collector', domain: 'collect.example.com', category: 'measurement' },
        {
          id: 'events',
          domain: 'example.com',
          pathIncludes: '/api/track',
          methods: ['POST'],
          category: 'measurement',
        },
      ],
      onRequestBlocked: ({ method, url, rule }) => {
        console.info('c15t blocked', method, url, rule?.id);
      },
    },
  }]);
</script>
```

The first rule blocks every request to `collect.example.com` and its
subdomains until measurement is allowed. The second blocks only POST requests
to paths on `example.com` that contain `/api/track`.

## Rule fields

|Field|Required|What it does|
|--|--|--|
|`domain`|Yes|The host to match. Subdomains match too: `example.com` covers `www.example.com`.|
|`category`|Yes|The category that lets matching requests through. A condition such as `{ and: ['measurement', 'marketing'] }` works too.|
|`pathIncludes`|No|Match only URLs whose path contains this text.|
|`methods`|No|Match only these HTTP methods, such as `['POST']`. All methods when omitted.|
|`id`|No|A name for the rule, shown in logs and passed to `onRequestBlocked`.|
|`vendor`|No|Also block while the visitor has turned this vendor off.|
|`vendorId`, `iabPurposes`, `iabLegIntPurposes`, `iabSpecialFeatures`|No|IAB TCF conditions, checked only under an IAB policy.|

## Blocker options

|Option|Default|What it does|
|--|--|--|
|`rules`|required|The rules above.|
|`enabled`|`true`|`false` keeps the configuration but blocks nothing.|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`.|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request.|

## What a blocked request sees

* A blocked `fetch` resolves with a `451` response. It does not reject, so
  check `response.ok` in code that expects data.
* A blocked `XMLHttpRequest` fires an `error` event.
* A request sent before the policy resolves waits, then goes out or is
  blocked once c15t knows the visitor's permissions. If the policy fails to
  load, it is blocked.
* A request that does not match any rule goes out at once.

The rules' categories are added to the preference dialog, as they are for
gated scripts.

## What it cannot block

The network blocker patches `fetch` and `XMLHttpRequest` after the script tag
runs. It does not cover:

* `navigator.sendBeacon`, WebSockets and `EventSource`;
* requests from `<img>`, `<script>`, `<link>` and `<iframe>` elements;
* requests sent before the c15t tag ran. With `defer`, the tag runs after the
  page has parsed, so inline scripts anywhere in the page run before it;
* requests from other frames and from service workers.

Use gated tags for scripts and iframes. When inline code sends requests while
the page parses, load the c15t tag without `defer` at the top of `<head>`, so
it runs first. The banner still waits for the document to parse before it
mounts.

## Check it works

1. Open the page in a private window with the console and Network tab open.
2. Trigger the request, for example by loading the page that sends it. The
   console shows `[c15t] blocked POST https://example.com/api/track (rule: events)`
   and the Network tab shows no request.
3. Allow measurement and trigger it again. The request goes out.

# Vendor consent
URL: https://c15t.com/docs/frameworks/html/vendor-consent
Let visitors allow a category such as marketing on a plain HTML page and still turn off one vendor in it, with the vendors option, data-c15t-vendor on gated tags and the vendor switches in the c15t script tag's preference dialog.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors

Queue a `config` call with `vendors` before the c15t script tag. Each `id` is
the slug your gated tags and iframes name:

```html title="index.html"
<!-- Runs before the deferred c15t.js tag, so init() picks it up -->
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			vendors: [
				{
					id: 'posthog',
					name: 'PostHog',
					category: 'measurement',
					description: 'Product analytics and session insights.',
					privacyPolicyUrl: 'https://posthog.com/privacy',
				},
				{
					id: 'youtube',
					name: 'YouTube',
					category: 'measurement',
					description: 'Embedded videos.',
					privacyPolicyUrl: 'https://policies.google.com/privacy',
				},
				{
					id: 'x-pixel',
					name: 'X Pixel',
					category: 'marketing',
					description: 'Ad conversion tracking.',
					privacyPolicyUrl: 'https://x.com/en/privacy',
				},
			],
		},
	]);
</script>
```

`vendors` is an ordinary `config` option, so `c15t.init({ vendors })` on a
page with `data-manual` works too. See
[configuration](/docs/frameworks/html/configuration).

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate tags and iframes by vendor

Add `data-c15t-vendor` to a gated `<script type="text/plain">` tag, next to
its `data-c15t-category`. The tag runs once its category is allowed and the
visitor has not switched its vendor off:

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	data-c15t-vendor="posthog"
	src="/vendor/posthog.js"
></script>
<!-- X Pixel's base code, pasted inline -->
<script
	type="text/plain"
	data-c15t-category="marketing"
	data-c15t-vendor="x-pixel"
>
	!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);
	},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',
	a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');
	twq('config','YOUR_X_PIXEL_ID');
</script>
```

Add `data-vendor` to a gated iframe:

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	data-vendor="youtube"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

|Target|Field|
|--|--|
|Gated `<script type="text/plain">` tag|`data-c15t-vendor="x-pixel"` next to `data-c15t-category`|
|Gated iframe|`data-vendor="x-pixel"`|
|`scripts` entry in `config`|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|

`data-c15t-vendor` does nothing without `data-c15t-category`. On a page whose
c15t tag has a nonce, a vendor-gated tag still needs that nonce, like every
[gated tag](/docs/frameworks/html/components/gated-script#gated-tags-on-a-page-with-a-nonce).
An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone.

A tag's `data-c15t-vendor` slug counts as declared, so a stored denial holds
even before your `vendors` list or the backend names that vendor. The
preference dialog lists the vendor only once a declaration gives it a `name`
and a `privacyPolicyUrl`.

## What the preference dialog shows

The preference dialog in `c15t.js` lists each declared vendor under its
category, with its own switch. `c15t.headless.js` has no dialog; record vendor
switches from your own UI with `save()`.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## Read and record vendor choices from your own script

`window.c15t` and `c15t.client` have three reads for vendor consent:

|Method|Returns|
|--|--|
|`getDeclaredVendors()`|The vendors from `vendors`, the backend and the slugs on scripts, gated tags and iframes. Empty under an IAB policy.|
|`getVendorChoice()`|The recorded vendor decision, whose `denied` lists the vendors the visitor switched off, or `null` before any vendor decision.|
|`isVendorAllowed(id)`|`true` when the vendor is declared, its category is allowed and the visitor has not switched it off.|

Reads cannot be queued, so call them from `onInit` or after `c15t.ready()`.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

`save()` accepts a `vendors` map next to the categories. Vendors you leave out
keep their recorded state. `save` can be queued, so this works before and
after the tag loads:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['save', { marketing: true, vendors: { 'x-pixel': false } }]);
</script>
```

Call it from a visitor's action, such as a switch in your own form, never at
page load. A save that changes only vendors still fires the `consent` event,
and c15t checks gated tags again, so a tag waiting on a vendor that was
switched back on runs. See [window.c15t API](/docs/frameworks/html/api) and
[events and callbacks](/docs/frameworks/html/callbacks).

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Open the page in a private window with DevTools Network open and filtered to
`ads-twitter.com`:

1. Declare `x-pixel` and gate X Pixel's tag with
   `data-c15t-category="marketing"` and `data-c15t-vendor="x-pixel"`. Open
   **Privacy settings**. The marketing row lists X Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open **Privacy settings**, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   tags still run.
4. Reload again. The X Pixel switch is still off, and in the console
   `c15t.isVendorAllowed('x-pixel')` returns `false`.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open **Privacy settings** and click **Accept All**. `uwt.js` loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/html/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns on a plain HTML page when that category is denied, with the clearOnRevocation option of the c15t script tag.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns in the script tag's
config. When that category is denied, c15t deletes them:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    clearOnRevocation: {
      measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
      marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
    },
  }]);
</script>
```

Put this before the c15t script tag. c15t reads the config once, at start.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/html/customize
Change the c15t script tag banner on a plain HTML site with theme tokens, extra CSS, layout, copy and legal links, or replace it with your own HTML.

## See the designs

See the [design gallery](/docs/customization/recipes) for five banner designs,
including a custom bottom bar built on the headless script tag.

## Change colors, radius and fonts

Queue a `config` call with `ui.theme` before the script tag. This block turns
the buttons purple and rounds the cards:

```html title="index.html"
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			ui: {
				theme: {
					colors: {
						primary: '#6943a3',
						primaryHover: '#533285',
						textOnPrimary: '#ffffff',
					},
					radius: { lg: '18px' },
				},
			},
		},
	]);
</script>
```

Put the block in the same `<head>` as the tag. The tag has `defer`, so any
inline script above or below it runs first. `theme` takes the same token
object as the other c15t packages; [theme tokens](/docs/customization/tokens)
lists every token and what it changes. The banner, the preference dialog and
the trigger button all read the same tokens.

## Add CSS inside the shadow root

The banner renders in a shadow root with its own copy of the stylesheet, so a
theme's global `button {}` rule cannot reach it and the banner cannot restyle
your page. To target one part, pass CSS in `ui.css`. c15t adds it after the
bundled stylesheet, inside the shadow root:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    ui: { css: '[data-testid="consent-banner-card"] { border: 3px solid #6943a3; }' },
  }]);
</script>
```

Select parts by their `data-testid` attributes, which match the other c15t
packages. Inspect the banner in the browser's element panel to find a part's
`data-testid`.

To style parts with classes from your own stylesheet, such as a Tailwind
build, put the classes on parts with `ui.theme.slots` and link the stylesheet
into the shadow root with `ui.stylesheetURLs`. Page CSS can also reach a part
by its slot key with `[data-c15t-ui]::part(consentBannerCard)`.
[Class names and CSS-in-JS](/docs/customization/class-names) and
[Tailwind CSS](/docs/customization/tailwind) show both, and
[component parts](/docs/customization/slots) lists the slot keys.

## Style it with your own stylesheet

Add `data-shadow="false"` to the script tag, or set `ui: { shadow: false }`, and
c15t renders the UI into the page. c15t still adds its stylesheet, and your
page's CSS now applies too:

```css
[data-c15t-ui] [data-testid="consent-banner-card"] {
  border: 3px solid #6943a3;
}
```

Your theme's global rules reach the banner in this mode, so check buttons and
headings after you switch. In the page, c15t's rules sit in
`@layer components`, and any CSS outside a layer beats them whatever its
specificity. That includes a theme's global `button {}` rule and Tailwind 3's
preflight, which removes the button padding and card borders. On a site with
Tailwind 3 or such global rules, keep the default shadow root. To write every rule yourself, set
`ui: { shadow: false, noStyle: true }`. c15t then renders unstyled markup with
the same `data-testid` attributes.

c15t puts its stylesheet in a `<style>` element next to the UI. To serve the
stylesheet as a file instead, set `ui: { shadow: false, styles: false }` and
link `dist/c15t.css` from the same package version as the script.

## Change the banner's shape and position

`presentation.prompt` sets the banner's shape and position:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    presentation: { prompt: { variant: 'bar', position: 'bottom' } },
  }]);
</script>
```

|`variant`|Positions|
|--|--|
|`floating` (default)|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

The [banner](/docs/frameworks/html/components/banner#change-the-layout) page
lists the button layout options. The policy still wins. A notice never blocks the page, a choice wall always
does, and a policy's required buttons stay visible.
[Keep behavior and appearance separate](/docs/customization/overview#keep-behavior-and-appearance-separate)
explains the split.

## Change the copy and language

For one-off wording, set `ui.banner.title`, `description`, `acceptButtonText`,
`rejectButtonText` or `customizeButtonText`; the [banner](/docs/frameworks/html/components/banner#change-the-text)
page lists them. For wording shared by the banner and the dialog, and for other
languages, see [translations](/docs/frameworks/html/translations).

The bundle only carries English. Other languages come from your Inth project,
the policy manifest or your `i18n` messages. Your `i18n` messages for the
language in use override the project's or manifest's copy key by key, and
keys you leave out keep that copy. `data-language="de"` on the tag forces a
language instead of the browser's.

## Show legal links

Add `data-privacy-policy-url`, `data-cookie-policy-url` or `data-terms-url` to
the tag and the banner and dialog show those links. To show different links on
each surface, set `legalLinks` in `config`, then list the links for each
surface in `ui.banner.legalLinks` and `ui.dialog.legalLinks`. An empty list or
`null` hides links on that surface.

`data-hide-branding` removes the "Secured by c15t" tag from both surfaces.

## Set dark mode and animation

`data-color-scheme` picks `light`, `dark` or `system`, the default. Set it to
`none` to follow a `dark` or `c15t-dark` class on your page's `<html>`
instead. [Dark mode](/docs/customization/dark-mode) covers dark tokens in
`ui.theme.dark`.

`data-disable-animation` turns off the banner and dialog animations. Without
it, c15t skips them for visitors who ask for reduced motion.
[Motion and animation](/docs/customization/motion) covers per-surface settings
and the duration tokens.

## Build your own banner

Load `c15t.headless.js` instead of `c15t.js` and write the banner in your own
HTML. The runtime still resolves the policy, stores choices and gates scripts,
and `data-c15t-action` buttons work without code. [Headless](/docs/frameworks/html/headless)
walks through a complete bottom bar.

## Check it works

1. Open the page in a private window. The banner uses your colors and radius.
2. Open the preference dialog and turn on the floating trigger, if you use it.
   Both use the same tokens as the banner.
3. Switch your system between light and dark mode. With
   `data-color-scheme="system"`, the banner follows it.

# Translations
URL: https://c15t.com/docs/frameworks/html/translations
Choose the language of the c15t banner and preference dialog on a plain HTML site, change its wording, and add languages in hosted and offline mode with the script tag.

## Where the copy comes from

The script tag bundles English only. Other languages come from outside the
bundle, and which source wins depends on the mode:

|Mode|Where the copy comes from|
|--|--|
|Hosted, with `data-backend-url`|Your Inth project. The backend picks the language from the visitor's browser, or from `data-language`, and sends its copy with the policy.|
|Manifest, including a tag loaded from your backend's `/c15t.js`|The manifest's translations for the visitor's language.|
|Offline|English, or the language and messages you set in `i18n`.|

In every mode, your `i18n.messages` for the language in use override that copy
key by key. Text you set in `ui.banner`, such as `title` or
`acceptButtonText`, replaces the translated text for all languages.

## Pick the language

In hosted and manifest mode, c15t follows the visitor's browser language. To
force one, add `data-language` to the tag:

```html
<script
  src="https://your-project.inth.app/c15t.js"
  data-language="de"
  defer
></script>
```

A multilingual site can print each page's language into the tag, for example
from the `lang` attribute your CMS already writes on `<html>`.

To switch after load, call `c15t.setLanguage('fr')`. With a backend, c15t asks
the backend for French copy and re-renders the banner and dialog. In offline
mode, `data-language` and `c15t.setLanguage()` switch to a language that has
copy in the bundle or in `i18n.messages`. A language with no copy shows the
default copy. See [add a language in offline mode](#add-a-language-in-offline-mode).

## Change the wording

Set `i18n.messages` in a queued `config` call. You only list the keys you
change; the rest keep their default text:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    i18n: {
      locale: 'en',
      messages: {
        en: {
          common: { acceptAll: 'Accept', rejectAll: 'Reject optional' },
          cookieBanner: { title: 'Cookies on this site' },
        },
      },
    },
  }]);
</script>
```

With a backend, the `/init` response or the manifest carries your Inth
project's copy for the visitor's language. Your `i18n.messages` for that
language override it key by key, and keys you leave out keep the project's
copy. c15t looks for the exact language first, then the primary language, so a
visitor on `de-AT` gets your `de` messages. Messages for other languages are
not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps edits made in your Inth project visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording.

## Add a language in offline mode

Load `c15t.offline.js` without `data-backend-url`. Queue your `i18n`
configuration before that tag. Offline mode shows the language named in
`i18n.locale`, built from your messages over the English defaults:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    i18n: {
      locale: 'de',
      messages: {
        de: {
          common: {
            acceptAll: 'Alle akzeptieren',
            rejectAll: 'Alle ablehnen',
            customize: 'Anpassen',
            save: 'Einstellungen speichern',
            acknowledge: 'OK',
          },
          cookieBanner: {
            title: 'Wir respektieren Ihre Privatsphäre',
            description: 'Diese Website verwendet Cookies, um Ihr Erlebnis zu verbessern.',
          },
        },
      },
    },
  }]);
</script>
```

Keys you leave out stay in English, so translate every key your banner and
dialog show. The messages follow the same structure every c15t package uses.

The script tag bundles English only, so in offline mode every other language
needs an entry in `i18n.messages`. With one entry per language,
`data-language` and `c15t.setLanguage()` switch between them. A regional
code such as `de-AT` uses the `de` entry when there is no `de-AT` entry. A
language with no entry shows the default copy.

## Message keys the stock UI reads

|Key|Where it shows|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Banner heading and text under a choice policy.|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Banner heading and text under a notice policy.|
|`common.acceptAll`, `common.rejectAll`, `common.customize`|Banner and dialog buttons.|
|`common.acknowledge`|The notice's dismiss button.|
|`common.save`|The dialog's save button.|
|`common.securedBy`|The "Secured by" tag.|
|`consentManagerDialog.title`, `consentManagerDialog.description`|Dialog heading and text.|
|`consentTypes.measurement.title`, `consentTypes.measurement.description` and the other categories|Each category row in the dialog.|
|`legalLinks.privacyPolicy`, `legalLinks.cookiePolicy`, `legalLinks.termsOfService`|Legal link labels, when a link has no `label` of its own.|
|`rights.optOut`, `rights.preferences`|The extra button an opt-out policy adds to the banner.|

The trigger's accessible name is not a message. Set `ui.trigger.ariaLabel`
per page instead.

## Right-to-left languages

For a right-to-left language such as Hebrew, the banner and dialog set
`dir="rtl"` and a banner at a default left or right position moves to the
other side. Check wrapping and button order after you switch.

[Copy and translations](/docs/customization/translations) covers labelling
actions honestly and testing long strings.

## Check it works

1. Set your browser's preferred language to German and open the page in a
   private window. With a backend, the banner shows your project's German
   copy.
2. Add `data-language="fr"` to the tag and reload. The banner switches to
   French.
3. Open the preference dialog. Its title, category names and buttons use the
   same language as the banner.

# Headless
URL: https://c15t.com/docs/frameworks/html/headless
Render your own consent banner and preferences in plain HTML with c15t.headless.js, the ui event and data-c15t-action buttons, while c15t keeps resolving the policy, storing choices and gating scripts.

## When to go headless

Load `c15t.headless.js` when theme tokens and CSS cannot give you the banner
you want, for example a bar that matches your site's markup exactly. The
headless build keeps everything except the UI:

* policy resolution, stored choices and backend saves;
* gated scripts, gated iframes and the network blocker;
* `window.c15t`, its events and the `data-c15t-action` page hooks.

It ships no banner, no preference dialog, no trigger and no CSS. Before you
switch, check whether [customize](/docs/frameworks/html/customize) covers the
change, because a custom UI takes on every duty the stock one handles.

## Build a bottom bar

This block replaces the stock tag. It loads the headless build, then renders a
bar with Accept, Reject, Preferences and Save controls. The accept, reject,
customize and dismiss buttons are `data-c15t-action` buttons, so they need no
code. One `ui` listener shows the bar, switches it into preferences mode and
swaps the buttons for a notice:

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.headless.js"
	defer
></script>

<style>
	.cookie-bar {
		position: fixed;
		inset: auto 0 0;
		z-index: 50;
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		gap: 0.75rem 1.5rem;
		padding: 0.875rem 1.5rem;
		background: #14213d;
		color: #f8f9fb;
		font:
			0.9375rem/1.5 system-ui,
			sans-serif;
		box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
	}

	.cookie-bar__text {
		flex: 1 1 20rem;
		margin: 0;
	}

	.cookie-bar__actions {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem;
	}

	.cookie-bar button {
		padding: 0.5rem 1rem;
		border: 1px solid #f8f9fb;
		border-radius: 999px;
		background: transparent;
		color: inherit;
		font: inherit;
		cursor: pointer;
	}

	.cookie-bar .cookie-bar__button {
		background: #f8f9fb;
		color: #14213d;
		font-weight: 600;
	}

	.cookie-bar .cookie-bar__link {
		border-color: transparent;
		text-decoration: underline;
		text-underline-offset: 3px;
	}

	.cookie-bar button:focus-visible {
		outline: 2px solid #fca311;
		outline-offset: 2px;
	}
	/* On narrow screens, Reject and Accept share a row at equal width. */
	@media (max-width: 30rem) {
		.cookie-bar__actions {
			width: 100%;
		}

		.cookie-bar__actions button {
			flex: 1 1 40%;
		}

		.cookie-bar__actions .cookie-bar__link {
			flex-basis: 100%;
		}
	}

	/* The headless build has no dialog, so preferences open inside the bar. */
	.cookie-bar[hidden],
	.cookie-bar__prefs[hidden] {
		display: none;
	}

	.cookie-bar__prefs {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem 1.25rem;
		flex-basis: 100%;
		margin: 0;
		padding: 0;
		border: 0;
	}

	.cookie-bar__prefs label {
		display: flex;
		align-items: center;
		gap: 0.375rem;
	}
</style>

<section
	id="cookie-bar"
	class="cookie-bar"
	aria-label="Cookie consent"
	hidden
>
	<p class="cookie-bar__text">
		We use cookies to measure traffic and improve this site. Choose which
		ones can run.
	</p>
	<fieldset
		class="cookie-bar__prefs"
		hidden
	>
		<legend class="cookie-bar__text">Allow these cookies:</legend>
		<label
			><input
				type="checkbox"
				name="functionality"
			/>
			Functionality</label
		>
		<label
			><input
				type="checkbox"
				name="measurement"
			/>
			Measurement</label
		>
		<label
			><input
				type="checkbox"
				name="experience"
			/>
			Experience</label
		>
		<label
			><input
				type="checkbox"
				name="marketing"
			/>
			Marketing</label
		>
	</fieldset>
	<div class="cookie-bar__actions">
		<!-- c15t wires data-c15t-action buttons itself; they need no code. -->
		<button
			type="button"
			class="cookie-bar__link"
			data-c15t-action="customize"
		>
			Preferences
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="dismiss"
			data-notice-only
			hidden
		>
			Got it
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="reject"
			data-choice-only
		>
			Reject all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="accept"
			data-choice-only
		>
			Accept all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-save
			hidden
		>
			Save
		</button>
	</div>
</section>

<script>
	const bar = document.getElementById('cookie-bar');
	const prefs = bar.querySelector('.cookie-bar__prefs');
	const saveButton = bar.querySelector('[data-save]');
	const switches = prefs.querySelectorAll('input');
	const choiceButtons = bar.querySelectorAll('[data-choice-only]');
	const noticeButtons = bar.querySelectorAll('[data-notice-only]');

	// The tag is deferred, so queue calls until window.c15t is the real API.
	window.c15t = window.c15t || [];
	const queue = (call) => {
		if (Array.isArray(window.c15t)) {
			window.c15t.push(call);
		} else {
			window.c15t[call[0]](...call.slice(1));
		}
	};

	// c15t says which surface is due; the page decides what it looks like.
	// 'banner' shows the bar, 'dialog' opens the switches, 'none' hides it.
	queue([
		'on',
		'ui',
		(surface) => {
			const { kind } = c15t.getSnapshot().promptRequirement;
			const editing = surface === 'dialog';
			// A notice gets one acknowledgement button instead of Accept and Reject.
			for (const button of choiceButtons) {
				button.hidden = kind === 'notice' && !editing;
			}
			for (const button of noticeButtons) {
				button.hidden = kind !== 'notice' || editing;
			}
			for (const input of switches) {
				input.checked = c15t.has(input.name);
			}
			prefs.hidden = !editing;
			saveButton.hidden = !editing;
			bar.hidden =
				surface === 'none' || (surface === 'banner' && kind === 'none');
		},
	]);

	// Save records exactly what the switches show.
	saveButton.addEventListener('click', () => {
		const choice = {};
		for (const input of switches) {
			choice[input.name] = input.checked;
		}
		c15t.save(choice);
	});
</script>
```

Put the block at the end of `<body>`.

## Follow the surface c15t wants shown

c15t still decides which surface should show. The `ui` event reports it:

|`ui` payload|What your page shows|
|--|--|
|`'banner'`|The first prompt. Read `promptRequirement.kind` to choose between a choice and a notice.|
|`'dialog'`|Your preferences view. A `data-c15t-action="customize"` button, a `#c15t-preferences` link or `c15t.openDialog()` asked for it.|
|`'none'`|Nothing. Hide the bar.|

A `ui` listener added after the policy resolved runs at once with the current
surface, so a late script does not miss the first banner. Your own controls
change the surface with `c15t.showBanner()`, `c15t.openDialog()` and
`c15t.closeDialog()`, or the matching `data-c15t-action` values. None of them
records anything.

## Read the prompt the policy requires

`c15t.getSnapshot()` returns the fields a custom UI renders from:

|Field|What it tells your UI|
|--|--|
|`promptRequirement.kind`|`'choice'` needs a decision, `'notice'` needs only an acknowledgement, `'none'` needs no prompt.|
|`policyRule.actions.required`|The buttons the policy requires on the first prompt, such as `accept` and `reject`.|
|`policyRule.actions.allowed`|Every button the policy allows there.|
|`policyRule.rights`|Rights the visitor has, such as `preferences` and `opt-out`.|
|`policyRule.scope`|The categories the policy covers.|
|`effectivePermissions`|Whether each category is allowed right now.|
|`explicitChoice`|What the visitor recorded, if anything.|

Use `c15t.has(category)` to set each switch in your preferences view to the
current permission. Save exactly what the switches show with
`c15t.save({ measurement: true, marketing: false })`.

## What your UI must handle

A custom UI takes on everything the stock banner does:

* **Every prompt kind.** Show a decision for `choice`, a dismissable notice
  for `notice`, and nothing for `none`. Do not assume every prompt is accept
  or reject, or that no prompt means consent.
* **The policy's required actions.** Render every action in
  `policyRule.actions.required`, at equal prominence where the policy asks.
* **A way back.** Keep a [preferences link](/docs/frameworks/html/components/preferences-link)
  on every page after the banner closes.
* **Visitor actions only.** Call `save()`, `acceptAll()`, `rejectAll()` and
  `dismissNotice()` only from a click or key press, never on load.
* **Accessibility.** Focus, keyboard use, labels, error states and narrow
  screens are yours. Use native buttons and a labelled region or dialog.

Read [how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice.

## Keep the stock dialog with your own banner

To replace only the banner, keep `c15t.js` and turn the stock banner off:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', { ui: { banner: false } }]);
</script>
```

Your banner then follows the `ui` event for `'banner'`, and its customize
button opens the stock preference dialog.

## Check it works

Open the page in a private window with the Network tab open.

1. The bar appears once the policy resolves, with the buttons your policy
   requires. Vendor requests are absent.
2. Click **Reject all** and reload. The bar stays hidden and vendors stay
   blocked.
3. Click the **Privacy settings** link, turn on Measurement only and click
   **Save**. Measurement vendors load and marketing vendors do not.
4. Tab through the bar. Every control is reachable and labelled.

# Components
URL: https://c15t.com/docs/frameworks/html/components
Every consent surface and page hook the c15t script tag gives a plain HTML site, from the stock banner and preference dialog to data-c15t-action buttons and gated scripts and iframes.

## What the script tag puts on your page

`c15t.js` renders three surfaces of its own and reads four kinds of markup you
write. Each has its own page:

|Component|What it is|Page|
|--|--|--|
|Banner|The first prompt: a card or bar with the actions the policy requires.|[Banner](/docs/frameworks/html/components/banner)|
|Preference dialog|The category list where a visitor changes each choice.|[Preference dialog](/docs/frameworks/html/components/dialog)|
|Floating trigger|An optional corner button that reopens the dialog.|[Floating trigger](/docs/frameworks/html/components/trigger)|
|`data-c15t-action` buttons|Your own buttons that accept, reject, open the dialog or show the banner.|[Action buttons](/docs/frameworks/html/components/action-buttons)|
|`#c15t-preferences` links|Your own links that open the preference dialog.|[Preferences link](/docs/frameworks/html/components/preferences-link)|
|`<script type="text/plain">`|A vendor script that runs once its category is allowed.|[Gated scripts](/docs/frameworks/html/components/gated-script)|
|`<iframe data-src>`|An embed that loads once its category is allowed.|[Embeds](/docs/frameworks/html/embeds)|
|DevTools panel|A debugging panel, loaded from a second tag.|[DevTools](/docs/frameworks/html/dev-tools)|

`c15t.headless.js` keeps the four kinds of markup and drops the three
surfaces, so your page renders the banner and dialog. See
[headless](/docs/frameworks/html/headless). `c15t.iab.js` replaces the banner
and dialog with IAB TCF versions under an IAB policy. See
[IAB TCF](/docs/frameworks/html/iab).

## Where the surfaces render

The banner, dialog and trigger render inside one host element,
`<div data-c15t-ui>`, which c15t appends to the end of `<body>`. By default
the host has a shadow root with its own copy of the stylesheet, so your
theme's CSS does not reach the UI and the UI's CSS does not reach your page.
[Customize](/docs/frameworks/html/customize) covers theme tokens, CSS inside
the shadow root, and rendering into the page instead.

A tag in `<head>` runs before `<body>` exists. c15t starts resolving the
policy at once and mounts the UI when the document has parsed.

## Which surface shows

c15t decides which surface should show from the policy and the visitor's
records, then renders it:

* **Banner.** Shows when the policy asks for a choice or a notice and the
  visitor has not answered it. A policy that needs no prompt shows no banner.
* **Dialog.** Shows only when something opens it, such as the banner's
  customize button, an action button, a preferences link, the trigger or
  `c15t.openDialog()`.
* **Trigger.** Shows while neither the banner nor the dialog is open.

Saving a choice closes the banner or dialog in the same click. The `ui` event
reports each change of surface; see
[events and callbacks](/docs/frameworks/html/callbacks).

# Banner
URL: https://c15t.com/docs/frameworks/html/components/banner
The stock consent banner the c15t script tag shows on a plain HTML site, with its options, layouts, policy-driven buttons, keyboard behavior and data-testid styling hooks.

## What the banner shows

The banner is the first prompt a visitor sees. `c15t.js` renders it when the
resolved policy asks for a choice or a notice and the visitor has not answered
it yet. A returning visitor with a valid choice, and a visitor whose policy
needs no prompt, sees no banner.

The banner has a title, a description, optional legal links, a row of buttons
and a "Secured by" tag. You do not add markup for it. The
[quickstart](/docs/frameworks/html/quickstart) tag is enough:

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.js"
	defer
></script>
```

## Which buttons it shows

The policy decides the buttons, not the page:

|Policy prompt|Buttons|
|--|--|
|A choice|The actions the policy allows. By default that is Reject All and Accept All at equal size, then Customize.|
|A choice under a policy with an opt-out right and no reject action|The allowed actions plus "Do not sell or share my data", which opens the dialog.|
|A notice|"OK", which acknowledges the notice, plus any other action the policy allows.|

Accept and reject record a choice and close the banner in the same click.
Customize opens the [preference dialog](/docs/frameworks/html/components/dialog)
and records nothing. The notice button records that the visitor saw the
notice. It grants nothing. [How consent works](/docs/concepts/how-consent-works#notices-and-privacy-signals)
explains the difference.

`presentation.prompt` can reorder buttons, group them or make one primary.
When your layout drops a button the policy requires, c15t puts it back, and it
keeps accept and reject equally prominent where the policy says so.

## Change the text

Queue a `config` call before the tag and set the banner options under
`ui.banner`:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    ui: {
      banner: {
        title: 'Cookies on this site',
        description: 'We use cookies to measure traffic. Choose what can run.',
        rejectButtonText: 'Reject optional',
      },
    },
  }]);
</script>
```

These options replace the text in every language. For copy that changes with
the visitor's language, use [translations](/docs/frameworks/html/translations).

## Banner options

These go under `ui.banner`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`title`|`string`|translated title|Heading. A notice uses the notice title by default.|
|`description`|`string`|translated description|Body text. A notice uses the notice description by default.|
|`acceptButtonText`|`string`|"Accept All"|Label of the accept button.|
|`rejectButtonText`|`string`|"Reject All"|Label of the reject button.|
|`customizeButtonText`|`string`|"Customize"|Label of the button that opens the dialog.|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description. `null` or `[]` shows none.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag. The IAB banner always keeps it.|
|`scrollLock`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|
|`trapFocus`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|

The dismiss button of a notice always uses the translated
`common.acknowledge` label. Change it through `i18n`.

## Change the layout

`presentation.prompt` picks the banner's shape, position and button layout:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    presentation: {
      prompt: { variant: 'bar', position: 'bottom', direction: 'row' },
    },
  }]);
</script>
```

|`variant`|Positions|
|--|--|
|`floating` (default)|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

|`presentation.prompt` option|What it does|
|--|--|
|`layout`|The order of the buttons. A nested array groups buttons together.|
|`primaryActions`|The buttons drawn with the primary style.|
|`direction`|`row` (default) or `column`.|
|`uiProfile`|`compact` (default) sizes buttons to their labels. `balanced` and `strict` stretch every button and stack the groups.|
|`blocking`|Dim the page, stop it scrolling and keep focus in the banner.|

A notice never blocks the page and cannot use `wall`. A `wall` always blocks.
An invalid position falls back to the variant's default. In a right-to-left
language, a default left or right position flips.

## Show legal links

Add the link URLs to the tag. The banner and the dialog both show them:

```html
<script
  src="https://your-project.inth.app/c15t.js"
  data-privacy-policy-url="/privacy"
  data-cookie-policy-url="/cookies"
  defer
></script>
```

To show different links on each surface, set `legalLinks` in `config` and list
the keys in `ui.banner.legalLinks` and `ui.dialog.legalLinks`. Each link opens
in a new tab unless its `target` says otherwise.

## Keyboard and screen readers

* A non-blocking banner is a `role="region"` landmark named by its title.
  Focus stays where it was, and the page remains usable.
* A blocking banner is a modal `role="dialog"`. c15t moves focus into it,
  keeps Tab inside it and stops the page scrolling until the visitor answers.
* The banner sets `lang` and `dir` from the resolved language, so screen
  readers use the right voice and right-to-left text lays out correctly.
* Every action is a native `button`. The banner has no close button, because
  closing it without answering would not settle the prompt.
* Enter and exit transitions follow the visitor's reduced motion setting. Set
  `ui.disableAnimation` to turn them off for everyone.

## Style it

Theme tokens change colors, radius, fonts and spacing for the banner and every
other surface. See [customize](/docs/frameworks/html/customize). To target one
part, use its `data-testid` in `ui.css`:

|`data-testid`|Element|
|--|--|
|`consent-banner-root`|The positioned wrapper. Carries `data-variant`, `data-position` and `data-blocking`.|
|`consent-banner-card`|The card or bar.|
|`consent-banner-title`, `consent-banner-description`|The heading and body text.|
|`consent-banner-legal-link-privacyPolicy` and the other link keys|Each legal link.|
|`consent-banner-footer`|The button row.|
|`consent-banner-accept-button`, `consent-banner-reject-button`, `consent-banner-customize-button`, `consent-banner-dismiss-button`|Each action button.|
|`consent-banner-branding`|The "Secured by" tag.|
|`consent-banner-overlay`|The backdrop of a blocking banner.|

## Turn the banner off

`ui: { banner: false }` renders no banner. The policy still requires a prompt,
so render your own with [headless](/docs/frameworks/html/headless) instead of
leaving visitors without one.

## Check it works

Open the page in a private window.

1. The banner appears once the policy resolves, with the buttons your policy
   requires.
2. Press Tab. Focus reaches every button in order.
3. Click **Reject All** and reload. The banner stays closed.
4. In the DevTools panel's Location tab, pick a country with a different
   policy and run init. The banner changes to that policy's buttons, or
   disappears.

# Preference dialog
URL: https://c15t.com/docs/frameworks/html/components/dialog
The stock c15t preference dialog on a plain HTML site, where visitors change each consent category, with how it opens, which categories it lists, its options, keyboard behavior and styling hooks.

## What the dialog shows

The preference dialog lists each consent category with a switch and a short
description. Visitors use it to allow some categories and not others, and to
change their choice later. `c15t.js` renders it. You add no markup.

The dialog opens only when something asks for it:

* the banner's **Customize** button;
* a [`data-c15t-action="customize"` button](/docs/frameworks/html/components/action-buttons);
* a [link to `#c15t-preferences`](/docs/frameworks/html/components/preferences-link);
* the [floating trigger](/docs/frameworks/html/components/trigger);
* `c15t.openDialog()` from your own script.

Opening it records nothing and changes no permission.

## Which categories it lists

The dialog lists `necessary` first, always on and not switchable, then the
optional categories this page uses:

* the categories on your `<script type="text/plain" data-c15t-category>` tags,
  `<iframe data-category>` embeds, `scripts` entries and network blocker
  rules;
* the categories in `data-categories` on the tag, or `consentCategories` in
  `config`.

Only categories inside the policy's scope appear. When the page names no
category at all, the dialog lists every category the policy covers. Name a
category in `data-categories` when a vendor you gate in another way, such as
a tag manager, needs it:

```html
<script
  src="https://your-project.inth.app/c15t.js"
  data-categories="measurement,marketing"
  defer
></script>
```

[Consent categories](/docs/concepts/consent-categories) describes all five.

When you declare `vendors`, each category row also lists its vendors, with a
switch per vendor. See [vendor consent](/docs/frameworks/html/vendor-consent).

## What the switches start at

Each switch shows, in order of precedence:

1. what the visitor switched in this dialog and has not saved yet;
2. the visitor's recorded choice for that category;
3. `presentation.preferences.defaults` for that category, if you set it;
4. on under an opt-out policy or for a category the policy preselects,
   otherwise off.

Switching does not save. Closing the dialog without saving drops the unsaved
switches.

## Buttons

The dialog shows Reject All, Accept All and Save Settings. Save records every
listed category as its switch shows it. Accept and reject record every listed
category at once, whatever the switches show. Each closes the dialog, and the
banner too if it was open underneath.

`presentation.preferences` sets the layout of these buttons, as
`presentation.prompt` does for the banner. The policy requires all three, so a
layout that drops one gets it back.

## Options

## Dialog options

These go under `ui.dialog`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag at the bottom of the dialog.|

The dialog's title, description, category names and button labels come
from translations. Change them through `i18n`.

`ui: { dialog: false }` renders no dialog. The banner's Customize button and
every page hook that opens preferences then open nothing, so only turn it off
when your page renders its own dialog with [headless](/docs/frameworks/html/headless).

## Keyboard and screen readers

* The dialog is a `role="dialog"` named by its title and described by its
  description.
* By default it blocks the page. c15t moves focus to the first control, keeps
  Tab inside the dialog and stops the page scrolling. Set
  `presentation.preferences.blocking: false` to leave the page usable behind
  it.
* Escape closes it without saving, wherever focus is. That includes a
  non-blocking dialog while focus is on the page behind it. If the policy
  still owes a choice, the banner comes back. Clicking the
  backdrop does not close it.
* The dialog has no close button by design. A visitor using a mouse closes it
  by saving, accepting or rejecting.
* Each category row has a button that expands its description and a
  `role="switch"` button named after the category. The `necessary` switch is
  disabled.
* The dialog sets `lang` and `dir` from the resolved language.

## Style it

Theme tokens apply to the dialog as to the banner; see
[customize](/docs/frameworks/html/customize). For single parts, use these
`data-testid` values in `ui.css`:

|`data-testid`|Element|
|--|--|
|`consent-dialog-root`|The dialog element.|
|`consent-dialog-card`, `consent-dialog-header`, `consent-dialog-content`|The card and its sections.|
|`consent-dialog-title`, `consent-dialog-description`|The heading and body text.|
|`consent-widget-accordion-item-measurement` and the other category names|One category row.|
|`consent-widget-switch-measurement` and the other category names|One category's switch.|
|`consent-widget-vendor-list-measurement` and the other category names|One category's vendor list.|
|`consent-widget-vendor-switch-measurement-posthog`|One vendor's switch, by category and vendor id.|
|`consent-widget-footer`|The button row.|
|`consent-widget-footer-accept-all-button`, `consent-widget-reject-button`, `consent-widget-footer-save-button`|Each button.|
|`consent-dialog-branding`|The "Secured by" tag.|
|`consent-dialog-overlay`|The backdrop.|

## Check it works

1. Click a Privacy settings link. The dialog opens with focus on its first
   control.
2. Turn on **Analytics** (the `measurement` category) only and click **Save Settings**. Measurement vendors
   load and marketing vendors stay blocked.
3. Open the dialog again. **Analytics** is on and **Marketing** is off.
4. Turn Marketing on, press Escape and open the dialog again. Marketing is
   off, because the change was not saved.

# Floating trigger
URL: https://c15t.com/docs/frameworks/html/components/trigger
Add the c15t floating button that reopens the preference dialog on a plain HTML site, and set its corner, size, visibility and accessible name.

## Add the trigger

The trigger is a small round button in a corner of the page. Clicking it opens
the [preference dialog](/docs/frameworks/html/components/dialog). It gives
visitors a way back to their choices on every page, without a link in your
footer.

Add `data-trigger` to the script tag:

```html
<script
  src="https://your-project.inth.app/c15t.js"
  data-trigger
  defer
></script>
```

`data-trigger="false"` leaves it off. The trigger is off by default. A footer
[preferences link](/docs/frameworks/html/components/preferences-link) does the
same job and fits better on sites with a legal links section.

## Set its corner, size and visibility

Pass options under `ui.trigger` in a queued `config` call:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    ui: {
      trigger: {
        position: 'bottom-left',
        size: 'sm',
        showWhen: 'after-consent',
        ariaLabel: 'Cookie settings',
      },
    },
  }]);
</script>
```

## Trigger options

`ui.trigger: true` shows the trigger with its defaults. An object sets these:

|Option|Type|Default|What it does|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner the button starts in.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`showWhen`|`'always'` or `'after-consent'`|`'always'`|`after-consent` hides the button until the visitor has answered the prompt.|
|`ariaLabel`|`string`|"Open privacy settings"|The button's accessible name. It has no visible text.|
|`persistPosition`|`boolean`|`true`|Remember the corner a visitor dragged the button to, in localStorage. A remembered corner wins over `position`.|

## When it shows

The trigger hides while the banner or the dialog is open, and shows when
neither is. With `showWhen: 'after-consent'`, it also waits until the visitor
has answered the prompt, so a visitor who has not chosen yet sees only the
banner.

## Drag it to another corner

Visitors can drag the trigger. It snaps to the nearest corner in the direction
they moved it, and c15t remembers that corner in the `c15t-trigger-position`
localStorage key. A remembered corner wins over `position` on later visits.
Set `persistPosition: false` to always start at `position`.

A drag does not open the dialog. A click, Enter or Space does.

## Keyboard and screen readers

The trigger is a native `button` with only an icon, so `ariaLabel` is its only
name. Write it in the page's language; the default is English. The trigger is
in the page's tab order after your content, because c15t appends it to the end
of `<body>`.

## Open DevTools from it

While the [DevTools tag](/docs/frameworks/html/dev-tools) is loaded, the
trigger becomes a two-button toolbar: a DevTools button and the button that
opens the dialog, which stays in the corner. Clicking the DevTools button opens
and closes the panel beside the toolbar. Without the DevTools tag, the trigger
stays a single button.

## Style it

The trigger reads the same theme tokens as the banner. In `ui.css`, select it
with `[data-testid="consent-dialog-trigger"]`. It carries `data-position` with
its current corner and `data-size` with its size.

## Check it works

1. Accept or reject in the banner. The trigger appears in its corner.
2. Click it. The preference dialog opens and the trigger hides.
3. Drag it to the opposite corner and reload. It starts in the new corner.
4. Press Tab until the trigger has focus and press Enter. The dialog opens.

# Action buttons
URL: https://c15t.com/docs/frameworks/html/components/action-buttons
Make your own HTML buttons accept, reject, open preferences, dismiss a notice or reopen the banner with the data-c15t-action attribute and the c15t script tag, with no JavaScript.

## Wire a button without code

Add `data-c15t-action` to any element and c15t runs that action when a
visitor clicks it. The page needs no script of its own:

```html
<button type="button" data-c15t-action="customize">Cookie settings</button>
```

This works with `c15t.js`, `c15t.offline.js`,
`c15t.headless.js` and `c15t.iab.js`, and with `init()` from `@c15t/browser`
in a bundled app.

## Actions

|Value|What a click does|
|--|--|
|`accept`|Like the banner's accept button, allows every category the dialog offers without IAB. Under an IAB policy it confirms the vendors' declared processing through the CMP. Optional categories without declared consent purposes remain denied. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).|
|`reject`|Rejects every optional category the dialog offers.|
|`customize`|Opens the preference dialog. Records nothing.|
|`dismiss`|Dismisses a notice. This records an acknowledgement, not consent, and does nothing unless the policy shows a notice.|
|`banner`|Shows the banner again. Records nothing.|
|`close`|Closes the banner or dialog. Records nothing.|

An unknown value does nothing. Accept and reject close the banner or dialog in
the same click, then send the choice to the backend in the background.

## How clicks are matched

c15t listens for clicks on the whole document, so:

* Buttons added after the page loaded, for example by a page builder widget
  or a CMS block, work too.
* A click on a child element counts. An icon inside
  `<button data-c15t-action="accept">` triggers the action.
* c15t calls `preventDefault()` on the click. A `data-c15t-action` link does
  not navigate, and a `data-c15t-action` button inside a form does not submit
  it.

## Only record choices from visitor clicks

`accept` and `reject` record a consent choice. Keep them on controls a visitor
clicks on purpose, with labels that say what they do. Do not trigger them
from script with `element.click()`, and do not hide an accept button inside a
larger clickable area.

Use `customize` for a "Cookie settings" or "Privacy choices" control. It only
opens the dialog, so it is safe anywhere.

## Build a banner from action buttons

The [headless build](/docs/frameworks/html/headless) renders no banner, so your
page writes one from these buttons. The headless page shows a complete bottom
bar that uses `accept`, `reject`, `customize` and `dismiss`, and switches
between them by policy.

## Accessibility

c15t adds no role, label or keyboard handling. Use a native `button` for
actions and an `a` for navigation, so the control is focusable and responds to
Enter and Space. A `div` with `data-c15t-action` responds to clicks only.

## Check it works

1. Add a `data-c15t-action="reject"` button to a page and open it in a private
   window.
2. Click the button. The banner closes, and in DevTools the Network tab shows
   the save request to your backend's `/subjects`.
3. Reload. The banner stays closed.

# Preferences link
URL: https://c15t.com/docs/frameworks/html/components/preferences-link
Let visitors reopen c15t privacy settings on a plain HTML site from a footer link, a CMS menu item or a page builder link to the c15t-preferences fragment, with no JavaScript.

## Add a privacy settings link

Visitors need a way to change their choice after the banner closes. A link
whose `href` ends in `#c15t-preferences` opens the preference dialog:

```html title="index.html"
<a href="#c15t-preferences">Privacy settings</a>
```

Put it in the footer or legal links menu that every page renders. The link
works in places where you cannot add a `data-*` attribute or a script, such as
a CMS menu editor or a page builder's link field. Set the menu item's URL to
`#c15t-preferences`.

## How the link behaves

* c15t matches any `a[href]` whose `href` ends in `#c15t-preferences`. A
  link to `/about#c15t-preferences` opens the dialog on the current page and
  does not go to `/about`.
* A click opens the dialog and records nothing. c15t calls `preventDefault()`,
  so the URL does not change and the page does not scroll.
* Links added after the page loaded work, because c15t listens for clicks on
  the whole document.
* Opening a URL that already contains `#c15t-preferences` does not open the
  dialog. Only a click does.

A `<button data-c15t-action="customize">` does the same thing. Use whichever
fits your markup; see [action buttons](/docs/frameworks/html/components/action-buttons).

## Word the link for your visitors

"Privacy settings", "Cookie settings" and "Your privacy choices" all work.
Some US state privacy laws name specific link text, such as "Do not sell or
share my personal information". c15t does not change your link text by
region, so choose the wording your policy requires.

## When the dialog is off

With `ui: { dialog: false }` or `c15t.headless.js`, the link makes `dialog`
the active surface but nothing renders it. Your page must render its own
dialog when the `ui` event reports `'dialog'`. See
[headless](/docs/frameworks/html/headless).

## Check it works

1. Click the link on any page. The preference dialog opens and the address
   bar keeps its URL.
2. Change a category and save. The dialog closes.
3. Check a page from each template your site uses, because the link only
   works where the footer renders it.

# Gated scripts
URL: https://c15t.com/docs/frameworks/html/components/gated-script
Hold a vendor's script tag on a plain HTML page until its consent category is allowed with type="text/plain" and data-c15t-category, including load order, copied attributes and what happens on withdrawal.

## Make a script wait for consent

Change the vendor's `<script>` to `type="text/plain"` and name the category it
needs in `data-c15t-category`. Browsers do not run a `text/plain` script. Once
the category is allowed, c15t puts a normal copy of the tag in its place, and
the browser runs the copy.

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	src="/posthog.js"
></script>
<!-- X Pixel's base code, pasted inline -->
<script
	type="text/plain"
	data-c15t-category="marketing"
>
	!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);
	},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',
	a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');
	twq('config','YOUR_X_PIXEL_ID');
</script>
```

The first tag loads a file, the second holds the vendor's snippet inline.
Both forms work. Remove the original, active copy of each vendor tag so it
cannot run on its own.

## Attributes

|Attribute|Required|What it does|
|--|--|--|
|`type="text/plain"`|Yes|Stops the browser running the script. A tag without it runs at once, whatever its category.|
|`data-c15t-category`|Yes|One category name: `necessary`, `functionality`, `experience`, `measurement` or `marketing`.|
|`data-c15t-vendor`|No|A vendor slug. The tag also waits while the visitor has switched that vendor off. See [vendor consent](/docs/frameworks/html/vendor-consent).|
|`src`|No|Load the script from a URL. Without it, c15t runs the tag's inline text.|
|`async`|No|Load without waiting for earlier gated scripts, and let later ones start without waiting for this one.|
|`data-c15t-activated`|Set by c15t|`true` once c15t has run the tag, `invalid` when its category name is unknown, `untrusted` when the page has a nonce and the tag lacks it. Do not set it yourself.|

`necessary` is always allowed, so a `necessary` tag runs as soon as c15t
starts. A category name c15t does not know logs a console warning, and the tag
never runs.

## What c15t copies to the new tag

The replacement tag gets `src`, `async`, `defer`, `crossorigin`, `integrity`,
`referrerpolicy`, `id`, `nonce`, every other `data-*` attribute, and the
inline text. It gets `data-c15t-activated="true"` in place of `type`. Other
attributes, such as `class` or `fetchpriority`, are not copied.

The copied `nonce` keeps a nonce-based Content Security Policy working. A
`defer` attribute has no effect on a script added after the page parsed, so
ordering follows the rules below instead.

## Load order

c15t runs allowed tags in page order:

* An external script without `async` finishes loading, or fails, before c15t
  runs the next tag. An inline snippet after a library tag can use that
  library.
* An external script with `async` starts loading and c15t moves on at once.
* Tags that become allowed later, after a visitor accepts, run in page order
  among themselves.

Google's GA4 snippet shows why this matters. Its first tag loads the library
and its second calls it:

```html
<script type="text/plain" data-c15t-category="measurement" src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script type="text/plain" data-c15t-category="measurement">
  window.dataLayer = window.dataLayer || [];
  function gtag() { dataLayer.push(arguments); }
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
</script>
```

Leave `async` off the first tag so the library loads before the second tag
runs.

## When c15t looks for tags

* When it starts, which runs every tag a returning visitor already allowed.
* After every change to permissions, such as an accept, a save, or a policy
  that resolves.
* When a new gated tag is added to the page, for example by a page builder
  widget. A new tag whose category is already allowed runs straight away.

Each tag runs at most once per page load.

## Gated tags on a page with a nonce

When the c15t tag has a nonce, from its own `nonce` attribute or from
`data-nonce`, c15t runs only the gated tags that carry the same nonce:

```html
<script nonce="RANDOM_PER_RESPONSE" type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet
</script>
```

c15t skips a gated tag without the nonce, logs a console warning and marks the
tag `data-c15t-activated="untrusted"`. The tag's category is not added to the
preference dialog. c15t never copies the nonce onto a gated tag, so add it to
every gated tag, including tags your own code inserts later. This check stops
markup injected into your page from running as a trusted script once its
category is allowed. A page without a nonce runs every gated tag.
[Content Security Policy](/docs/frameworks/html/content-security-policy)
covers the rest of the policy.

## The categories reach the dialog

c15t adds the category of every gated tag to the categories the
[preference dialog](/docs/frameworks/html/components/dialog) offers, as long as
the policy covers it. A visitor can then allow a category because your page
uses it.

## What happens when a visitor withdraws permission

A script that ran cannot be stopped. When a visitor turns off a category they
had allowed, c15t saves the choice and reloads the page, and the new page
starts with the tag inert again. [Scripts](/docs/frameworks/html/scripts#what-happens-when-a-visitor-withdraws-permission)
covers turning the reload off and cleaning up cookies.

## When to use config scripts instead

A gated tag is the simplest form and works in any CMS field that accepts
HTML. Use a `scripts` entry in `config` instead when you need a callback after
the vendor loads or when consent changes. See
[load a script with callbacks](/docs/frameworks/html/scripts#load-a-script-with-callbacks).

## Check it works

Open the page in a private window with the Network tab open.

1. Filter for the vendor's domain. Nothing loads before a choice.
2. Allow the tag's category. The vendor's request appears, and in the Elements
   panel the tag now has `data-c15t-activated="true"` and no `type`.
3. Reload. The vendor loads at once, before you touch the banner.

# window.c15t API
URL: https://c15t.com/docs/frameworks/html/api
Reference for window.c15t on a plain HTML page, covering the call queue, manual start, reading permissions and recorded choices, saving choices, opening the banner and dialog, and properties.

## Call c15t before and after the tag loads

`window.c15t` is the only global the script tag uses. Before the tag runs, it
is an array of calls. Push `[method, ...args]` entries onto it:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', { legalLinks: { privacyPolicy: { href: '/privacy' } } }]);
  c15t.push(['on', 'ui', (surface) => console.log('surface:', surface)]);
</script>
```

When the tag runs, it replaces the array with the API object and replays the
calls in order. Always push onto the existing array.
`window.c15t = [[...]]` throws away calls that other scripts queued earlier,
including the DevTools tag's.

`c15t.push([...])` keeps working after the tag has loaded, and runs each call
by the same rules as a queued one. So a snippet written as
`window.c15t = window.c15t || []; c15t.push([...])` works whether it runs
before or after the tag. `push` returns the number of calls it received.

### Which calls you can queue

|Queued method|When it runs|
|--|--|
|`config`, `init`, `on`, `onInit`|In place, in queue order, as the bundle loads.|
|`subscribe`|Once the client exists.|
|`acceptAll`, `rejectAll`, `save`, `dismissNotice`, `saveIAB`, `showBanner`, `openDialog`, `closeDialog`, `setLanguage`, `identify`, `mountUI`, `processIframes`|In queue order, once the policy has resolved. A queued `openDialog` therefore stays open instead of being replaced by the banner.|
|Any other method, such as `getSnapshot`, `has`, `hasConsented`, `isVendorAllowed`, `ready` or `dispose`, and names c15t does not know|Skipped, with a console warning. Call them from `onInit` or after `ready()`.|

A queued call that throws is reported with `console.error`, and the calls
after it still run. A queue cannot hand back a return value, which is why
reads are skipped.

### How options merge

Options merge in this order, with later ones winning:

1. The tag's `data-*` attributes.
2. Each queued `config` call, in order.
3. Options passed to `c15t.init()`, when the tag has `data-manual`.

`ui`, `ui.banner` and `ui.dialog` merge key by key, so a `config` call that
sets `ui.theme` keeps the legal links the tag's attributes set. Every other
option replaces the earlier value.

`config` after the client has started logs a warning and does nothing.

## Start c15t yourself

With `data-manual` on the tag, the bundle installs `window.c15t` and waits.
`c15t.js` still requires a backend URL or hosted factory when `init()` runs.
Use `c15t.offline.js` for browser-only policy resolution. Manifest and custom
modes need the `@c15t/browser` ES module, a headless script with your own UI,
or the IAB script for an IAB policy.

Call `c15t.init()` when your page is ready, for example once it knows the
visitor's country:

```html
<script>
  window.c15t = window.c15t || [];
  document.addEventListener('DOMContentLoaded', () => {
    c15t.push(['init', { overrides: { country: document.body.dataset.country } }]);
  });
</script>
```

`init()` reads the original tag's attributes even if the tag has since been
removed, layers queued `config` calls and its own options on top, starts the
client and returns it. A second call returns the same client. Until `init()`,
queued actions and `subscribe` wait, and direct calls to methods that read or
change consent throw `call c15t.init() first`.

After `c15t.dispose()`, a new `c15t.init()` starts a fresh client with the
same attributes and queued `config` calls.

## Read state

|Method|Returns|Use it for|
|--|--|--|
|`ready()`|a promise of the snapshot|Wait until the policy has resolved. Safe to call before `init()`.|
|`has(category)`|`boolean`|Whether a category is allowed right now. Accepts a condition such as `{ and: ['measurement', 'marketing'] }`.|
|`hasConsented()`|`boolean`|Whether the visitor has answered the choice prompt, by a recorded choice or an acknowledgement of a prompt with nothing to decide.|
|`getSnapshot()`|the snapshot|The full consent state: permissions, recorded choice, policy, prompt and surface.|
|`subscribe(listener)`|an unsubscribe function|Call `listener` with the snapshot after every change.|
|`isVendorAllowed(id)`|`boolean`|Whether a vendor may run now: it is declared, its category is allowed and the visitor has not switched it off. `false` for an id nothing declares, with a console warning in development.|
|`getDeclaredVendors()`|an array of vendors|The vendors from `vendors`, the backend and the slugs on scripts, gated tags and iframes. Empty under an IAB policy.|
|`getVendorChoice()`|the vendor decision, or `null`|Which vendors the visitor switched off, in `denied`.|
|`on(event, listener)`|an unsubscribe function|Listen for `ready`, `consent`, `ui` or `error`. Safe to call before `init()`. See [events and callbacks](/docs/frameworks/html/callbacks).|

### A permission is not a recorded choice

`has('measurement')` answers "may measurement code run now?" Under an opt-out
policy it is `true` before the visitor has done anything. Use it, or
`snapshot.effectivePermissions`, to gate code.

`hasConsented()` and `snapshot.explicitChoice` answer "what did the visitor
decide?" They change only when the visitor accepts, rejects or saves. Use
them to report or display the visitor's decision, never to gate a vendor.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
lists which to read for each task.

Answers can change once the policy resolves, so wait for `c15t.ready()` or a
`ready` listener before you read them at page load.

## Record a choice

Call these only in response to a visitor's click or key press, never at load.

|Method|What it records|
|--|--|
|`acceptAll()`|Without IAB, allows every category the dialog offers. Under an IAB policy it confirms the vendors' declared processing through the CMP. Optional categories without declared consent purposes remain denied. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).|
|`rejectAll()`|Denies every optional category the dialog offers.|
|`save(choices)`|The categories you name, such as `{ measurement: true, marketing: false }`. Categories the dialog does not offer are ignored. A `vendors` map, such as `{ vendors: { 'x-pixel': false } }`, records vendor switches too. Fails under an IAB policy; use `saveIAB()`.|
|`saveIAB()`|Confirms the IAB purpose and vendor choices set on the CMP. `c15t.iab.js` only. See [IAB TCF](/docs/frameworks/html/iab).|
|`dismissNotice()`|Acknowledges a notice. Grants nothing. Resolves with `{ ok: false, reason: 'not-required' }` when no notice is showing.|
|`identify(user)`|Links the consent record to a signed-in user, such as `{ externalId: 'user_123', identityProvider: 'auth0' }`. An [`identityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link.|

`acceptAll()`, `rejectAll()`, `save()` and `saveIAB()` resolve to a result
with an `ok` flag. The choice applies in the browser and the banner closes
before the backend request finishes. When the request fails, `ok` is `false`,
the choice stays in effect, and c15t retries the request later.

## Show and hide the UI

|Method|What it does|
|--|--|
|`showBanner()`|Shows the banner. Records nothing.|
|`openDialog()`|Opens the preference dialog. Records nothing.|
|`closeDialog()`|Closes the dialog, or the banner when no dialog is open. Closing the dialog brings the banner back while the policy still owes a choice. Records nothing.|
|`setLanguage(code)`|Switches language and re-renders with that language's copy, from the backend or, in offline mode, from the bundled copy and `i18n.messages`. See [translations](/docs/frameworks/html/translations).|
|`mountUI(options?)`|Removes the stock UI and mounts it again, with new UI options or the configured ones. Throws in `c15t.headless.js`.|

In `c15t.headless.js`, `showBanner`, `openDialog` and `closeDialog` still
change the surface c15t reports through the `ui` event, so your own banner
can follow them.

## Lifecycle

|Method|What it does|
|--|--|
|`config(options)`|Adds options before the client starts. See [configuration](/docs/frameworks/html/configuration).|
|`init(options?)`|Starts the client. Only needed with `data-manual`.|
|`onInit(listener)`|Calls `listener` with the client once it exists, at once if it already does. Returns a function that cancels the call.|
|`push(...calls)`|Runs `[method, ...args]` calls by the queue rules above.|
|`processIframes()`|Pauses gated iframes that consent does not allow and restores the ones it allows. Needed only with `iframeBlocker: { disableAutomaticBlocking: true }`. See [embeds](/docs/frameworks/html/embeds#check-iframes-yourself).|
|`dispose()`|Removes the UI, the DevTools panel, page listeners, blockers and the scripts c15t added. Code that already ran keeps running.|

## Properties

|Property|What it holds|
|--|--|
|`version`|The `@c15t/browser` version.|
|`pkg`|`@c15t/browser`, `@c15t/browser/offline`, `@c15t/browser/headless` or `@c15t/browser/iab`, by bundle.|
|`mode`|`hosted`, `offline`, `manifest` or `custom` once started, else `null`. A transport factory passed as `mode` reports `custom`, except `hosted()` and `offline()`.|
|`hosting`|`'inth'` or `'self-hosted'` once `/init` reports who runs the backend, else `null`. Stays `null` in `offline` mode and with backends older than the field.|
|`client`|The started client, or `null`. It has the same methods plus `kernel`, `runtime`, `options`, `consentCategories`, `ui` and `setOverrides()`.|
|`devtools`|The DevTools panel once `c15t.devtools.js` mounted it, else `null`.|
|`hosted`, `offline`, `manifest`, `custom`|Transport factories. `c15t.js` exports only `hosted`; `c15t.offline.js` exports only `offline`. Headless and IAB export all four, for calls such as `c15t.init({ mode: c15t.manifest({ … }) })` with `data-manual`.|

`c15t.js` reports `pkg: '@c15t/browser'` and `mode: 'hosted'` once started.

`c15t.client.setOverrides({ country, region, language, gpc })` changes the
location, language or GPC signal policy matching uses. The DevTools Location
tab uses the same inputs.

## Check it works

1. Open the browser console on a page with the tag and run
   `await c15t.ready()`. It resolves with a snapshot whose `resolution.status`
   is `matched`.
2. Run `c15t.has('measurement')` and `c15t.hasConsented()` before and after
   you click **Reject All**. Under an opt-in policy both start `false`;
   afterwards `hasConsented()` is `true` and `has` stays `false`.
3. Run `c15t.push(['openDialog'])`. The dialog opens.

# Callbacks
URL: https://c15t.com/docs/frameworks/html/callbacks
Run code on a plain HTML page when c15t resolves the policy, when a visitor records a choice, when permissions change or when a request fails, with window.c15t events, DOM events and config callbacks.

## Pick the hook for the job

|You want to|Use|
|--|--|
|Start or stop your own code as permissions change|The `consent` event, or `callbacks.onPermissionsChanged`|
|Know that a visitor clicked accept, reject or save|`callbacks.onChoiceRecorded`|
|Wait until c15t knows the visitor's permissions|The `ready` event, or `c15t.ready()`|
|Show, hide or switch your own banner|The `ui` event|
|Report failed backend calls|The `error` event, or `callbacks.onError`|
|Flush data before the reload after a withdrawal|`callbacks.onBeforeConsentRevocationReload`|
|Listen from a script that does not use `window.c15t`|The `c15t:*` events on `document`|

Most pages need only the `consent` event. Prefer gating a vendor with a
[gated script](/docs/frameworks/html/components/gated-script) where you can,
because that works before any script of yours runs.

## Listen for events

Queue `on` calls before the tag. c15t attaches them when it starts, so they
hear the first `ready` and `consent` events:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['on', 'consent', (snapshot) => {
    if (snapshot.effectivePermissions.measurement) {
      startAnalytics();
    }
  }]);
</script>
```

`startAnalytics` stands for your own code. After the tag has loaded,
`c15t.on(event, listener)` works directly and returns a function that removes
the listener.

|Event|Payload|When it fires|
|--|--|--|
|`ready`|the snapshot|The policy has resolved and the UI can render. For a returning visitor, `hasConsented()` is reliable from here.|
|`consent`|the snapshot|Permissions, the recorded choice or the vendor switches changed. This includes a stored choice restored at start, a save, an expiry and a GPC change.|
|`ui`|`'banner'`, `'dialog'` or `'none'`|The surface c15t wants shown changed.|
|`error`|the error|A backend call failed, or an IAB step failed.|

A `ready` listener added after the policy resolved runs at once with the
snapshot from that moment. A `ui` listener added after that runs at once
with the current surface. `consent` and `error` listeners only hear later
changes.

## Listen on document

Each event is also dispatched on `document` as a `CustomEvent` named
`c15t:ready`, `c15t:consent`, `c15t:ui` or `c15t:error`, with the payload in
`event.detail`. A script that loads in any order, such as a tag manager
snippet, can listen without touching `window.c15t`:

```html
<script>
  document.addEventListener('c15t:consent', (event) => {
    const allowed = event.detail.effectivePermissions;
    console.log('measurement allowed:', allowed.measurement);
  });
</script>
```

Unlike `c15t.on`, a `document` listener added after an event fired does not
receive it. Add it before the c15t tag runs, or read the current state with
`c15t.getSnapshot()` once `window.c15t` is the API.

## Config callbacks

Callbacks go under `callbacks` in a queued `config` call:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    callbacks: {
      onChoiceRecorded: ({ snapshot, confirmed }) => {
        console.log('visitor confirmed', confirmed, snapshot.explicitChoice);
      },
      onPermissionsChanged: ({ snapshot, previous }) => {
        console.log('permissions', previous, '->', snapshot.effectivePermissions);
      },
      onError: ({ error }) => console.warn('c15t:', error),
    },
  }]);
</script>
```

|Callback|Payload|When it runs|
|--|--|--|
|`onChoiceRecorded`|`{ snapshot, confirmed, actionAt }`|A visitor accepted, rejected or saved. `confirmed` lists the categories this action recorded.|
|`onPermissionsChanged`|`{ snapshot, previous }`|Effective permissions changed value, for any reason.|
|`onError`|`{ error }`, a message string|A backend call or another command failed.|
|`onBeforeConsentRevocationReload`|`{ preferences }`|Right before the reload that follows a withdrawal. Runs synchronously; keep it short.|

## A recorded choice is not a permission change

`onChoiceRecorded` and `onPermissionsChanged` answer different questions:

* `onChoiceRecorded` runs only for a visitor's own accept, reject or save. It
  does not run when a stored choice is restored at load. Use it to report
  consent rates or to thank the visitor.
* `onPermissionsChanged` runs whenever what may run changes. That
  includes a save that changed something, a stored choice restored at load, a
  policy resolving, a choice expiring and a GPC signal. Use it to start and stop your code.

A save that leaves every permission as it was can run `onChoiceRecorded`
without `onPermissionsChanged`. Dismissing a notice runs neither, because it
records no choice and changes no permission.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Follow every change with subscribe

`c15t.subscribe(listener)` calls your listener with the full snapshot after
every change, including UI and policy changes that the events above skip. It
suits code that renders from the whole state, such as a custom banner. Queue
it like `on`; it attaches as soon as the client exists.

## Errors thrown by your listeners

A listener that throws does not fail the action that caused the event. c15t
logs the error with `console.error`, then runs the later `on` listeners for
the same event and dispatches the matching `c15t:*` event on `document`. The
same holds for a `ready` or `ui` listener that `c15t.on()` runs at once after
the policy resolved, so `c15t.on()` still returns the function that removes
the listener. Keep listeners quick, because they run synchronously while the
change is applied.

## Check it works

1. Add a `consent` listener that logs `effectivePermissions` and an
   `onChoiceRecorded` callback that logs `confirmed`.
2. Open the page in a private window under an opt-in policy. Neither logs,
   because nothing is allowed yet and nobody has chosen.
3. Click **Accept All**. Both log.
4. Reload. The `consent` listener logs the restored permissions and
   `onChoiceRecorded` stays silent.

# IAB TCF
URL: https://c15t.com/docs/frameworks/html/iab
Load the c15t IAB TCF build on a plain HTML page with one script tag, configure the CMP ID and vendors, and confirm TC strings from your own code.

## Load the IAB build

Load `c15t.iab.js` instead of `c15t.js` when your policy uses IAB TCF. It
contains the CMP, the TC string encoder, the IAB banner and the purpose and
vendor preference dialog. `c15t.js`, `c15t.offline.js` and
`c15t.headless.js` leave all of that out, so pages without an IAB policy stay
smaller. The stock banner on those builds stands aside for a policy that
uses the `iab` model, so a page that resolves one emits an `error` event and
throws an `IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`) as an uncaught
error. So does `c15t.iab.js` with `iab: false`. Load `c15t.iab.js` for
visitors whose policy uses IAB TCF, or remove the `iab` model from the
policy.

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    iab: { cmpId: YOUR_CMP_ID, vendors: [1, 2, 755] },
    legalLinks: {
      privacyPolicy: { href: '/privacy' },
      cookiePolicy: { href: '/cookies' },
    },
    ui: {
      banner: { legalLinks: ['privacyPolicy', 'cookiePolicy'] },
      dialog: { legalLinks: ['privacyPolicy'] },
    },
  }]);
</script>
<script
  src="https://your-project.inth.app/c15t.iab.js"
  defer
></script>
```

Replace `YOUR_CMP_ID` with the ID IAB Europe assigned your CMP at
[registration](https://register.consensu.org/CMP). Every TC string names the
CMP that wrote it, so never copy an ID from an example. A backend can supply
`cmpId` and the vendor list instead. `vendors` limits the list to the vendors
your site works with.

Load only one c15t bundle. `c15t.iab.js` throws an error if `c15t.js`,
`c15t.offline.js` or `c15t.headless.js` loaded first. When the resolved policy is not an IAB
policy, the IAB build shows the ordinary banner. If an IAB policy cannot load
its vendor list, the banner shows an error and keeps its confirm buttons
disabled.

A [self-hosted backend](/docs/self-host/overview) serves this build at
`/c15t.iab.js`. Set `script.config.iab` on the backend to supply CMP defaults.

## Confirm IAB choices from your code

`c15t.acceptAll()` and `c15t.rejectAll()` confirm through the CMP when the
policy is IAB. For individual choices, change the draft on the CMP handle and
confirm it with `c15t.saveIAB()`:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['onInit', async (client) => {
    await client.ready();
    const cmp = client.runtime.iab;
    if (!cmp) return;
    await cmp.whenReady?.();
    cmp.setPurposeConsent(1, true);
    cmp.setVendorConsent(755, true);
    const result = await client.saveIAB();
    if (!result.ok) client.openDialog();
  }]);
</script>
```

`ready()` waits for the policy. `cmp.whenReady()` waits for the vendor list and
CMP setup, and rejects if setup fails. The handle also has
`setPurposeLegitimateInterest`, `setVendorLegitimateInterest` and
`setSpecialFeatureOptIn`. Each edits the draft; `saveIAB()` confirms it.
`c15t.save({ ... })` with categories fails under an IAB policy, because it
cannot produce a TC string.

The CMP installs `window.__tcfapi`. `c15t.dispose()` removes it.

## How the stock dialog groups choices

In the stock preference dialog, turning on a purpose also gives consent to the
vendors that use that purpose on a consent basis. A purpose's
legitimate-interest control changes the purpose and its legitimate-interest
vendors, and turning it off records an objection. A stack's control covers
its purposes and their consent-based vendors, and shows a mixed state when only
some are on. The vendor tab has search, per-vendor consent and
legitimate-interest controls, and each vendor's disclosures from the Global
Vendor List.

The `runtime.iab` setters each change only the choice they name. A custom UI
that wants the same grouping must set the related vendor choices itself.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Style and word the IAB UI

The IAB UI takes the same `ui.theme`, `ui.css` and `ui.shadow` options as the
ordinary banner; see [customize](/docs/frameworks/html/customize). With
`shadow: false` and your own stylesheet, load both `dist/c15t.css` and
`dist/c15t.iab.css` from the package.

The IAB banner always shows the c15t branding. `ui.dialog.hideBranding` hides
it in the preference dialog. `ui.banner.title`, `description` and the button
text options apply to the IAB banner too, and a description can include
`{partnerCount}`. `ui.iab.loadErrorText`, `saveErrorText` and
`moreVendorsText` change the loading error, save error and pagination copy.

Set `ui: false` to render your own IAB UI against the client. The page still
downloads the IAB build.

## Try it locally

The repository's `internals/fixtures/script-tag/iab.html` runs the IAB build offline with
a sample vendor list. Build `@c15t/browser`, run
`bun run --cwd internals/fixtures/script-tag dev` and open `/iab`. It uses a
demonstration CMP ID; replace it with your own for a real site.

# IAB GPP
URL: https://c15t.com/docs/frameworks/html/gpp
Add the IAB Global Privacy Platform API (__gpp) to a plain HTML page with the c15t.gpp.js script tag, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

`c15t.gpp.js` installs `window.__gpp`, the GPP 1.1 CMP API, and keeps its GPP
string in step with the visitor's choices. Prebid.js, Google Ad Manager and
other ad tech read US privacy signals from it.

## Load the GPP script

Add `c15t.gpp.js` next to the c15t script. It works with `c15t.js`,
`c15t.offline.js`, `c15t.headless.js` and `c15t.iab.js`:

```html
<script src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.gpp.js"></script>
<script
  src="https://your-project.inth.app/c15t.js"
  defer
></script>
```

Loading the script turns GPP on with the defaults. It installs a `__gpp`
stub as soon as it runs, so ad tags that call `__gpp` before c15t starts
are queued rather than lost. Load it without `defer`, before your ad tags,
to get that. The order relative to `c15t.js` does not matter.

Use the same version for both files. Pages that do not load `c15t.gpp.js`
download none of the GPP code. It also carries the TCF decoder that fills in
`parsedSections.tcfeuv2`, which makes it about 15 kB gzipped.

## Change the GPP options

Queue a `gpp` object with the rest of your configuration:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    gpp: { usFallback: 'none' },
  }]);
</script>
```

`gpp: false` keeps GPP off on a page that loads the script, and removes its
stub. `c15t.dispose()` removes `__gpp`.

To add the TCF EU section for visitors under an `iab` policy, load
`c15t.iab.js` instead of `c15t.js`; see [IAB TCF](/docs/frameworks/html/iab).

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/html/content-security-policy
Allow the c15t script tag, its stylesheet, backend requests, gated scripts and embeds under a Content Security Policy on a plain HTML site, with nonces or allowed origins.

## What c15t needs from your policy

The script tag loads one file, sends requests to your backend, adds a
`<style>` element for the stock UI, and runs your gated scripts and iframes
when they are allowed. Each needs a directive:

|Directive|Allow|Why|
|--|--|--|
|`script-src`|The host that serves `c15t.js`, such as `https://your-project.inth.app`. Add `https://cdn.jsdelivr.net` for `c15t.gpp.js`, `c15t.devtools.js`, or a bundle you load from the CDN.|The c15t bundle.|
|`script-src`|A nonce or hash for each inline script|Your queued `config` and `on` calls, and inline gated snippets.|
|`script-src`|Each vendor's script origin|Gated `<script src>` tags and `scripts` entries.|
|`connect-src`|Your backend's origin, such as `https://your-project.inth.app`|`/init`, `/subjects`, and `/manifest` in manifest mode.|
|`style-src`|The same nonce as the c15t tag, or the host you serve `c15t.css` from|The stock UI's `<style>` element, or the stylesheet file.|
|`frame-src`|Each embed's origin, such as `https://www.youtube-nocookie.com`|Gated iframes.|
|`img-src`, `connect-src`|Each vendor's collection endpoints|What the vendor scripts send once they run.|

A missing `connect-src` entry is the most common failure. The `/init`
request fails with a CSP error in the console, no policy resolves, and no
banner shows.

## Use a nonce

With a nonce-based policy, put the nonce on the c15t tag, on every inline
script that talks to `window.c15t`, and on every gated inline script:

```html
<script nonce="RANDOM_PER_RESPONSE">
  window.c15t = window.c15t || [];
  c15t.push(['config', { legalLinks: { privacyPolicy: { href: '/privacy' } } }]);
</script>
<script
  nonce="RANDOM_PER_RESPONSE"
  src="https://your-project.inth.app/c15t.js"
  defer
></script>
<script nonce="RANDOM_PER_RESPONSE" type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet
</script>
```

Your server generates `RANDOM_PER_RESPONSE` for each response and sends the
same value in the header, such as
`Content-Security-Policy: script-src 'nonce-RANDOM_PER_RESPONSE' 'strict-dynamic'; style-src 'nonce-RANDOM_PER_RESPONSE'`.
A static host that cannot vary the response cannot use a nonce; list origins
and hashes instead.

The c15t tag reads its own `nonce` and puts it on the stock UI's `<style>`
element and on every script that a `scripts` entry in `config` loads. An
entry's own `nonce` wins. To give c15t a nonce without putting it on the tag,
for example when `script-src` allows the tag by its origin, set
`data-nonce="RANDOM_PER_RESPONSE"` on the tag instead. `data-nonce` wins over
the tag's `nonce`.

Once the c15t tag has a nonce, c15t runs only the gated `text/plain` tags
that carry the same nonce. c15t runs a gated tag by creating a new `<script>`,
and `'strict-dynamic'` lets scripts that trusted code creates run without a
nonce, so without this check a tag injected into your page would run once its
category was allowed. c15t skips a gated tag without the nonce, logs a console
warning and marks the tag `data-c15t-activated="untrusted"`. It never copies
the nonce onto a gated tag, so add `nonce="RANDOM_PER_RESPONSE"` to every gated
tag you write, including tags your own code inserts later.

When c15t runs a gated tag, it copies that tag's `nonce` to the tag it
creates, so the browser accepts the snippet. With `'strict-dynamic'`, scripts
that c15t creates are trusted because the c15t tag itself carries the nonce.
Without `'strict-dynamic'`, each vendor origin must be in `script-src`.

## Allow the stock UI's styles

`c15t.js` renders its CSS in a `<style>` element inside the UI's shadow root.
Theme tokens and `ui.css` go into the same element. The element carries the
nonce from the c15t tag, or from `data-nonce`, so
`style-src 'nonce-RANDOM_PER_RESPONSE'` allows it without `'unsafe-inline'`.

A host that cannot send a nonce can render into the page and serve the
stylesheet as a file instead:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.css" />
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', { ui: { shadow: false, styles: false } }]);
</script>
```

With `styles: false` and no `theme` or `css` option, c15t adds no `<style>`
element. Put your token overrides in your own stylesheet. Your site's CSS now
reaches the banner, so check it after the switch. Use the same version for
the stylesheet and the script.

`c15t.headless.js` adds no styles at all. The DevTools panel adds its own
`<style>` element, so remove its tag before you apply a strict policy.

## IAB TCF

`c15t.iab.js` loads the Global Vendor List through your backend in hosted
mode, so the backend's origin in `connect-src` covers it. It adds
`dist/c15t.iab.css` rules to the same `<style>` element as the stock UI.

## Check it works

1. Send your policy as `Content-Security-Policy-Report-Only` first, and open
   the page with the console open.
2. The console shows no CSP violation for the c15t tag, `/init` or the
   banner's styles. The banner renders styled.
3. Allow each category. Each vendor's script and requests load without a
   violation.
4. Switch the header to `Content-Security-Policy` and repeat.

# Script tag attributes
URL: https://c15t.com/docs/frameworks/html/attributes-and-api
Reference for the c15t script tag on plain HTML pages, covering the bundle files, every data attribute on the script tag, the DevTools tag and your own markup, and the modes the attributes select.

## Where each part is documented

|Reference|Page|
|--|--|
|Bundle files and every `data-*` attribute|This page|
|`window.c15t` methods and the call queue|[window.c15t API](/docs/frameworks/html/api)|
|Options for `c15t.push(['config', …])`|[Configuration](/docs/frameworks/html/configuration)|
|Events, `c15t:*` DOM events and callbacks|[Events and callbacks](/docs/frameworks/html/callbacks)|

## Script files

`@c15t/browser` publishes browser bundles. Inth and a self-hosted c15t
backend serve `c15t.js`, `c15t.headless.js` and `c15t.iab.js` from the
backend's URL, such as `https://your-project.inth.app/c15t.js`, with the
backend URL already configured. Headless and IAB routes also inline the
policy manifest. Load a file from
`https://cdn.jsdelivr.net/npm/@c15t/browser@<version>/dist/<file>`, or the
same path on unpkg, when no backend serves it, such as `c15t.devtools.js` or
`c15t.offline.js`.

|File|What it contains|
|--|--|
|`c15t.js`|The default stock UI and client for hosted mode. Excludes offline policy presets, offline resolution and manifest transport code. Requires a backend URL or a queued hosted factory.|
|`c15t.offline.js`|The stock UI and client for offline mode only. Includes policy presets and excludes hosted and manifest transport code.|
|`c15t.headless.js`|The same runtime and `window.c15t` API with no banner, dialog or CSS. Your page renders the UI. See [headless](/docs/frameworks/html/headless).|
|`c15t.iab.js`|Replaces `c15t.js` when your policy uses IAB TCF. See [IAB TCF](/docs/frameworks/html/iab).|
|`c15t.devtools.js`|The DevTools panel, loaded as a second tag. See [DevTools](/docs/frameworks/html/dev-tools).|

Load one of `c15t.js`, `c15t.offline.js`, `c15t.headless.js` or
`c15t.iab.js` on a page, never two. `c15t.iab.js` throws an error if another one loaded first. When
`c15t.js`, `c15t.offline.js` or `c15t.headless.js` finds another c15t bundle
already installed, it leaves the first one in place and does not start a
second client.

`dist/c15t.css` and `dist/c15t.iab.css` are the stylesheets, for pages that
render the UI with `data-shadow="false"` and load the CSS themselves.

## Script tag attributes

The tag reads attributes once, when the script runs. The default `c15t.js`
bundle uses hosted mode and requires `data-backend-url` unless a queued
`config` supplies a backend URL or hosted factory.

`c15t.js` rejects offline or manifest mode, manifest options and
`data-policy-rules`, because the attribute contains preset names. Authored
`PolicyRule` objects can be passed in a queued `config` instead.
`c15t.offline.js` rejects backend URLs, manifest options and modes other
than offline. The headless and IAB bundles also accept manifest and custom
transports. Every bundle keeps the call queue, `data-manual` and the page
hooks described below.

|Attribute|What it does|
|--|--|
|`data-backend-url`|Your Inth or self-hosted backend URL. Selects hosted mode.|
|`data-mode`|Optional `hosted` for `c15t.js` or `offline` for `c15t.offline.js`. Headless and IAB also accept `manifest`; without it, they pick `manifest` when a manifest URL is set, `hosted` when a backend URL is set, and `offline` otherwise. Headless and IAB ignore unknown values; hosted and offline reject them.|
|`data-manifest-url`|Where headless or IAB fetches the policy manifest in manifest mode. See [choose a mode](#choose-a-mode).|
|`data-policy-rules`|Comma-separated policy presets for offline mode, such as `europeOptIn,usPrivacyStatesOptOut,worldNone`. Any name exported by `policyRulePresets` works; an unknown name throws. [Policies](/docs/concepts/policies) describes the presets.|
|`data-categories`|Comma-separated categories to offer in the preference dialog, such as `measurement,marketing`. Without it, the dialog offers the categories your gated scripts, iframes and rules use. This changes the dialog, not the policy.|
|`data-country`, `data-region`|The visitor's location, when your host can print it into the page. Policy matching uses these instead of detection.|
|`data-language`|Use this language instead of the browser's. See [translations](/docs/frameworks/html/translations).|
|`data-privacy-policy-url`, `data-cookie-policy-url`, `data-terms-url`|Show these legal links in the banner and the preference dialog.|
|`data-color-scheme`|`light`, `dark` or `system`. Defaults to `system`.|
|`data-trigger`|Show the [floating trigger](/docs/frameworks/html/components/trigger) that reopens the preference dialog.|
|`data-hide-branding`|Hide the "Secured by" tag in the banner and dialog. The IAB banner always keeps it.|
|`data-shadow="false"`|Render the UI into the page instead of a shadow root, so your stylesheet applies. See [customize](/docs/frameworks/html/customize#style-it-with-your-own-stylesheet).|
|`data-no-ui`|Start the runtime without the stock UI. `c15t.js` still downloads the UI code and CSS; load `c15t.headless.js` to skip them. The UI attributes above are ignored.|
|`data-manual`|Do not start. Your page calls `c15t.init()` later. See [start c15t yourself](/docs/frameworks/html/api#start-c15t-yourself).|
|`data-nonce`|The Content Security Policy nonce for the stock UI's `<style>` element and the scripts c15t loads. Without it, c15t uses the tag's own `nonce` attribute. See [Content Security Policy](/docs/frameworks/html/content-security-policy).|

Flag attributes such as `data-trigger` are on when present, unless their value
is `false`. `data-shadow` is the exception. Only `data-shadow="false"` changes
anything. `data-backend` is accepted as an older spelling of
`data-backend-url`.

Everything the attributes set, and every option they cannot express, can also
be passed in a queued `config` call. See
[configuration](/docs/frameworks/html/configuration).

## DevTools tag attributes

These go on the `c15t.devtools.js` tag:

|Attribute|What it does|
|--|--|
|`data-open`|Open the panel on load. `data-open="false"` keeps it closed.|
|`data-tab`|The first tab: `consents`, `scripts`, `location`, `policy`, `iab`, `events` or `actions`.|
|`data-position`|The corner: `bottom-right`, `bottom-left`, `top-right` or `top-left`.|

## Attributes on your own markup

These work anywhere on the page, including markup added after load:

|Markup|What it does|Page|
|--|--|--|
|`data-c15t-action="accept"`, `"reject"`, `"customize"`, `"dismiss"`, `"banner"` or `"close"`|Runs the action on click.|[Action buttons](/docs/frameworks/html/components/action-buttons)|
|A link whose `href` ends in `#c15t-preferences`|Opens the preference dialog on click.|[Preferences link](/docs/frameworks/html/components/preferences-link)|
|`<script type="text/plain" data-c15t-category="…">`|Runs the script once that category is allowed. `data-c15t-vendor` adds a vendor gate.|[Gated scripts](/docs/frameworks/html/components/gated-script)|
|`<iframe data-src="…" data-category="…">`|Sets the iframe's `src` once that category is allowed. `data-vendor` adds a vendor gate.|[Embeds](/docs/frameworks/html/embeds)|

c15t sets these attributes itself. Read them in CSS or tests, but do not
write them:

|Attribute|Where|Meaning|
|--|--|--|
|`data-c15t-activated`|Gated `<script>`|`true` once the tag ran, `invalid` when its category is unknown, `untrusted` when the page has a nonce and the tag lacks it.|
|`data-c15t-paused`|Gated `<iframe>`|c15t removed a `src` the iframe already had.|
|`data-c15t-ui`|The UI host `<div>`|The element that holds the banner, dialog and trigger.|
|`data-testid`|Parts of the stock UI|Stable names for styling and tests. Each component page lists them.|

## Choose a mode

|Mode|Set it with|What happens|
|--|--|--|
|Hosted|`c15t.js` with `data-backend-url`|Each fresh visit asks the backend's `/init` endpoint for the visitor's policy. Choices are saved to the backend.|
|Manifest|`c15t.headless.js` or `c15t.iab.js` with `data-manifest-url`, or `mode: 'manifest'` with an inline `manifest` in `config`|The browser resolves the policy from the backend's public, cacheable `/manifest`. Choices still go to the backend.|
|Offline|`c15t.offline.js` with no backend URL|Policy rules come from `data-policy-rules` or c15t's recommended rules. Choices stay in the browser. Not recommended for production environments.|

A tag loaded from a backend's `/c15t.js`, such as
`https://your-project.inth.app/c15t.js`, starts in hosted mode with the
backend URL already configured, so it needs no `data-backend-url`.

In manifest mode, c15t can take the backend URL from a manifest URL that ends
in `/manifest`. A manifest on another host, or an inline manifest, also needs
`data-backend-url` so saves have somewhere to go. When a policy depends on the
visitor's location and the page does not supply it, c15t falls back to the
backend's `/init`. [Data fetching](/docs/concepts/data-fetching) compares the
modes.

Use the default `c15t.js` for hosted mode and `c15t.offline.js` for offline
mode. For manifest mode or custom transports with the stock UI, use the
`@c15t/browser` ES module. The headless script supports those modes with your
own UI, and the IAB script supports them for IAB policies. Loading `c15t.js`
without a backend URL throws unless a hosted factory is supplied.

Offline mode cannot see the visitor's country. Without `data-country`, every
visitor gets the strict opt-in fallback.

# Configuration
URL: https://c15t.com/docs/frameworks/html/configuration
Every option you can pass to the c15t script tag on a plain HTML page through a queued config call, including scripts with callbacks, the network blocker, theme tokens, presentation, translations and storage.

## Pass options before the tag

Attributes on the script tag cover the common options. For everything else,
queue a `config` call in an inline script before the tag:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    legalLinks: { privacyPolicy: { href: '/privacy' } },
    ui: { banner: { legalLinks: ['privacyPolicy'] } },
    reloadOnConsentRevoked: true,
  }]);
</script>
<script
  src="https://your-project.inth.app/c15t.js"
  defer
></script>
```

The tag has `defer`, so an inline script anywhere in `<head>` runs before it.
Later `config` calls win over earlier ones, and all of them win over the tag's
attributes. `ui`, `ui.banner` and `ui.dialog` merge key by key; other options
replace the earlier value. A `config` call after the client started does
nothing and logs a warning. [window.c15t API](/docs/frameworks/html/api#how-options-merge)
explains the order.

A `config` object can hold functions, such as script callbacks, because it
never leaves the page.

## Connection and policy

The `init()` and `createConsentClient()` of the `@c15t/browser` ES module,
`@c15t/browser/headless` and `@c15t/browser/iab` take `mode` as a factory
and none of the connection options below it. The script-tag builds and the
`@c15t/browser/hosted` and `@c15t/browser/offline` entries take the rest of
the table: `c15t.js` and `@c15t/browser/hosted` accept hosted mode only and
require a backend URL or hosted factory, and `c15t.offline.js` and
`@c15t/browser/offline` accept offline mode only.

|Option|Type|Default|What it does|
|--|--|--|--|
|`mode`|A transport factory. Script-tag builds also take `'hosted'`, `'offline'` or `'manifest'`.|Required in the ES modules. Script-tag builds pick it from the other options.|A factory from `manifest()`, `hosted()`, `offline()` or `custom()` is used as is; see [consent modes](/docs/concepts/modes). In the script-tag builds, `manifest` when `manifest` or `manifestURL` is set, `hosted` when `backendURL` is set, otherwise `offline`. Hosted mode without `backendURL` throws.|
|`backendURL`|`string`|none|Script-tag builds, `/hosted` and `/offline` entries. Your Inth or self-hosted backend URL, for hosted and manifest modes. In the ES modules, pass it to the factory, such as `hosted({ backendURL })`.|
|`manifest`|`ConsentManifest`|none|Script-tag builds. The backend's policy manifest, inlined in the page, for manifest mode. In the ES modules, `manifest({ snapshot })`.|
|`manifestURL`|`string`|none|Script-tag builds. Where manifest mode fetches the manifest. A URL that ends in `/manifest` also gives the backend URL; any other URL needs `backendURL` too. In the ES modules, `manifest({ manifestURL })`.|
|`policyRules`|array of policy rules or preset names|recommended rules|Script-tag builds and the `/hosted` and `/offline` entries. Offline mode only. A preset name such as `'europeOptIn'` stands for that preset in `policyRulePresets`. An unknown name throws. In the ES modules, `offline({ policyRules })` with rule objects.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|The visitor's location, language or GPC signal, when the page knows it. Policy matching uses these instead of detection.|
|`prefetch`|kernel configuration|none|A server-resolved init answer. When it carries a resolved policy, the client renders from it and does not call `/init`.|
|`enabled`|`boolean`|`true`|`false` grants every category, shows no UI and loads every configured script at once.|

The [attributes reference](/docs/frameworks/html/attributes-and-api#choose-a-mode)
compares the modes and their bundle files.

## Scripts, blockers and data

|Option|Type|Default|What it does|
|--|--|--|--|
|`scripts`|`Script[]`|`[]`|Vendor scripts to load once their category is allowed. Each entry needs `id`, `category`, and `src` or `textContent`.|
|`consentCategories`|category names|categories your scripts, iframes and rules use|The categories the preference dialog offers, within the policy's scope. `necessary` is always included.|
|`networkBlocker`|`{ rules, enabled?, logBlockedRequests?, onRequestBlocked? }` or `false`|off|Hold `fetch` and `XMLHttpRequest` calls that match a rule until the rule's category is allowed.|
|`iframeBlocker`|`{ disableAutomaticBlocking? }` or `false`|on|Gate iframes that carry `data-category` or `data-vendor`. `false` turns it off. With `disableAutomaticBlocking: true`, c15t checks iframes only when you call `processIframes()`.|
|`nonce`|`string`|none|Content Security Policy nonce for the stock UI's `<style>` element and every `<script>` the `scripts` option loads. A script's own `nonce` wins. With a nonce set, c15t runs only the `<script type="text/plain" data-c15t-category>` tags that carry the same `nonce`.|
|`scriptLoader`|`{ onDebug? }`|none|`onDebug` receives every script loader lifecycle event.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. The preference dialog lists a switch for each. They merge with vendors from the backend, `vendor` fields on scripts and rules, and `data-c15t-vendor` on gated tags.|
|`clearOnRevocation`|cookies and storage keys per category|off|Delete named cookies and storage keys when their category is denied. Read once, at start.|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reload the page after an accept, reject or save turns off a category that was allowed, once the save request finishes.|
|`callbacks`|`{ onChoiceRecorded?, onPermissionsChanged?, onError?, onBeforeConsentRevocationReload? }`|none|Functions c15t calls on consent events.|
|`storageConfig`|`{ storageKey?, crossSubdomain?, defaultDomain?, defaultExpiryDays? }`|key `c15t`, current host, 365 days|The name, domain and lifetime of the consent cookie and localStorage key.|
|`persistence`|`boolean` or `{ storageConfig?, skipHydration?, sync? }`|`true`|Read and write choices in the cookie and localStorage, and follow other tabs. `false` keeps choices in memory only. `{ sync: false }` stops following other tabs.|
|`user`|`{ externalId, identityProvider?, identityToken?, externalIdType?, properties? }`|none|An identified visitor, sent with consent records. [`identityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link. Links only a subject the next save creates; use `identify()` for an existing one.|
|`iab`|IAB options or `false`|none|CMP settings such as `cmpId` and `vendors`. Only the IAB build accepts it; the other builds throw when it is set.|

Each of these has a guide: [scripts](/docs/frameworks/html/scripts),
[embeds](/docs/frameworks/html/embeds),
[network blocker](/docs/frameworks/html/network-blocker) and
[events and callbacks](/docs/frameworks/html/callbacks).

## Presentation and copy

|Option|Type|Default|What it does|
|--|--|--|--|
|`ui`|UI options or `false`|stock UI on|Theme tokens, CSS, surfaces and mounting. `false` starts the client with no UI. See [UI options](#ui-options).|
|`presentation`|`{ prompt?, preferences? }`|floating banner, bottom left|Banner shape, position, button layout and blocking, within what the policy allows.|
|`i18n`|`{ locale?, messages }`|English|The language to start in, and messages per language that override the bundled, backend or manifest copy key by key for that language.|
|`legalLinks`|`{ privacyPolicy?, cookiePolicy?, termsOfService? }`|none|Each link is `{ href, label?, target?, rel? }`. The banner and dialog show only the links their `legalLinks` option lists.|

## UI options

These go under `ui`. The headless builds ignore them.

|Option|Type|Default|What it does|
|--|--|--|--|
|`theme`|theme tokens|none|Colors, radius, typography, spacing and motion. The same token object every c15t package takes.|
|`css`|`string`|none|CSS added after the bundled stylesheet, in the same root as the UI.|
|`colorScheme`|`'light'`, `'dark'` or `'system'`|`'system'`|Which token set to use. `system` follows the visitor's setting and updates when it changes.|
|`shadow`|`boolean`|`true`|Render inside a shadow root. `false` renders into the page, where your stylesheet applies.|
|`styles`|`boolean`|`true`|Include the bundled stylesheet. Set `false` with `shadow: false` when the page loads the stylesheet itself.|
|`noStyle`|`boolean`|`false`|Render markup with no c15t classes and no bundled stylesheet, for fully custom CSS. `theme` and `css` still apply.|
|`disableAnimation`|`boolean`|the visitor's reduced motion setting|Show and hide surfaces without transitions.|
|`container`|element or CSS selector|`document.body`|Where the UI host element is appended. A selector that matches nothing throws.|
|`banner`|`boolean` or banner options|`true`|`false` renders no banner. An object sets copy and behavior; see the banner options.|
|`dialog`|`boolean` or dialog options|`true`|`false` renders no preference dialog.|
|`trigger`|`boolean` or trigger options|`false`|Render the floating button that reopens the dialog.|
|`iab`|`{ loadErrorText?, saveErrorText?, moreVendorsText? }`|translated copy|Copy for the IAB vendor list states. IAB build only.|

The banner, dialog and trigger options are on their component pages:
[banner](/docs/frameworks/html/components/banner),
[preference dialog](/docs/frameworks/html/components/dialog) and
[floating trigger](/docs/frameworks/html/components/trigger).

## Which attribute sets which option

|Attribute|Option|
|--|--|
|`data-backend-url`|`backendURL`|
|`data-mode`|`mode`|
|`data-manifest-url`|`manifestURL`|
|`data-policy-rules`|`policyRules`|
|`data-categories`|`consentCategories`|
|`data-country`, `data-region`, `data-language`|`overrides.country`, `overrides.region`, `overrides.language`|
|`data-privacy-policy-url`, `data-cookie-policy-url`, `data-terms-url`|`legalLinks`, plus `ui.banner.legalLinks` and `ui.dialog.legalLinks`|
|`data-color-scheme`|`ui.colorScheme`|
|`data-trigger`|`ui.trigger: true`|
|`data-hide-branding`|`ui.banner.hideBranding` and `ui.dialog.hideBranding`|
|`data-shadow="false"`|`ui.shadow: false`|
|`data-no-ui`|`ui: false`|
|`data-nonce`, or the tag's own `nonce`|`nonce`|

## Store the consent cookie across subdomains

By default c15t stores choices in a cookie and a localStorage key named `c15t`
on the current host, for 365 days. To share one choice between
`www.example.com` and `shop.example.com`, set `storageConfig`:

```html
<script>
  window.c15t = window.c15t || [];
  c15t.push(['config', {
    storageConfig: { crossSubdomain: true, defaultExpiryDays: 180 },
  }]);
</script>
```

`crossSubdomain` sets the cookie on the root domain. `defaultDomain`, such as
`'.example.com'`, sets it explicitly and wins over `crossSubdomain`. Use the
same settings on every site that shares the cookie. localStorage stays per
host, so a tab on another subdomain picks up a change when it next becomes
visible. [Consent state](/docs/concepts/consent-state#keep-open-tabs-in-step)
explains the rules.

## Turn consent management off

`enabled: false` allows every category, shows no UI and loads every
configured script at once, as for a visitor who accepted everything. Use it
for internal preview builds, not for visitors a consent law covers.

# DevTools
URL: https://c15t.com/docs/frameworks/html/dev-tools
Add the c15t DevTools panel to a plain HTML page with a second script tag to inspect consent, gated scripts, the resolved policy and events, and to test other countries.

## Add the panel

Add the DevTools tag next to the c15t tag while you debug:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@c15t/browser@alpha/dist/c15t.devtools.js"
  data-open
  data-tab="location"
  defer
></script>
```

Tag order does not matter. Loaded first, the DevTools tag queues itself on
`window.c15t` and mounts once the client starts. Loaded after, it mounts at
once. With `data-manual` on the c15t tag, it waits for `c15t.init()`.

|Attribute|What it does|
|--|--|
|`data-open`|Open the panel on load. `data-open="false"` keeps it closed.|
|`data-tab`|The first tab: `consents`, `scripts`, `location`, `policy`, `iab`, `events` or `actions`. An unknown value is ignored.|
|`data-position`|The corner: `bottom-right`, `bottom-left`, `top-right` or `top-left`.|

The panel renders in its own shadow root, so your theme's CSS does not change
it.

## Open DevTools from the trigger

With `data-trigger` on the c15t tag, the trigger shows a DevTools button next
to its own while the panel is mounted, and the panel hides its floating
launcher, so one control sits in the corner. The DevTools button sits at the
end farthest from the corner. The panel opens just past the trigger, aligned
with its outer edge, and follows it when you drag the trigger to another
corner.

The trigger hides while the banner or the dialog is open. The panel then shows
its own launcher in the `data-position` corner until the trigger returns. With
`c15t.headless.js` there is no trigger, so the panel always keeps its launcher.

## What each tab shows

|Tab|Shows|
|--|--|
|Consents|Each category's current permission, with switches and **Save changes**, **Accept all** and **Reject optional** buttons. Those buttons record a real choice.|
|Scripts|Scripts from `config` and their state: blocked, loading, loaded, failed or retained. A page scan lists other script and iframe elements.|
|Location|The country, region, language and GPC signal. **Apply and refresh** resolves the policy again with your values; **Clear overrides** goes back to detection.|
|Policy|The resolved policy rule and the prompt it requires.|
|IAB|Purposes, vendors and the TC string, under an IAB policy with `c15t.iab.js`.|
|Events|Every consent event in order.|
|Actions|**Show banner**, **Open preferences** and **Clear stored records**.|

The page scan in the Scripts tab lists what is in the DOM. It is not proof
that a request was sent or held back; check the Network tab for that.

## Use it from the console

Once mounted, the panel is `c15t.devtools` in the console. Call
`c15t.devtools.destroy()` to remove it. `c15t.dispose()` removes it too.

## Test another country

A policy that depends on location shows different banners around the world.
Open the Location tab, set the country to `DE`, or `US` with region `CA`, and
click **Apply and refresh**. The banner follows the policy for that location,
without a VPN. The override lasts until you reload.

## Keep it out of production

The panel shows internal consent state to anyone who opens the page. Remove
the tag before you publish, or print it only in a staging template. It also
adds a `<style>` element, which a strict [Content Security Policy](/docs/frameworks/html/content-security-policy)
blocks.

## Check it works

1. Add the tag and reload. The panel opens on the tab you chose.
2. Click **Accept All** in the banner. The Events tab lists the save, and
   the Consents tab shows each category allowed.
3. Remove the tag and reload. No panel appears and `c15t.devtools` is `null`.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/html/troubleshooting
Fix a missing banner, vendor scripts that run before consent, script tag errors and blocked requests on a plain HTML site that uses the c15t script tag.

## Inspect consent with DevTools

Add the DevTools tag next to the c15t tag while you debug. The panel shows
consent state, gated scripts, the resolved policy and every event, and its
Location tab tries the policy for another country. See
[DevTools](/docs/frameworks/html/dev-tools) for the tag and its attributes.
Remove the tag before you publish.

## Why is there no banner?

**Check.** In the Network tab, find the request to your backend's `/init`
endpoint.

**Fix.** Act on what you find:

* **The request failed with a CORS error.** Add your site's exact origin,
  including `https://` and any `www`, to the trusted origins in your Inth
  project.
* **The request returned 200.** The policy for your location may not ask for a
  banner. Many policies show none outside regions with consent laws. Open the
  DevTools Location tab and try a country such as `DE`.
* **There is no request.** The tag did not run. Check that the `src` loads,
  that no other script on the page threw first, and that the tag has no
  `data-manual`. A Content Security Policy must allow the CDN in `script-src`
  and your backend in `connect-src`; see
  [Content Security Policy](/docs/frameworks/html/content-security-policy).
* **You already chose.** A stored choice hides the banner. Open a private
  window, or clear the `c15t` cookie and localStorage key.

## Why does a vendor script run before a choice?

**Check.** Search the page source for the vendor's domain. The script tag only
holds scripts that are `type="text/plain"` with a `data-c15t-category`. A
second copy added by a theme setting, a plugin or a tag manager runs on its own
terms.

**Fix.** Remove the second copy, or gate it too.

**Check.** View the published page's source and check that each gated tag still
has `type="text/plain"`. A caching or optimization plugin can rewrite a gated
tag's `type` or move it.

**Fix.** Follow
[caching and optimization plugins](/docs/frameworks/html/platforms#caching-and-optimization-plugins).

Check the category as well. Under an opt-out policy, optional categories are
allowed until the visitor refuses, so vendors load on the first visit by
design.

## Why does a gated script never run on a page with a nonce?

**Check.** When the c15t tag has a `nonce` or `data-nonce`, c15t runs only gated
`text/plain` tags that carry the same nonce. Open the console and look for a
warning that c15t skipped a `data-c15t-category` script, and check the tag in
the Elements panel for `data-c15t-activated="untrusted"`.

**Fix.** Add `nonce="RANDOM_PER_RESPONSE"`, with the value your server sends, to
the tag, including tags your own code inserts later. See
[gated tags on a page with a nonce](/docs/frameworks/html/components/gated-script#gated-tags-on-a-page-with-a-nonce).

## Why is the banner unstyled or missing its colors?

**Check.** The console shows a CSP violation. A Content Security Policy whose
`style-src` does not allow the stock UI's `<style>` element blocks it.

**Fix.** Put the nonce from your `style-src` on the c15t tag, as `nonce` or
`data-nonce`, or serve the stylesheet as a file as
[Content Security Policy](/docs/frameworks/html/content-security-policy#allow-the-stock-uis-styles)
describes.

## Why does the preferences link do nothing?

**Check.** Confirm that the link's `href` ends in `#c15t-preferences` and that
the page loads the c15t tag. With `c15t.headless.js` or `ui: { dialog: false }`, the link asks for
the dialog but nothing renders it.

**Fix.** Correct the `href` or add the c15t tag. With a headless setup, your
page must render its own dialog, as [headless](/docs/frameworks/html/headless)
shows.

## Why does the console say "call c15t.init() first"?

**Check.** Something called a `window.c15t` method directly before the client
existed, for example from an inline script that ran before the tag, or on a
page whose tag has `data-manual` before anything called `c15t.init()`.

**Fix.** Queue the call with `c15t.push()`, move it into an `on('ready', ...)`
listener, or wait for `c15t.ready()`. See
[which calls you can queue](/docs/frameworks/html/api#which-calls-you-can-queue).

## Why does the console say a queued call "was skipped"?

**Check.** `c15t.push()` received a method it does not queue, such as `has`,
`getSnapshot` or `dispose`, or a name c15t does not know. A queue cannot hand
a value back, so c15t skips the call.

**Fix.** Call those methods inside `c15t.onInit()` or after `c15t.ready()`.

## Why is my queued configuration ignored?

**Check.** Look for an inline script that assigns `window.c15t = [...]`.
Assignment replaces calls other scripts queued before it.

**Fix.** Use `window.c15t = window.c15t || []` followed by `c15t.push(...)`
everywhere.

**Check.** Look for a `config` call made after the bundle ran. It does nothing.

**Fix.** Run the `config` call before the tag, or pass the configuration to
`c15t.init()` with `data-manual`.

## Why does the page throw "Load c15t.iab.js instead of c15t.js"?

**Check.** Two c15t bundles are on the page, including copies a plugin adds.

**Fix.** Keep only `c15t.iab.js` for an IAB policy, and remove `c15t.js`,
`c15t.offline.js` or `c15t.headless.js`.

## Why did the banner change after a release?

**Check.** `@alpha` in the tag's URL follows the newest prerelease.

**Fix.** Replace it with an exact version so your page changes only when you
change it.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Quickstart
URL: https://c15t.com/docs/frameworks/javascript/quickstart
Add the stock c15t banner, preferences and script gating to a JavaScript app built with Vite or another bundler, with no UI framework, using @c15t/browser.

## Connect Inth

[Create an Inth project](https://inth.com), set its policy rules, add your
app's origin to its trusted origins, and copy the project's backend URL.

This guide uses `@c15t/browser` as an ES module in a Vite app, with your
project's policy bundled at build time. `init()` starts the consent runtime
and mounts the stock banner and preference dialog. For your own UI, use the
[headless runtime](/docs/frameworks/javascript/headless) instead. Sites
without a build step load the same package from a script tag;
[choose your setup](/docs/concepts/choose-your-setup) points to that guide.

Bundling the policy at build time is the recommended production setup.
Rebuild after changing policies, translations or vendors.

## Install

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/browser@alpha c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/browser@alpha c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/browser@alpha c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add @c15t/browser@alpha c15t@alpha @c15t/integrations@alpha`|

`@c15t/browser` is not part of the `c15t` package. `c15t` supplies the Vite
plugin at `c15t/build`, and `@c15t/integrations` the PostHog helper used
below.

## Bundle your policy

Add `consentManifest` to `vite.config.ts`:

```ts title="vite.config.ts"
import { consentManifest } from 'c15t/build';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [consentManifest()] });
```

The plugin reads `VITE_C15T_BACKEND_URL`. Set it to your project's backend URL,
including any path prefix, in `.env` or wherever you build:

```sh title=".env"
VITE_C15T_BACKEND_URL=https://your-project.inth.app
```

If your app already sets `VITE_INTH_PROJECT_URL` for other Inth SDKs, that works
too. When both are set, `VITE_C15T_BACKEND_URL` wins.

`consentManifest` downloads your project's public policy from `/manifest`
during `vite build`, or in `vite dev` when the app first loads it, and serves
it to your app as `snapshot`
from `c15t/generated`. No file is written into your project.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

## Start c15t

Call `init()` once, in your browser entry point:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`manifest()` resolves the policy from the bundled snapshot in the browser,
with no `/manifest` request. It reads the snapshot and the backend URL from
what `consentManifest` downloaded. Consent choices go to that backend, and so
does an `/init` request when the policy depends on the visitor's country or
region and `overrides` does not supply it. That request returns the backend's
current policy, which can be newer than the snapshot. Vite reads
`VITE_C15T_BACKEND_URL` at build time, so set it before you build, not when
you serve the files.

To apply policy edits without rebuilding, pass `hosted()` from
`@c15t/browser` as the mode instead. The browser then requests the policy from
`/init` on every page load. Your bundle keeps only the mode you import.

PostHog waits for measurement permission with `loadMode: 'after-consent'`, and
`cookieless_mode: 'never'` turns off its cookieless capture. Replace
`phc_your_project_key` with your PostHog project key. The PostHog helper sends
events to PostHog's EU cloud; for a US project, add `region: 'us'`.

Include the measurement category in your Inth policy. Remove any other loader
for PostHog, such as a snippet in `index.html`, so it loads once and only
through c15t. Add other vendors to the same list, each with the category it
needs; the [integration guides](/docs/integrations/overview) give the helper
for each one.

`init()` returns the client. It reads stored choices, resolves the visitor's
policy, shows the banner when the policy needs one, and loads each
script once its category is allowed. The banner renders in a shadow root with
its own styles, so you do not import a stylesheet. The client lasts for the
page; call `consent.dispose()` only if your app removes consent entirely.

When a visitor withdraws a permission they had given, the client saves the
choice and reloads the page, because code that already ran cannot be unloaded.
[Scripts](/docs/frameworks/javascript/scripts) explains how to change that.

## Gate embeds and add a privacy settings button

Put the embed's URL in `data-src` and name its category in `data-category`.
The client sets `src` only while that category is allowed:

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

Visitors need a way to change their choice after the banner closes. The
client opens the preference dialog from any link to `#c15t-preferences`:

```html title="index.html"
<a href="#c15t-preferences">Privacy settings</a>
```

A button with `data-c15t-action="customize"` opens it too, without code.

## Change the look

Pass theme tokens in `ui.theme`, next to the options your `init()` call
already has. This example turns the buttons purple and rounds the cards:

```ts title="src/main.ts"
const consent = init({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
	ui: {
		theme: {
			colors: {
				primary: '#6943a3',
				primaryHover: '#533285',
				textOnPrimary: '#ffffff',
			},
			radius: { lg: '18px' },
		},
	},
});
```

`theme` takes the same tokens as every c15t package; see
[theme tokens](/docs/customization/tokens). `presentation.prompt` changes the
banner's shape and position, `ui.css` adds CSS inside the shadow root, and
`i18n` changes the copy. [Customize](/docs/frameworks/javascript/customize)
covers each option.

## Check it works

Run the app, open it in a private window, and open the browser's developer
tools on the Network tab.

1. Before you choose, filter for `posthog`. There are no requests, and the
   YouTube iframe has no `src`.
2. Click **Reject All** and reload. The banner stays closed and the PostHog
   requests stay absent.
3. Click **Privacy settings**, turn on **Analytics** (the `measurement` category) and save. PostHog and
   the YouTube player load.
4. Open **Privacy settings** again and turn **Analytics** off. The page reloads,
   and PostHog and YouTube do not load again.

If no banner appears, see [why is there no banner](/docs/guides/troubleshooting#why-is-there-no-banner).
Run the full [verification checklist](/docs/guides/verify-consent) before you
ship.

## Next steps

* Render your own banner with the [headless runtime](/docs/frameworks/javascript/headless).
* Inspect consent with [DevTools](/docs/frameworks/javascript/dev-tools).
* Read consent from your code. `consent.has('measurement')` answers whether a
  category is allowed now, `consent.on('consent', listener)` reports changes,
  and `consent.save({ measurement: true })` records a choice. The
  [@c15t/browser API](/docs/frameworks/javascript/api/browser) lists every
  method, and [options](/docs/frameworks/javascript/api/browser-options) every
  option.
* Run code on consent events with [callbacks](/docs/frameworks/javascript/callbacks).
* Add languages with [translations](/docs/frameworks/javascript/translations).

# Upgrade from v2
URL: https://c15t.com/docs/frameworks/javascript/upgrade-v3
Upgrade a JavaScript app from the c15t v2 store and getOrCreateConsentRuntime to v3. Covers @c15t/browser, createConsentRuntime, the consent kernel, moved exports, callbacks, policies and stored consent.

**Upgrade this JavaScript app to c15t v3**

Paste into Claude Code, Codex, Cursor or another coding agent at the root of your app.

```prompt
Upgrade this JavaScript app from the c15t v2 store to c15t v3.

Read [https://v3.c15t.com/docs/frameworks/javascript/upgrade-v3.md](https://v3.c15t.com/docs/frameworks/javascript/upgrade-v3.md) first and follow it in order. Do not guess v3 APIs from memory.

1. Find every use of the `c15t` package and `@c15t/scripts`: `getOrCreateConsentRuntime`, `configureConsentManager`, `consentStore`, cookie helpers, script loader and iframe blocker functions.
2. Decide which v3 entry fits. Use `@c15t/browser` if the app wants the stock banner, `createConsentRuntime` from `c15t/runtime` if it renders its own UI, and `createConsentKernel` only if it mounts each module itself. Tell me which one you picked and why.
3. Install `c15t@alpha`, or `@c15t/browser@alpha` for the stock banner, plus `@c15t/integrations@alpha` if the app uses vendor helpers and `@c15t/dev-tools@alpha` if it uses dev tools.
4. Run `npx @c15t/cli@alpha codemods scripts-to-integrations consent-provider-options policy-packs-to-policy-rules callbacks-to-v3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
5. If you picked `createConsentRuntime`, call `runtime.start()` after creating it. Replace each store call with its v3 equivalent from the guide's mapping table.
6. Update callbacks and policy presets as the guide describes.
7. Keep the existing backend URL. If the app runs its own c15t backend, stop and tell me, because it has to be upgraded in the same release with [https://v3.c15t.com/docs/self-host/upgrade-v3.md](https://v3.c15t.com/docs/self-host/upgrade-v3.md).
8. Run the typecheck and build, and resolve every `TODO(c15t v3)` comment.

When you finish, list the files you changed, anything you could not migrate, and how you checked that vendor requests still wait for consent.
```

## Before you start

If you run your own c15t backend, upgrade it in the same release. A v3 client
can't read a v2 backend. See
[Upgrade a self-hosted backend](/docs/self-host/upgrade-v3).
Inth-hosted backends need no change.

Every v3 package ships ESM only. If a CommonJS file in your app calls
`require()` on a c15t package, convert it to ESM.

## Pick a replacement

v2's `getOrCreateConsentRuntime()`, `configureConsentManager()` and the
Zustand `consentStore` are gone. Pick a replacement by how much you want c15t
to do.

|You want|Use|
|--|--|
|The stock banner and dialog|`@c15t/browser`. Call `init()` from a bundled app, or add the script tag to a site without a build step. See the [quickstart](/docs/frameworks/javascript/quickstart).|
|Your own UI, with persistence, the script loader and the blockers wired for you|`createConsentRuntime()` from `c15t/runtime`, then `runtime.start()`. See [headless](/docs/frameworks/javascript/headless).|
|The engine alone, mounting each module yourself|`createConsentKernel()` from `c15t`. See the [kernel API](/docs/frameworks/javascript/api/kernel).|

Install `c15t` for the runtime or the kernel:

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha`|
|pnpm|`pnpm add c15t@alpha`|
|yarn|`yarn add c15t@alpha`|
|bun|`bun add c15t@alpha`|

The runtime takes the same kind of options v2 did. `mode` and `backendURL`
become one transport, such as `hosted({ backendURL })` or `offline({ policyRules })`,
exported from `c15t`. `translations` becomes `i18n`, and
`iframeBlockerConfig` becomes `iframeBlocker`. See the
[runtime reference](/docs/frameworks/javascript/api/runtime) for every option.

`createConsentRuntime()` only builds the runtime. Call `runtime.start()` to
read stored consent, resolve the policy and mount the script loader and
blockers. Until then nothing is gated.

The `consent-provider-options` codemod rewrites `mode`, `backendURL` and
`iframeBlockerConfig` in the object you pass to `getOrCreateConsentRuntime()`
and adds the `hosted` or `offline` import from `c15t`. Rename the call to
`createConsentRuntime()` from `c15t/runtime` yourself.

## Replace store calls

The runtime exposes the kernel as `runtime.kernel`. Read state from
`kernel.getSnapshot()` and listen with `kernel.subscribe()`.

|v2 store|v3|
|--|--|
|`consentStore.getState()`|`kernel.getSnapshot()`|
|`consentStore.subscribe(listener)`|`kernel.subscribe(listener)`. The listener gets the whole snapshot, on every change.|
|`subscribeToConsentChanges(listener)`|`kernel.events.on('permissions:changed', ({ snapshot }) => listener(snapshot.effectivePermissions))`, or the `onPermissionsChanged` callback|
|`has(category)`|`kernel.getSnapshot().effectivePermissions[category]`|
|`consents`|`kernel.getSnapshot().effectivePermissions`|
|`consentInfo`|`kernel.getSnapshot().explicitChoice`, which is `null` until the visitor chooses|
|`hasConsented()`|`kernel.getSnapshot().explicitChoice !== null`|
|`saveConsents('all')`|`kernel.commands.save('all')`|
|`saveConsents('necessary')`|`kernel.commands.save('none')`|
|`selectedConsents`, `setSelectedConsent(name, value)`|`createPreferenceDraft(kernel)` from `c15t/preference-draft`, then `draft.getState()` and `draft.set(name, value)`|
|`saveConsents('custom')`|`draft.save()` on that preference draft|
|`setConsent(name, value)`|`kernel.commands.save({ [name]: value })`|
|`activeUI`, `setActiveUI(ui)`|`kernel.getSnapshot().activeUI`, `kernel.set.activeUI(ui)`|
|`locationInfo`|`kernel.getSnapshot().location`|
|`setOverrides(overrides)`|`runtime.setOverrides(overrides)`, then `runtime.reinit()`|
|`setLanguage(code)`|`runtime.setLanguage(code)`|
|`identifyUser(user)`|`runtime.identify(user)`|

`effectivePermissions` is what may run now. `explicitChoice` is what the
visitor decided. Under an opt-out policy a category can be allowed before any
choice, so don't treat a `true` permission as a recorded grant. See
[snapshot](/docs/frameworks/javascript/api/snapshot).

## Update moved exports

|v2 export from `c15t`|v3|
|--|--|
|`getCookie`, `setCookie`, `deleteCookie`, `getConsentFromStorage`, `saveConsentToStorage`, `deleteConsentFromStorage`|Removed. `createPersistence()` from `c15t/modules/persistence` owns storage.|
|`loadScripts`, `unloadScripts`, `updateScripts`, `isScriptLoaded`, `getLoadedScriptIds`|Removed. Pass `scripts` to `createConsentRuntime()`, which mounts the loader on `start()`. To run a loader yourself, `createScriptLoader({ kernel, scripts })` from `c15t/modules/script-loader` returns `updateScripts(next)`, `getLoadedScriptIds()` and `dispose()`. Use `getLoadedScriptIds().includes(id)` for `isScriptLoaded(id)`.|
|`createIframeBlocker`|`c15t/modules/iframe-blocker`|
|`getEffectivePolicy`, `filterConsentCategoriesByPolicy` and the other policy helpers|`resolveConsentPresentation()` from `c15t` and the helpers in `c15t/surface-actions`|
|`C15tClient`, `OfflineClient`, `CustomClient`, `API_ENDPOINTS`|Transports: `hosted()`, `offline()` and `custom()` from `c15t`|
|`policyPackPresets`|`policyRulePresets`|
|`configureConsentManager`, `createConsentManagerStore`, `clearConsentRuntimeCache`|Removed|

## Rename the integrations dependency

v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts`
from your dependencies and install `@c15t/integrations` from the `alpha`
dist-tag:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

Replace the package name in each import. Vendor subpaths and helper names stay
the same.

Before, in v2:

```ts
import { googleTagManager } from '@c15t/scripts/google-tag-manager';
import { posthog } from '@c15t/scripts/posthog';
```

After:

```ts
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { posthog } from '@c15t/integrations/posthog';
```

The `scripts` configuration option and the `Script` type keep their names.

Two helper behaviors change. A helper that needs an ID, such as `metaPixel`,
`googleTagManager` or `posthog`, now logs an error and skips its script when
the ID is empty or only whitespace, where v2 loaded a broken script. And if
your code reads `@c15t/integrations/registry`, an entry's `consentCategory` can
now be a compound condition such as `{ and: ['marketing', 'measurement'] }`,
not only a category name.

`@c15t/scripts` stays available as a deprecated compatibility package for all
of v3. It re-exports the implementation and types of `@c15t/integrations`, so
you can migrate imports separately from the rest of the upgrade. Compatibility
ends in v4; versions already published stay on npm.

To preview the import changes in JavaScript and TypeScript files:

```bash
npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
```

Review the output, then run it again without `--dry-run`. The codemod runs
only when you name it. It does not change `package.json`, lockfiles, or
imports inside `.vue`, `.svelte` or `.astro` files; update those by hand, then
reinstall dependencies and build the app.

## Replace callbacks

Callbacks stay under `callbacks` in your options, with new names:

|v2 callback|v3 callback|
|--|--|
|`onConsentSet`|`onPermissionsChanged` to react to what may run now. `onChoiceRecorded` to react to the visitor's accept, reject or save.|
|`onConsentChanged`|`onChoiceRecorded`. See the note below the table.|
|`onBannerFetched`|No callback. In React and Next.js, read `usePolicyResolution()` to know when the policy has resolved. In JavaScript, read `resolution` from the kernel snapshot.|
|`onError`, `onBeforeConsentRevocationReload`|Unchanged|

The `callbacks-to-v3` codemod renames `onConsentChanged` to
`onChoiceRecorded`. It leaves a `TODO(c15t v3)` comment there about the new
payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
replacement for:

```bash
npx @c15t/cli@alpha codemods callbacks-to-v3 --dry-run --json
```

v2's `onConsentChanged` fired only when a save changed at least one category's
value, and passed `preferences` and `previousPreferences`. v3's
`onChoiceRecorded` fires for every accept, reject or save that confirms a
category, including one that saves the same values again, because each save
renews the choice's confirmation time. Its payload carries `snapshot`,
`confirmed` and `actionAt`. v3 has no callback that fires only when a save
changes a value. If you need the before and after values, use
`onPermissionsChanged`: it passes `previous` and the new `snapshot` whenever
effective permissions change, whether a save or something else changed them.

v2's `onConsentSet` also fired on initialization and hydration. In v3,
`onChoiceRecorded` runs only when the visitor acts, and `onPermissionsChanged`
runs when effective permissions change for any reason, including expiry, a
policy update or a privacy signal. Neither runs at startup if the resolved
permissions match the defaults, such as an opt-in policy that leaves every
category denied. If an external API needs the starting state, read it once at
startup as well: in React and Next.js from `useEffectivePermissions()` in an
effect, which also runs on later changes, and in JavaScript from
`kernel.events.on('init:applied', ({ snapshot }) => ...)`.

```ts title="After (v3): callbacks in your options"
callbacks: {
  onChoiceRecorded(event) {
    console.log('Visitor recorded a choice', event);
  },
  onPermissionsChanged(event) {
    console.log('Effective permissions changed', event);
  },
},
```

## Move policy packs to policy rules

v2 policy packs become policy rules, and `policyPackPresets` becomes
`policyRulePresets`, exported from `c15t`. Where the rules live depends on your
backend:

* **Inth**: set the rules in your Inth project. Rules in client code do not
  change a hosted policy.
* **Self-hosted**: move the backend's `policyPacks` to `manifest.policyRules`.
  See [policy configuration](/docs/self-host/guides/policy-packs).
* **Offline**: move `offlinePolicy.policyPacks` to `offline({ policyRules })`.

```tsx title="After (v3): offline policy rules"
import { offline, policyRulePresets } from 'c15t';

const mode = offline({
	policyRules: [
		policyRulePresets.europeOptIn(),
		policyRulePresets.worldOptOutNoPrompt(),
	],
});
```

In Next.js, import `offline` from `c15t/next` instead and set the result as
`mode` in `c15t.config.ts`. Both take the same `policyRules`.

|v2 preset|v3 preset|
|--|--|
|`europeOptIn()`, `europeIab()`|Same names|
|`californiaOptIn()`, `californiaOptOut()`|Same names|
|`quebecOptIn()`|Same name|
|`worldNoBanner()`|`worldOptOutNoPrompt()`|

`worldNone()` is a separate, new preset: it shows nothing and grants no
rights, while `worldOptOutNoPrompt()` keeps v2's opt-out and preference rights.

The `policy-packs-to-policy-rules` codemod renames `policyPackPresets` and
`worldNoBanner()`, and moves the import to `c15t` where it came from
`c15t/react` or `c15t/next`. `consent-provider-options` moves
`offlinePolicy.policyPacks` into `offline({ policyRules })`. Preset calls need
no other change, but a hand-written v2 pack uses `consent` and `ui` keys,
which v3 rules replace with flat keys such as `model` and `prompt`; the
codemods mark those with a `TODO(c15t v3)` comment.

v3 adds presets for more regions. `offline()` without `policyRules` uses
`recommendedPolicyRules()`. Read [policies](/docs/concepts/policies) before you
change a rule's model or prompt, and
[how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice.

## Update complete translation objects

Partial overrides through `i18n.messages` and objects typed as `Translations`
need no change. A complete translation object typed as `CompleteTranslations`
fails type-checking until you add the new sections and keys: `consentGate`, which
replaces `frame`, `rights`, the notice and dismiss strings such as
`common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy
under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves
`frame` copy to `consentGate`.

`i18n.messages` for the visitor's language now merge over the backend's copy
instead of being replaced by it.

## Keep visitors' existing choices

v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It
does not rewrite them on page load; the next accept, reject or save writes a
v3 record.

A v2 denial keeps restricting its category. A v2 grant keeps applying until
the policy's validity period runs out, and then c15t asks again. If the rule
comes from a preset and the v2 record noted the policy it was made under, c15t
also asks again when that policy has changed. Under custom rules, a v2 grant
applies until it expires. Do not copy permissions into new
records yourself; c15t decides which v2 choices still count.

## Update dev tools

Dev tools no longer depend on React. Upgrade `@c15t/dev-tools` to
`@c15t/dev-tools@alpha` with the rest of c15t, then call
`createDevTools({ kernel })` with your runtime's kernel. See
[dev tools](/docs/frameworks/javascript/dev-tools).

## Upgrade from an earlier v3 alpha

The v3 alphas renamed and removed APIs that never shipped in a stable release.
Names that were in stable v2 keep a deprecated alias. Every other renamed name
is removed with no alias, so a build that still uses one fails to type-check
or throws at runtime.

### Removed

Modes and build integrations:

|Removed|Use instead|
|--|--|
|`hosted({ url })`|`hosted({ backendURL })`, or the framework's backend URL variable|
|`createManifestTransport({ manifest })`|`createManifestTransport({ snapshot })`|
|`assertDecisionInputs` defaulting to `false` on `hosted()`|It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.|
|`hostedModes` from `c15t/runtime/provider`|`readHostedMode(mode)`|
|`buildManifest: true` in Astro and Nuxt|`onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`.|
|A generated `c15t-manifest.ts` and its `.gitignore` entry|`import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.|
|The build options `outputFile`, `exportName`, `importSource` and `rootDir`|Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.|

`@c15t/browser`:

|Removed|Use instead|
|--|--|
|`init({ backendURL })`|`init({ mode: hosted() })`, or `init({ mode: manifest() })` with `consentManifest()` from `c15t/build`|
|`init({ mode: 'hosted' })`, `'manifest'`, `'offline'`|`init({ mode: hosted() })`, `manifest()`, `offline()`. Names work only in the script-tag builds.|
|`init({ manifest, manifestURL })`|`init({ mode: manifest({ snapshot, manifestURL }) })`|
|`init({ policyRules: ['europeOptIn'] })`|`init({ mode: offline({ policyRules: [policyRulePresets.europeOptIn()] }) })`|
|`manifest({ manifest })`|`manifest({ snapshot })`|

The script-tag builds and the `@c15t/browser/hosted` and
`@c15t/browser/offline` entries keep `backendURL`, `manifest`, `manifestURL`,
`policyRules` and mode names.

## Update the CLI

* Run `c15t login` again. The CLI signs in through Inth now and no longer
  reads sessions saved by v2.
* `c15t setup` no longer writes `.env.local` or `.env.example` and no longer
  accepts `--env`. It writes the backend URL into the files it generates.
* `c15t setup` no longer detects Remix or Gatsby. Pick a guide from
  [Choose your setup](/docs/concepts/choose-your-setup) for those apps.

## Check the migration

1. Run your typecheck and build.
2. Load the app with a v2 consent cookie from before the upgrade. The banner
   stays closed if that choice still applies, and a rejected category stays
   blocked.
3. In a private window, check in DevTools Network that vendor requests wait for
   consent, start after you accept, and stay absent after you reject and
   reload.
4. Reopen preferences and change a category.

The [verification guide](/docs/guides/verify-consent) has the full release
checklist.

# Scripts
URL: https://c15t.com/docs/frameworks/javascript/scripts
Register vendor scripts with @c15t/browser, createConsentRuntime or a consent kernel in JavaScript, and control what happens when a visitor withdraws permission.

## Register scripts where you start c15t

Pass the `scripts` list to whichever API starts c15t. The list is the same in
each case, built from `@c15t/integrations` helpers or your own script objects:

|Setup|Where `scripts` goes|
|--|--|
|`@c15t/browser`|`init({ scripts, … })`, as in the [quickstart](/docs/frameworks/javascript/quickstart#start-c15t).|
|`c15t/runtime`|`createConsentRuntime({ mode, scripts })`, as in [headless](/docs/frameworks/javascript/headless#create-the-runtime).|
|Your own kernel|`createScriptLoader({ kernel, scripts })`. See [script loader](/docs/frameworks/javascript/modules/script-loader#attach-the-loader-to-your-own-kernel).|

The quickstart's `src/main.ts` shows PostHog:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

Each [integration guide](/docs/integrations/overview) gives the helper and
options for one vendor. For a vendor without a helper, write the object
yourself:

```ts
const scripts = [
	{
		id: 'analytics',
		src: 'https://analytics.example/sdk.js',
		category: 'measurement',
		onLoad: () => window.analytics?.track('page_view'),
	},
];
```

`window.analytics` stands for your vendor's global. The
[script loader](/docs/frameworks/javascript/modules/script-loader) page lists
every field and callback.

## When the script loader downloads

With `@c15t/browser` from npm, the script loader and the network blocker
share a separate chunk. It loads when c15t starts, and only if `scripts` is
not empty or `networkBlocker` has rules, so a page with neither never
downloads it. On a page with either, the browser requests it after your
JavaScript has run, which delays a returning visitor's consented scripts and
held requests by one request.

Your bundler names that chunk, so c15t cannot link it from your HTML. To
start the download earlier, add a `<link rel="modulepreload">` for the chunk
your build emits for `@c15t/core/dist/modules/loader-and-blocker.js`. With
Vite, `.vite/manifest.json` lists it under that path when `build.manifest` is
on. Give the link `fetchpriority="low"`. c15t needs the chunk only when it
starts, and at the default priority the preload can delay your app's own
chunks over HTTP/1.1. The script-tag build, `c15t.js`, already contains the
loader.

## Gate a snippet in your HTML

`@c15t/browser` also runs `<script type="text/plain" data-c15t-category>`
tags in your `index.html` once their category is allowed, in page order. Use
it for a vendor snippet you would rather keep in HTML. `createConsentRuntime`
and a plain kernel do not scan the page for these tags;
`activateGatedScripts(snapshot)` from `@c15t/browser` runs them for you.

With the `nonce` option set, `@c15t/browser` runs only the tags that carry the
same `nonce`, and marks the others `data-c15t-activated="untrusted"`. Pass
`{ nonce }` as the third argument of `activateGatedScripts` for the same
check. See [Content Security Policy](/docs/frameworks/javascript/content-security-policy).

## When a visitor withdraws permission

A script that has run cannot be unloaded. `@c15t/browser` and
`createConsentRuntime` reload the page after a visitor turns off a category
they had allowed, so the new page starts without that vendor. Allowing a
category never reloads.

Set `reloadOnConsentRevoked: false` to handle withdrawal yourself, for
example with the vendor's opt-out call in the script's `onConsentChange`.
Until the next page load, code that already ran keeps running.
`callbacks.onBeforeConsentRevocationReload` runs right before the reload, for
work that must finish first. A kernel you create yourself does not reload;
add `watchRevocationReload` from `c15t` if you want it.

## Keep one owner per vendor

Use stable script IDs and remove the vendor's original snippet, so each
vendor loads once and only through c15t. Ordinary scripts wait for
permission. Helpers with `alwaysLoad` load at once and pass consent to the
vendor's own API instead. Read the individual integration guide before
assuming all helpers have the same network behavior.

Create `init()` or the runtime once per page. A second client, or a second
loader on a kernel that `@c15t/browser` or `createConsentRuntime` owns, loads
vendors twice.

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Declare
the vendors in the `vendors` option and render the switch yourself; helpers
from `@c15t/integrations` already carry their vendor slug. See
[vendor consent](/docs/frameworks/javascript/vendor-consent).

## Clear stored tracking data

Script gating does not remove cookies or Web Storage entries that a script
already wrote. Configure [clear on revocation](/docs/frameworks/javascript/clear-on-revocation)
to delete them when their category is denied.

## Send your own events to allowed vendors

To send your own analytics events only to the vendors a visitor allows, use
the event dispatcher from `@c15t/integrations`. See
[send events only to allowed integrations](/docs/integrations/overview#send-events-only-to-allowed-integrations).

## Check it works

Run the app in a private window with the Network tab open.

1. Filter for each vendor's host. Nothing loads before a choice.
2. Allow one category. Only that category's vendors load.
3. Withdraw it. The page reloads and the vendor stays absent.

# Iframe blocker
URL: https://c15t.com/docs/frameworks/javascript/modules/iframe-blocker
Hold YouTube videos, maps and other embeds in a JavaScript app until their consent category is allowed, with data-src iframes and the c15t iframe blocker in @c15t/browser, createConsentRuntime or your own kernel.

## Gate an embed

Put the embed's URL in `data-src` instead of `src`, and name its category in
`data-category`:

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

The iframe blocker gives the iframe its `src` once the category is allowed,
and takes it away again when the visitor withdraws it. An iframe without
`src` loads nothing, so the vendor gets no request before consent.
`@c15t/browser` and `createConsentRuntime` run the blocker by default.

## Attributes

|Attribute|What it does|
|--|--|
|`data-src`|The embed's URL. Only `http:` and `https:` URLs load. Relative URLs resolve against the page.|
|`data-category`|One category name. An unknown name logs a warning and keeps the iframe blocked.|
|`data-vendor`|Optional vendor slug. The iframe also stays blocked while the visitor has turned that vendor off.|
|`data-c15t-paused`|Set by c15t when it removed a `src` the iframe already had.|

Iframes without `data-category` or `data-vendor` are left alone. An iframe
written with `src` and `data-category` starts loading before the blocker
runs, so always use `data-src`.

## Iframes your code adds

The blocker watches the whole document for new iframes and for changes to
`data-category` and `data-vendor`. An iframe your app renders after load is
gated as soon as it is inserted, before the browser fetches it, as long as it
is inserted with `data-src` and no `src`. Watching the document root keeps the
blocker working when a client router such as Turbo replaces `<body>`, and lets
it start from a script in `<head>` before `<body>` exists.

To render the embed yourself instead, skip the attributes and create the
iframe when `snapshot.effectivePermissions.measurement` becomes `true`. The
[headless example](/docs/frameworks/javascript/headless) does this for its
YouTube video.

## Show a placeholder

c15t draws nothing in place of a blocked iframe. Show your own message beside
it and hide it once the iframe has a `src`:

```css
iframe[data-category]:not([src]) { display: none; }
iframe[src] + .placeholder { display: none; }
```

Give the placeholder a button that calls `consent.openDialog()`, so the
visitor can allow the category.

## Configure it

|`iframeBlocker` value|Effect|
|--|--|
|omitted or `{}`|Gate every iframe with `data-category` or `data-vendor`.|
|`{ disableAutomaticBlocking: true }`|Do not scan or watch the page. c15t checks iframes only when you call `processIframes()`. See [check iframes on demand](#check-iframes-on-demand).|
|`false`|No blocker. `data-src` iframes never load.|

The categories of gated iframes are added to the categories the preference
dialog offers.

## Check iframes on demand

With `iframeBlocker: { disableAutomaticBlocking: true }`, the blocker does
nothing until you call `processIframes()`. Each call pauses gated iframes,
those with `data-category` or `data-vendor`, that consent does not allow, and
restores the ones it does. Call it after you add iframes and after consent
changes:

```ts
consent.on('consent', () => consent.processIframes());
```

`consent.processIframes()` is on the `@c15t/browser` client, and
`runtime.processIframes()` on a runtime from `createConsentRuntime`. The call
does nothing before `start()`, after `dispose()`, or when `iframeBlocker` is
`false`. With automatic blocking on, the blocker does this by itself.

## Attach it to your own kernel

A kernel from `createConsentKernel` has no iframe blocker. Create one for
it:

```ts title="src/iframe-blocker.ts"
import type { ConsentKernel } from 'c15t';
import { createIframeBlocker } from 'c15t/modules/iframe-blocker';

// Watches the page for <iframe data-src data-category> and sets `src` while
// the category is allowed.
export const gateIframes = function gateIframes(kernel: ConsentKernel) {
	return createIframeBlocker({ kernel });
};
```

`createIframeBlocker` returns `{ dispose, processAllIframes }`.
`processAllIframes()` scans the page again and applies the current consent.
`dispose()` stops watching and leaves the iframes as they are.

## Check it works

1. Before a choice, the iframe has no `src` and the Network tab shows no
   request to the embed's host.
2. Allow the category. The iframe gets its `src` and loads.
3. Add an iframe with `data-src` from the console after the page loaded. It
   loads only while its category is allowed.

# Network blocker
URL: https://c15t.com/docs/frameworks/javascript/modules/network-blocker
Hold fetch and XMLHttpRequest calls in a JavaScript app until their consent category is allowed, with networkBlocker rules in @c15t/browser or createConsentRuntime, or createNetworkBlocker on your own kernel.

## When you need it

The network blocker holds `fetch` and `XMLHttpRequest` calls that match a rule
until the rule's category is allowed. Use it for requests you cannot move
behind the [script loader](/docs/frameworks/javascript/modules/script-loader),
such as a first-party events endpoint or a vendor SDK you bundle yourself.

## Add rules

With `@c15t/browser` or `createConsentRuntime`, pass `networkBlocker` next to
your other options:

```ts
networkBlocker: {
	rules: [
		{
			id: 'events',
			domain: 'example.com',
			pathIncludes: '/api/track',
			methods: ['POST'],
			category: 'measurement',
		},
	],
},
```

Rules start holding matching requests when the client or runtime is created,
before `start()`, so a request sent early in your app still waits.

For a kernel you created yourself, attach the module:

```ts title="src/network-blocker.ts"
import type { ConsentKernel } from 'c15t';
import { createNetworkBlocker } from 'c15t/modules/network-blocker';

export const blockTracking = function blockTracking(kernel: ConsentKernel) {
	return createNetworkBlocker({
		kernel,
		onRequestBlocked: ({ method, url, rule }) => {
			console.info('Held back', method, url, rule?.id);
		},
		rules: [
			{
				category: 'measurement',
				domain: 'collect.example.com',
				id: 'collector',
			},
			{
				category: 'measurement',
				domain: 'example.com',
				id: 'events',
				methods: ['POST'],
				pathIncludes: '/api/track',
			},
		],
	});
};
```

`createNetworkBlocker` returns `{ dispose, updateRules, setEnabled }`.
`updateRules(next)` takes effect on the next request. `setEnabled(false)`
keeps the patches but lets everything through. `dispose()` restores `fetch`
and `XMLHttpRequest`. Dispose blockers in the reverse order you created them.

## Rule fields

|Field|Required|What it does|
|--|--|--|
|`domain`|Yes|The host to match. Subdomains match too.|
|`category`|Yes|The category, or a condition, that lets matching requests through.|
|`pathIncludes`|No|Match only URLs whose path contains this text.|
|`methods`|No|Match only these HTTP methods. All methods when omitted.|
|`id`|No|A name shown in logs and passed to `onRequestBlocked`.|
|`vendor`|No|Also block while the visitor has turned this vendor off.|
|`vendorId`, `iabPurposes`, `iabLegIntPurposes`, `iabSpecialFeatures`|No|IAB conditions, checked only under an IAB policy.|

## Blocker options

|Option|Default|What it does|
|--|--|--|
|`rules`|required|The rules.|
|`enabled`|`true`|`false` keeps the configuration but blocks nothing.|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`, as `[c15t] blocked POST https://… (rule: events)`.|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request.|

## What a blocked request sees

* A blocked `fetch` resolves with a `451` response. Check `response.ok`.
* A blocked `XMLHttpRequest` aborts and fires an `error` event.
* A request sent while the policy is still loading waits, then goes out or
  is blocked. If the policy fails to load, it is blocked.
* A synchronous XHR cannot wait. While matching requests are held, a
  matching synchronous XHR throws a `NetworkError`.
* When the blocker loads on demand and its chunk fails to load, requests its
  rules match are blocked, including ones already waiting for it, even for
  granted categories. Nothing can check consent for them. The chunk is tried
  again when the browser comes back online, and the blocker then decides
  requests as usual.
* Requests that match no rule go out at once.

## What it cannot block

It patches `fetch` and `XMLHttpRequest` in the page's own window. It does not
cover `navigator.sendBeacon`, WebSockets, `EventSource`, requests from
elements such as `<img>` and `<script>`, other frames, or service workers.

## Check it works

1. Send a matching request before any choice. The console logs
   `[c15t] blocked …` and the Network tab shows nothing.
2. Allow the category and send it again. It goes out.
3. Withdraw the category with `reloadOnConsentRevoked: false`. The next
   request is blocked again.

# Vendor consent
URL: https://c15t.com/docs/frameworks/javascript/vendor-consent
Let visitors allow a category such as marketing in a JavaScript app and still turn off one vendor in it, with the vendors option on createConsentRuntime and a vendor switch you render yourself.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Declare the vendors and record a switch

Built-in `@c15t/integrations` helpers already list their vendor by name, so
you only declare a vendor for a script of your own, or to replace a helper's
name and privacy policy.

With `createConsentRuntime`, declare the vendors, then render the switch in
your own UI with the [headless runtime](/docs/frameworks/javascript/headless).
The stock preference dialog that `init()` from `@c15t/browser` mounts lists
vendor switches on its own. This module declares X Pixel, reads whether it
may run, and records a new switch:

```ts title="src/vendor-consent.ts"
import { isVendorAllowed } from 'c15t';
import type { SaveResult, Vendor } from 'c15t';
import type { ConsentRuntime } from 'c15t/runtime';

export const vendors: Vendor[] = [
	{
		category: 'marketing',
		id: 'x-pixel',
		name: 'X Pixel',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];

// Whether the vendor may run now: it is declared, its category is allowed
// and the visitor has not switched it off. An undeclared id returns false.
export const canVendorRun = function canVendorRun(
	runtime: ConsentRuntime,
	vendorId: string
): boolean {
	return isVendorAllowed(runtime.kernel.getSnapshot(), vendorId);
};

// Record one vendor switch. The empty category input confirms no category;
// `save()` with no input would also confirm every displayed category.
export const saveVendorSwitch = function saveVendorSwitch(
	runtime: ConsentRuntime,
	vendorId: string,
	granted: boolean
): Promise<SaveResult> {
	return runtime.kernel.commands.save({}, { vendors: { [vendorId]: granted } });
};
```

Pass `vendors` to the runtime next to `scripts`:

```ts title="src/consent-runtime.ts (partial)"
import { vendors } from './vendor-consent';

export const runtime = createConsentRuntime({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
	vendors,
});
```

`init()` from `@c15t/browser` accepts the same `vendors` option. Its client
exposes the runtime as `client.runtime`, so the functions above work with it
too.

`isVendorAllowed(snapshot, id)` from `c15t` backs `canVendorRun()`.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

Call `saveVendorSwitch(runtime, 'x-pixel', false)` from your switch's change
handler. To confirm categories and vendors in one action, pass both to the
kernel's save:

```ts
await runtime.kernel.commands.save({
	marketing: true,
	measurement: true,
	vendors: { 'x-pixel': false },
});
```

To stage vendor switches next to category switches and save them together,
use a [preference draft](/docs/frameworks/javascript/headless#build-a-preference-form-with-a-draft):
`draft.setVendor(id, granted)` stages one, and `draft.reset()` drops them.
`runtime.kernel.getSnapshot().vendors?.declared` lists the declared vendors,
and `vendorChoice` holds the recorded decision.

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

[Iframe blocker](/docs/frameworks/javascript/modules/iframe-blocker) and
[network blocker](/docs/frameworks/javascript/modules/network-blocker) cover
those targets.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()` and declare `x-pixel`. Allow marketing. `uwt.js`
   loads.
2. Switch X Pixel off in your control. c15t reloads the page. After the reload
   there is no `uwt.js` request, and other marketing scripts still load.
3. Reload again. `canVendorRun(runtime, 'x-pixel')` still returns `false`.
4. Record Accept all with `runtime.kernel.commands.save('all')`. `uwt.js`
   loads again.

# Clear on revocation
URL: https://c15t.com/docs/frameworks/javascript/clear-on-revocation
Delete the first-party cookies and Web Storage keys a consent category owns in a JavaScript app when that category is denied, with clearOnRevocation on init() or createConsentRuntime, or createClearOnRevocation on your own kernel.

## Configure cleanup

Gating stops new requests, but it leaves the cookies and storage keys a vendor
already wrote. List the ones each optional category owns in
`clearOnRevocation`. When that category is denied, c15t deletes them:

```ts title="src/main.ts (partial)"
init({
	mode: manifest(),
	scripts,
	clearOnRevocation: {
		measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
		marketing: { cookies: ['_fbp'], sessionStorage: ['campaign-id'] },
	},
});
```

`init()` from `@c15t/browser` and `createConsentRuntime` from `c15t/runtime`
take the same option. Each reads it once, when the client or runtime is
created.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Attach cleanup to your own kernel

If you assemble c15t modules yourself, attach cleanup in the browser after
persistence and the script loader:

```ts title="src/clear-on-revocation.ts"
import type { ConsentKernel } from 'c15t';
import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';

export const clearTrackingData = function clearTrackingData(
	kernel: ConsentKernel
) {
	return createClearOnRevocation({
		config: {
			marketing: { cookies: ['_fbp', '_gcl_au'] },
			measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
		},
		kernel,
	});
};
```

`createClearOnRevocation({ kernel, config, storageConfig? })` returns
`{ dispose }`. Pass the same `storageConfig` as your persistence module, so a
custom `storageKey` stays protected. If the policy has already resolved,
attaching can delete data for denied categories at once. Disposing stops the
cleanup; it deletes nothing. Do not attach it when `init()` or the runtime
already has `clearOnRevocation`.

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Customize
URL: https://c15t.com/docs/frameworks/javascript/customize
Change the stock @c15t/browser banner, preference dialog and floating trigger in a bundled JavaScript app with theme tokens, CSS, layout, copy, legal links and UI options.

## Pick the right option

The stock UI from `init()` in `@c15t/browser` is a banner, a preference
dialog and an optional floating trigger. Each change has one place to go:

|Change|Option|
|--|--|
|Colors, radius, fonts, spacing|`ui.theme`|
|One part's CSS|`ui.theme.slots` with `ui.stylesheetURLs`, `::part()`, or `ui.css`|
|Your own stylesheet|`ui: { shadow: false }`|
|Banner shape, position, button layout, blocking|`presentation.prompt`|
|Banner text|`ui.banner`|
|Wording and languages everywhere|`i18n`; see [translations](/docs/frameworks/javascript/translations)|
|Legal links|`legalLinks` with `ui.banner.legalLinks` and `ui.dialog.legalLinks`|
|A reopen button|`ui.trigger`|
|Entirely different markup|[Headless](/docs/frameworks/javascript/headless)|

The [design gallery](/docs/customization/recipes) shows banner designs built
from these options.

## Change colors, radius and fonts

Pass tokens in `ui.theme`. This version of `init()` turns the buttons purple
and rounds the cards:

```ts title="src/main.ts"
const consent = init({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
	ui: {
		theme: {
			colors: {
				primary: '#6943a3',
				primaryHover: '#533285',
				textOnPrimary: '#ffffff',
			},
			radius: { lg: '18px' },
		},
	},
});
```

`theme` takes the same token object as every c15t package; see
[theme tokens](/docs/customization/tokens). The banner, the dialog and the
trigger all read it. `ui.colorScheme` picks `'light'`, `'dark'` or
`'system'`, the default, which follows the visitor's setting. `null` follows a
`dark` or `c15t-dark` class on your page's `<html>` instead.
[Dark mode](/docs/customization/dark-mode) covers dark tokens in
`ui.theme.dark`.

## Add CSS inside the shadow root

The UI renders in a shadow root with its own copy of the stylesheet, so your
app's CSS does not reach it and its CSS does not reach your app. To target
one part, pass CSS in `ui.css`. c15t adds it after the bundled stylesheet:

```ts
ui: {
  css: '[data-testid="consent-banner-card"] { border: 3px solid #6943a3; }',
},
```

Every part has a `data-testid`, such as `consent-banner-card`,
`consent-banner-accept-button`, `consent-dialog-root`,
`consent-widget-switch-measurement` and `consent-dialog-trigger`. Inspect the
UI in the browser's element panel to find one.

To style parts with classes from your own stylesheet, such as a Tailwind or
CSS Modules build, put the classes on parts with `ui.theme.slots` and link the
stylesheet into the shadow root with `ui.stylesheetURLs`. Page CSS can also
reach a part by its slot key with `[data-c15t-ui]::part(consentBannerCard)`.
[Class names and CSS-in-JS](/docs/customization/class-names) and
[Tailwind CSS](/docs/customization/tailwind) show both, and
[component parts](/docs/customization/slots) lists the slot keys.

## Use your own stylesheet

`ui: { shadow: false }` renders into the page, so your stylesheet applies.
c15t still adds its own stylesheet. To load it from your bundle instead,
import it and turn the inline copy off:

```ts
import '@c15t/browser/styles.css';

const consent = init({
	mode: manifest(),
	ui: { shadow: false, styles: false },
});
```

If your bundler runs Tailwind 3, add `@c15t/browser/postcss-tailwind3` before
`tailwindcss` in your PostCSS plugins, using the object form:
`{ '@c15t/browser/postcss-tailwind3': {}, tailwindcss: {} }`. Without the
plugin, Tailwind 3 drops the imported rules without an
error and its preflight overrides the UI. A page that keeps the default shadow
root needs none of this, because page CSS does not reach the UI.

`ui: { shadow: false, noStyle: true }` renders markup with no c15t classes,
for a design written from scratch. Parts keep their `data-testid`. Your app's
global rules reach the UI in either mode, so check buttons and headings after
you switch.

## Change the banner's layout

`presentation.prompt` sets the banner's shape, position and button layout:

```ts
presentation: {
  prompt: { variant: 'bar', position: 'bottom', uiProfile: 'balanced' },
},
```

|`variant`|Positions|
|--|--|
|`floating` (default)|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

`layout`, `primaryActions`, `direction`, `uiProfile` and `blocking` arrange
the buttons and decide whether the banner blocks the page.
`presentation.preferences` does the same for the dialog and adds `defaults`,
the starting state of switches the visitor has not set. The policy still
wins. A notice never blocks, a wall always does, and required buttons come
back if a layout drops them.

## Change the banner text

## Banner options

These go under `ui.banner`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`title`|`string`|translated title|Heading. A notice uses the notice title by default.|
|`description`|`string`|translated description|Body text. A notice uses the notice description by default.|
|`acceptButtonText`|`string`|"Accept All"|Label of the accept button.|
|`rejectButtonText`|`string`|"Reject All"|Label of the reject button.|
|`customizeButtonText`|`string`|"Customize"|Label of the button that opens the dialog.|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description. `null` or `[]` shows none.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag. The IAB banner always keeps it.|
|`scrollLock`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|
|`trapFocus`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|

The dismiss button of a notice always uses the translated
`common.acknowledge` label. Change it through `i18n`.

The dialog's copy comes from translations only.

## Show legal links

Set the links once and list them per surface:

```ts
legalLinks: {
  privacyPolicy: { href: '/privacy' },
  cookiePolicy: { href: '/cookies' },
},
ui: {
  banner: { legalLinks: ['privacyPolicy', 'cookiePolicy'] },
  dialog: { legalLinks: ['privacyPolicy'] },
},
```

Each link opens in a new tab unless its `target` says otherwise. `label`
replaces the translated link text.

## Add the floating trigger

`ui: { trigger: true }` shows a corner button that opens the dialog while no
other surface is open. Visitors can drag it to another corner, and c15t
remembers that corner. While the [DevTools panel](/docs/frameworks/javascript/dev-tools)
is mounted, the trigger also carries a button that opens it.

## Trigger options

`ui.trigger: true` shows the trigger with its defaults. An object sets these:

|Option|Type|Default|What it does|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner the button starts in.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`showWhen`|`'always'` or `'after-consent'`|`'always'`|`after-consent` hides the button until the visitor has answered the prompt.|
|`ariaLabel`|`string`|"Open privacy settings"|The button's accessible name. It has no visible text.|
|`persistPosition`|`boolean`|`true`|Remember the corner a visitor dragged the button to, in localStorage. A remembered corner wins over `position`.|

## Mount the UI somewhere else

`ui.container` takes an element or a selector for the UI host, instead of
`<body>`. `consent.mountUI(options)` removes the UI and mounts it again with
new options, for example after your app changes theme:

```ts
consent.mountUI({ colorScheme: 'dark', theme });
```

The options you pass replace the configured `ui` options, so include every
option you still want, such as `theme` here.

## Keyboard and screen readers

The stock UI handles focus for you. A blocking banner and the dialog keep
Tab inside themselves and stop the page scrolling. Escape closes the dialog
without saving, wherever focus is, including a non-blocking dialog. The
dialog has no close button by design. Surfaces set `lang` and `dir` from the resolved language.
Transitions follow the visitor's reduced motion setting, and
`ui.disableAnimation` turns them off. `ui.banner.disableAnimation` and
`ui.dialog.disableAnimation` set it for one surface; see
[motion and animation](/docs/customization/motion).

## Check it works

1. Run the app and open it in a private window. The banner uses your
   tokens and layout.
2. Open the dialog. It uses the same tokens and shows your legal links.
3. Switch your system between light and dark mode. With `colorScheme: 'system'`, the UI follows.

# Translations
URL: https://c15t.com/docs/frameworks/javascript/translations
Choose the language of the c15t banner and preference dialog in a JavaScript app, change its wording with i18n, and add languages with @c15t/browser or createConsentRuntime.

## Where the copy comes from

`@c15t/browser` and `c15t` bundle English only. Other languages come from
outside the bundle, and which source wins depends on the transport:

|Transport|Where the copy comes from|
|--|--|
|Hosted|Your Inth project. The backend picks the language from the browser's `Accept-Language` header or your `language` override, and sends that copy with the policy.|
|Manifest|The manifest's translations for the visitor's language.|
|Offline or custom|English, or the `locale` and `messages` you set in `i18n`.|

In every mode, your `i18n.messages` for the language in use override that copy
key by key. Text you set in `ui.banner`, such as `title` or
`acceptButtonText`, replaces the translated banner text for all languages.

## Set messages

`i18n.locale` picks the starting language and `i18n.messages` supplies copy
per language. Messages merge over the bundled English, so a partial set
keeps every default you leave out:

```ts title="src/main.ts"
import { init, offline } from '@c15t/browser';
import { policyRulePresets } from 'c15t';

import { scripts } from './scripts';

// Offline mode shows the copy in `i18n`. With a backend, the backend's copy
// for the visitor's language replaces these messages.
export const consent = init({
	i18n: {
		locale: 'de',
		messages: {
			de: {
				common: {
					acceptAll: 'Alle akzeptieren',
					acknowledge: 'OK',
					customize: 'Anpassen',
					rejectAll: 'Alle ablehnen',
					save: 'Einstellungen speichern',
				},
				cookieBanner: {
					description:
						'Wir verwenden Cookies, um die Nutzung dieser Website zu messen.',
					title: 'Wir respektieren Ihre Privatsphäre',
				},
			},
		},
	},
	mode: offline({ policyRules: [policyRulePresets.europeOptIn()] }),
	scripts,
});
```

This example runs offline, so the German copy shows as written. With a
backend, the `/init` response, a server prefetch or the manifest carries your
Inth project's copy for the visitor's language. Your `i18n.messages` for that
language override it key by key, and keys you leave out keep the project's
copy. c15t looks for the exact language first, then the primary language, so
a visitor on `de-AT` gets your `de` messages. Messages for other languages
are not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps edits made in your Inth project visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording.

Offline mode is shown here to keep the example short. Not recommended for
production environments.

## Switch language at runtime

`consent.setLanguage('fr')` from `@c15t/browser` sets the language override
and resolves the policy again, which fetches French copy from the backend.
The banner and dialog re-render. With a runtime or kernel, call
`kernel.set.language('fr')` and then `kernel.commands.init()`.

To follow your app's own language setting from the first render, pass it as
an override: `init({ mode, overrides: { language: 'fr' } })`.

In offline mode there is no copy to fetch. With `offline()` from `c15t` or
`@c15t/browser`, a language set with the `language` override,
`setLanguage()` or `kernel.set.language()` switches to that language's copy
from the bundle or `i18n.messages`. This works for `@c15t/browser` and for a
headless `createConsentRuntime({ mode: offline() })`. A language with no copy
shows the default copy, and the language a server prefetch detected from
`Accept-Language` does not switch the copy. The bundle has English only, so
put every other language in `messages`.

## Use c15t's bundled translations

`@c15t/translations` has complete copy in more than 30 languages. Its
`@c15t/translations/all` entry exports `baseTranslations`, keyed by language
code, which you can pass as `messages`:

```ts
import { baseTranslations } from '@c15t/translations/all';

init({ i18n: { locale: 'de', messages: { de: baseTranslations.de } } });
```

Importing `baseTranslations` adds every language to your bundle. Import it
only where you need offline copy in many languages. Install
`@c15t/translations@alpha` to use it.

## Message keys the stock UI reads

|Key|Where it shows|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Banner under a choice policy.|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Banner under a notice policy.|
|`common.acceptAll`, `common.rejectAll`, `common.customize`|Banner and dialog buttons.|
|`common.acknowledge`|The notice's dismiss button.|
|`common.save`|The dialog's save button.|
|`common.securedBy`|The "Secured by" tag.|
|`consentManagerDialog.title`, `consentManagerDialog.description`|Dialog heading and text.|
|`consentTypes.<category>.title`, `consentTypes.<category>.description`|Each category row in the dialog.|
|`legalLinks.privacyPolicy`, `legalLinks.cookiePolicy`, `legalLinks.termsOfService`|Legal link labels.|
|`rights.optOut`, `rights.preferences`|The extra button an opt-out policy adds to the banner.|

A headless UI reads the same copy from `snapshot.translations`.

## Right-to-left languages

For a language such as Hebrew, the stock banner and dialog set `dir="rtl"`,
and a banner at a default left or right position moves to the other side.

[Copy and translations](/docs/customization/translations) covers labelling
actions honestly and testing long strings.

## Check it works

1. Set your browser's preferred language to German and open the app in a
   private window. With a backend, the banner shows your project's German
   copy.
2. Call `consent.setLanguage('fr')`. The banner switches to French.
3. Open the dialog. Its title, categories and buttons use the same language.

# Headless
URL: https://c15t.com/docs/frameworks/javascript/headless
Render your own consent banner and preferences in JavaScript, or connect a framework without a c15t adapter such as Solid, with createConsentRuntime from c15t/runtime.

## Choose a headless API

All three run the same consent engine. They differ in how much of the page
lifecycle they handle for you.

|API|Use it when|
|--|--|
|`createConsentRuntime` from `c15t/runtime`|You render the UI yourself, connect a UI framework, or share one consent state between several parts of the page. This page covers it.|
|`init` from `@c15t/browser/headless`|You want the `@c15t/browser` client without its UI: `data-c15t-action` buttons, `on('ui', ...)` and `acceptAll()` work as with the stock UI.|
|`createConsentKernel` from `c15t`|You assemble every module yourself. See the [consent kernel API](/docs/frameworks/javascript/api/kernel#create-a-kernel-yourself).|

The [createConsentRuntime reference](/docs/frameworks/javascript/api/runtime)
lists every option and method of the runtime.

`createConsentRuntime` builds the kernel and connects stored choices, script
loading, iframe gating and the reload after a visitor withdraws permission. It
also adds the network blocker, data clearing and IAB when you configure them.
A kernel you create yourself has none of these until you add them.

## Install

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/integrations@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/integrations@alpha`|
|yarn|`yarn add c15t@alpha @c15t/integrations@alpha`|
|bun|`bun add c15t@alpha @c15t/integrations@alpha`|

`@c15t/integrations` supplies vendor helpers. Leave it out if you gate no vendor
scripts.

## Create the runtime

Create one runtime for the page, in its own module, so every part of your UI
imports the same instance:

```ts title="src/consent-runtime.ts"
import { hosted } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

import { scripts } from './scripts';

// One runtime for the page: policy, stored choices, script loading,
// iframe blocking and the reload after a revocation.
export const runtime = createConsentRuntime({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});
```

Replace `https://your-project.inth.app` with your project's backend URL,
including any path prefix. `scripts` is the list from `src/scripts.ts` in the
[quickstart](/docs/frameworks/javascript/quickstart#register-consent-gated-scripts).
Creating the runtime has no side effects. It reads no storage and sends no
request until you call `start()`, so the module can also load on a server.

## Render the banner from the snapshot

`runtime.kernel.getSnapshot()` returns the current consent state, and
`runtime.kernel.subscribe(listener)` calls the listener with each new one.
Your UI renders from these fields; the [snapshot reference](/docs/frameworks/javascript/api/snapshot)
lists the rest:

|Field|What it tells your UI|
|--|--|
|`policyPending`, `resolution.status`|Whether the policy has resolved. Render nothing optional until `resolution.status` is `'matched'`.|
|`activeUI`|Which surface to show: `'banner'`, `'dialog'` or `'none'`.|
|`promptRequirement.kind`|`'choice'` needs a decision, `'notice'` needs only a dismissal, `'none'` needs no prompt.|
|`policyRule.scope`|The categories to offer in preferences.|
|`effectivePermissions`|Whether each category is allowed right now. Use it to gate features.|
|`explicitChoice`|What the visitor recorded, if anything.|

`resolveConsentPresentation` from `c15t` turns the policy into the buttons each
surface must show, in order. This module renders them and turns each click into
a kernel command:

```ts title="src/consent-ui.ts"
const label: Record<PresentationAction, string> = {
	accept: 'Accept all',
	customize: 'Choose cookies',
	dismiss: 'OK',
	reject: 'Reject optional',
	save: 'Save preferences',
};

// Each button is a visitor action. Only these calls record a choice.
const perform = async function perform(action: PresentationAction) {
	if (action === 'customize') {
		kernel.set.activeUI('dialog');
		return;
	}
	if (action === 'dismiss') {
		await kernel.commands.dismissNotice();
		return;
	}
	let choice: Partial<ConsentState> | 'all' | 'none' =
		action === 'accept' ? 'all' : 'none';
	if (action === 'save') {
		choice = {};
		for (const input of fields.querySelectorAll<HTMLInputElement>('input')) {
			const category = latest.policyRule.scope.find(
				(name) => name === input.name
			);
			if (category) {
				choice[category] = input.checked;
			}
		}
	}
	kernel.set.activeUI('none');
	const result = await kernel.commands.save(choice);
	status.textContent = result.ok
		? 'Your preferences are saved.'
		: 'Saved in this browser. Backend delivery will retry.';
};

// The policy decides which actions each surface offers, and in what order.
const renderActions = function renderActions(
	container: HTMLElement,
	surface: 'prompt' | 'preferences',
	snapshot: ConsentSnapshot
) {
	const presentation = resolveConsentPresentation({
		policy: snapshot.policyRule,
		surface,
	});
	const buttons = presentation.orderedActions.map((action) => {
		const button = document.createElement('button');
		button.type = 'button';
		button.textContent = label[action];
		button.addEventListener('click', () => {
			void perform(action);
		});
		return button;
	});
	if (surface === 'prompt') {
		for (const right of presentation.rights) {
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent =
				right === 'opt-out'
					? 'Do not sell or share my data'
					: 'Privacy settings';
			button.addEventListener('click', () => kernel.set.activeUI('dialog'));
			buttons.push(button);
		}
	}
	container.replaceChildren(...buttons);
};
```

In this file, `kernel` is `runtime.kernel`, `fields` is the element holding the
preference checkboxes, `latest` is the last snapshot the UI rendered, and
`status` is a live region for messages. `kernel.set.activeUI()` opens and closes
surfaces without recording anything. `kernel.commands.save()` records a choice:
`'all'` accepts, `'none'` rejects, and an object such as
`{ measurement: true }` saves those categories. `dismissNotice()` records that
the visitor saw a notice, not that they consented.

## Build a preference form with a draft

A preference form shows switches the visitor can move and keep moving before
anything is recorded. `createPreferenceDraft(kernel)` from
`c15t/preference-draft` holds those unsaved choices. It is the same draft the
React, Vue, Svelte and `@c15t/browser` preference dialogs use:

```ts title="src/preference-form.ts"
import type { AllConsentNames } from 'c15t';
import { createPreferenceDraft } from 'c15t/preference-draft';
import type { ConsentRuntime } from 'c15t/runtime';

// Render a form of category switches that records nothing until Save.
export const mountPreferenceForm = function mountPreferenceForm(
	runtime: ConsentRuntime,
	form: HTMLFormElement
): () => void {
	const draft = createPreferenceDraft(runtime.kernel);

	const render = () => {
		const { displayedCategories, isStale, values } = draft.getState();
		form.replaceChildren(
			...displayedCategories.map((category: AllConsentNames) => {
				const label = document.createElement('label');
				const input = document.createElement('input');
				input.type = 'checkbox';
				input.checked = values[category];
				input.disabled = category === 'necessary';
				input.addEventListener('change', () => {
					draft.set(category, input.checked);
				});
				label.append(input, ` ${category}`);
				return label;
			})
		);
		if (isStale) {
			// The policy changed under an unsaved edit: Save records nothing
			// until the visitor reviews the current choices.
			const review = document.createElement('button');
			review.type = 'button';
			review.textContent = 'Review choices';
			review.addEventListener('click', draft.reset);
			form.append(review);
		}
		const save = document.createElement('button');
		save.textContent = 'Save';
		form.append(save);
	};

	form.addEventListener('submit', (event) => {
		event.preventDefault();
		void draft.save();
	});
	render();
	// The draft follows the record and the policy while subscribed.
	return draft.subscribe(render);
};
```

`draft.getState()` returns what the form renders:

|Field|What it holds|
|--|--|
|`displayedCategories`|`necessary` plus the categories the policy lets the visitor decide, always in the order necessary, functionality, measurement, experience, marketing.|
|`values`|Each category's value: a staged edit, else the recorded choice, else the policy default. Categories outside `displayedCategories` read `false`.|
|`vendors`|Each declared vendor's switch. Empty under an IAB policy.|
|`isDirty`|Whether any staged value differs from the record.|
|`isStale`|Whether the policy, the displayed categories or the vendor list changed under a staged edit.|

`set(category, value)` and `setVendor(id, granted)` stage a switch;
`draft.save()` records the displayed categories and only the vendors the
visitor moved. While subscribed, the draft follows the record: when another
surface or tab saves, switches the visitor left alone take the new value, and
staged ones keep theirs. A stale draft records nothing and `save()` resolves
`{ ok: false }` until `reset()`. `draft.save({ input: 'all' })` and
`{ input: 'none' }` record a bulk choice under the current policy and drop
every staged switch.

Load the draft only where a preference form renders. Pages that show only a
banner do not need it.

## Close surfaces the way the stock UI does

`kernel.commands.save()` records a choice. The kernel hides the banner once no
prompt is owed, but a dialog the visitor opened stays open. To close surfaces
the way every c15t adapter does, wrap your clicks in the functions from
`c15t/surface-actions`:

|Function|What it does|
|--|--|
|`saveConsentSurface(kernel, () => kernel.commands.save(input))`|Runs the save and closes the open banner or dialog once the choice is recorded, before the backend answers. A save that records nothing new closes when it resolves successfully. The banner stays only while the policy still owes a choice or a notice.|
|`saveConsentBlanket(kernel, 'all' \|'none', runtime.iab)`|Accept all or reject all. Under an IAB policy it goes through the CMP so the TC string records it.|
|`saveIABConsentSurface(kernel, () => runtime.iab.save())`|Closes an IAB surface in the click task and brings it back if the CMP recorded nothing, for example when the vendor list failed to load.|
|`showConsentSurface(kernel, 'banner' \|'dialog' \|'none')`|Opens or closes a surface. `'none'` with the dialog open brings the banner back while the policy still owes a choice or a notice. A pending save started before it can no longer close or reopen anything.|
|`hasConsentUI(snapshot)`|Whether the policy owes any c15t banner or dialog. `false` until a rule resolves, for a `none` rule without rights, and while an external CMP owns the decision.|
|`hasConsentPreferences(snapshot)`|Whether a privacy settings control has somewhere to go: `hasConsentUI`, or an external CMP.|

A draft's save records in the same call, so it closes the dialog the same way:
`saveConsentSurface(kernel, () => draft.save(), () => !draft.getState().isDirty)`.
A stale draft resolves `{ ok: false }`, so its dialog stays open. The last
argument stops a save that recorded nothing new from closing the dialog over
switches the visitor moved while it ran. The stock React and Vue dialogs do the
same.

[When a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
explains the order of the local record, storage and the backend request.

## Start and stop the runtime

Subscribe before you start, so the UI renders the resolved policy the moment
it arrives:

```ts title="src/consent-ui.ts"
const unsubscribe = kernel.subscribe(render);
const stopErrors = kernel.events.on('command:error', ({ command }) => {
	if (command === 'init') {
		status.textContent =
			'Consent could not load. Check the backend endpoint and allowed origin.';
	}
});
render(kernel.getSnapshot());
// Reads stored choices, resolves the policy and starts script loading.
runtime.start();

window.addEventListener('pagehide', (event) => {
	// Back and Forward restore a cached page with the same runtime.
	if (event.persisted) {
		return;
	}
	unsubscribe();
	stopErrors();
	runtime.dispose();
});
```

`runtime.start()` reads stored choices, requests the policy and starts script
loading. Call it once, in the browser. `runtime.dispose()` removes everything
`start()` set up. The `pagehide` check keeps the runtime alive when the
browser stores the page for Back and Forward navigation.

The complete script, with the preference dialog, is
`internals/doc-snippets/javascript/src/headless.ts` in the c15t repository.

## What your UI must handle

A custom UI takes on everything the stock banner does:

* **Every prompt kind.** Show a decision for `choice`, a dismissable notice for
  `notice`, and nothing for `none`. Do not assume every prompt is accept or
  reject, or that no prompt means consent.
* **The policy's required actions and rights.** Render every action
  `resolveConsentPresentation` returns, including rights such as an opt-out
  link.
* **A way back.** Keep a privacy settings control on every page after the
  banner closes.
* **Visitor actions only.** Call `save()` and `dismissNotice()` only from a
  click or key press, never on load or during rendering.
* **Accessibility.** Focus, keyboard use, labels, error states and narrow
  screens are yours. The example uses a native `<dialog>` for focus handling.
* **Copy.** `snapshot.translations` carries the resolved language's copy,
  if you want the same text as the stock UI. See
  [translations](/docs/frameworks/javascript/translations).

Read [how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice, then run the
[verification checklist](/docs/guides/verify-consent).

## Use c15t with Solid

There is no published Solid adapter. Create the runtime as above and read it
through a signal:

```ts title="src/use-consent.ts"
import { createSignal, onCleanup } from 'solid-js';

import { runtime } from './consent-runtime';

export function useConsentSnapshot() {
	const [snapshot, setSnapshot] = createSignal(runtime.kernel.getSnapshot());
	onCleanup(runtime.kernel.subscribe((next) => setSnapshot(() => next)));
	return snapshot;
}
```

Call `runtime.start()` once in your entry file, after `render()`. Components
read `snapshot().effectivePermissions` and call `runtime.kernel.commands` from
event handlers, as in the example above. Other frameworks without an adapter
follow the same shape, with one runtime and one subscription per component
tree.

## Use the browser client without its UI

`@c15t/browser/headless` gives you the `@c15t/browser` client with no banner or
stylesheet. Page hooks such as `data-c15t-action="accept"` still work, and the
`ui` event says which surface to show:

```ts
import { init, manifest } from '@c15t/browser/headless';

const consent = init({ mode: manifest(), scripts });
consent.on('ui', (surface) => {
	banner.hidden = surface !== 'banner';
});
```

`scripts` is the list from the
[quickstart](/docs/frameworks/javascript/quickstart), and `banner` is your
banner element. Install `@c15t/browser@alpha` for this path.

## Check it works

Run the example or your app in a private window with the Network tab open.

1. Your banner appears once the policy resolves, with the actions
   `resolveConsentPresentation` returned. Vendor requests are absent.
2. Reject and reload. Your banner stays hidden and vendors stay blocked.
3. Open your preferences, allow Measurement only and save. Measurement
   vendors load and marketing vendors do not.
4. Tab through your banner and dialog. Every control is reachable, and
   Escape closes the dialog.

# @c15t/browser API
URL: https://c15t.com/docs/frameworks/javascript/api/browser
Reference for the @c15t/browser ES module in a bundled JavaScript app, covering its entry points, init and createConsentClient, the client's methods and properties, events, page hooks and helper exports.

## Entry points

|Import|What it gives you|
|--|--|
|`@c15t/browser`|`init`, `createConsentClient` and `mountConsentUI`, with the stock banner, dialog and trigger. `mode` is required: a factory from `manifest()`, `hosted()`, `offline()` or `custom()`.|
|`@c15t/browser/hosted`|The stock UI and client for hosted mode only. Requires a backend URL or a hosted transport factory.|
|`@c15t/browser/offline`|The stock UI and client for offline mode only, with bundled policy rules and presets.|
|`@c15t/browser/headless`|The same client with no UI and no CSS. `mountUI()` throws.|
|`@c15t/browser/iab`|The client with the IAB TCF CMP and the IAB banner and dialog. See [IAB TCF](/docs/frameworks/javascript/iab).|
|`@c15t/browser/devtools`|`mountDevTools(client, options)`. See [DevTools](/docs/frameworks/javascript/dev-tools).|
|`@c15t/browser/styles.css`, `@c15t/browser/iab/styles.css`|The stylesheets, for `ui: { shadow: false, styles: false }`.|

Install it with:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/browser@alpha`|
|pnpm|`pnpm add @c15t/browser@alpha`|
|yarn|`yarn add @c15t/browser@alpha`|
|bun|`bun add @c15t/browser@alpha`|

In the ES module build the preference dialog code is a separate chunk. It
starts loading in idle time once the banner or trigger is on screen, and at
the latest when the dialog opens. Idle preloading can download it even when
the visitor never opens preferences.

The script-tag files `c15t.js`, `c15t.offline.js` and `c15t.iab.js` each carry
their complete stylesheet in one file. The default `c15t.js` uses the hosted
client and requires a backend URL or hosted factory. `c15t.offline.js` uses
the offline client. For manifest or custom mode with the stock UI, use the
ES module root `@c15t/browser`, which takes any mode factory.

`@c15t/browser` is not part of the `c15t` package. Use one entry per page.
Each creates its own client, and two clients on one page would each run the
script loader and blockers.

### Choose a bundle for one mode

Use `@c15t/browser/hosted` when Inth or a self-hosted backend supplies the
policy. It excludes offline policy presets, offline resolution and manifest
transport code. Hosted mode already resolves the visitor's policy on the
server through `/init`; this entry removes unused client code without
changing that request.

Use `@c15t/browser/offline` when the browser resolves bundled rules. It
excludes hosted and manifest transport code. The default offline transport
keeps choices in the browser's consent cookie and localStorage, with no
consent backend requests or server records. Not recommended for production
environments.

Both entries keep the banner, preference dialog, page hooks, script gating,
blockers, callbacks and persistence. Their `init()` and
`createConsentClient()` methods have the same lifecycle as the general entry.

|Entry|Accepted configuration|Configuration that throws|
|--|--|--|
|`@c15t/browser/hosted`|`backendURL`, optional `mode: 'hosted'`, or a factory from `hosted()`. `policyRules` accepts authored `PolicyRule` objects.|Missing backend URL without a hosted factory; a different mode; `manifest` or `manifestURL`; preset-name strings in `policyRules`.|
|`@c15t/browser/offline`|Optional `mode: 'offline'` or a factory from `offline()`. `policyRules` accepts authored rules and preset names, or defaults to the recommended rules.|`backendURL`, `manifest` or `manifestURL`; a different mode.|

Use `@c15t/browser` for manifest or custom mode, or when an application
chooses its mode at runtime. Use `@c15t/browser/iab` for IAB TCF. The general
entry imports no transport itself, so a bundle keeps only the factory it
imports. It takes `mode` as a factory only: `backendURL`, `manifest`,
`manifestURL`, `policyRules` and mode names such as `'hosted'` are options of
the `/hosted` and `/offline` entries and the script-tag builds.

## Start the client

`init(options)` creates the client and starts it:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`createConsentClient(options)` creates the client without starting it.
Construction reads no storage, sends no request and touches no DOM, so a
module can create it at import time and call `client.start()` later:

```ts
import { createConsentClient, manifest } from '@c15t/browser';

export const consent = createConsentClient({ mode: manifest(), scripts });
```

`start()` reads stored choices, requests the policy, starts the script loader,
the iframe blocker and any network blocker, listens for page hooks and mounts
the UI. It mounts on `DOMContentLoaded` when `<body>` does not exist yet. A
second `start()` does nothing. [Options](/docs/frameworks/javascript/api/browser-options)
lists everything `init` and `createConsentClient` accept.

## Read state

|Member|Returns|Use it for|
|--|--|--|
|`ready()`|`Promise<ConsentSnapshot>`|Wait until the policy has resolved. For a returning visitor, `hasConsented()` is reliable after it.|
|`has(condition)`|`boolean`|Whether a category, or a condition such as `{ or: ['measurement', 'marketing'] }`, is allowed right now.|
|`hasConsented()`|`boolean`|Whether the visitor has answered the choice prompt.|
|`getSnapshot()`|`ConsentSnapshot`|The full state. See the [snapshot reference](/docs/frameworks/javascript/api/snapshot).|
|`subscribe(listener)`|`() => void`|Call `listener` with each new snapshot. Returns an unsubscribe function.|
|`on(event, listener)`|`() => void`|Listen for `ready`, `consent`, `ui` or `error`.|
|`consentCategories`|`AllConsentNames[]`|The categories the dialog offers, in a fixed order: `necessary`, `functionality`, `measurement`, `experience`, `marketing`, limited to the policy's categories. The order of the `consentCategories` option doesn't change it.|

`has()` reads a permission, which says whether code may run now. Under an opt-out policy
it is `true` before the visitor does anything. `hasConsented()` and
`getSnapshot().explicitChoice` read the recorded choice, which says what the
visitor decided. Gate code on permissions; report on recorded choices.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Record a choice

Call these only from a visitor's click or key press.

|Method|Returns|What it records|
|--|--|--|
|`acceptAll()`|`Promise<SaveResult>`|Without IAB, allows every category the dialog offers. Under an IAB policy it confirms the vendors' declared processing through the CMP. Optional categories without declared consent purposes remain denied. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).|
|`rejectAll()`|`Promise<SaveResult>`|Denies every optional category the dialog offers.|
|`save(consents)`|`Promise<SaveResult>`|The categories you name, such as `{ measurement: true }`. Categories the dialog does not offer are dropped. Under an IAB policy it resolves `{ ok: false }` and emits `error`; use `saveIAB()`.|
|`saveIAB()`|`Promise<SaveResult>`|The IAB purpose and vendor choices on `runtime.iab`. IAB entry only.|
|`dismissNotice()`|`Promise<NoticeDismissResult>`|Acknowledges a notice. Grants nothing. `{ ok: false, reason: 'not-required' }` when no notice is due.|
|`identify(user)`|`Promise<void>`|Links the consent record to `{ externalId, identityProvider?, identityToken? }`; the [token](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link. Failures surface through `error`.|

Each save applies in the browser and closes the banner or dialog before the
backend request finishes. `SaveResult.ok` is `false` when the request failed;
the choice stays in effect and c15t retries the request later.

## Control the UI

|Method|What it does|
|--|--|
|`showBanner()`, `openDialog()`, `closeDialog()`|Change the surface c15t wants shown. Records nothing.|
|`setLanguage(code)`|Sets the language and resolves the policy again, which fetches that language's copy from the backend. In offline mode the copy comes from the bundled translations and `i18n.messages`. See [translations](/docs/frameworks/javascript/translations).|
|`setOverrides(overrides)`|Merges into the country, region, language and GPC inputs to policy matching. A key you pass replaces its value, `undefined` clears it, and a key you leave out stays.|
|`mountUI(options?)`|Removes the stock UI and mounts it again with new UI options. Throws in the headless entry.|
|`processIframes()`|Pauses gated iframes that consent does not allow and restores the ones it allows. Needed only with `iframeBlocker: { disableAutomaticBlocking: true }`. See [iframe blocker](/docs/frameworks/javascript/modules/iframe-blocker#check-iframes-on-demand).|
|`ui`|The mounted UI handle, with `host`, `root`, `update()` and `destroy()`, or `null`.|

## Lifecycle and internals

|Member|What it is|
|--|--|
|`start()`|Starts the client. `init()` calls it for you.|
|`started`|Whether `start()` has run and the client is not disposed.|
|`dispose()`|Removes the UI, page listeners, blockers and the scripts c15t added, then disposes the runtime. Code that already ran keeps running.|
|`options`|The options the client was created with.|
|`mode`|`hosted`, `offline`, `manifest` or `custom`.|
|`runtime`|The [consent runtime](/docs/frameworks/javascript/api/runtime) that owns the kernel and modules. `runtime.iab` is the CMP handle under IAB.|
|`kernel`|The [consent kernel](/docs/frameworks/javascript/api/kernel): snapshot, commands and events.|

Do not attach a second script loader, network blocker or iframe blocker to
`client.kernel`. The client already runs one of each.

## Events

`on(event, listener)` returns an unsubscribe function:

|Event|Payload|When it fires|
|--|--|--|
|`ready`|the snapshot|The policy has resolved and the UI can render. For a returning visitor, `hasConsented()` is reliable from here.|
|`consent`|the snapshot|Permissions, the recorded choice or the vendor switches changed. This includes a stored choice restored at start, a save, an expiry and a GPC change.|
|`ui`|`'banner'`, `'dialog'` or `'none'`|The surface c15t wants shown changed.|
|`error`|the error|A backend call failed, or an IAB step failed.|

A `ready` listener added after the policy resolved runs at once with the
snapshot from that moment. A `ui` listener added after that runs at once
with the current surface. `consent` and `error` listeners only hear later
changes.

Each event is also dispatched on `document` as `c15t:ready`, `c15t:consent`,
`c15t:ui` and `c15t:error`, with the payload in `event.detail`.
[Callbacks](/docs/frameworks/javascript/callbacks) compares events with the
`callbacks` option.

## Page hooks

A started client also wires markup on the page, with no code:

|Markup|What it does|
|--|--|
|`<button data-c15t-action="…">`|Runs the action on click. Values below.|
|A link whose `href` ends in `#c15t-preferences`|Opens the preference dialog.|
|`<script type="text/plain" data-c15t-category="…">`|Runs the script once that category is allowed, in page order.|
|`<iframe data-src="…" data-category="…">`|Sets `src` once that category is allowed.|

|Value|What a click does|
|--|--|
|`accept`|Like the banner's accept button, allows every category the dialog offers without IAB. Under an IAB policy it confirms the vendors' declared processing through the CMP. Optional categories without declared consent purposes remain denied. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).|
|`reject`|Rejects every optional category the dialog offers.|
|`customize`|Opens the preference dialog. Records nothing.|
|`dismiss`|Dismisses a notice. This records an acknowledgement, not consent, and does nothing unless the policy shows a notice.|
|`banner`|Shows the banner again. Records nothing.|
|`close`|Closes the banner or dialog. Records nothing.|

## Helper exports

The general `@c15t/browser` entry exports all the helpers below. The hosted
entry exports `hosted`; the offline entry exports `offline` and
`resolveRules`. Both include the page action constants, gated script
helpers, `mountConsentUI` and `version`.

|Export|What it does|
|--|--|
|`hosted`, `offline`, `manifest`, `custom`|Transport factories for the `mode` option. See [transports](/docs/frameworks/javascript/transports).|
|`manifestNeedsLocation(manifest)`|Whether some location gets a different banner, or none, under this manifest, so a page knows it must supply a country to resolve it without `/init`. `false` when every country and region rule gives the same banner.|
|`resolveRules(rules)`|Turns preset names such as `'europeOptIn'` into policy rules. Throws on an unknown name.|
|`activateGatedScripts(snapshot, root?, options?)`|Runs allowed `text/plain` scripts under `root` yourself, for a setup without a client. `options.nonce` runs only tags that carry that nonce. Returns how many ran.|
|`mountConsentUI(client, options?)`|Mounts the stock UI for a client. `mountUI()` calls it.|
|`ACTION_ATTRIBUTE`, `PREFERENCES_HASH`, `CATEGORY_ATTRIBUTE`, `ACTIVATED_ATTRIBUTE`|`'data-c15t-action'`, `'#c15t-preferences'`, `'data-c15t-category'` and `'data-c15t-activated'`.|
|`version`|The package version.|

The package also exports the `ConsentClient`, `ConsentClientOptions`,
`ConsentUIOptions`, `ConsentBannerOptions`, `ConsentDialogOptions`,
`ConsentTriggerOptions`, `ConsentClientEventMap`, `ConsentSnapshot` and
`ConsentState` types.

The hosted and offline entries export `HostedConsentClientOptions` and
`OfflineConsentClientOptions`, respectively. These types restrict connection
options to the entry's mode. Runtime validation also checks a supplied
transport factory's `kind`.

## Check it works

1. Start the app and run `await consent.ready()` from code or a breakpoint.
   It resolves with a snapshot whose `resolution.status` is `matched`.
2. Click **Reject All**. `consent.hasConsented()` is `true` and
   `consent.has('measurement')` is `false`.
3. Call `consent.openDialog()`. The preference dialog opens with
   **Analytics** (the `measurement` category) off.

# Callbacks
URL: https://c15t.com/docs/frameworks/javascript/callbacks
Run code in a JavaScript app when a visitor records a consent choice, when permissions change, when a request fails or before the withdrawal reload, with c15t callbacks, client events and kernel events.

## Pick the hook for the job

|You want to|Use|
|--|--|
|Start or stop your own code as permissions change|`callbacks.onPermissionsChanged`, or the client's `consent` event|
|Know that a visitor clicked accept, reject or save|`callbacks.onChoiceRecorded`|
|Wait until c15t knows the visitor's permissions|`consent.ready()`, or the `ready` event|
|Show, hide or switch your own UI|The client's `ui` event, or `kernel.subscribe`|
|Report failed backend calls|`callbacks.onError`, or the `error` event|
|Flush data before the reload after a withdrawal|`callbacks.onBeforeConsentRevocationReload`|

Prefer gating a vendor through `scripts` where you can. The loader starts and
stops it for you, and its own `onLoad` and `onConsentChange` callbacks cover
per-vendor work; see the [script loader](/docs/frameworks/javascript/modules/script-loader).

## Pass callbacks

`callbacks` works the same in `init()` from `@c15t/browser` and in
`createConsentRuntime`:

```ts title="src/main.ts"
import { hosted, init } from '@c15t/browser';

import { scripts } from './scripts';

export const consent = init({
	callbacks: {
		// Only a visitor's own accept, reject or save.
		onChoiceRecorded: ({ confirmed, snapshot }) => {
			console.info('Visitor confirmed', confirmed, snapshot.explicitChoice);
		},
		onError: ({ error }) => {
			console.warn('Consent request failed:', error);
		},
		// Any change to what may run, including a restored choice.
		onPermissionsChanged: ({ previous, snapshot }) => {
			console.info('Permissions', previous, snapshot.effectivePermissions);
		},
	},
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});

// The surface c15t wants shown: 'banner', 'dialog' or 'none'.
consent.on('ui', (surface) => {
	document.documentElement.dataset.consentSurface = surface ?? 'none';
});
```

|Callback|Payload|When it runs|
|--|--|--|
|`onChoiceRecorded`|`{ snapshot, confirmed, actionAt }`|A visitor accepted, rejected or saved. `confirmed` lists the categories this action recorded.|
|`onPermissionsChanged`|`{ snapshot, previous }`|Effective permissions changed value, for any reason. `previous` is the old permission map.|
|`onError`|`{ error }`, a message string|A command failed, such as `/init` or a save request.|
|`onBeforeConsentRevocationReload`|`{ preferences }`|Right before the reload that follows a withdrawal. Runs synchronously; keep it short.|

Callbacks are read when the client or runtime is created.

## A recorded choice is not a permission change

* `onChoiceRecorded` runs only for a visitor's own accept, reject or save. It
  does not run when a stored choice is restored at load, when a choice
  expires, or when a notice is dismissed. Use it for analytics about the
  decision itself.
* `onPermissionsChanged` runs whenever what may run changes. That includes a
  save that changed something, a stored choice restored at load, a policy
  resolving, a choice expiring and a GPC signal. Use it to start and stop
  your code.

A save that leaves every permission as it was can run `onChoiceRecorded`
without `onPermissionsChanged`. Never call a save from
`onPermissionsChanged`; that turns a permission into a recorded choice the
visitor did not make. [How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Client events

The `@c15t/browser` client also emits events. `consent.on(event, listener)`
returns an unsubscribe function:

|Event|Payload|When it fires|
|--|--|--|
|`ready`|the snapshot|The policy has resolved and the UI can render. For a returning visitor, `hasConsented()` is reliable from here.|
|`consent`|the snapshot|Permissions, the recorded choice or the vendor switches changed. This includes a stored choice restored at start, a save, an expiry and a GPC change.|
|`ui`|`'banner'`, `'dialog'` or `'none'`|The surface c15t wants shown changed.|
|`error`|the error|A backend call failed, or an IAB step failed.|

A `ready` listener added after the policy resolved runs at once with the
snapshot from that moment. A `ui` listener added after that runs at once
with the current surface. `consent` and `error` listeners only hear later
changes.

Each event is also dispatched on `document` as `c15t:ready`, `c15t:consent`,
`c15t:ui` and `c15t:error`, with the payload in `event.detail`, for code that
cannot import the client.

## Kernel events

A runtime or a kernel you own has no client events. Listen on the kernel
instead:

```ts
const stop = runtime.kernel.events.on('choice:recorded', ({ confirmed }) => {
	console.info('Visitor confirmed', confirmed);
});
```

The four callbacks are built on `choice:recorded`, `permissions:changed` and
`command:error`. The [kernel reference](/docs/frameworks/javascript/api/kernel#events)
lists every event. To attach the callbacks to a kernel you created yourself,
call `wireRuntimeCallbacks({ kernel, callbacks })` from `c15t/runtime`.

## Errors thrown by your code

A callback or kernel listener that throws does not stop other listeners or
fail the action. c15t reports it with `reportError` in the browser.

A listener added with `on()` on the `@c15t/browser` client that throws is
logged with `console.error`. The later `on` listeners for the same event and
the matching `c15t:*` event on `document` still run. This covers the `ready`
and `ui` listeners that `on()` calls at once after the policy resolved, so
`on()` still returns its unsubscribe function.

## Check it works

1. Add the callbacks above and open the app in a private window under an
   opt-in policy. Nothing logs, because nothing is allowed and nobody chose.
2. Click **Accept All**. Both `onChoiceRecorded` and `onPermissionsChanged`
   log.
3. Reload. `onPermissionsChanged` logs the restored permissions and
   `onChoiceRecorded` stays silent.

# IAB TCF
URL: https://c15t.com/docs/frameworks/javascript/iab
Add IAB TCF to a JavaScript app with the @c15t/browser IAB build, or attach the IAB module to a consent runtime or kernel you own.

## Use the IAB build of @c15t/browser

With the stock UI from the [quickstart](/docs/frameworks/javascript/quickstart),
import `init` from `@c15t/browser/iab` instead of `@c15t/browser`. This entry
adds the CMP, the TC string encoder, the IAB banner and the purpose and vendor
dialog. The plain entry leaves them out. Its stock banner stands aside for a
policy that uses the `iab` model, so a client that resolves one emits an
`error` event and throws an `IABUnavailableError` (code
`C15T_IAB_UNAVAILABLE`) as an uncaught error. So does the IAB entry with
`iab: false`.

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser/iab';

const consent = init({
	mode: manifest(),
	iab: { cmpId: YOUR_CMP_ID, vendors: [1, 2, 755] },
});

await consent.ready();
const cmp = consent.runtime.iab;
if (cmp) {
	await cmp.whenReady?.();
	cmp.setPurposeConsent(1, true);
	cmp.setVendorConsent(755, true);
	const result = await consent.saveIAB();
	if (!result.ok) consent.openDialog();
}
```

Replace `https://your-project.inth.app` with your project's backend URL and
`YOUR_CMP_ID` with your registered CMP ID, as explained below. The
second half shows confirming individual choices from code; the stock dialog
does this for visitors. `ready()` waits for the policy, and `whenReady()` waits
for the vendor list and CMP setup. `acceptAll()` and `rejectAll()` confirm
through the CMP under an IAB policy. `save({ ... })` with categories fails
under an IAB policy because it cannot produce a TC string; use `saveIAB()`.

When the resolved policy is not an IAB policy, this entry shows the ordinary
banner. For your own stylesheet with `ui: { shadow: false }`, import both
`@c15t/browser/styles.css` and `@c15t/browser/iab/styles.css`.

## Attach the module to your kernel

Without `@c15t/browser`, install `@c15t/iab` with `c15t`. The following
fragment assumes an existing kernel connected to Inth and an applicable IAB
policy:

```ts
import { createIAB } from '@c15t/iab';

function attachIAB(
	kernel: Parameters<typeof createIAB>[0]['kernel'],
	cmpId: number
) {
	return createIAB({ kernel, cmpId });
}
```

Supply your deployment's CMP ID and vendor configuration. Do not copy a demo ID
into production: IAB Europe assigns CMP IDs at registration
([register.consensu.org/CMP](https://register.consensu.org/CMP)), every TC
String names the CMP that wrote it, and `createIAB` throws unless the ID is an
integer from 2 to 4095 rather than encoding a string that names no registered
CMP. The module installs the CMP API, manages vendor data and can encode the TC
String. It does not render your banner or preferences UI.

To expose the same TC String through the Global Privacy Platform API
(`__gpp`), and US state opt-outs alongside it, add
[IAB GPP](/docs/frameworks/javascript/gpp).

## Restrict how vendors use a purpose

Publisher restrictions override a vendor's declared use of one purpose. Pass
them as `publisherRestrictions` to `createIAB`, in the runtime's `iab`
options, or in the `iab` options of the Astro integration. The vendor IDs
below are placeholders; use vendors from your list whose declarations allow
each restriction.

```ts
import { createIAB } from '@c15t/iab';

function attachIAB(
	kernel: Parameters<typeof createIAB>[0]['kernel'],
	cmpId: number
) {
	return createIAB({
		kernel,
		cmpId,
		publisherRestrictions: [
			// Vendors 10 and 755 may not use purpose 4.
			{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] },
			// Vendor 755 must use legitimate interest for purpose 7.
			{ purposeId: 7, restrictionType: 2, vendorIds: [755] },
		],
	});
}
```

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Own the lifecycle

Dispose the IAB handle before disposing its kernel. When using a shared runtime,
provide the IAB factory through that runtime's configuration instead of creating
a second module for each UI root. Await lazy readiness before calling a lazily
loaded handle's actions.

A complete implementation needs policy-aware actions, vendor and purpose
controls, persistent preferences access and keyboard interaction. Test the
resulting TC String, `__tcfapi` and actual vendor requests. Keep backend, schema,
core and IAB packages on compatible v3 versions.

## Server-rendered vendor data

Server integrations serialize a `gvlReference` and the banner's summary instead
of embedding the full Global Vendor List. The reference contains its URL,
language and `vendorListVersion`. The banner shows the same purpose names and
vendor count on the server and during hydration.

Configure vendor filtering on the server when the banner must render immediately.
An additional client-only `vendors` allowlist makes the server summary unsuitable:
the banner waits for the full list, then shows the filtered count and disclosures.
Unknown or duplicate IDs do not increase the count. This case adds the list fetch
to banner visibility time; the default server-configured path does not wait.

The IAB module fetches the full list when it mounts in the browser. Loading
starts before interaction so CMP initialization and validation of returning
visitors' consent do not wait for a click. Early Accept and Reject actions wait
for the list before encoding a TC String. A failed fetch leaves the banner
visible and does not grant consent. A later action retries a failed request.
A list version mismatch requires a new init response or a reload.
A new reference from initialization or a language change starts a new load and
cancels actions queued for the previous list. Existing TCF listeners are retained.
Client-only manifest transports keep their fetched GVL, including custom fetcher
filtering; deferral applies at server-rendering boundaries.

Astro, TanStack Start, Nuxt, Next.js and SvelteKit manifest init handlers also serve
versioned list requests on their existing init route. These responses contain
only the public list and use `public, max-age=86400`. Resolved init data remains
private. Next.js and Svelte hosted prefetch retain the inline list when cookies,
forwarded headers or a custom fetch are required. Those server credentials are
not serialized into a browser reference. The list URL includes its language and version; a route returns an
uncacheable `409` if it can no longer supply that version. Responses are not
marked immutable because translations or publisher filtering can change
without a new vendor-list version.

Astro, Next.js and TanStack Start use a same-origin route when `routePrefix`
names a mounted consent route. Astro mounts one at `/api/c15t` by
default. Without those options, Next.js and TanStack Start reference the public
list URL from the manifest. Allow `'self'` in CSP `connect-src` for same-origin
routes, or allow the public list origin for direct requests.

Hosted init responses use an `init` reference to read the list from
the existing init endpoint. These references include the original country,
region and GPC inputs so a hosted request resolves the same regional policy.
They do not carry credentials. The inputs travel as query parameters, so a
cross-origin request needs no CORS preflight.
The endpoint keeps its existing private caching
rules. Allow the referenced origin in your CSP `connect-src` directive.

An explicit `gvl` supplied by your application still takes precedence, including
`gvl: null` to disable IAB. Applications that supply a list inline are responsible
for its serialized size. Vendor allowlists still apply after the list loads.

# IAB GPP
URL: https://c15t.com/docs/frameworks/javascript/gpp
Add the IAB Global Privacy Platform API (__gpp) to a JavaScript app with mountGPP from @c15t/browser/gpp, so ad tech can read US state opt-outs and the TCF EU consent string.

## What GPP does

`mountGPP()` from `@c15t/browser/gpp` installs `window.__gpp`, the GPP 1.1
CMP API, and keeps its GPP string in step with the visitor's choices.
Prebid.js, Google Ad Manager and other ad tech read US privacy signals from
it.

## Turn on GPP

Pass the client from `init()` to `mountGPP()`:

```ts title="src/main.ts"
import { hosted, init } from '@c15t/browser';
import { mountGPP } from '@c15t/browser/gpp';

const consent = init({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
});

// Installs `window.__gpp` and keeps it in step with the visitor's choices.
const gpp = mountGPP(consent);

window.__gpp?.('addEventListener', (event) => {
	const { eventName, data } = event as { eventName: string; data: unknown };
	if (eventName === 'signalStatus' && data === 'ready') {
		console.log('GPP string', gpp.getGPPString());
	}
});
```

`mountGPP()` lives in its own entry, so apps that do not import
`@c15t/browser/gpp` bundle none of the GPP code. `@c15t/browser` already
depends on `@c15t/iab`; nothing else to install. The second argument takes
the GPP options listed below, for example `mountGPP(consent, { usFallback: 'none' })`. Call `gpp.dispose()` to remove `__gpp`, before
`consent.dispose()` if you dispose the client.

Replace `https://your-project.inth.app` with your project's backend URL. The
GPP string follows the policy and location Inth resolves for the visitor, so
a US visitor's state comes from the backend. With `offline()` mode, pass the
state yourself, for example `overrides: { country: 'US', region: 'CA' }`.

To add the TCF EU section for visitors under an `iab` policy, set up
[IAB TCF](/docs/frameworks/javascript/iab) as well.

## Use GPP with your own runtime

`createConsentRuntime()` takes a `gpp` option and the loader for it:

```ts title="src/consent-runtime.ts"
import { hosted } from '@c15t/core';
import { createConsentRuntime } from '@c15t/core/runtime';

const runtime = createConsentRuntime({
	gpp: true,
	loadGPP: () => import('@c15t/iab/gpp'),
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
});
runtime.start();
```

With any other consent kernel, call `createGPP({ kernel })` from
`@c15t/iab/gpp`. It takes the options below and returns the same handle as
`mountGPP()`. Both throw when a CMP that has already loaded owns `__gpp`.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Transports
URL: https://c15t.com/docs/frameworks/javascript/transports
Choose where a JavaScript app's c15t policy comes from and where choices go, with the hosted, manifest, offline and custom transports for @c15t/browser, createConsentRuntime and your own kernel.

## Compare the transports

A transport tells the kernel which policy applies to this visitor and where
to record their choice.

|Transport|Policy comes from|Choices go to|Use it when|
|--|--|--|--|
|`manifest()` with a build-time snapshot, recommended|Public policy bundled during the build, resolved in the browser|The backend's `/subjects`|You use Vite and can rebuild after policy edits. Regional policies may still request location.|
|`hosted()`|The backend's `/init`, per visit|The backend's `/subjects`|Policy changes must apply without rebuilding, or you need backend resolution on every visit.|
|`manifest()` at runtime|The backend's public `/manifest`, resolved in the browser|The backend's `/subjects`|You want the banner to render without a per-visit `/init` request and cannot bundle the policy.|
|Offline|Rules bundled in your app|Nowhere; the browser only|Prototypes and tests. Not recommended for production environments.|
|Custom|Your own `init` function|Your own `save` function|You run your own consent API.|

[Consent modes](/docs/concepts/modes) covers the same factories in every
framework, and [data fetching](/docs/concepts/data-fetching) compares the
paths in more depth, including what each one sends.

## Pass a transport

Each setup takes the transport in a slightly different form:

|Setup|Where it goes|
|--|--|
|`@c15t/browser`|`init({ mode })`, a factory such as `manifest()`, `hosted()` or `offline()` from `@c15t/browser`. Required.|
|`createConsentRuntime`|`mode`, a factory such as `hosted({ backendURL })`. Required.|
|Script tag|`data-mode="hosted"`, `"manifest"` or `"offline"`. Mode names work only in the script-tag builds.|
|`createConsentKernel`|`transport`, the transport object itself, such as `createHostedTransport({ backendURL })`.|

A factory is created once. To switch transports, dispose the client or
runtime and create a new one.

`init()` from `@c15t/browser` imports no transport itself, so the bundle keeps
only the factory you import. Passing a name throws:

```txt
@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or offline() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.
```

## Hosted

`hosted()` talks to your Inth or self-hosted backend. `hosted({ backendURL })`
from `c15t` requires the URL:

```ts title="src/consent-runtime.ts"
import { hosted } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

import { scripts } from './scripts';

// One runtime for the page: policy, stored choices, script loading,
// iframe blocking and the reload after a revocation.
export const runtime = createConsentRuntime({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});
```

|Option|What it does|
|--|--|
|`backendURL`|The backend URL. Relative URLs such as `/api/c15t` work behind a proxy.|
|`headers`|Request headers to forward on `/init`: `accept-language`, the geo headers and `sec-gpc`. Meant for server code forwarding a visitor's request. In a browser, any but `accept-language` makes a cross-origin `/init` wait for a CORS preflight; pass overrides through the runtime's `overrides` instead, which travel in the query string.|
|`fetch`|A `fetch` implementation, for tests or unusual runtimes.|
|`domain`|The domain recorded with each save. Defaults to the page's host.|
|`initURL`|Send `/init` somewhere else, such as a same-origin route, while saves still go to `backendURL`. Saves then assert the policy they were made against. Its query string may carry your own parameters, but c15t replaces any named `v`, `contract`, `country`, `region`, `gpc`, `experiment`, `journey`, `journeyScope` or `stored` with its own value.|
|`assertDecisionInputs`|Send the resolved policy inputs with each save, so the backend can reject a save made against a stale policy. Defaults to `true` when `initURL` is set.|

`hosted()` from `@c15t/browser` takes the same options, and `backendURL`
defaults to the URL `consentManifest()` from `c15t/build` read from
`VITE_C15T_BACKEND_URL` or `VITE_INTH_PROJECT_URL`. Without the plugin or the
option it throws:

```txt
@c15t/browser: hosted() needs `backendURL`. Pass it, or add consentManifest() from c15t/build to your Vite config and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL).
```

A production build prints only the first sentence.

Add your app's origin to the Inth project's trusted origins, or the browser
blocks consent saves with a CORS error.

A cross-origin `/init` is a CORS simple request: the client version, policy
contract, overrides and experiment arm go in the query string, and the request
carries no cookies, so the browser sends it without an `OPTIONS` preflight.
Saves still go out with cookies and still need the trusted origin.

## Manifest

`manifest()` from `@c15t/browser` resolves the policy in the browser from the
backend's public manifest. With no options it uses the snapshot and backend
URL `consentManifest()` downloaded; without a snapshot it fetches
`${backendURL}/manifest` once. It works with `init()` and with
`createConsentRuntime`:

```ts title="src/consent-runtime.ts"
import { manifest } from '@c15t/browser';
import { createConsentRuntime } from 'c15t/runtime';

// Fetch the backend's public manifest and resolve the policy in the browser.
// Saves still go to the backend.
export const runtime = createConsentRuntime({
	mode: manifest({ manifestURL: 'https://your-project.inth.app/manifest' }),
});
```

|Option|What it does|
|--|--|
|`manifestURL`|Where to fetch the manifest when the page loads. The build's snapshot is not used, but saves still go to the build's backend URL. Without one, a URL that ends in `/manifest` also gives the backend URL.|
|`snapshot`|The manifest object itself, inlined into the page. No manifest request at all. Defaults to the build's snapshot unless you set `manifestURL`.|
|`source`|`'runtime'` ignores the build's snapshot and fetches the manifest. You can pass `snapshot` or `source`, not both.|
|`backendURL`|Where saves go. Defaults to the build's backend URL. Required otherwise, unless `manifestURL` ends in `/manifest`. `''` means this origin.|
|`inputs`|`{ country, region }` known ahead of time, such as a country your edge injected into the page.|
|`geoURL`|A same-origin route that answers `{ country, region }`, asked when the policy needs a location the page doesn't have.|
|`initFallback`|`false` resolves for an unknown location instead of asking the backend's `/init`. Defaults to `true`.|
|`fetch`|A `fetch` implementation.|

When some locations get a different banner than others, or no banner, and
neither the page nor `geoURL` supplies a country, the transport asks the
backend's `/init` instead, so the answer stays correct. That visitor's banner
waits for the round trip. Rules keyed by country or region that all give the
same banner (same model, prompt, categories, copy and GPC handling, only the
rule id differs) resolve in the browser, so the banner shows without a
request. Such a manifest needs a default rule, plus a fallback rule when it
has region rules, so that every location matches one. When the location is
unknown, an IAB policy behind country or region rules still goes to `/init`.
`manifestNeedsLocation(manifest)` from `@c15t/browser` tells you in advance.

The browser bundle carries English base copy. Another language's base copy
loads the first time a visitor needs it, and the manifest's own translations
apply on top.

A manifest resolved in the browser without a known location reports no
location: `getSnapshot().location` and `useLocation()` have a `null` country
and region. Code that reads the visitor's country should supply it through
`inputs`, or use `/init`. IAB GPP needs it for its US state sections, so when
GPP is on, through the runtime's `gpp` option, `<ConsentGPP>` or `mountGPP()`,
an unknown location goes to `/init` even when every location gets the same
banner. The script-tag build counts GPP as on, because `c15t.gpp.js` can load
after `init()`; pass `gpp: false` to `c15t.init()` to resolve in the browser on
pages that do not load it.

`createManifestTransport` from `c15t/transports/manifest` is for server code
only. It bundles every language. Browser code uses `manifest()`, or
`createBrowserManifestTransport` from `c15t/transports/manifest-browser`.

### Bundle the manifest during Vite builds

The [quickstart](/docs/frameworks/javascript/quickstart) and
`examples/javascript` in the c15t repository use this setup.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Install `c15t@alpha` alongside `@c15t/browser` for the build plugin. Add it to
your existing Vite plugins:

```ts title="vite.config.ts (plugins option)"
import { consentManifest } from 'c15t/build';

export default {
	plugins: [
		// Keep your existing framework plugins here.
		consentManifest({ backendURL: 'https://your-project.inth.app' }),
	],
};
```

Without `backendURL`, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`. The plugin
fetches the policy during `vite build`, or in `vite dev` when the app first
loads it, and serves it as `snapshot` from `c15t/generated`. A build fetches
only when the app uses `manifest()`. In your browser entry point, pass
`manifest()` as the mode of the existing `init()` call. It reads the snapshot
and the backend URL from `c15t/generated`:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';

init({ mode: manifest() });
```

Keep your scripts and UI options. The browser resolves the snapshot without
a manifest request when the policy does not need geography, or the required
country and region are known through `overrides`. When required
geography is missing, it calls backend `/init` and uses the backend's resolved
policy and translations. Those visitors still wait for a backend round trip
and can receive newer policy than the build snapshot.

When the build has no snapshot, as in `vite dev` after a failed fetch,
`snapshot` is `undefined`, and the browser fetches
`${backendURL}/manifest` instead.

A script-tag site without a build step cannot run this hook.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy updates without a rebuild, use `hosted()`, which asks the backend's
`/init` on each page load, or `manifest({ source: 'runtime' })`, which fetches
the manifest at runtime. Both keep reading the backend URL from the plugin.

## Offline

`offline()` resolves bundled rules in the browser and sends nothing. `c15t`
and `@c15t/browser` export the same `offline()`, so it works with `init()` and
with `createConsentRuntime`:

```ts title="src/consent-runtime.ts"
import { offline } from '@c15t/browser';
import { policyRulePresets } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

// No backend: rules resolve in the browser and choices stay there. The
// browser does not know the visitor's country, so the page supplies it.
export const runtime = createConsentRuntime({
	mode: offline({
		policyRules: [
			policyRulePresets.europeOptIn(),
			policyRulePresets.worldNone(),
		],
	}),
	overrides: { country: document.documentElement.dataset.country },
});
```

Without `policyRules`, it uses c15t's recommended rules. They are strict
opt-in for Europe, the UK, Quebec and unknown locations, opt-out for US
states with a privacy law, and no prompt elsewhere. The browser cannot see the visitor's
country, so without a `country` override every visitor gets the strict
opt-in fallback. Choices stay in that browser and there are no consent
records. Not recommended for production environments.

`init()` from `@c15t/browser` takes `mode: offline({ policyRules })` with rule
objects from `policyRulePresets`. Preset names such as
`['europeOptIn', 'worldNone']` work only in the script-tag builds, through
`data-policy-rules` or a queued `policyRules`.
[Policies](/docs/concepts/policies) lists the presets.

In offline mode, a language your app sets with `overrides.language`,
`setLanguage()` or `kernel.set.language()` switches the copy when the bundle
or `i18n.messages` has that language. A language with no copy shows the
default copy. The language a server prefetch detected from `Accept-Language`
does not switch the copy. See
[translations](/docs/frameworks/javascript/translations#switch-language-at-runtime).

For a kernel you create yourself, `createOfflineTransport({ policyRules })`
from `c15t` returns the transport object. Pass it `translationsFor`, a
function that returns the copy for a language or `undefined`, and
`detectedLanguage` to get the same language switching. Without
`translationsFor`, the transport serves its starting copy under whatever
language the kernel asks for.

## Custom

`custom(transport)` from `c15t` wraps your own `init` and `save`. This one
resolves the policy locally and records choices with your API:

```ts title="src/consent-runtime.ts"
import { createOfflineTransport, custom, policyRulePresets } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

// Resolve the policy in the browser and record choices with your own API.
const local = createOfflineTransport({
	policyRules: [policyRulePresets.europeOptIn()],
});

export const runtime = createConsentRuntime({
	mode: custom({
		init: local.init,
		async save(payload) {
			const response = await fetch('/api/consent', {
				body: JSON.stringify({
					choice: payload.choice,
					consents: payload.consents,
					subjectId: payload.subjectId,
				}),
				headers: { 'content-type': 'application/json' },
				method: 'POST',
			});
			return { ok: response.ok, subjectId: payload.subjectId };
		},
	}),
});
```

|Method|Receives|Returns|
|--|--|--|
|`init(context)`|`{ overrides, user }`|An init response with a `policyResolution`. Build it with `createOfflineTransport`, or return what a c15t backend returns.|
|`save(payload)`|The choice, the resulting permissions, the subject ID, the decision inputs and a `policySnapshotToken`|`{ ok, subjectId? }`. Return `ok: false` or throw to have the kernel keep and retry the payload.|
|`identify(user, subjectId)`|Optional.|Link a signed-in user.|
|`loadSubjectRecord(subjectId)`|Optional.|Stored records for a subject, applied without counting as a choice.|

Every method is optional; a missing one makes its command succeed without a
request. An `init` response without a valid `policyResolution` fails safely:
optional categories stay denied and no banner shows. `custom()` rejects v2
endpoint handlers such as `setConsent`.

## Check it works

1. With hosted mode, the Network tab shows one `/init` request per fresh
   visit and a `/subjects` request after a choice.
2. With a build-time manifest, it shows no `/manifest` request. With runtime
   manifest mode, it shows a `/manifest` request. Neither calls `/init`, unless
   the policy needs a country the page did not supply.
3. With offline mode, it shows no c15t request at all, and the choice survives
   a reload.

# Content Security Policy
URL: https://c15t.com/docs/frameworks/javascript/content-security-policy
Allow c15t in a JavaScript app under a Content Security Policy, covering backend requests, the stock UI's styles, nonces for vendor scripts and gated snippets, and embeds.

## What c15t needs from your policy

Your bundle contains c15t, so `script-src` already covers it. The rest:

|Directive|Allow|Why|
|--|--|--|
|`connect-src`|Your backend's origin, such as `https://your-project.inth.app`|`/init`, `/subjects`, and `/manifest` in manifest mode.|
|`script-src`|Each vendor's script origin, or a nonce|Scripts the script loader adds and gated `text/plain` tags it runs.|
|`style-src`|A nonce, or the origin of the CSS file your bundler emits|The stock UI's `<style>` element.|
|`frame-src`|Each embed's origin|Iframes the iframe blocker releases.|
|`img-src`, `connect-src`|Each vendor's collection endpoints|What vendor scripts send once they run.|

A missing `connect-src` entry stops the policy from resolving. The console
shows a CSP violation for `/init`, and no banner appears.

## Put a nonce on created scripts and styles

Pass the page's nonce once, to `init()` or `createConsentClient()` from
`@c15t/browser`. The script loader puts it on every `<script>` it creates, and
the stock UI puts it on its `<style>` element:

```ts
init({ mode: manifest(), scripts, nonce });
```

`createConsentRuntime` takes the same `nonce` option for the scripts it
loads. A script's own `nonce` wins over the configured one. Read the nonce from wherever
your server puts it, such as a `<meta>` tag or a data attribute. With
`'strict-dynamic'` in `script-src`, scripts that a trusted script creates are
allowed, so vendor origins need no entry. Some vendors then load more scripts
of their own, which `'strict-dynamic'` allows too.

With `nonce` set, `@c15t/browser` runs only the
`<script type="text/plain" data-c15t-category>` tags in your HTML that carry
the same nonce. c15t runs an inert tag by creating a new `<script>`, and
`'strict-dynamic'` lets scripts that trusted code creates run without a
nonce, so without this check injected markup would run once its category was
allowed. A tag without the nonce is skipped with a console warning and marked
`data-c15t-activated="untrusted"`. c15t never copies the nonce onto an inert
tag, so add it to every inert tag, including tags your code inserts later.
`activateGatedScripts(snapshot, root, { nonce })` applies the same check.

## Allow the stock UI's styles

The stock UI renders its CSS, theme tokens and `ui.css` into a `<style>`
element inside its shadow root. With the `nonce` option set, the element
carries the nonce, so `style-src 'nonce-…'` allows it without
`'unsafe-inline'`.

Without a per-response nonce, render into the page and import the stylesheet
from your bundle, which your bundler emits as a CSS file:

```ts
import '@c15t/browser/styles.css';

init({ mode: manifest(), ui: { shadow: false, styles: false } });
```

With `styles: false` and no `theme` or `css` option, c15t adds no `<style>`
element. Put token overrides in your own CSS. Under IAB, also import
`@c15t/browser/iab/styles.css`.

The headless entries, `createConsentRuntime` and the kernel add no styles.
The DevTools panel adds a `<style>` element, which is one more reason to keep
it out of production builds.

## Check it works

1. Send the policy as `Content-Security-Policy-Report-Only` and open the app
   with the console open.
2. The console shows no violation for `/init`, `/subjects` or the banner's
   styles. The banner renders styled.
3. Allow each category. Each vendor's scripts and requests load without a
   violation.
4. Switch to `Content-Security-Policy` and repeat.

# @c15t/browser options
URL: https://c15t.com/docs/frameworks/javascript/api/browser-options
Every option init() and createConsentClient() from @c15t/browser accept in a bundled JavaScript app, from the mode to scripts, blockers, callbacks, storage, presentation and the stock UI.

## Pass options to init

`init()` and `createConsentClient()` from `@c15t/browser`,
`@c15t/browser/headless` and `@c15t/browser/iab` take one options object:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

`mode` is required: a factory from `manifest()`, `hosted()`, `offline()` or
`custom()`, imported from the same entry. Every other option is optional. The
options are read when the client is created. To change
`ui`, call `mountUI()` again; to change anything else, dispose the client and
create a new one.

The mode-specific `@c15t/browser/hosted` and `@c15t/browser/offline` entries
accept the same UI, gating and lifecycle options. Their connection options
are restricted to their mode. The hosted entry requires a backend URL or a
hosted factory and rejects preset names; the offline entry rejects backend
and manifest options. See [mode-specific configuration](/docs/frameworks/javascript/api/browser#choose-a-bundle-for-one-mode).

## Connection and policy

The `init()` and `createConsentClient()` of the `@c15t/browser` ES module,
`@c15t/browser/headless` and `@c15t/browser/iab` take `mode` as a factory
and none of the connection options below it. The script-tag builds and the
`@c15t/browser/hosted` and `@c15t/browser/offline` entries take the rest of
the table: `c15t.js` and `@c15t/browser/hosted` accept hosted mode only and
require a backend URL or hosted factory, and `c15t.offline.js` and
`@c15t/browser/offline` accept offline mode only.

|Option|Type|Default|What it does|
|--|--|--|--|
|`mode`|A transport factory. Script-tag builds also take `'hosted'`, `'offline'` or `'manifest'`.|Required in the ES modules. Script-tag builds pick it from the other options.|A factory from `manifest()`, `hosted()`, `offline()` or `custom()` is used as is; see [consent modes](/docs/concepts/modes). In the script-tag builds, `manifest` when `manifest` or `manifestURL` is set, `hosted` when `backendURL` is set, otherwise `offline`. Hosted mode without `backendURL` throws.|
|`backendURL`|`string`|none|Script-tag builds, `/hosted` and `/offline` entries. Your Inth or self-hosted backend URL, for hosted and manifest modes. In the ES modules, pass it to the factory, such as `hosted({ backendURL })`.|
|`manifest`|`ConsentManifest`|none|Script-tag builds. The backend's policy manifest, inlined in the page, for manifest mode. In the ES modules, `manifest({ snapshot })`.|
|`manifestURL`|`string`|none|Script-tag builds. Where manifest mode fetches the manifest. A URL that ends in `/manifest` also gives the backend URL; any other URL needs `backendURL` too. In the ES modules, `manifest({ manifestURL })`.|
|`policyRules`|array of policy rules or preset names|recommended rules|Script-tag builds and the `/hosted` and `/offline` entries. Offline mode only. A preset name such as `'europeOptIn'` stands for that preset in `policyRulePresets`. An unknown name throws. In the ES modules, `offline({ policyRules })` with rule objects.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|The visitor's location, language or GPC signal, when the page knows it. Policy matching uses these instead of detection.|
|`prefetch`|kernel configuration|none|A server-resolved init answer. When it carries a resolved policy, the client renders from it and does not call `/init`.|
|`enabled`|`boolean`|`true`|`false` grants every category, shows no UI and loads every configured script at once.|

[Transports](/docs/frameworks/javascript/transports) compares the modes and
shows each with an example.

## Scripts, blockers and data

|Option|Type|Default|What it does|
|--|--|--|--|
|`scripts`|`Script[]`|`[]`|Vendor scripts to load once their category is allowed. Each entry needs `id`, `category`, and `src` or `textContent`.|
|`consentCategories`|category names|categories your scripts, iframes and rules use|The categories the preference dialog offers, within the policy's scope. `necessary` is always included.|
|`networkBlocker`|`{ rules, enabled?, logBlockedRequests?, onRequestBlocked? }` or `false`|off|Hold `fetch` and `XMLHttpRequest` calls that match a rule until the rule's category is allowed.|
|`iframeBlocker`|`{ disableAutomaticBlocking? }` or `false`|on|Gate iframes that carry `data-category` or `data-vendor`. `false` turns it off. With `disableAutomaticBlocking: true`, c15t checks iframes only when you call `processIframes()`.|
|`nonce`|`string`|none|Content Security Policy nonce for the stock UI's `<style>` element and every `<script>` the `scripts` option loads. A script's own `nonce` wins. With a nonce set, c15t runs only the `<script type="text/plain" data-c15t-category>` tags that carry the same `nonce`.|
|`scriptLoader`|`{ onDebug? }`|none|`onDebug` receives every script loader lifecycle event.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. The preference dialog lists a switch for each. They merge with vendors from the backend, `vendor` fields on scripts and rules, and `data-c15t-vendor` on gated tags.|
|`clearOnRevocation`|cookies and storage keys per category|off|Delete named cookies and storage keys when their category is denied. Read once, at start.|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reload the page after an accept, reject or save turns off a category that was allowed, once the save request finishes.|
|`callbacks`|`{ onChoiceRecorded?, onPermissionsChanged?, onError?, onBeforeConsentRevocationReload? }`|none|Functions c15t calls on consent events.|
|`storageConfig`|`{ storageKey?, crossSubdomain?, defaultDomain?, defaultExpiryDays? }`|key `c15t`, current host, 365 days|The name, domain and lifetime of the consent cookie and localStorage key.|
|`persistence`|`boolean` or `{ storageConfig?, skipHydration?, sync? }`|`true`|Read and write choices in the cookie and localStorage, and follow other tabs. `false` keeps choices in memory only. `{ sync: false }` stops following other tabs.|
|`user`|`{ externalId, identityProvider?, identityToken?, externalIdType?, properties? }`|none|An identified visitor, sent with consent records. [`identityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link. Links only a subject the next save creates; use `identify()` for an existing one.|
|`iab`|IAB options or `false`|none|CMP settings such as `cmpId` and `vendors`. Only the IAB build accepts it; the other builds throw when it is set.|

Each has a guide: [scripts](/docs/frameworks/javascript/scripts),
[iframe blocker](/docs/frameworks/javascript/modules/iframe-blocker),
[network blocker](/docs/frameworks/javascript/modules/network-blocker),
[clear on revocation](/docs/frameworks/javascript/clear-on-revocation)
and [callbacks](/docs/frameworks/javascript/callbacks).

## Presentation and copy

|Option|Type|Default|What it does|
|--|--|--|--|
|`ui`|UI options or `false`|stock UI on|Theme tokens, CSS, surfaces and mounting. `false` starts the client with no UI. See [UI options](#ui-options).|
|`presentation`|`{ prompt?, preferences? }`|floating banner, bottom left|Banner shape, position, button layout and blocking, within what the policy allows.|
|`i18n`|`{ locale?, messages }`|English|The language to start in, and messages per language that override the bundled, backend or manifest copy key by key for that language.|
|`legalLinks`|`{ privacyPolicy?, cookiePolicy?, termsOfService? }`|none|Each link is `{ href, label?, target?, rel? }`. The banner and dialog show only the links their `legalLinks` option lists.|

## UI options

These go under `ui`. The headless builds ignore them.

|Option|Type|Default|What it does|
|--|--|--|--|
|`theme`|theme tokens|none|Colors, radius, typography, spacing and motion. The same token object every c15t package takes.|
|`css`|`string`|none|CSS added after the bundled stylesheet, in the same root as the UI.|
|`colorScheme`|`'light'`, `'dark'` or `'system'`|`'system'`|Which token set to use. `system` follows the visitor's setting and updates when it changes.|
|`shadow`|`boolean`|`true`|Render inside a shadow root. `false` renders into the page, where your stylesheet applies.|
|`styles`|`boolean`|`true`|Include the bundled stylesheet. Set `false` with `shadow: false` when the page loads the stylesheet itself.|
|`noStyle`|`boolean`|`false`|Render markup with no c15t classes and no bundled stylesheet, for fully custom CSS. `theme` and `css` still apply.|
|`disableAnimation`|`boolean`|the visitor's reduced motion setting|Show and hide surfaces without transitions.|
|`container`|element or CSS selector|`document.body`|Where the UI host element is appended. A selector that matches nothing throws.|
|`banner`|`boolean` or banner options|`true`|`false` renders no banner. An object sets copy and behavior; see the banner options.|
|`dialog`|`boolean` or dialog options|`true`|`false` renders no preference dialog.|
|`trigger`|`boolean` or trigger options|`false`|Render the floating button that reopens the dialog.|
|`iab`|`{ loadErrorText?, saveErrorText?, moreVendorsText? }`|translated copy|Copy for the IAB vendor list states. IAB build only.|

## Banner options

These go under `ui.banner`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`title`|`string`|translated title|Heading. A notice uses the notice title by default.|
|`description`|`string`|translated description|Body text. A notice uses the notice description by default.|
|`acceptButtonText`|`string`|"Accept All"|Label of the accept button.|
|`rejectButtonText`|`string`|"Reject All"|Label of the reject button.|
|`customizeButtonText`|`string`|"Customize"|Label of the button that opens the dialog.|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description. `null` or `[]` shows none.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag. The IAB banner always keeps it.|
|`scrollLock`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|
|`trapFocus`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|

The dismiss button of a notice always uses the translated
`common.acknowledge` label. Change it through `i18n`.

## Dialog options

These go under `ui.dialog`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag at the bottom of the dialog.|

The dialog's title, description, category names and button labels come
from translations. Change them through `i18n`.

## Trigger options

`ui.trigger: true` shows the trigger with its defaults. An object sets these:

|Option|Type|Default|What it does|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner the button starts in.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`showWhen`|`'always'` or `'after-consent'`|`'always'`|`after-consent` hides the button until the visitor has answered the prompt.|
|`ariaLabel`|`string`|"Open privacy settings"|The button's accessible name. It has no visible text.|
|`persistPosition`|`boolean`|`true`|Remember the corner a visitor dragged the button to, in localStorage. A remembered corner wins over `position`.|

[Customize](/docs/frameworks/javascript/customize) shows these options at
work.

## Options the client passes to the runtime

`@c15t/browser` builds a [consent runtime](/docs/frameworks/javascript/api/runtime)
for you and passes every option in the tables above through, including
`nonce`, `persistence`, `scriptLoader` and `vendors`. Two runtime options have
no client equivalent. The `@c15t/browser/iab` entry supplies `createIAB`, and
the client turns `windowDebug` off so the runtime does not replace
`window.c15t`.

# createConsentRuntime
URL: https://c15t.com/docs/frameworks/javascript/api/runtime
Reference for createConsentRuntime from c15t/runtime, the framework-agnostic consent runtime behind every c15t adapter, with every option, what start and dispose do, and the runtime handle's methods.

## What the runtime owns

`createConsentRuntime` builds a [consent kernel](/docs/frameworks/javascript/api/kernel)
and connects the modules a page needs, such as stored choices, script
loading, iframe gating, network blocking, data clearing, IAB, callbacks and
the reload after a withdrawal. It renders nothing. Use it when you render your own UI, connect a
framework without a c15t adapter, or share one consent state between several
parts of a page. `@c15t/browser` builds one for you; see
[choose a headless API](/docs/frameworks/javascript/headless#choose-a-headless-api).

```ts title="src/consent-runtime.ts"
import { hosted } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

import { scripts } from './scripts';

// One runtime for the page: policy, stored choices, script loading,
// iframe blocking and the reload after a revocation.
export const runtime = createConsentRuntime({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});
```

Creating the runtime has no side effects. It reads no storage and sends no
request until `start()`, so the module can also load on a server.

## Options

Only `mode` is required.

|Option|Type|Default|What it does|
|--|--|--|--|
|`mode`|transport factory|required|Where the policy comes from and where choices go: `hosted()`, `offline()`, `manifest()` or `custom()`. `offline()` switches copy when the kernel's language changes. See [transports](/docs/frameworks/javascript/transports). Read once.|
|`scripts`|`Script[]`|none|Vendor scripts the loader mounts as categories are allowed. See [script loader](/docs/frameworks/javascript/modules/script-loader).|
|`consentCategories`|category names|inferred|Categories to offer alongside those your scripts, rules and vendors use, within the policy's scope.|
|`networkBlocker`|`{ rules, enabled?, logBlockedRequests?, onRequestBlocked? }` or `false`|off|Hold matching `fetch` and XHR requests until their category is allowed. See [network blocker](/docs/frameworks/javascript/modules/network-blocker).|
|`iframeBlocker`|`{ disableAutomaticBlocking? }` or `false`|on|Gate `<iframe data-src data-category>`. See [iframe blocker](/docs/frameworks/javascript/modules/iframe-blocker).|
|`clearOnRevocation`|cookies and storage keys per category|off|Delete named browser data when its category is denied. Read once. See [clear on revocation](/docs/frameworks/javascript/clear-on-revocation).|
|`persistence`|`boolean` or `{ storageConfig?, skipHydration?, sync? }`|`true`|Read and write choices in the cookie and localStorage, and follow other tabs. `false` keeps choices in memory only. See [persistence](/docs/frameworks/javascript/modules/persistence).|
|`storageConfig`|`{ storageKey?, crossSubdomain?, defaultDomain?, defaultExpiryDays? }`|key `c15t`, 365 days|Cookie and localStorage naming and lifetime.|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reload after an accept, reject or save turns off a category or vendor that was allowed, once the save request finishes.|
|`callbacks`|`{ onChoiceRecorded?, onPermissionsChanged?, onError?, onBeforeConsentRevocationReload? }`|none|See [callbacks](/docs/frameworks/javascript/callbacks).|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|Decision inputs the page knows.|
|`prefetch`|kernel configuration|none|A server-resolved init answer. With a resolved policy, `start()` skips the `/init` request. A prefetch marked `initialPolicyPending` is provisional, so `start()` still sends it.|
|`policyRules`|`PolicyRule[]`|none|Rules a local transport resolves.|
|`i18n`|`{ locale?, messages }`|English|Initial language, and messages that override the bundled or backend copy key by key for the same language. See [translations](/docs/frameworks/javascript/translations).|
|`presentation`|`{ prompt?, preferences? }`|none|Layout and blocking, for UIs that call `resolveConsentPresentation`.|
|`journey`|`'page'`, `'tab'` or `false`|`'page'`|Random id that links each `/init` to the save that follows. See [session reports](/docs/concepts/data-fetching#link-an-init-to-the-save-that-follows).|
|`user`|`{ externalId, identityProvider? }`|none|An identified visitor.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB.|
|`nonce`|`string`|none|CSP nonce the script loader puts on every `<script>` it creates. A script's own `nonce` wins.|
|`scriptLoader`|`{ onDebug? }`|none|Receive every script loader lifecycle event.|
|`iab`|IAB options or `false`|none|CMP settings. Needs `createIAB`.|
|`createIAB`|`createIAB` from `@c15t/iab`|none|The IAB module factory. Without it, `iab` is ignored.|
|`enabled`|`boolean`|`true`|`false` grants every category, skips init and mounts no blocker, persistence or IAB. Scripts load at once.|
|`windowDebug`|`boolean`|`true`|Install a small `window.c15t` object with `version`, `pkg`, `mode` and `hosting` on `start()`. `hosting` reads the current snapshot, so it changes from `null` once `/init` reports it.|
|`pkg`|`string`|`'@c15t/core'`|The package name `window.c15t` reports.|

## What start and dispose do

`runtime.start()` mounts, in order:

1. the `window.c15t` debug object, unless `windowDebug: false`;
2. persistence, which reads stored choices;
3. the `/init` request. With a resolved `prefetch` it adopts that answer
   instead: the choice is evaluated at the server's clock, the banner the
   server rendered counts as the first impression, a detected Global Privacy
   Control signal is honoured, and `init:applied` fires as it would for a
   response;
4. the script loader, when `scripts` is not empty;
5. the network blocker, when configured;
6. the iframe blocker, unless `iframeBlocker: false`;
7. the IAB module, when `iab` and `createIAB` are set;
8. data clearing, when `clearOnRevocation` is set.

`start()` does nothing without a `document`, so you can call it from shared
code. A second call does nothing. The callback bridge and the reload watcher
attach at construction, so they hear events from the first `start()`.

In a client-only app, with no server-rendered markup to hydrate, you can call
`start()` before the first render: the `/init` request then runs while the app
mounts, and nothing waits for it. With server-rendered markup, call it after
hydration so the first browser render matches the server's.

The network blocker and data clearing are opt-in, so they load as separate
chunks, and only when configured. Network blocker rules hold matching requests
from construction until the blocker has loaded and decides each one. Data
clearing waits for the policy anyway.

`runtime.dispose()` undoes everything in reverse, then disposes the kernel.
A runtime disposed before it started blocks the requests it was holding.

## Runtime handle

|Member|What it does|
|--|--|
|`kernel`|The kernel. Read and change consent through it.|
|`start()`, `dispose()`|Mount and unmount every browser side effect.|
|`started`|Whether `start()` has run and the runtime is not disposed.|
|`identify(user)`|Link the consent record to a user. Failures surface through `onError`, not a rejection.|
|`setOverrides(overrides)`|Merge into the country, region, language and GPC inputs. A key you pass replaces its value, `undefined` clears it, and a key you leave out stays.|
|`reinit()`|Run `/init` again, for example after `setOverrides`. Does nothing while disabled.|
|`setLanguage(code)`|Show the copy in another language. Does nothing for the current language; otherwise runs `/init` again, unless the runtime is disabled or uses `consentSource`.|
|`processIframes()`|Pause gated iframes that consent does not allow and restore the ones it allows. Needed only with `iframeBlocker: { disableAutomaticBlocking: true }`. Does nothing before `start()`, after `dispose()` or with `iframeBlocker: false`.|
|`reconcileStorage()`|Read stored records again and apply changes another runtime or tab made. Returns whether anything changed.|
|`clearRecords()`|Delete stored choices and reset the kernel's records: choice, notice dismissal, subject and vendor choice. Saves still queued for the cleared subject are dropped.|
|`consentCategories`|`necessary` plus the categories in the current choice scope, in the order the preference dialog lists them.|
|`setConsentCategories(categories)`|Replace the configured categories. Discovered ones stay. `undefined` drops the configured list.|
|`experiment`|The experiment the runtime runs: the one a ready `prefetch` carries, otherwise the `experiment` option. Resolve presentation and theme against it.|
|`iab`|The CMP handle under IAB, or `null`.|
|`subscribe(listener)`|Called when `iab` is mounted, replaced or removed; read it again in the listener. Returns an unsubscribe function. A provider runtime also calls it when `kernel` or `enabled` changes.|

## Runtime for a framework provider

`createConsentRuntime` is for a page that configures consent once. A framework
provider whose options follow its props uses
`createConsentProviderRuntime(options, modules)` instead. It has every member
above, plus:

|Member|What it does|
|--|--|
|`update(options)`|Apply the provider's new options. Pass the whole option set each time; the runtime compares it with the previous one and applies only what changed. Returns a promise that settles once every change has applied.|
|`setEnabled(enabled)`|Turn consent management off or on. Off renders a separate permissive kernel that grants every category and shows no UI; only the script loader runs, and no request waits for the network blocker. On renders the visitor's kernel again, with their records, and adopts the prefetch again. It runs `/init` instead when there is no prefetch, or when overrides or the language changed while it was off.|
|`enabled`|Whether consent management is on.|
|`kernel`|The kernel to render. It changes when `enabled` changes.|
|`subscribe(listener)`|Called when `kernel`, `iab` or `enabled` changes. Read them again in the listener. Returns an unsubscribe function.|

`update()` applies these options to a running runtime:

|Option|On change|
|--|--|
|`enabled`|Same as `setEnabled()`.|
|`user`|The new user is identified. The user the runtime was created with is sent with `/init` and every save, and is not identified separately.|
|`overrides`|The overrides are set and `/init` runs again. Key order does not count as a change. Before `start()` or while disabled, the next start sends `/init` instead of adopting the prefetch.|
|`consentCategories`|The configured categories are replaced.|
|`vendors`, `scripts`, network blocker `rules`|Vendors are declared again. Scripts go to the script loader, rules to the network blocker. A loader starts when scripts first appear.|
|`networkBlocker`|New `rules` and `enabled` apply; leaving `enabled` out turns the blocker on. Requests new rules match wait until the blocker has them, including while an on-demand blocker loads. `false` removes the blocker; options where there were none add one.|
|`iframeBlocker`|`false` removes the blocker. A new `disableAutomaticBlocking` rebuilds it.|
|`callbacks`, `reloadOnConsentRevoked`|Read when an event fires, so the latest values apply.|

`enabled`, `overrides` and `consentCategories` apply before `update()`
returns. The rest of the comparison loads with the first `update()` in which
some option is a new value. Calling `update()` with the option values the
runtime already has, as a mount-time effect does, downloads nothing. Those
changes apply once it has loaded, and the returned promise settles then. Until
the network blocker has new or wider rules, requests they match are held, the
way the runtime holds requests from construction until the blocker loads, so
none goes out unchecked.

`nonce`, `scriptLoader.onDebug` and the network blocker's `logBlockedRequests`
and `onRequestBlocked` are read when their module starts. Every other option is
read once. Storage counts among them: persistence keeps reading and writing
where it started, and data clearing keeps protecting that location. Outside
production, a change to `mode`, `i18n`, `experiment`, `persistence` or
`storageConfig` logs a warning; create a new runtime to change them.

`prefetch` may also be a promise, for example the result of a server helper
that a framework streams to the browser, when `modules` includes
`streamPrefetch` from `c15t/runtime`, or `lazyStreamPrefetch` from
`c15t/runtime/provider`, which loads that code only for a runtime whose prefetch
is a promise. Without either, a pending prefetch is ignored with a warning
outside production, and the runtime requests the policy itself. That keeps the
code out of providers that never stream. The runtime starts with a provisional
policy, so no consent surface shows, and its first `/init` waits for the
promise and applies the result instead of sending a request. A result without
a policy is applied as a baseline (records, location, language) and the
request is sent with those overrides. A rejected promise sends the request as
if there were no prefetch. Records cleared while the promise is pending stay
cleared. An experiment in a streamed result arrives too late to run.

`modules` decides how each module loads. Pass `defaultRuntimeModules` to load
them the way `createConsentRuntime` does. To keep a module out of the first
chunk, replace its factory with `lazyRuntimeModule(() => import(...))`: calls
made before the module has loaded are queued and replayed. A module that
fails to load stays inactive and, outside production, logs a warning. Keep
`watchRevocationReload` static, because it has to see the first save, and
prefer a static `createPersistence`, because a lazy one shows a returning
visitor the banner until it has loaded. When the script loader is lazy, data
clearing subscribes once it has loaded, so revocation callbacks still run before
browser data is removed. IAB mounts through the `mountIAB` module
(`mountRuntimeIAB`, included in `defaultRuntimeModules`); without it `iab` is
ignored.

`onDemandRuntimeModules` loads the script loader, the network blocker, data
clearing and a `consentSource` connection on demand, in chunks that import
nothing your first chunk has. The script loader and the network blocker share
one chunk, so a page with scripts and blocker rules downloads, or preloads, one
file. Spread it into `modules` next to the modules you import statically:

```ts
import { watchRevocationReload } from 'c15t';
import { createIframeBlocker } from 'c15t/modules/iframe-blocker';
import { createPersistence } from 'c15t/modules/persistence';
import { createWindowDebug } from 'c15t/modules/window-debug';
import { onDemandRuntimeModules } from 'c15t/runtime/on-demand';
import { createConsentProviderRuntime } from 'c15t/runtime/provider';

const runtime = createConsentProviderRuntime(options, {
	...onDemandRuntimeModules,
	createIframeBlocker,
	createPersistence,
	createWindowDebug,
	watchRevocationReload,
});
```

A page that configures none of those modules never downloads them. A page
with only scripts, or only blocker rules, downloads both. Consented scripts
mount, and matching requests stay held, until the shared chunk has loaded.
Optional categories stay denied until a `consentSource` connects. A module
whose chunk fails to load is tried again when the browser comes back online.
Until then a failed network blocker blocks every request its rules match
instead of holding it. A module you load yourself with `lazyRuntimeModule`
works the same way, but if it imports code your first chunk also uses,
bundlers that split shared code (Vite, esbuild) move that code into extra
chunks the first load then fetches.

Import from `c15t/runtime/provider` when your provider loads modules on
demand. It exports `createConsentProviderRuntime`, `lazyRuntimeModule` and
`lazyStreamPrefetch`, and none of the modules `defaultRuntimeModules` imports
statically. Some bundlers, esbuild among them, keep a module in the first chunk
when it is imported statically anywhere in the graph, even unused, and also
through `import()`.

`c15t/runtime/on-demand` exports `onDemandRuntimeModules`,
`createConsentRuntimeWith` and `mountRuntimeIAB`.
`createConsentRuntimeWith(options, modules)` is `createConsentRuntime` with the
modules you choose, for a page that configures once (a script tag, an Astro
page) and loads some modules on demand. The same lifecycle and handle apply.
The two entries are separate because esbuild emits a chunk for every
`import()` in the files it reaches, used or not. A provider that loads modules
through its own `import()` calls would get the on-demand chunks as well, plus
an extra chunk for each module both load, and a page that configures once
would get the provider runtime's update and streamed-prefetch chunks.

`c15t/runtime/on-demand-factories` exports each on-demand factory on its own:
`scriptLoaderOnDemand`, `networkBlockerOnDemand`, `clearOnRevocationOnDemand`
and `connectConsentSourceOnDemand`. `scriptLoaderOnDemand` and
`networkBlockerOnDemand` each load a chunk with only their module. Use them
when you import some of those modules statically and load the rest on demand.
Spreading `onDemandRuntimeModules` instead would load the module you import
statically a second time, in the shared chunk, and a bundler then moves that
module into a chunk of its own. The factories have their own entry because
esbuild emits a chunk for every `import()` in the files it reaches, used or
not, which would split the shared chunk apart:

```ts
import { watchRevocationReload } from 'c15t';
import { createIframeBlocker } from 'c15t/modules/iframe-blocker';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';
import { createWindowDebug } from 'c15t/modules/window-debug';
import { createConsentRuntimeWith } from 'c15t/runtime/on-demand';
import {
	clearOnRevocationOnDemand,
	connectConsentSourceOnDemand,
	networkBlockerOnDemand,
} from 'c15t/runtime/on-demand-factories';

const runtime = createConsentRuntimeWith(options, {
	connectConsentSource: connectConsentSourceOnDemand,
	createClearOnRevocation: clearOnRevocationOnDemand,
	createIframeBlocker,
	createNetworkBlocker: networkBlockerOnDemand,
	createPersistence,
	createScriptLoader,
	createWindowDebug,
	watchRevocationReload,
});
runtime.start();
```

## Other exports

|Export from `c15t/runtime`|What it does|
|--|--|
|`createLazyIABFactory(loader)`|Wrap a dynamic `import('@c15t/iab')` so the IAB code loads as a separate chunk when the runtime mounts IAB. Pass its `create` as `createIAB`.|
|`isIABConfigured(iab)`|Whether an `iab` option turns IAB on.|
|`wireRuntimeCallbacks({ kernel, callbacks })`|Attach the four callbacks to a kernel you own. Returns a disposer.|
|`createConsentProviderRuntime(options, modules)`|The runtime for a framework provider. See [runtime for a framework provider](#runtime-for-a-framework-provider).|
|`defaultRuntimeModules`|The module factories `createConsentRuntime` mounts.|
|`lazyRuntimeModule(load)`|Wrap a module factory so its module loads through a dynamic `import()` on first use.|
|`streamPrefetch`|Add to the provider runtime's modules to accept a `prefetch` promise.|
|`mountRuntimeIAB`|The `mountIAB` module: mounts the CMP once the kernel knows its `cmpId`.|

## Check it works

1. Create the runtime and subscribe to `runtime.kernel` before `start()`.
2. Call `start()` in the browser. The Network tab shows one `/init` request,
   and your subscriber receives a snapshot whose `resolution.status` is
   `matched`.
3. Call `runtime.kernel.commands.save('none')` from a button. A `/subjects`
   request follows and reloading keeps the choice.
4. Call `runtime.dispose()`. Scripts the loader added are removed.

# Kernel API
URL: https://c15t.com/docs/frameworks/javascript/api/kernel
Reference for the c15t consent kernel in JavaScript, covering how to get or create one, its snapshot and subscriptions, commands, setters, hydration, events and listener ordering.

## Get a kernel

The kernel holds consent state and runs commands. Every JavaScript setup has
one:

* `consent.kernel`, from `init()` in `@c15t/browser`.
* `runtime.kernel`, from `createConsentRuntime` in `c15t/runtime`.
* A kernel you create yourself, as shown [below](#create-a-kernel-yourself).

The kernel alone supplies state and commands. It renders nothing, loads no
script and reads no storage; the modules around it do that.

```ts
const unsubscribe = kernel.subscribe((snapshot) => {
	console.log(snapshot.resolution.status, snapshot.effectivePermissions);
});
```

This fragment assumes one of the kernels above. Keep `unsubscribe` and call it
during teardown.

## Read state

|Member|Returns|What it does|
|--|--|--|
|`getSnapshot()`|`ConsentSnapshot`|The current state, frozen. Cheap to call. See the [snapshot reference](/docs/frameworks/javascript/api/snapshot).|
|`subscribe(listener)`|`() => void`|Call `listener` with each new snapshot.|
|`getServerSnapshot()`|`ConsentSnapshot`|The first snapshot, as a server render saw it. Render from this during hydration, then switch to `getSnapshot()`.|
|`refresh(now?)`|`ConsentSnapshot`|Evaluate again at `now`, so an expired choice cannot linger behind a timer. Returns the new snapshot.|

A snapshot keeps the same object for a field whose value did not change, so
`previous.effectivePermissions === next.effectivePermissions` tells you
permissions did not change.

## Choose commands by intent

Commands are asynchronous and are the only way to record anything.

|Command|Returns|Effect|
|--|--|--|
|`commands.init()`|`Promise<{ ok, error? }>`|Resolve the policy through the transport. Failed attempts retry in the background.|
|`commands.save('all')`|`Promise<SaveResult>`|Record acceptance of every category in scope.|
|`commands.save('none')`|`Promise<SaveResult>`|Record rejection of every optional category in scope.|
|`commands.save({ marketing: false })`|`Promise<SaveResult>`|Record only the categories you name.|
|`commands.save()`|`Promise<SaveResult>`|Record the staged draft, falling back to the current choice or the policy's defaults for each category.|
|`commands.dismissNotice()`|`Promise<NoticeDismissResult>`|Record that the visitor saw a notice. Grants nothing. Only works while `promptRequirement.kind` is `notice`.|
|`commands.identify(user)`|`Promise<void>`|Link the record to `{ externalId, identityProvider?, identityToken? }` and load the server's record for that subject. The [token](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link.|

`save(input, context)` takes a second argument. `context.categories` narrows
`'all'`, `'none'` or an empty input to the categories your UI displays, which
is how `@c15t/browser` limits Accept All to the dialog's categories.
`context.vendors` records vendor-level grants.

A save updates permissions and notifies subscribers before the backend
request starts. `SaveResult.ok` reports the request. When it fails, the choice
stays in effect and the payload is queued for retry.
[Consent state](/docs/concepts/consent-state#when-a-choice-is-saved)
documents the ordering.

## Change inputs and UI state

`set` operations run synchronously and notify subscribers. None of them
records a choice.

|Setter|What it changes|
|--|--|
|`set.activeUI('banner' \|'dialog' \|'none')`|The surface your UI should show.|
|`set.draft(values)`|Staged category values that a no-argument `save()` confirms. Never a grant.|
|`set.overrides({ country, region, language, gpc })`|Decision inputs, merged into the current ones; `undefined` clears a key. Call `commands.init()` after it to resolve the policy again.|
|`set.language(code)`|The language override.|
|`set.privacySignals({ gpc })`|The detected GPC signal. c15t reads the browser's signal itself; use this to pass one detected elsewhere, such as a `Sec-GPC` request header.|
|`set.consentCategories(categories)`|The configured categories. Discovered categories stay.|
|`set.registerConsentCategories(categories)`|Add categories your integrations use. They stay for the kernel's lifetime.|
|`set.vendors(patch, options?)`|Merge declared vendors.|
|`set.subjectId(id)`|The subject ID.|
|`set.iab(patch)`|Written by the IAB module. Do not call it yourself.|

## Apply stored records

Pass validated records as `initialRecords` to `createConsentKernel()`, such
as a choice read from a cookie with `readStoredRecordsFromCookieHeader()`.
They apply without counting as a visitor action. In the browser,
[`createPersistence()`](/docs/frameworks/javascript/modules/persistence)
reads storage into the kernel on mount and keeps tabs in step afterwards.

## Events

`kernel.events.on(type, listener)` returns an unsubscribe function. Each
listener receives the event object.

|Event|Fields|When|
|--|--|--|
|`init:applied`|`snapshot`|A policy resolved, from the transport or a resolved prefetch.|
|`init:failed`|`error`, `attempt`, `nextRetryMs`|Initialization failed. `nextRetryMs` is `null` when no retry remains.|
|`choice:recorded`|`snapshot`, `confirmed`, `actionAt`|An accept, reject or save recorded categories.|
|`permissions:changed`|`snapshot`, `previous`|Effective permissions changed value, for any reason.|
|`notice:dismissed`|`snapshot`, `dismissal`|A notice was acknowledged.|
|`vendors:recorded`|`snapshot`, `actionAt`|A save changed which vendors are denied.|
|`vendors:set`|`snapshot`|The declared vendor list changed.|
|`overrides:set`|`snapshot`|Decision inputs changed.|
|`user:identified`|`snapshot`|`identify` linked a user.|
|`subject:resolved`|`snapshot`|A save received the server's subject ID.|
|`iab:set`|`snapshot`|The IAB state changed.|
|`records:cleared`|none|Stored records were cleared.|
|`save:replayed`|`subjectId`, `ok`, `rejected?`|A queued save was sent again. `rejected` holds the backend's refusal code.|
|`command:init:started`, `command:save:started`|none|A command began.|
|`command:init:completed`, `command:save:completed`|`result`|A command finished.|
|`command:error`|`command`, `error`|A command failed.|

Use `choice:recorded` to react to a visitor's decision and
`permissions:changed` to start and stop code. [Callbacks](/docs/frameworks/javascript/callbacks)
explains the difference.

## How listeners are notified

`kernel.subscribe()` and `kernel.events.on()` listeners run synchronously when
a change commits, in registration order. Each receives the frozen snapshot that
change produced.

* A listener that throws does not stop the listeners after it or fail the
  command that caused the change. In a browser page c15t passes the error to
  `reportError`. Everywhere else, including Bun and Deno servers where
  `reportError` would end the process, it logs the error with `console.error`.
* A listener can call commands and setters. Before the nested call returns,
  every other listener receives the change in progress and then the new one.
  No listener misses a change, such as a denial that another listener
  immediately reverses, or receives changes out of order.
* A listener added during a notification first receives the next change. A
  listener removed during a notification is not called again.
* Listeners that keep changing consent in response to each other are stopped
  after 100 nested notifications, and the error is reported. Notifications
  already queued still arrive, so other listeners end on the current snapshot.
  A listener that changes consent after that point is not called again.

## Create a kernel yourself

Most apps should use `createConsentRuntime` or `@c15t/browser`, which connect
the modules for you. Create the kernel directly only when you need to choose
every module:

```ts title="src/consent.ts"
import { createConsentKernel, createHostedTransport } from 'c15t';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';

import { scripts } from './scripts';

export const startConsentKernel = async function startConsentKernel(
	backendURL: string
) {
	const kernel = createConsentKernel({
		transport: createHostedTransport({ backendURL }),
	});
	// Each module is yours to create and dispose. This kernel has no iframe
	// blocker, network blocker, data clearing or reload after revocation.
	const persistence = createPersistence({ kernel });
	const loader = createScriptLoader({ kernel, scripts });
	await kernel.commands.init();
	return {
		dispose() {
			loader.dispose();
			persistence.dispose();
			kernel.dispose();
		},
		kernel,
	};
};
```

This kernel stores choices and loads scripts. It has no iframe blocker,
network blocker or data clearing, and it does not reload the page when a
visitor withdraws permission, so a vendor that already ran keeps running.
Add each one you need from its `c15t/modules/*` entry point, and dispose it
before the kernel:

|Module|Entry point|Page|
|--|--|--|
|Persistence|`c15t/modules/persistence`|[Persistence](/docs/frameworks/javascript/modules/persistence)|
|Script loader|`c15t/modules/script-loader`|[Script loader](/docs/frameworks/javascript/modules/script-loader)|
|Network blocker|`c15t/modules/network-blocker`|[Network blocker](/docs/frameworks/javascript/modules/network-blocker)|
|Iframe blocker|`c15t/modules/iframe-blocker`|[Iframe blocker](/docs/frameworks/javascript/modules/iframe-blocker)|
|Clear on revocation|`c15t/modules/clear-on-revocation`|[Clear on revocation](/docs/frameworks/javascript/clear-on-revocation)|
|Reload after withdrawal|`watchRevocationReload` from `c15t`|This page, below|

`watchRevocationReload({ kernel, isEnabled, getOnBeforeReload? })` reloads the
page after a save turns off something that was allowed. It returns a
disposer.

`createConsentKernel(config)` takes a `transport`, not a transport factory.
Use `createHostedTransport({ backendURL })` or `createOfflineTransport()`
from `c15t`, or your own object with `init` and `save`. Other useful config
fields:

|Field|What it does|
|--|--|
|`transport`|Carries `init`, `save`, `identify` and `loadSubjectRecord`. Without it, commands succeed and send nothing.|
|`consentCategories`|Categories to offer, within the policy's scope.|
|`initialOverrides`, `initialUser`|Decision inputs and an identified user at start.|
|`initialRecords`, `initialPolicyResolution`|Records and a policy a server already resolved.|
|`initialTranslations`|Copy to start with.|
|`translationOverrides`|Messages keyed by language, such as your `i18n.messages`. The kernel applies the entry for the active language over `initialTranslations` and over each init response, key by key.|
|`initRetry`|Retry for a failed `init`: `{ maxAttempts, baseDelayMs, maxDelayMs }`, or `false`. Defaults to 5 attempts from 1 second up to 30 seconds.|
|`now`|The evaluation clock at start, for a server render and its hydration to agree.|

Construction has no side effects, so a server can build a kernel and read its
snapshot.

## Check it works

1. Subscribe to the kernel and log `policyPending` and `resolution.status`.
   After `commands.init()`, `policyPending` is `false` and the status is
   `matched`.
2. Add an `events.on('choice:recorded', …)` listener. It logs once for each
   accept, reject or save, and not on reload.
3. Call `kernel.dispose()`. Background retries stop; `getSnapshot()` still
   works.

# Consent snapshot
URL: https://c15t.com/docs/frameworks/javascript/api/snapshot
Reference for every field of the c15t consent snapshot a JavaScript app reads from the kernel, @c15t/browser or createConsentRuntime, grouped by the question each field answers.

## Read a snapshot

`kernel.getSnapshot()`, `consent.getSnapshot()` from `@c15t/browser`, and
every `subscribe` listener give you the same frozen object. It describes the
visitor's permissions, what they recorded, the policy that applies and the
surface to show.

A field keeps the same object when its value did not change, so compare with
`===` to skip work:

```ts
let previous = kernel.getSnapshot();
kernel.subscribe((next) => {
	if (next.effectivePermissions !== previous.effectivePermissions) {
		updateGates(next.effectivePermissions);
	}
	previous = next;
});
```

`updateGates` stands for your own code.

## May this run now?

|Field|Type|What it holds|
|--|--|--|
|`effectivePermissions`|`Record<category, boolean>`|Whether each category is allowed now. Scripts, iframes and network rules follow this. Under an opt-out policy an optional category can be `true` before any choice.|
|`restrictions`|per category, a list of `'explicit-denial'`, `'strict-scope'` or `'gpc'`|Why a category is denied.|
|`privacySignals.gpc`|`{ detected, override, active }`|The browser's Global Privacy Control signal, a test override, and the one c15t honors.|
|`nextDeadline`|`number \|null`|The next time, in epoch milliseconds, when a choice or notice expires and permissions or the prompt can change.|

## What did the visitor decide?

|Field|Type|What it holds|
|--|--|--|
|`explicitChoice`|`{ version, categories } \|null`|The visitor's recorded decision per category, each with `value` and `confirmedAt`. Only accept, reject and save write it. `null` when they never chose.|
|`noticeDismissal`|`{ dismissedAt, fingerprint } \|null`|When the visitor acknowledged the current notice. Not a grant.|
|`vendorChoice`|`{ denied, confirmedAt } \|null`|Vendors the visitor turned off, outside IAB.|
|`subject`|`{ subjectId?, externalId?, identityProvider? } \|null`|The consent subject the backend knows.|

Read permissions to gate code and recorded choices to report decisions.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains why.

## What does the policy require?

|Field|Type|What it holds|
|--|--|--|
|`promptRequirement`|`{ kind: 'choice' \|'notice', reason } \|{ kind: 'none' }`|The interaction still owed. `reason` is `missing`, `expired` or `policy-changed`.|
|`resolution`|`{ status, policy }`|How the policy resolved: `matched`, `no-match`, `failed` or `unconfigured`. `policy` is set only when `matched`.|
|`policyPending`|`boolean`|`true` until the transport's first answer. The UI stays hidden while it is `true`.|
|`policyRule`|resolved rule|The rule c15t evaluates with: the matched rule, or a strict opt-in fallback. Has `id`, `model`, `prompt`, `scope`, `preselectedCategories`, `actions`, `rights` and `validity`.|
|`model`|`'opt-in' \|'opt-out' \|'iab' \|'none'`|The permission model in force.|
|`consentCategories`|category list or `null`|Categories configured or discovered on the page. `null` means the policy's full scope.|
|`evaluationPolicy`|object|The validated projection c15t evaluated. For DevTools and debugging.|

Check `resolution.status === 'matched'` before you trust `policyRule` as the
visitor's real policy. While the policy loads or after it fails, `policyRule`
is the strict fallback.

## What should the UI show?

|Field|Type|What it holds|
|--|--|--|
|`activeUI`|`'banner' \|'dialog' \|'none' \|null`|The surface to render. Derived from the prompt, and changed by `set.activeUI`.|
|`translations`|`{ language, translations } \|null`|The copy for the resolved language.|
|`branding`|`'c15t' \|'inth' \|'consent' \|null`|The brand for the "Secured by" tag.|
|`hosting`|`'inth' \|'self-hosted' \|null`|Who runs the backend, as `/init` reported it. Separate from `branding`. `null` before init, for `offline()` and `custom()` transports that do not send it, and for backends older than the field. Not verified.|

## Context and bookkeeping

|Field|What it holds|
|--|--|
|`overrides`|The country, region, language and GPC inputs you set.|
|`location`|The country and region the backend reported.|
|`user`|The identified user, if any.|
|`policySnapshotToken`|A signed token sent back with saves so the backend can check the policy.|
|`iab`|The IAB state under an IAB policy: vendor list, TC string and purpose and vendor choices. `null` otherwise.|
|`vendors`|Declared vendors, or `null`.|
|`revision`|A counter that increases on every change.|
|`evaluatedAt`|When the snapshot was last evaluated, in epoch milliseconds.|

## Check it works

1. Log `getSnapshot()` after `ready()` resolves. `resolution.status` is
   `matched`, `policyPending` is `false`, and `explicitChoice` is `null` for a
   new visitor.
2. Accept all and log it again. `explicitChoice.categories` has an entry per
   category and `promptRequirement.kind` is `none`.

# Script loader
URL: https://c15t.com/docs/frameworks/javascript/modules/script-loader
Reference for the c15t script loader in JavaScript, covering every Script field, lifecycle callbacks, updateScripts, disposal and createScriptLoader for a kernel you own.

## What the script loader does

The script loader adds a vendor's `<script>` to the page once the script's
category is allowed, and removes the element again when the visitor withdraws
it. `@c15t/browser` and `createConsentRuntime` create one from their `scripts`
option. Create one yourself only for a kernel you built with
`createConsentKernel`.

The [scripts guide](/docs/frameworks/javascript/scripts) shows where the list
goes in each setup. The helpers in `@c15t/integrations` return `Script` objects for
common vendors; each [integration guide](/docs/integrations/overview) covers
one.

## Script fields

|Field|Type|Default|What it does|
|--|--|--|--|
|`id`|`string`|required|A unique, stable name. The loader tracks the script by it.|
|`category`|category or condition|required|What must be allowed, such as `'measurement'` or `{ and: ['measurement', 'marketing'] }`.|
|`src`|`string`|none|The URL to load.|
|`resourceKey`|`string`|`id`|The DOM resource identity. Matching keys share one element within and across loaders, while each logical script keeps its callbacks and consent state. Use different keys for different resources under the same script ID.|
|`textContent`|`string`|none|Inline code to run instead of `src`.|
|`callbackOnly`|`boolean`|`false`|Add no element, run only the callbacks. For a vendor already on the page.|
|`alwaysLoad`|`boolean`|`false`|Load whatever the consent state, for tags that manage consent themselves through the vendor's API.|
|`observeConsentBeforeLoad`|`boolean`|`false`|Notify `onConsentChange` during initial denial and subsequent updates before the resource loads. Useful for integrations that coordinate a shared SDK.|
|`persistAfterConsentRevoked`|`boolean`|`false`|Keep the element after withdrawal instead of removing it.|
|`target`|`'head' \|'body'`|`'head'`|Where the element goes.|
|`async`, `defer`|`boolean`|none|Attributes on the created element.|
|`nonce`|`string`|the runtime's `nonce`|CSP nonce for this element.|
|`fetchPriority`|`'high' \|'low' \|'auto'`|none|Fetch priority hint.|
|`attributes`|`Record<string, string>`|none|Other attributes for the element.|
|`anonymizeId`|`boolean`|`true`|Give the element a random `id`, so content blockers cannot match it by name.|
|`vendor`|`string`|none|A vendor slug for vendor-level consent. The script also waits while the visitor has turned that vendor off.|
|`vendorId`, `iabPurposes`, `iabLegIntPurposes`, `iabSpecialFeatures`|IAB IDs|none|Under an IAB policy, the TC string decides instead of the category.|

## Lifecycle callbacks

Each callback receives `{ id, elementId, hasConsent, consents, element?, error?, vendor? }`.

|Callback|When it runs|
|--|--|
|`onBeforeLoad`|Before a load attempt. It can run again for the same script if consent changes before the load starts, so make it safe to repeat.|
|`onLoad`|After the script loaded. Use it for set-up that needs the vendor's code.|
|`onError`|When the script failed to load.|
|`onConsentChange`|Each time a loaded script's consent changes. With `observeConsentBeforeLoad`, also during initial denial and later changes before loading. Use it for a vendor's opt-out call when you turn off the reload.|
|`onDispose`|When the configuration is removed or the loader is disposed, including a script that never loaded.|

Withdrawal alone does not call `onDispose`. With the default reload, the page
reloads after withdrawal anyway; with `reloadOnConsentRevoked: false`, use
`onConsentChange` to stop the vendor.

When scripts share an element, each active registration receives its own
`onLoad` or `onError` callback. A registration that joins after c15t observed
completion receives that callback in a microtask, after its consent callback,
using its current callbacks and consent. Inline scripts share their deferred
completion too. Removing a registration cancels its pending callback. c15t does
not infer completion for elements added outside the loader.

Removing the original loader transfers ownership to a remaining loader. c15t
removes an element it created when the last loader releases it.

## Update the list

`loader.updateScripts(next)` replaces the configuration and reconciles at
once:

* A script with the same `id`, source, inline code and attributes keeps its
  element. New callback functions alone do not reload it.
* Changing the source, inline code or attributes starts a new load.
* A script that adds `onDispose` is tracked by object. Replacing the object
  disposes it and starts again, even with the same `id`. Keep such objects
  stable.
* A removed script releases its element. Shared external elements stay while
  another loader still uses them.

Updates requested from inside a callback run after the current pass; the
latest wins. A chain of callbacks that keeps changing consent or the list is
stopped after 100 passes, and the loader disposes itself.

`loader.getLoadedScriptIds()` lists the scripts currently loaded.

## Attach the loader to your own kernel

A kernel from `createConsentKernel` has no loader. This file creates one with
persistence, before initialization:

```ts title="src/consent.ts"
import { createConsentKernel, createHostedTransport } from 'c15t';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';

import { scripts } from './scripts';

export const startConsentKernel = async function startConsentKernel(
	backendURL: string
) {
	const kernel = createConsentKernel({
		transport: createHostedTransport({ backendURL }),
	});
	// Each module is yours to create and dispose. This kernel has no iframe
	// blocker, network blocker, data clearing or reload after revocation.
	const persistence = createPersistence({ kernel });
	const loader = createScriptLoader({ kernel, scripts });
	await kernel.commands.init();
	return {
		dispose() {
			loader.dispose();
			persistence.dispose();
			kernel.dispose();
		},
		kernel,
	};
};
```

`createScriptLoader({ kernel, scripts, nonce?, onDebug? })` returns the
handle. `onDebug` receives every lifecycle step, for logging. Dispose the
loader before the kernel. Do not attach a loader to a kernel that
`@c15t/browser` or `createConsentRuntime` owns; each already has one.

## Check it works

1. Filter the Network tab for the vendor's host. Nothing loads before a
   choice.
2. Allow the category. The vendor loads and `onLoad` runs. In the Elements
   panel, the script sits in `<head>` with a random `id`.
3. With `reloadOnConsentRevoked: false`, withdraw the category.
   `onConsentChange` runs with `hasConsent: false` and the element is gone.

# Persistence
URL: https://c15t.com/docs/frameworks/javascript/modules/persistence
How c15t stores consent choices in a JavaScript app, with the storage key, cookie domain and lifetime options, multi-tab sync, reconcile and clear, and createPersistence for your own kernel.

## Where choices are stored

The persistence module writes each recorded choice to a first-party cookie
and to localStorage, and reads them back when the page loads. The visitor's
choice survives reloads and later visits without a backend request.
`@c15t/browser` and `createConsentRuntime` run it by default.

|Stored item|Name, with the default key|
|--|--|
|Category choice|`c15t` cookie and localStorage key|
|Notice acknowledgement|`c15t-notice`|
|Vendor choice|`c15t-vendors`|
|Saves waiting to reach the backend|a separate localStorage queue|

The cookie is readable by your server, so a server-rendered page can see the
visitor's choice before any script runs.

## When records are read and written

Stored records are read synchronously when the module starts, so a
returning visitor's choice applies before the first banner renders.

The code that writes and reconciles records is a separate chunk. Once a
banner or dialog has been shown, it starts loading in browser idle time after
the page's `load` event. It also starts at the first write or reconciliation
if one comes sooner. A returning visitor who sees no prompt downloads it only
when something needs it. Until it has loaded:

* A save waits for its record to be stored before its backend request
  leaves, and before the save resolves. On the first save of a page load,
  this can add the time it takes to fetch the chunk.
* If the chunk fails to load, the save keeps waiting rather than count as
  stored. Its request does not leave, and a revocation reload does not run
  while storage still holds the old choice. c15t tries the chunk again after
  1, 4 and 16 seconds, and at every later save, focus or tab change.
* `reconcile()` returns `false` and runs when the chunk lands.

`clear()` needs no chunk. It removes every record from the cookie and
localStorage, stores the clear epoch and resets the kernel's records before
it returns, so reloading right after a clear cannot restore a cleared choice.

* `pagehide` cannot store anything. A page restored from the back/forward
  cache stores its pending records when the chunk lands. A page that unloads
  first loses them, along with the save request still waiting for them.

After the chunk has loaded, each write runs in the macrotask after the
visitor acts, and `pagehide` runs any write still waiting.

## Name, domain and lifetime

`storageConfig` sets where and how long records live:

|Option|Default|What it does|
|--|--|--|
|`storageKey`|`'c15t'`|The cookie and localStorage name. Other records use it as a prefix.|
|`crossSubdomain`|`false`|Set the cookie on the root domain, so `www.example.com` and `shop.example.com` share it.|
|`defaultDomain`|current host|An explicit cookie domain, such as `'.example.com'`. Wins over `crossSubdomain`.|
|`defaultExpiryDays`|`365`|Cookie lifetime in days. The policy's own validity still decides when a choice expires.|

Use the same `storageConfig` on every site that shares the cookie. Pass it to
`init()` or `createConsentRuntime`, or inside `persistence` for a runtime:

```ts
storageConfig: { crossSubdomain: true },
```

## Keep open tabs in step

Tabs on the same origin share localStorage, so a choice made in one tab
reaches the others at once through the `storage` event. A tab on another
subdomain that shares only the cookie gets no such event. It reads stored
records again when the page becomes visible or the window regains focus.

Call `runtime.reconcileStorage()` to read them at another moment, for
example after a response set the consent cookie. With `@c15t/browser`, call
`client.runtime.reconcileStorage()`. `persistence: { sync: false }` on the
runtime or the `@c15t/browser` client turns the automatic reads off.
[Keep open tabs in step](/docs/concepts/consent-state#keep-open-tabs-in-step)
explains the merge rules.

## Turn it off

`persistence: false` on `createConsentRuntime` or on `init()` from
`@c15t/browser` keeps choices in memory only.
Every page load starts without a choice, so the banner shows on every page.

## Attach it to your own kernel

A kernel from `createConsentKernel` stores nothing. Create the module before
`commands.init()` so stored choices apply first:

```ts title="src/consent.ts"
import { createConsentKernel, createHostedTransport } from 'c15t';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';

import { scripts } from './scripts';

export const startConsentKernel = async function startConsentKernel(
	backendURL: string
) {
	const kernel = createConsentKernel({
		transport: createHostedTransport({ backendURL }),
	});
	// Each module is yours to create and dispose. This kernel has no iframe
	// blocker, network blocker, data clearing or reload after revocation.
	const persistence = createPersistence({ kernel });
	const loader = createScriptLoader({ kernel, scripts });
	await kernel.commands.init();
	return {
		dispose() {
			loader.dispose();
			persistence.dispose();
			kernel.dispose();
		},
		kernel,
	};
};
```

`createPersistence({ kernel, storageConfig?, skipHydration?, sync? })`
returns:

|Member|What it does|
|--|--|
|`hydrate()`|Read storage again. Returns whether any record was found.|
|`reconcile()`|Merge records another tab or runtime stored. Returns whether anything changed.|
|`clear()`|Delete every c15t record and reset the kernel's records.|
|`dispose()`|Stop writing and remove the tab listeners. Stored records stay.|

`skipHydration: true` skips the first read, for a kernel a server already
seeded with the visitor's records.

## Check it works

1. Accept all and open DevTools, Application. A `c15t` cookie and a `c15t`
   localStorage entry exist.
2. Reload. The banner stays closed.
3. Open a second tab, reject all there and switch back. The first tab now
   shows the rejection.

# DevTools
URL: https://c15t.com/docs/frameworks/javascript/dev-tools
Mount the c15t DevTools panel in a JavaScript app to inspect consent, scripts, policy and events for @c15t/browser, a consent runtime or a kernel.

## Mount the panel with @c15t/browser

`@c15t/browser` includes the panel. Mount it against the client from `init()`,
behind your bundler's development flag:

```ts title="src/main.ts"
if (import.meta.env.DEV) {
	const { mountDevTools } = await import('@c15t/browser/devtools');
	mountDevTools(consent, { defaultTab: 'scripts' });
}
```

The panel reads the client's kernel and the categories its dialog offers.
`defaultTab` picks the first tab: `consents`, `scripts`, `location`, `policy`,
`iab`, `events` or `actions`. The Location tab changes the country, region,
language and GPC signal and runs the policy again, so you can check what a
visitor elsewhere gets.

## Open DevTools from the trigger

With `ui.trigger` on, the stock trigger shows a DevTools button next to its own
while the panel is mounted, and the panel hides its floating launcher, so one
control sits in the corner. The DevTools button sits at the end farthest from
the corner. The panel opens just past the trigger, aligned with its outer
edge, and follows it when a visitor drags the trigger to another corner.
`mountDevTools` and `mountConsentUI` can run in either order.

The trigger hides while the banner or the dialog is open. The panel then shows
its own launcher in its `position` corner until the trigger returns.
`destroy()` on the panel turns the trigger back into a single button. A panel
mounted with `embedded: true` keeps the trigger as it is.

## Mount the panel with a runtime or kernel

For [`createConsentRuntime`](/docs/frameworks/javascript/headless) or a kernel
you created yourself, install the panel on its own:

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha @c15t/dev-tools@alpha`|
|pnpm|`pnpm add c15t@alpha @c15t/dev-tools@alpha`|
|yarn|`yarn add c15t@alpha @c15t/dev-tools@alpha`|
|bun|`bun add c15t@alpha @c15t/dev-tools@alpha`|

Pass the same kernel your consent UI and script loader use:

```ts title="src/consent-ui.ts"
if (import.meta.env.DEV) {
	const { createDevTools } = await import('@c15t/dev-tools');
	const tools = createDevTools({ kernel });
	import.meta.hot?.dispose(() => tools.destroy());
}
```

`kernel` is `runtime.kernel`. Pass `getConsentCategories` with the categories
your UI displays if they differ from the policy's. Call `tools.destroy()` from
your app's teardown; the example uses Vite's hot-module disposal. Destroying
the panel does not dispose the kernel or change consent.

To host the panel inside another devtools UI, pass that UI's element as
`container` and set `embedded: true`. The panel then fills the container,
starts open, and hides its launcher, header and close button. The container can
belong to a same-origin iframe; the panel still inspects the page that owns the
kernel.

## Keep it out of production

`import.meta.env.DEV` is Vite's development flag. Webpack and other bundlers
replace `process.env.NODE_ENV` instead; neither is a standard browser global.
The dynamic import behind the flag keeps the panel out of your production
bundle. The panel shows internal state, so never ship it to visitors.

The CLI's plain JavaScript scaffold adds an unconditional `createDevTools` call
when you opt in. Move it behind your development flag before you ship.

## Inspect scripts and IAB

The Scripts tab reads loaders registered with the supplied kernel. It shows
blocked, loading, loaded, failed, and retained scripts. The separate page scan
shows DOM resources, not proof that they loaded successfully or passed a
consent gate.

The IAB tab uses the IAB module already attached to that kernel. Vendor,
purpose, legitimate-interest, and special-feature editing becomes available
under an IAB policy after the module and vendor list initialize. DevTools does
not initialize a second CMP. Toggles change live choices; Save IAB consent
generates the TC string and runs the configured save transport.

# Troubleshooting
URL: https://c15t.com/docs/frameworks/javascript/troubleshooting
Diagnose vendor scripts that run early, unexpected reloads, empty custom banners, CORS errors, duplicate consent owners and policy resolution in a JavaScript app that uses @c15t/browser or c15t/runtime.

## Why do scripts load twice or before consent?

**Check.** Each vendor needs one owner. Look for a snippet left in
`index.html`, a second `init()` call, or a script loader attached to a kernel
that `@c15t/browser` or `createConsentRuntime` already owns. Each of these loads
vendors outside the consent gate or twice.

**Fix.** Call `init()` or create the runtime once per page, in the browser
entry point, and pass every vendor through its `scripts` list.

## Why does the page reload when a visitor saves?

**Check.** Did the visitor turn off a category they had allowed?
`@c15t/browser` and `createConsentRuntime` reload the page then, because code
that already ran cannot be unloaded. Allowing categories never reloads.

**Fix.** To handle withdrawal yourself, pass `reloadOnConsentRevoked: false`,
and stop each vendor with its own opt-out call. See
[scripts](/docs/frameworks/javascript/scripts#when-a-visitor-withdraws-permission).

## Why is my custom banner empty?

**Check.** Confirm that you subscribed before calling `runtime.start()`, that
you wait for `resolution.status` to be `'matched'`, and that you render
`promptRequirement.kind` `'notice'` as well as `'choice'`.

**Fix.** Render the headless UI from the snapshot, not from assumptions.
[Headless](/docs/frameworks/javascript/headless#what-your-ui-must-handle) lists
what a custom UI must cover.

## Why does the build fail to download the manifest?

**Check.** `vite build` stops with an error from `consentManifest` that
starts with the plugin's name, such as
`@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite`
for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps
going. The part in parentheses names the cause:

|Message|Cause|Fix|
|--|--|--|
|`fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error|The build cannot reach the backend|Build where the backend is reachable|
|`no response within 10 seconds`|The backend did not answer in time|Check the backend, or build where it is reachable|
|`/manifest responded 404`|The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix|Copy the backend URL exactly as Inth shows it, or set `VITE_C15T_BACKEND_URL`|
|`/manifest returned an invalid consent manifest.`|The URL answered with something other than a consent manifest, such as an HTML page|Point `backendURL` at the backend itself, not your site or a dashboard page|

A failed download never reuses an old snapshot. To deploy while the backend
is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
`undefined`, and the browser fetches the policy from the backend at runtime.

Only a build that uses `manifest()` downloads the manifest. The plugin
fetches after Vite has dropped the code the app does not use, so a `hosted()`
or `offline()` build never contacts the backend and never fails this way.

An error or warning that says `no backend URL is set` means the plugin found
no `backendURL` option and no variable. Set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass the absolute backend URL from your Inth
project. The [troubleshooting guide](/docs/guides/troubleshooting#why-does-the-build-fail-to-download-the-manifest)
lists every message.

A notice that the build `skipped the consent manifest fetch` means the backend
URL is relative, such as `/api/c15t`. Pass the absolute backend URL instead.
With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL`.

## Why is snapshot undefined?

**Check.** `snapshot` from `c15t/generated` is `undefined`, and the browser
requests `${backendURL}/manifest` on page load.

**Fix.** `snapshot` is `undefined` when Vite has no policy to serve:

* `consentManifest` is missing from `plugins` in `vite.config.ts`. Without the
  plugin, `c15t/generated` still resolves, but exports `undefined`.
* The fetch failed in `vite dev`, or in a build with
  `C15T_ON_BUILD_ERROR=runtime`. The terminal shows a `could not fetch the consent manifest` warning.
* The backend URL is relative, so the plugin skipped the fetch.
* `consentManifest({ source: 'runtime' })` is set, so the plugin never
  fetches.

Fix the cause, then restart `vite dev` or rebuild. The plugin fetches once
when Vite starts.

## Why does /init fail with a CORS or CSP error?

**Check.** A CORS error means the backend does not trust your app's origin.

**Fix.** Add the exact origin, including the port in development, to your Inth
project's trusted origins.

**Check.** A CSP error means your policy's `connect-src` lacks the backend's
origin.

**Fix.** Add the backend's origin to `connect-src`. See
[Content Security Policy](/docs/frameworks/javascript/content-security-policy).

## Why does a gated script in my HTML never run?

**Check.** With the `nonce` option set, `@c15t/browser` runs only
`<script type="text/plain" data-c15t-category>` tags that carry the same
nonce. Open the console and look for a warning that c15t skipped a
`data-c15t-category` script, and check the tag for
`data-c15t-activated="untrusted"`.

**Fix.** Add the page's nonce to the tag, including tags your code inserts
later. See
[Content Security Policy](/docs/frameworks/javascript/content-security-policy).

## Why is the stock banner unstyled?

**Check.** Look at your Content Security Policy's `style-src`. If it does not
allow the `<style>` element the stock UI adds, the policy blocks it.

**Fix.** Pass the nonce from your `style-src` as the `nonce` option, or import
`@c15t/browser/styles.css` with `ui: { shadow: false, styles: false }` as
[Content Security Policy](/docs/frameworks/javascript/content-security-policy#allow-the-stock-uis-styles)
describes.

## Why does a fetch return status 451?

**Check.** A [network blocker](/docs/frameworks/javascript/modules/network-blocker)
rule matched the request and its category is not allowed. The console logs
`[c15t] blocked` with the rule's ID.

**Fix.** If the request should not match, check the rule's `domain` and
`pathIncludes`.

## Inspect the active policy

Call this helper with your kernel: `consent.kernel` from `@c15t/browser`,
`runtime.kernel` from `createConsentRuntime`, or one you created. It logs the
current state and later changes without recording a choice.

```ts title="src/observe-consent-policy.ts"
import type { ConsentKernel } from 'c15t';

export function observeConsentPolicy(kernel: ConsentKernel) {
	const report = () => {
		const snapshot = kernel.getSnapshot();
		const resolution = snapshot.resolution;

		console.log({
			status: resolution.status,
			policy: resolution.status === 'matched' ? resolution.policy.id : null,
			prompt: snapshot.promptRequirement,
			permissions: snapshot.effectivePermissions,
			location: snapshot.location,
			privacySignals: snapshot.privacySignals,
		});
	};

	report();
	return kernel.subscribe(report);
}
```

The helper returns an unsubscribe function. Call it when you remove the
diagnostic or dispose the app. Production gates should read
`kernel.getSnapshot().effectivePermissions` at the point where an optional
feature would run.

## More help

[Troubleshoot consent](/docs/guides/troubleshooting) covers problems shared by
every framework, such as a missing banner, analytics that load before a choice,
imports that fail because npm installed c15t v2, choices that disappear on
reload, server HTML that differs from the browser, static builds that fail and
content blockers that hide the consent UI.

# Integrations
URL: https://c15t.com/docs/integrations/overview
Find all c15t integrations for analytics, tag managers, advertising, email and SMS, chat and embedded content.

## Choose an integration

Each vendor helper in `@c15t/integrations` returns a script configuration that you
register with your c15t provider. Importing a helper installs nothing on its
own. Set up consent with your [framework quickstart](/docs/frameworks) first,
then follow the vendor guide.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

`@c15t/integrations` is a separate package. Keep importing c15t itself from `c15t`,
for example `c15t/react` or `c15t/next`.

The Loading behavior column shows when each helper requests the vendor. Most
wait for the category to be allowed. A few load on every page and pass the
permission to the vendor's own consent API, so the browser contacts the vendor
before a choice.

## Embeds

|Integration|v3 implementation|Loading behavior|
|--|--|--|
|[Google Maps](/docs/integrations/google-maps)|Framework-specific consent-gated map iframe|Iframe mounts only while the chosen permission is allowed|
|[YouTube](/docs/integrations/youtube)|Framework-specific consent-gated video iframe|Iframe mounts only while the chosen permission is allowed|

Both guides include all nine framework examples. React and Svelte use `ConsentGate`;
Vue conditionally renders the iframe, and Astro and JavaScript use the existing
kernel to control its DOM lifecycle. Embeds do not require `@c15t/integrations`.

## Tag managers

|Integration|Helper|Category|Loading behavior|
|--|--|--|--|
|[Cloudflare Zaraz](/docs/integrations/cloudflare-zaraz)|`cloudflareZaraz`|`necessary`|Always runs; syncs purposes, Zaraz runs the tools|
|[Google Tag Manager](/docs/integrations/google-tag-manager)|`googleTagManager`|`necessary`; `measurement` or `marketing` when gated|Always loads and signals Google consent by default; `loadMode: 'after-consent'` waits for permission|

## Analytics

|Integration|Helper|Category|Loading behavior|
|--|--|--|--|
|[Google Tag](/docs/integrations/google-tag)|`gtag`|`measurement` or `marketing`|Always loads and signals Google consent by default; `loadMode: 'after-consent'` waits for permission|
|[Ahrefs Analytics](/docs/integrations/ahrefs-analytics)|`ahrefsAnalytics`|`measurement`|Waits for effective permission|
|[Adobe Analytics](/docs/integrations/adobe-analytics)|`adobeAnalytics`|`measurement`|Waits for effective permission|
|[Amplitude](/docs/integrations/amplitude)|`amplitude`|`measurement`|Waits for effective permission; opts the SDK out on revocation|
|[Cloudflare Web Analytics](/docs/integrations/cloudflare-web-analytics)|`cloudflareWebAnalytics`|`measurement`|Waits for effective permission|
|[Clearbit](/docs/integrations/clearbit)|`clearbit`|`marketing`|Waits for effective permission|
|[Microsoft Clarity](/docs/integrations/microsoft-clarity)|`clarity`|`measurement`|Gated initially; keeps the SDK and signals storage consent|
|[Databuddy](/docs/integrations/databuddy)|`databuddy`|`measurement`|Always loads; switches the SDK's disabled flag|
|[Fathom Analytics](/docs/integrations/fathom-analytics)|`fathomAnalytics`|`measurement`|Waits for effective permission|
|[Heap](/docs/integrations/heap)|`heap`|`measurement`|Waits for effective permission|
|[Matomo Analytics](/docs/integrations/matomo-analytics)|`matomoAnalytics`|`measurement`|Gated by default; optional consent mode|
|[Mixpanel](/docs/integrations/mixpanel-analytics)|`mixpanelAnalytics`|`measurement`|Always loads; calls opt-in and opt-out APIs|
|[OneDollarStats](/docs/integrations/one-dollar-stats)|`oneDollarStats`|`measurement`|Waits for effective permission|
|[Hotjar](/docs/integrations/hotjar)|`hotjar`|`measurement`|Waits for effective permission|
|[Hightouch](/docs/integrations/hightouch)|`hightouch`|`measurement`|Waits for effective permission|
|[LogRocket](/docs/integrations/logrocket)|`logRocket`|`measurement`|Waits for effective permission|
|[Plausible Analytics](/docs/integrations/plausible-analytics)|`plausibleAnalytics`|`measurement`|Waits for effective permission|
|[PostHog](/docs/integrations/posthog)|`posthog`|`measurement`|Configurable; defaults to always loading and calling opt-in and opt-out APIs|
|[Promptwatch](/docs/integrations/promptwatch)|`promptwatch`|`measurement`|Waits for effective permission|
|[Pirsch](/docs/integrations/pirsch)|`pirsch`|`measurement`|Waits for effective permission|
|[RudderStack](/docs/integrations/rudderstack)|`rudderstack`|`measurement`|Gated by default; optional destination consent mode|
|[Segment](/docs/integrations/segment)|`segment`|`measurement`|Waits for effective permission|
|[Sentry](/docs/integrations/sentry)|`sentry`|`necessary`; Replay and user data `measurement`|Configurable; defaults to always loading and loads Replay after permission|
|[Rybbit Analytics](/docs/integrations/rybbit-analytics)|`rybbitAnalytics`|`measurement`|Waits for effective permission|
|[Umami Analytics](/docs/integrations/umami-analytics)|`umamiAnalytics`|`measurement`|Waits for effective permission|
|[Vercel Analytics](/docs/integrations/vercel-analytics)|`vercelAnalytics`|`measurement`|Waits for effective permission|

## Chat and support

|Integration|Helper|Category|Loading behavior|
|--|--|--|--|
|[Crisp](/docs/integrations/crisp)|`crisp`|`functionality`|Waits for effective permission|
|[Front Chat](/docs/integrations/front-chat)|`frontChat`|`functionality`|Waits for effective permission|
|[Intercom](/docs/integrations/intercom)|`intercom`|`functionality`|Waits for effective permission|

## Email and SMS

|Integration|Helper|Category|Loading behavior|
|--|--|--|--|
|[Klaviyo](/docs/integrations/klaviyo)|`klaviyo`|`marketing` and `measurement`|Waits for both; optional forms-only mode needs `marketing`|

## Ads and pixels

|Integration|Helper|Category|Loading behavior|
|--|--|--|--|
|[Meta Pixel](/docs/integrations/meta-pixel)|`metaPixel`|`marketing`|Gated initially; keeps the SDK and signals consent|
|[OpenAI Pixel](/docs/integrations/openai-pixel)|`openaiPixel`|`marketing`|Gated initially; keeps the SDK and signals consent|
|[Pinterest Tag](/docs/integrations/pinterest-tag)|`pinterestTag`|`marketing`|Gated initially; keeps the tag and signals consent|
|[Reddit Pixel](/docs/integrations/reddit-pixel)|`redditPixel`|`marketing`|Gated initially; keeps the pixel and toggles first-party cookies|
|[TikTok Pixel](/docs/integrations/tiktok-pixel)|`tiktokPixel`|`marketing`|Gated initially; keeps the SDK and signals consent|
|[LinkedIn Insight Tag](/docs/integrations/linkedin-insights)|`linkedinInsights`|`marketing`|Waits for effective permission|
|[Microsoft UET](/docs/integrations/microsoft-uet)|`microsoftUet`|`marketing`|Always loads; signals ad storage consent|
|[Snapchat Pixel](/docs/integrations/snapchat-pixel)|`snapchatPixel`|`marketing`|Waits for effective permission|
|[X Pixel](/docs/integrations/x-pixel)|`xPixel`|`marketing`|Waits for effective permission|

## Load each vendor once

Remove the vendor's own snippet, tracking image, framework plugin or tag
manager entry before adding its helper. c15t cannot gate a copy it did not
load. Tag managers and data pipelines such as Segment can load further
destinations, which need consent settings of their own.

Framework packages are loaders too. To move their vendors to c15t, see
[migrate from `@next/third-parties`](/docs/frameworks/next/scripts#migrate-from-nextthird-parties)
for Next.js, and
[migrate from `@nuxt/scripts`](/docs/frameworks/nuxt/scripts#migrate-from-nuxtscripts)
or [migrate from `nuxt-gtag`](/docs/frameworks/nuxt/scripts#migrate-from-nuxt-gtag)
for Nuxt.

When a visitor turns off a category they had allowed, c15t reloads the page so
that code which already ran stops. Each vendor guide lists what its helper does
on revocation and how to check it.

## Vendor switches and cookie cleanup

Every helper sets a `vendor` slug, so once you declare that vendor a visitor
can allow its category and still switch the vendor off. Gating also leaves
behind the cookies a vendor already wrote; `clearOnRevocation` deletes them
when their category is denied. Each framework documents both in its Scripts
and embeds group:

|Framework|Vendor consent|Clear on revocation|
|--|--|--|
|Next.js|[Vendor consent](/docs/frameworks/next/vendor-consent)|[Clear on revocation](/docs/frameworks/next/clear-on-revocation)|
|TanStack Start|[Vendor consent](/docs/frameworks/tanstack-start/vendor-consent)|[Clear on revocation](/docs/frameworks/tanstack-start/clear-on-revocation)|
|React|[Vendor consent](/docs/frameworks/react/vendor-consent)|[Clear on revocation](/docs/frameworks/react/clear-on-revocation)|
|Nuxt|[Vendor consent](/docs/frameworks/nuxt/vendor-consent)|[Clear on revocation](/docs/frameworks/nuxt/clear-on-revocation)|
|Vue|[Vendor consent](/docs/frameworks/vue/vendor-consent)|[Clear on revocation](/docs/frameworks/vue/clear-on-revocation)|
|Astro|[Vendor consent](/docs/frameworks/astro/vendor-consent)|[Clear on revocation](/docs/frameworks/astro/clear-on-revocation)|
|Svelte|[Vendor consent](/docs/frameworks/svelte/vendor-consent)|[Clear on revocation](/docs/frameworks/svelte/clear-on-revocation)|
|SvelteKit|[Vendor consent](/docs/frameworks/sveltekit/vendor-consent)|[Clear on revocation](/docs/frameworks/sveltekit/clear-on-revocation)|
|HTML|[Vendor consent](/docs/frameworks/html/vendor-consent)|[Clear on revocation](/docs/frameworks/html/clear-on-revocation)|
|JavaScript|[Vendor consent](/docs/frameworks/javascript/vendor-consent)|[Clear on revocation](/docs/frameworks/javascript/clear-on-revocation)|

## Send events only to allowed integrations

`createEventDispatcher` from `@c15t/integrations/events` sends one named event to
every registered integration that has an event API and is allowed right now.
It drops events while measurement is denied, and one vendor's error does not
stop delivery to the others:

```ts
import { createEventDispatcher } from '@c15t/integrations/events';

const events = createEventDispatcher({
	scripts,
	getSnapshot: () => runtime.kernel.getSnapshot(),
	pageviews: ['segment'],
});

events.track('docs_search', { resultCount: 4 });
events.pageview(location.pathname);
```

Pass the same `scripts` you registered and a function that returns the live
consent snapshot. `track` supports Google Tag Manager, Google Tag, PostHog,
Mixpanel, Segment, Hightouch, Heap, Amplitude, LogRocket, Adobe Analytics,
Databuddy, Plausible, Fathom, Pirsch, Microsoft Clarity, Hotjar, Vercel
Analytics, OneDollarStats, Umami, Rybbit, RudderStack and Matomo.
`pageview` sends single-page-app page views only to the integrations named in
`pageviews`: PostHog, Segment or Hightouch. Call it from your router's
navigation hook. The first call records the path without sending, and repeated
paths or hash-only changes are skipped.

## Add a vendor without a helper

Use [custom integrations](/docs/integrations/building-integrations) for a
vendor without a helper, or an SDK your app already loads. Test every
integration with the [consent verification guide](/docs/guides/verify-consent).

# Custom integrations
URL: https://c15t.com/docs/integrations/building-integrations
Gate a vendor that has no @c15t/integrations helper, or sync consent with an SDK your app already loads, using a c15t script configuration.

## Define a script

Check the [integration list](/docs/integrations/overview) first. For a vendor
without a helper, write a script configuration with a stable `id`, a category
and the source URL, then register it like any helper:

```ts title="src/consent-scripts.ts"
import type { Script } from 'c15t';

const exampleAnalytics: Script = {
	id: 'example-analytics',
	category: 'measurement',
	src: 'https://analytics.example.com/sdk.js',
	onLoad() {
		// Initialize the vendor here with its documented API.
	},
	onError({ error }) {
		console.error('Analytics SDK failed to load', error);
	},
};

export const scripts = [exampleAnalytics];
```

Replace the URL and the `onLoad` body with the vendor's own setup. c15t adds the
`<script>` element only while measurement is allowed. To register `scripts`
with your framework, follow any vendor guide, for example
[Ahrefs Analytics](/docs/integrations/ahrefs-analytics).

## Script fields

|Field|Default|Behavior|
|--|--|--|
|`id`|Required|Stable identifier. c15t tracks the script by it across renders.|
|`category`|Required|A category name, or a condition such as `{ or: ['measurement', 'marketing'] }`, `{ and: [...] }` or `{ not: '...' }`.|
|`src` / `textContent`|None|Set exactly one, unless `callbackOnly` is `true`.|
|`vendor`|None|Vendor slug, so a visitor can turn this vendor off inside an allowed category.|
|`callbackOnly`|`false`|Run callbacks without adding a script element.|
|`alwaysLoad`|`false`|Load regardless of permission.|
|`persistAfterConsentRevoked`|`false`|Keep the script element when permission is revoked.|
|`onBeforeLoad`, `onLoad`, `onError`|None|Run before the element is added, after it loads, and if it fails.|
|`onConsentChange`|None|Runs when permissions change after the script has loaded, and when it is removed.|
|`onDispose`|None|Runs when this configuration is removed or its loader is disposed. Revocation alone does not call it.|
|`target`|`'head'`|`'head'` or `'body'`.|
|`async`, `defer`, `attributes`, `fetchPriority`|None|Copied to the script element.|
|`nonce`|The provider's `nonce`|Content Security Policy nonce for this element.|
|`anonymizeId`|`true`|Use a random element ID. Set `false` for `c15t-script-<id>`.|

Every callback receives `{ id, elementId, hasConsent, consents }`, plus
`vendor` when the script declares one, and `element` for scripts with an
element.

## Load before consent and signal the vendor

Use `alwaysLoad` only for an SDK that has its own consent API, such as a
Consent Mode tag. The script loads on every page and c15t never removes it on
a permission change. `hasConsent` in each callback still reports the real
permission, so pass it to the SDK:

```ts
const consentModeTag = {
	id: 'example-consent-mode',
	category: 'marketing',
	src: 'https://tags.example.com/tag.js',
	alwaysLoad: true,
	onBeforeLoad({ hasConsent }) {
		window.exampleTag = window.exampleTag ?? [];
		window.exampleTag.push(['consent', hasConsent ? 'grant' : 'deny']);
	},
	onConsentChange({ hasConsent }) {
		window.exampleTag?.push(['consent', hasConsent ? 'grant' : 'deny']);
	},
};
```

`window.exampleTag` stands for the vendor's own queue. An `alwaysLoad` script
makes requests before any choice, so it does not meet a requirement of no
vendor request before consent.

## Keep a loaded SDK and switch it off

`persistAfterConsentRevoked: true` keeps the script element when permission is
revoked. c15t then calls `onConsentChange` with `hasConsent: false`, which is
where you call the vendor's opt-out API. If permission comes back on the same
page, c15t reuses the element and calls `onConsentChange` again with
`hasConsent: true`; `onLoad` does not run twice.

```ts
const examplePixel = {
	id: 'example-pixel',
	category: 'marketing',
	src: 'https://pixel.example.com/pixel.js',
	persistAfterConsentRevoked: true,
	onConsentChange({ hasConsent }) {
		window.examplePixel?.(hasConsent ? 'optIn' : 'optOut');
	},
};
```

Nothing persists across a reload. After c15t's revocation reload, or any later
page load, the script loads again only when permission allows it. Without
`persistAfterConsentRevoked`, c15t removes the element on revocation, then
calls `onConsentChange`.

## Sync an SDK your app already loads

`callbackOnly: true` adds no script element. Use it when your app imports and
initializes the SDK itself and c15t only has to tell it the permission. Pair
it with `alwaysLoad` so the callbacks run on the first page load even while
permission is denied:

```ts
const existingSdkConsent = {
	id: 'existing-sdk-consent',
	category: 'measurement',
	callbackOnly: true,
	alwaysLoad: true,
	onBeforeLoad({ hasConsent }) {
		existingSdk.setTracking(hasConsent);
	},
	onConsentChange({ hasConsent }) {
		existingSdk.setTracking(hasConsent);
	},
};
```

`existingSdk` stands for your initialized SDK. c15t does not delay its import
or its first request, so initialize it with tracking off. Without `alwaysLoad`,
a callback-only script runs `onBeforeLoad` and `onLoad` only once permission is
allowed. [PostHog](/docs/integrations/posthog#use-an-existing-posthog-sdk) shows
this pattern with a real SDK.

## Revocation and verification

By default c15t reloads the page when a visitor turns off a category or vendor
they had allowed, because removing a script element does not stop code that
already ran. Set `reloadOnConsentRevoked: false` only if every script stops
itself in `onConsentChange`.

For a nonce-based Content Security Policy, set the provider's `nonce` option or
a per-script `nonce`. Then test the script the way the vendor guides do. Check
for no request before a choice or after rejection, a load after allowing, and
no request after revocation and reload. See
[consent verification](/docs/guides/verify-consent).

# Google Maps
URL: https://c15t.com/docs/integrations/google-maps
Gate a Google Maps iframe embed with c15t v3 so the map loads only after the visitor allows its consent category, in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.

## Configure the map

Copy the map's iframe embed URL. Choose the category matching its use in your
application; this example uses functionality permission.

```ts title="src/embed-config.ts"
export const embedCategory = 'functionality' as const;
export const embedURL =
	'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
export const embedTitle = 'Map showing our office location';
export const embedAspectRatio = '4 / 3';
```

Replace the example URL with the complete embed URL for your map. Keep the
address and a directions link outside the consent-gated embed.

## Add the embed to your framework

Create `src/embed-config.ts` using the configuration on this page, then select
your framework. Keep the existing [consent setup](/docs/frameworks), its policy
and preferences UI. These examples do not create a second consent provider.

**Next.js**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**TanStack Start**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/tanstack-start';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**React**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/react';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**Nuxt**

The Nuxt module registers `ConsentGate` and `ConsentDialogLink`, so
this component imports only the embed configuration.

```vue title="app/components/ConsentEmbed.vue"
<script setup lang="ts">
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the server HTML and the DOM while
permission is denied, and removes it on revocation. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Render this component inside the app that installed the c15t Vue plugin.

```vue title="src/ConsentEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the DOM while permission is denied,
and removes it on revocation. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Use the shared browser helper below with Astro's existing page runtime.
Add this component to pages using your consent-enabled base layout:

```astro title="src/components/ConsentEmbed.astro"
<c15t-consent-embed style="display: block"></c15t-consent-embed>

<script>
  import { getConsentClient } from 'c15t/astro/client';
  import { mountConsentEmbed } from '../consent-embed';

  class ConsentEmbed extends HTMLElement {
    dispose?: () => void;

    connect = () => {
      if (this.dispose) return;
      const client = getConsentClient();
      if (!client) return;
      this.dispose = mountConsentEmbed(
        this,
        client.runtime.kernel,
        () => { void client.openDialog(); },
      );
    };

    connectedCallback() {
      document.addEventListener('DOMContentLoaded', this.connect, { once: true });
      this.connect();
    }

    disconnectedCallback() {
      document.removeEventListener('DOMContentLoaded', this.connect);
      this.dispose?.();
      this.dispose = undefined;
    }
  }

  if (!customElements.get('c15t-consent-embed')) {
    customElements.define('c15t-consent-embed', ConsentEmbed);
  }
</script>
```

The first mount waits for the page's module scripts, including c15t's boot
script. Later `ClientRouter` mounts reuse the existing runtime. Removing the
component unsubscribes and removes the iframe. Do not create another consent
runtime for this embed.

**Svelte**

Render this component inside the existing `ConsentProvider`.
The provider from your quickstart supplies its consent state.

```svelte title="src/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**SvelteKit**

Render this component inside the existing `ConsentRoot`.
Keep the SvelteKit root and its server-resolved state unchanged.

```svelte title="src/lib/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**HTML**

The c15t script tag gates iframes that name a category. Put the embed's URL
in `data-src` instead of `src`, using the values from the configuration on
this page:

```html
<iframe
  data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1"
  data-category="measurement"
  title="Product video"
  loading="lazy"
  allowfullscreen
></iframe>
```

c15t sets `src` once the category is allowed and removes it on revocation.
Without `src` the iframe loads nothing, so hide it with CSS and show a link
to `#c15t-preferences` in its place. See
[HTML embeds](/docs/frameworks/html/embeds).

**JavaScript**

Use the shared browser helper below with your existing client. Put an
empty container where the embed should appear:

```html
<div id="consent-embed"></div>
```

In your browser entry point, after `init()`:

```ts
import { mountConsentEmbed } from './consent-embed';

const container = document.querySelector<HTMLElement>('#consent-embed');
if (!container) throw new Error('Missing consent embed container');

const disposeEmbed = mountConsentEmbed(container, consent.kernel, () =>
  consent.openDialog(),
);
```

`consent` is the client from `init()` in your quickstart. With
`createConsentRuntime`, pass `runtime.kernel` and your own function that
opens preferences. Call `disposeEmbed()` when the page or component is
destroyed. Iframe markup with `data-src` and `data-category` also works
without the helper, because both setups gate iframes by default.

## Browser helper for Astro and JavaScript

Only the Astro and JavaScript examples need this helper. It creates the iframe
when permission allows it, keeps an existing player mounted across unrelated
snapshot updates, and removes it on revocation.

```ts title="src/consent-embed.ts"
import {
	embedCategory,
	embedURL,
	embedTitle,
	embedAspectRatio,
} from './embed-config';

type EmbedKernel = {
	getSnapshot: () => {
		effectivePermissions: Record<typeof embedCategory, boolean>;
	};
	subscribe: (listener: () => void) => () => void;
};

export function mountConsentEmbed(
	container: HTMLElement,
	kernel: EmbedKernel,
	openPreferences: () => void
) {
	const render = () => {
		if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
			if (container.querySelector('iframe')) return;
			const frame = document.createElement('iframe');
			frame.src = embedURL;
			frame.title = embedTitle;
			frame.loading = 'lazy';
			frame.allowFullscreen = true;
			Object.assign(frame.style, {
				width: '100%',
				aspectRatio: embedAspectRatio,
				minHeight: '200px',
				border: '0',
			});
			container.replaceChildren(frame);
		} else {
			if (container.querySelector('button')) return;
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent = 'Open privacy settings to view this content';
			button.onclick = openPreferences;
			container.replaceChildren(button);
		}
	};

	render();
	const unsubscribe = kernel.subscribe(render);
	return () => {
		unsubscribe();
		container.replaceChildren();
	};
}
```

Keep a transcript, address or other useful alternative outside the embed.
`loading="lazy"` is a performance hint; the consent condition controls whether
the iframe exists at all. A denied category may be fixed by policy, so opening
preferences does not guarantee that the visitor can grant it.

## Gate existing iframe markup

For markup that uses `data-category` and `data-src`, the
`createIframeBlocker` module from `c15t/modules/iframe-blocker` promotes
`data-src` only when the category has consent and the URL resolves to HTTP or
HTTPS. Relative URLs resolve against the iframe document's base URL.
Malformed URLs and other schemes, including `javascript:`, `data:` and `blob:`,
remain in `data-src` without loading. Correct the URL and call
`processAllIframes()` to retry.

Keep the initial URL in `data-src`, without `src`, so the browser cannot load
it before the blocker runs. The module does not sanitize arbitrary HTML or
modify iframes without `data-category`.

## Verify before and after permission

On a fresh opt-in session, inspect Network and confirm the iframe has not
requested the map. Grant the category and confirm the map mounts. Revoke it and
check the frame returns to its blocked state. Keep useful fallback information,
such as the address and directions link, available outside the map.

For a JavaScript Maps SDK instead of an iframe, register a category-gated script
and manage the widget's cleanup. Do not use this iframe recipe as evidence that
an independently loaded Maps SDK is blocked.

# YouTube
URL: https://c15t.com/docs/integrations/youtube
Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.

## Configure the video

Use the ID of an embeddable video and the category matching its purpose in your
policy. This page uses `marketing` because the YouTube player can set
advertising identifiers. The framework quickstarts gate their demo video on
`measurement` instead; either works if your policy says so. The current v3 adapters use consent-gated iframes rather than the v2
`YouTubeEmbed` convenience component.

```ts title="src/embed-config.ts"
export const embedCategory = 'marketing' as const;
export const embedURL =
	'https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1';
export const embedTitle = 'Product walkthrough';
export const embedAspectRatio = '16 / 9';
```

Replace `VIDEO_ID` before running the example.

## Add the embed to your framework

Create `src/embed-config.ts` using the configuration on this page, then select
your framework. Keep the existing [consent setup](/docs/frameworks), its policy
and preferences UI. These examples do not create a second consent provider.

**Next.js**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**TanStack Start**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/tanstack-start';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**React**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/react';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**Nuxt**

The Nuxt module registers `ConsentGate` and `ConsentDialogLink`, so
this component imports only the embed configuration.

```vue title="app/components/ConsentEmbed.vue"
<script setup lang="ts">
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the server HTML and the DOM while
permission is denied, and removes it on revocation. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Render this component inside the app that installed the c15t Vue plugin.

```vue title="src/ConsentEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the DOM while permission is denied,
and removes it on revocation. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Use the shared browser helper below with Astro's existing page runtime.
Add this component to pages using your consent-enabled base layout:

```astro title="src/components/ConsentEmbed.astro"
<c15t-consent-embed style="display: block"></c15t-consent-embed>

<script>
  import { getConsentClient } from 'c15t/astro/client';
  import { mountConsentEmbed } from '../consent-embed';

  class ConsentEmbed extends HTMLElement {
    dispose?: () => void;

    connect = () => {
      if (this.dispose) return;
      const client = getConsentClient();
      if (!client) return;
      this.dispose = mountConsentEmbed(
        this,
        client.runtime.kernel,
        () => { void client.openDialog(); },
      );
    };

    connectedCallback() {
      document.addEventListener('DOMContentLoaded', this.connect, { once: true });
      this.connect();
    }

    disconnectedCallback() {
      document.removeEventListener('DOMContentLoaded', this.connect);
      this.dispose?.();
      this.dispose = undefined;
    }
  }

  if (!customElements.get('c15t-consent-embed')) {
    customElements.define('c15t-consent-embed', ConsentEmbed);
  }
</script>
```

The first mount waits for the page's module scripts, including c15t's boot
script. Later `ClientRouter` mounts reuse the existing runtime. Removing the
component unsubscribes and removes the iframe. Do not create another consent
runtime for this embed.

**Svelte**

Render this component inside the existing `ConsentProvider`.
The provider from your quickstart supplies its consent state.

```svelte title="src/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**SvelteKit**

Render this component inside the existing `ConsentRoot`.
Keep the SvelteKit root and its server-resolved state unchanged.

```svelte title="src/lib/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**HTML**

The c15t script tag gates iframes that name a category. Put the embed's URL
in `data-src` instead of `src`, using the values from the configuration on
this page:

```html
<iframe
  data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1"
  data-category="measurement"
  title="Product video"
  loading="lazy"
  allowfullscreen
></iframe>
```

c15t sets `src` once the category is allowed and removes it on revocation.
Without `src` the iframe loads nothing, so hide it with CSS and show a link
to `#c15t-preferences` in its place. See
[HTML embeds](/docs/frameworks/html/embeds).

**JavaScript**

Use the shared browser helper below with your existing client. Put an
empty container where the embed should appear:

```html
<div id="consent-embed"></div>
```

In your browser entry point, after `init()`:

```ts
import { mountConsentEmbed } from './consent-embed';

const container = document.querySelector<HTMLElement>('#consent-embed');
if (!container) throw new Error('Missing consent embed container');

const disposeEmbed = mountConsentEmbed(container, consent.kernel, () =>
  consent.openDialog(),
);
```

`consent` is the client from `init()` in your quickstart. With
`createConsentRuntime`, pass `runtime.kernel` and your own function that
opens preferences. Call `disposeEmbed()` when the page or component is
destroyed. Iframe markup with `data-src` and `data-category` also works
without the helper, because both setups gate iframes by default.

## Browser helper for Astro and JavaScript

Only the Astro and JavaScript examples need this helper. It creates the iframe
when permission allows it, keeps an existing player mounted across unrelated
snapshot updates, and removes it on revocation.

```ts title="src/consent-embed.ts"
import {
	embedCategory,
	embedURL,
	embedTitle,
	embedAspectRatio,
} from './embed-config';

type EmbedKernel = {
	getSnapshot: () => {
		effectivePermissions: Record<typeof embedCategory, boolean>;
	};
	subscribe: (listener: () => void) => () => void;
};

export function mountConsentEmbed(
	container: HTMLElement,
	kernel: EmbedKernel,
	openPreferences: () => void
) {
	const render = () => {
		if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
			if (container.querySelector('iframe')) return;
			const frame = document.createElement('iframe');
			frame.src = embedURL;
			frame.title = embedTitle;
			frame.loading = 'lazy';
			frame.allowFullscreen = true;
			Object.assign(frame.style, {
				width: '100%',
				aspectRatio: embedAspectRatio,
				minHeight: '200px',
				border: '0',
			});
			container.replaceChildren(frame);
		} else {
			if (container.querySelector('button')) return;
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent = 'Open privacy settings to view this content';
			button.onclick = openPreferences;
			container.replaceChildren(button);
		}
	};

	render();
	const unsubscribe = kernel.subscribe(render);
	return () => {
		unsubscribe();
		container.replaceChildren();
	};
}
```

Keep a transcript, address or other useful alternative outside the embed.
`loading="lazy"` is a performance hint; the consent condition controls whether
the iframe exists at all. A denied category may be fixed by policy, so opening
preferences does not guarantee that the visitor can grant it.

## Gate existing iframe markup

For markup that uses `data-category` and `data-src`, the
`createIframeBlocker` module from `c15t/modules/iframe-blocker` promotes
`data-src` only when the category has consent and the URL resolves to HTTP or
HTTPS. Relative URLs resolve against the iframe document's base URL.
Malformed URLs and other schemes, including `javascript:`, `data:` and `blob:`,
remain in `data-src` without loading. Correct the URL and call
`processAllIframes()` to retry.

Keep the initial URL in `data-src`, without `src`, so the browser cannot load
it before the blocker runs. The module does not sanitize arbitrary HTML or
modify iframes without `data-category`.

## Customize the player and placeholder

Set playback options in the iframe URL. For example, append `start=36` to begin
36 seconds into the video. Use supported
[YouTube player parameters](https://developers.google.com/youtube/player_parameters)
and reserve at least a 200-by-200-pixel player area.

React and Svelte `ConsentGate` components provide a blocked-state placeholder and
consent action. Their `placeholder` APIs differ. React takes a node, and
Svelte takes a snippet. Keep a clear way to reopen preferences when customizing them.
The Vue and browser examples show that action explicitly. `loading="lazy"` delays an
allowed iframe for performance; it does not implement consent gating.

## Consent behavior

Add `data-vendor="youtube"` next to `data-category` and declare a `youtube`
vendor in the runtime's `vendors` option or the backend manifest to let visitors
turn YouTube off while keeping the rest of the category on. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

Each example keeps the iframe absent until the category is allowed. After
permission, the iframe can load. Revoking permission removes the iframe and its
embedded document. Requests already sent cannot be recalled.

The `youtube-nocookie.com` hostname does not replace the consent boundary. Avoid
loading a remote thumbnail, preconnecting to YouTube, or installing the IFrame
Player API separately if you require no YouTube request before permission.
This recipe embeds a video; it does not load the JavaScript Player API.

## Verify the integration

In a fresh opt-in session, confirm no iframe or YouTube request exists. Grant
marketing permission and play the video, then revoke it and confirm the iframe
is removed. Test a narrow viewport and keyboard access to the placeholder and
player. See [consent verification](/docs/guides/verify-consent).

# Google Tag Manager
URL: https://c15t.com/docs/integrations/google-tag-manager
Load a Google Tag Manager container before or after consent with c15t Consent Mode v2 signals, configure consent checks inside the container, and verify both in DevTools.

## Configure Google Tag Manager

Copy the container ID, which starts with `GTM-`, from your GTM workspace.
Remove the existing GTM snippet, its `<noscript>` iframe and any framework
plugin that loads the same container.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { googleTagManager } from '@c15t/integrations/google-tag-manager';

export const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Container ID, for example `GTM-1234XXX`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`dataLayer`|`'dataLayer'`|Queue name. A custom name adds `&l=<name>` to the container URL and renames the helper's queue function to `<name>Gtag`.|
|`updateEventName`|`'consent-update'`|`dataLayer` event pushed after every consent update. Use it as a GTM trigger.|
|`consentMapping`|The table below|Replaces the category-to-Google mapping.|
|`loadMode`|`'always'`|When `gtm.js` loads. See [choose when the container loads](#choose-when-the-container-loads).|
|`category`|`'necessary'`, or `{ or: ['measurement', 'marketing'] }` with `loadMode: 'after-consent'`|Consent condition for the container. With `'after-consent'`, `gtm.js` waits for it. With `'always'`, it sets the script's permission, which callbacks receive, but does not delay loading.|

## Choose when the container loads

|`loadMode`|Until the category is allowed|After the category is allowed|
|--|--|--|
|`'always'`|Loads `gtm.js` and sends `consent` `default` with the current permissions before the `gtm.js` start event.|Sends `consent` `update`, then the `consent-update` event.|
|`'after-consent'`|Sends nothing to Google. The helper creates no `dataLayer` or `gtag` function.|Loads `gtm.js` once. `consent` `default` carries the current permissions and comes before the `gtm.js` start event. Later changes send `update` and `consent-update`.|

Use `'after-consent'` when your policy forbids any request to Google before
the visitor opts in:

```ts title="src/consent-scripts.ts (partial)"
googleTagManager({ id: 'GTM-XXXXXXX', loadMode: 'after-consent' }),
```

`'after-consent'` waits for the category to be allowed, not for a recorded
choice. Under an `opt-in` policy, that happens when the visitor allows it.
Under an `opt-out` or `none` policy, optional categories are allowed before a
choice, so `gtm.js` loads on the first page unless a saved refusal or a
privacy signal restricts the category; see
[policies](/docs/concepts/policies).

`necessary` is always allowed, so a gated container needs another category.
This mode defaults to `{ or: ['measurement', 'marketing'] }`. A container
usually holds Analytics tags and advertising tags, and this default loads it
once the visitor allows either purpose. Google tags inside still follow the
Consent Mode types, so an Ads tag stays restricted for a visitor who allowed
only measurement. If the container holds only Analytics tags, pass
`category: 'measurement'`.

This mode gives up part of Consent Mode. With `'always'`, Google tags send
cookieless pings while a type is denied, and Google uses them to model
conversions and behavior for visitors who refused or have not chosen. With
`'after-consent'`, visitors whose category is denied send nothing, so Google
has no data to model them from. Reports cover only visitors who allowed the
category.

The container starts with the visitor's current choice in its `default`
command. On the page where the visitor accepts, it loads after the choice, so
no `consent-update` event fires for that choice. Triggers that wait only for
`consent-update` first fire on a later change. Use the tag's consent settings,
described below, for tags that should fire on the first page.

When the visitor withdraws the category, c15t reloads the page and the new
page does not load `gtm.js`. With `reloadOnConsentRevoked: false`, the running
container stays on the page and gets an `update` that denies the withdrawn
types. A later grant reuses it instead of starting a second container.

## Google loads before a choice by default

With the default `loadMode: 'always'`, the `googleTagManager` and `gtag`
helpers set `alwaysLoad: true`. Before the visitor chooses, the helper creates
the `dataLayer` queue, sends `gtag('consent', 'default', ...)` with the current
permissions and loads Google's script. After each permission change it sends
`gtag('consent', 'update', ...)`. Google's tags then adjust what they store and
send; see Google's
[Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode).

So the browser contacts Google before consent. If your policy requires no
Google request until the visitor allows it, set `loadMode: 'after-consent'`.
The helper then creates nothing and requests nothing until its category is
allowed. When it loads, it sends the `default` command first, with the
permissions at that moment, and `update` commands after later changes. Under
an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

## How categories map to Google consent types

|c15t category|Google consent types|
|--|--|
|`necessary`|`security_storage`|
|`functionality`|`functionality_storage`|
|`measurement`|`analytics_storage`|
|`marketing`|`ad_storage`, `ad_user_data`, `ad_personalization`|
|`experience`|`personalization_storage`|

Each Google type is `granted` when its category is allowed and `denied`
otherwise. If a visitor turns off the helper's vendor, every optional type is
sent as `denied`. The `consentMapping` option replaces the whole table, so
include every category you still want signalled.

Under an opt-out policy, the default command can grant types before the
visitor has chosen anything. That is a permission, not a recorded choice.

## Configure consent inside the container

With the default `loadMode: 'always'`, `googleTagManager` uses the `necessary`
category and `alwaysLoad`, so the container loads on every page. With
`'after-consent'`, it loads once its category is allowed. In both modes,
consent signals reach Google tags that support Consent Mode. Other tags in the
container, such as a third-party pixel added as Custom HTML, ignore those
signals and fire on their triggers.

For each non-Google tag, add a consent requirement in the tag's consent
settings, or fire it from a Custom Event trigger on `consent-update`. If a
vendor must make no request before consent, remove it from the container and
register its own c15t helper instead.

## Measure opt-in rate

If you run a banner experiment, the backend already counts visitors and
choices per arm. To see the arm in GTM as well, forward the `onSurfaceShown` and
`onChoiceRecorded` callbacks, which carry `experiment: { id, arm }`. See
[banner experiments](/docs/guides/banner-experiments#send-the-events-to-your-own-analytics-too).

## Verify Google Tag Manager

With the default `loadMode: 'always'`:

1. In a private window with an opt-in policy, load the page. `gtm.js` loads.
   In Google Tag Assistant, the first consent command is `default` with
   `analytics_storage` and `ad_storage` set to `denied`.
2. Click Reject, then reload. The `default` command still denies every
   optional type, and in DevTools Network no non-Google tag in the container
   fires.
3. Open Privacy settings and allow measurement. Tag Assistant shows an
   `update` command with `analytics_storage` set to `granted`, followed by a
   `consent-update` event, and measurement tags fire.
4. Turn measurement off again and save. c15t reloads the page, and the new
   page starts with `analytics_storage` denied.

With `loadMode: 'after-consent'`:

1. In a private window with an opt-in policy, filter DevTools Network by
   `google` and load the page. No request appears, and `window.dataLayer` is
   `undefined` in the Console.
2. Allow measurement. `gtm.js` loads once. In Tag Assistant, the first command
   is `consent` `default` with `analytics_storage` set to `granted`, before
   the container starts.
3. Allow marketing as well. Tag Assistant shows an `update` command that
   grants the ad types, followed by a `consent-update` event. No second
   `gtm.js` request appears.
4. Turn both off again and save. c15t reloads the page, and the new page makes
   no request to Google.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation and hosting checks.

# Cloudflare Zaraz
URL: https://c15t.com/docs/integrations/cloudflare-zaraz
Sync c15t permissions to Cloudflare Zaraz purposes with the c15t cloudflareZaraz bridge, which runs on every page without loading a script, and check the tools it controls.

## Configure Cloudflare Zaraz

`cloudflareZaraz` connects c15t to an existing Zaraz installation. It inserts
no script and configures no tools. Zaraz loads the tools; c15t decides which
purposes they may use. In the Zaraz dashboard:

1. Enable Consent Management and create purposes for the c15t categories you
   use.
2. Assign a purpose to every tool that needs permission. Zaraz runs a tool
   without a purpose regardless of consent.
3. Turn off automatic display of the Zaraz consent modal. c15t owns the UI.
4. Turn off **Automatic Pageview Tracking**, and automatic SPA pageviews too if
   your app sends them itself.
5. Copy the purpose IDs, not the purpose names, into the mapping below.

Zaraz keeps its own consent cookie. An automatic pageview can run with a grant
from a previous visit before c15t applies the current permissions. With
automatic pageviews off, send the first pageview from `onReady`, which runs
after the first synchronization. DOM-ready, timer and click triggers you add in
Zaraz can still run before the bridge starts; audit them. Cloudflare documents
[purpose assignment](https://developers.cloudflare.com/zaraz/consent-management/)
and [pageview settings](https://developers.cloudflare.com/zaraz/reference/settings/).

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { cloudflareZaraz } from '@c15t/integrations/cloudflare-zaraz';

// Zaraz provides this global after its loader runs.
declare const zaraz: { track: (event: string) => void };

export const scripts = [
	cloudflareZaraz({
		purposes: {
			measurement: ['your-measurement-purpose-id'],
			marketing: ['your-marketing-purpose-id'],
		},
		onReady: () => {
			zaraz.track('Pageview');
		},
	}),
];
```

Register one bridge per app. Keep Zaraz's own loader and its dashboard tools
when you follow the registration steps below; remove only standalone loaders
for tools that Zaraz already runs, including a separate `@c15t/integrations` helper
for the same tool. If Zaraz auto-injection is off, load
[Zaraz manually](https://developers.cloudflare.com/zaraz/advanced/load-zaraz-manually/)
once.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`purposes`|Required|Maps c15t categories to Zaraz purpose IDs. A category can list several IDs. An empty mapping, a blank ID, an ID with surrounding whitespace or an ID mapped twice throws.|
|`hideBuiltInModal`|`true`|Hides the Zaraz modal if it is visible. Also turn off auto-display in Zaraz.|
|`sendQueuedEvents`|`true`|Calls `zaraz.consent.sendQueuedEvents()` after a purpose changes from denied to allowed. Set `false` to discard pageviews Zaraz queued before consent.|
|`onReady`|None|Runs once after the first successful synchronization, even when every purpose is denied.|
|`onError`|None|Receives synchronization errors.|

## Loading and revocation

`cloudflareZaraz` returns a callback-only script with the `necessary` category
and `alwaysLoad`, so the bridge runs for every visitor. That does not make the
tools behind it necessary. Control each tool through its Zaraz purpose.

The bridge's vendor slug is `cloudflare-zaraz`. Declare a vendor with that
`id` to give visitors a switch for Zaraz in the preference dialog. While a
visitor has it switched off, the bridge denies every purpose mapped to an
optional category, whatever the categories allow. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

When the Zaraz consent API is ready, the bridge reads `zaraz.consent.getAll()`
and sets each returned purpose to `true` only if its mapped category is
allowed in c15t's effective permissions, which include policy restrictions.
Purposes you did not map are set to `false`. If the API is not ready,
the bridge waits for the `zarazConsentAPIReady` event and applies the latest
permissions; it does not poll. On each consent change it calls
`zaraz.consent.set()` only when a value differs, then replays queued events
for newly allowed purposes. Revocation sets purposes to `false` and replays
nothing. Zaraz returns only purposes attached to enabled tools, so a mapped ID
missing from `getAll()` gets no grant.

If a Zaraz call throws, `onReady` waits and the bridge retries on the next
consent change or readiness event. Without `onError`, the error reaches the
script loader's debug events, or the browser's error handler for readiness
events. A failed revocation can leave the previous Zaraz grant in place, and a
retried replay can send a queued event twice. Disposing the loader detaches the
bridge but does not revoke purposes or stop tools that already ran. The bridge
maps categories to purposes only; it does not translate IAB TCF choices.

## Verify Cloudflare Zaraz

Test with isolated destinations. `getAll()` shows what the bridge set, but only
a tool's own requests show whether it respected that.

1. In a private window with an opt-in policy, load the page. The bridge adds
   no script element. `zaraz.consent.getAll()` returns `false` for every
   purpose, the Zaraz modal stays hidden, and no purpose-gated tool sends a
   request.
2. Click Reject, then reload. Every purpose is still `false`.
3. Open Privacy settings and allow measurement. Without a reload, the
   measurement purposes become `true`, the queued pageview replays and
   measurement tools send requests. Marketing tools stay silent.
4. Turn measurement off again and save. c15t reloads the page, and the new
   page starts with every purpose `false`.
5. In the console, call `zaraz.consent.set()` to grant a purpose that c15t
   denies, then reload. The bridge sets it back to `false` before `onReady`
   runs.

[Cloudflare Web Analytics](/docs/integrations/cloudflare-web-analytics) is a
separate product with its own helper. See the
[consent verification guide](/docs/guides/verify-consent) for navigation and
hosting checks.

# Google Tag
URL: https://c15t.com/docs/integrations/google-tag
Load gtag.js for Google Analytics or Google Ads before or after consent with c15t Consent Mode v2 signals, and verify the consent commands in DevTools.

## Configure the Google tag

Copy the tag ID, for example `G-XXXXXXXXXX` for Google Analytics or
`AW-XXXXXXXXX` for Google Ads. Remove any `gtag.js` snippet already in your
HTML and any tag-manager entry that loads the same tag.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';

export const scripts = [gtag({ id: 'G-XXXXXXXXXX', category: 'measurement' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Tag ID passed to `gtag('config', ...)` and the loader URL. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`category`|Required|`measurement` for Analytics, `marketing` for Ads and Floodlight. With `loadMode: 'after-consent'`, `gtag/js` waits for it. With `'always'`, it sets the script's permission, which callbacks receive, but does not delay loading.|
|`loadMode`|`'always'`|When `gtag/js` loads. See [choose when Google loads](#choose-when-google-loads).|
|`config`|None|Parameters passed as the third argument to `gtag('config', id, config)`.|
|`consentMapping`|The table below|Replaces the category-to-Google mapping.|

The deprecated `script` option overrides fields of the returned script. Use the
options above instead.

## Choose when Google loads

|`loadMode`|Until the category is allowed|After the category is allowed|
|--|--|--|
|`'always'`|Loads `gtag/js` and sends `consent` `default` with the current permissions, then `config`.|Sends `consent` `update` with the mapped types granted.|
|`'after-consent'`|Sends nothing to Google. The helper creates no `dataLayer` or `gtag` function.|Loads `gtag/js` once. `consent` `default` carries the current permissions and comes before `config`. Later changes send `update`.|

Use `'after-consent'` when your policy forbids any request to Google before
the visitor opts in:

```ts title="src/consent-scripts.ts (partial)"
gtag({ id: 'G-XXXXXXXXXX', category: 'measurement', loadMode: 'after-consent' }),
```

`'after-consent'` waits for the category to be allowed, not for a recorded
choice. Under an `opt-in` policy, that happens when the visitor allows it.
Under an `opt-out` or `none` policy, optional categories are allowed before a
choice, so `gtag/js` loads on the first page unless a saved refusal or a
privacy signal restricts the category; see
[policies](/docs/concepts/policies). `necessary` is always allowed, so
`category: 'necessary'` loads `gtag/js` before a choice in either mode. Use
`measurement` or `marketing`.

This gives up part of Consent Mode. With `'always'`, Google tags send
cookieless pings while a type is denied, and Google uses them to model
conversions and behavior for visitors who refused or have not chosen. With
`'after-consent'`, visitors whose category is denied send nothing, so Google
has no data to model them from. Reports cover only visitors who allowed the
category.

When the visitor withdraws the category, c15t reloads the page and the new
page does not load `gtag/js`. With `reloadOnConsentRevoked: false`, the tag
already running stays on the page and gets an `update` that denies the
withdrawn types. A later grant reuses it instead of loading a second copy.

## Google loads before a choice by default

With the default `loadMode: 'always'`, the `googleTagManager` and `gtag`
helpers set `alwaysLoad: true`. Before the visitor chooses, the helper creates
the `dataLayer` queue, sends `gtag('consent', 'default', ...)` with the current
permissions and loads Google's script. After each permission change it sends
`gtag('consent', 'update', ...)`. Google's tags then adjust what they store and
send; see Google's
[Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode).

So the browser contacts Google before consent. If your policy requires no
Google request until the visitor allows it, set `loadMode: 'after-consent'`.
The helper then creates nothing and requests nothing until its category is
allowed. When it loads, it sends the `default` command first, with the
permissions at that moment, and `update` commands after later changes. Under
an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

## How categories map to Google consent types

|c15t category|Google consent types|
|--|--|
|`necessary`|`security_storage`|
|`functionality`|`functionality_storage`|
|`measurement`|`analytics_storage`|
|`marketing`|`ad_storage`, `ad_user_data`, `ad_personalization`|
|`experience`|`personalization_storage`|

Each Google type is `granted` when its category is allowed and `denied`
otherwise. If a visitor turns off the helper's vendor, every optional type is
sent as `denied`. The `consentMapping` option replaces the whole table, so
include every category you still want signalled.

Under an opt-out policy, the default command can grant types before the
visitor has chosen anything. That is a permission, not a recorded choice.

## Verify the Google tag

On a plain HTML page with the script tag, you gate Google's snippet instead
and it loads only after consent; see
[HTML scripts](/docs/frameworks/html/scripts#google-consent-mode-and-tag-managers).

With the default `loadMode: 'always'`:

1. In a private window with an opt-in policy, load the page. `gtag/js` loads.
   In Google Tag Assistant, the `consent` `default` command comes before
   `config`, with `analytics_storage` and `ad_storage` set to `denied`.
2. Open Privacy settings and allow the tag's category. Tag Assistant shows an
   `update` command that grants the mapped types.
3. Turn the category off again and save. c15t reloads the page, and the new
   page starts with those types denied.

With `loadMode: 'after-consent'`:

1. In a private window with an opt-in policy, filter DevTools Network by
   `google` and load the page. No request appears, and `window.dataLayer` is
   `undefined` in the Console.
2. Allow the tag's category. `gtag/js` loads once. In Tag Assistant, the first
   command is `consent` `default` with the mapped types granted, before
   `config`.
3. Turn the category off again and save. c15t reloads the page, and the new
   page makes no request to Google.

In either mode, with client-side navigation, check that each route change
sends one page view. A separate router integration that also sends
`page_view` doubles the count.

See the [consent verification guide](/docs/guides/verify-consent) for hosting
checks.

# Ahrefs Analytics
URL: https://c15t.com/docs/integrations/ahrefs-analytics
Load Ahrefs Web Analytics only after measurement consent with the c15t ahrefsAnalytics helper, and check it in DevTools.

## Configure Ahrefs Analytics

Copy the project key from the Ahrefs installation snippet. The helper passes it
to the analytics script as `data-key`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { ahrefsAnalytics } from '@c15t/integrations/ahrefs-analytics';

export const scripts = [ahrefsAnalytics({ key: 'YOUR_PROJECT_KEY' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`key`|Required|Project key. Empty or whitespace-only values log an error and the script does not load.|
|`scriptUrl`|`https://analytics.ahrefs.com/analytics.js`|Loader URL override.|

## Loading and revocation

`ahrefsAnalytics` uses the `measurement` category. The script loads only while
measurement is allowed. On revocation the helper removes the script element and
calls no Ahrefs API.

## Verify Ahrefs Analytics

After you allow measurement, the `analytics.js` request appears and its script
element carries your `data-key`. If your code calls
`window.AhrefsAnalytics?.sendEvent`, check measurement permission before each
call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Adobe Analytics
URL: https://c15t.com/docs/integrations/adobe-analytics
Load an Adobe Data Collection Tags property only after measurement consent with the c15t adobeAnalytics helper, and check its extensions in DevTools.

## Configure Adobe Analytics

Copy the full embed URL for your property environment from the Adobe Data
Collection embed code. Adobe has no shared loader that takes only an account
ID, so `adobeAnalytics` needs the whole URL. Remove the original embed code.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { adobeAnalytics } from '@c15t/integrations/adobe-analytics';

export const scripts = [
	adobeAnalytics({
		scriptUrl:
			'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
	}),
];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`scriptUrl`|Required|Full `https:` embed URL of the Tags property environment. Self-hosted embeds work. The helper trims the value. Empty, unparseable and non-`https:` URLs log an error and the script does not load.|
|`async`|`true`|Loads the Tags library asynchronously. Set `false` only for a legacy synchronous deployment.|
|`seedAdobeDataLayer`|`true`|Sets `window.adobeDataLayer` to an empty array before the library loads, only when the global is undefined.|

## Loading and revocation

`adobeAnalytics` uses the `measurement` category. The property embed loads
only while measurement is allowed. On revocation the helper removes the script
element and calls no Adobe API.

The property can load Adobe Analytics, Web SDK and other extensions through its
rules. c15t sees only the embed script, so every extension runs under the one
measurement permission. If a rule loads a service with another purpose, such
as advertising, configure that rule in Adobe to respect your consent model too.

## Verify Adobe Analytics

After you allow measurement, the request for your embed URL appears, then the
requests from the extensions the property enables. `window._satellite` exists
once the Tags library runs. Check that each extension's requests match the
measurement purpose.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Amplitude
URL: https://c15t.com/docs/integrations/amplitude
Load the Amplitude Browser SDK 2 only after measurement consent with the c15t amplitude helper, which opts the SDK out on revocation and back in on a new grant.

## Configure Amplitude

Use your Amplitude project API key. The `amplitude` helper initializes Browser
SDK 2 for you, so remove any existing Amplitude snippet or `init` call.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { amplitude } from '@c15t/integrations/amplitude';

export const scripts = [amplitude({ apiKey: 'YOUR_PROJECT_API_KEY' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`apiKey`|Required|Project API key passed to `amplitude.init`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`initOptions`|`{}`|Browser SDK 2 options passed as the second argument to `init`. Use JSON-serializable values only.|
|`scriptUrl`|`https://cdn.amplitude.com/libs/analytics-browser-2.44.4-min.js.gz`|Loader URL override. The default pins Browser SDK 2 version `2.44.4`. A blank value falls back to the default.|

## Loading and revocation

`amplitude` uses the `measurement` category. Before measurement is allowed,
c15t defines no `window.amplitude` and loads nothing from Amplitude. When
measurement becomes allowed, the helper creates the Browser SDK 2 queue stub,
queues `init(apiKey, initOptions)` and `setOptOut(false)`, then loads the SDK,
which replays the queue. Amplitude saves an opt-out in its cookie, so the
queued `setOptOut(false)` clears one left by an earlier revocation.

On revocation the helper calls `amplitude.setOptOut(true)` and leaves the SDK
on the page, because removing the script would not stop the running client.
If the visitor allows measurement again before the page reloads, the helper
calls `setOptOut(false)` on that SDK instead of loading a second copy.

## Verify Amplitude

After you allow measurement, the `analytics-browser-2.44.4-min.js.gz` request
loads and a test event reaches your Amplitude project. Revoke measurement, then
allow it again on a later page and check that events reach Amplitude again.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Cloudflare Web Analytics
URL: https://c15t.com/docs/integrations/cloudflare-web-analytics
Load the Cloudflare Web Analytics beacon only after measurement consent with the c15t cloudflareWebAnalytics helper, and check it in DevTools.

## Configure Cloudflare Web Analytics

Copy the beacon token from the Web Analytics installation snippet. If
Cloudflare adds the beacon to this site automatically, turn that off so the
page has one beacon and c15t controls it.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { cloudflareWebAnalytics } from '@c15t/integrations/cloudflare-web-analytics';

export const scripts = [cloudflareWebAnalytics({ token: 'YOUR_BEACON_TOKEN' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`token`|Required|Beacon token, written into the `data-cf-beacon` attribute. The helper trims it. Empty values log an error and the script does not load.|
|`spa`|`true`|Written into `data-cf-beacon`. Turns on Cloudflare's route tracking for single-page apps. Set `false` for a site with only full page loads.|
|`scriptUrl`|`https://static.cloudflareinsights.com/beacon.min.js`|Loader URL override.|

## Loading and revocation

`cloudflareWebAnalytics` uses the `measurement` category. Cloudflare Web
Analytics sets no cookies, but the helper still waits for measurement
permission. It loads `beacon.min.js` with `defer`. On revocation the helper
removes the script element and calls no Cloudflare API.

## Verify Cloudflare Web Analytics

Filter DevTools Network by `cloudflareinsights.com`. After you allow
measurement, `beacon.min.js` loads and its script element carries
`data-cf-beacon` with your token and `"spa":true`. Change route in your app and
check that the beacon reports the new page.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Clearbit
URL: https://c15t.com/docs/integrations/clearbit
Load the Clearbit enrichment tag only after marketing consent with the c15t clearbit helper, and check it in DevTools.

## Configure Clearbit

Use the publishable key from your Clearbit tag installation. Do not put a
secret Clearbit API key in browser code.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { clearbit } from '@c15t/integrations/clearbit';

export const scripts = [clearbit({ publishableKey: 'YOUR_PUBLISHABLE_KEY' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`publishableKey`|Required|Publishable key. The helper trims it and URL-encodes it into the default loader URL. Empty or non-string values log an error and the script does not load.|
|`scriptUrl`|`https://tag.clearbitscripts.com/v1/<publishableKey>/tags.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`clearbit` uses the `marketing` category, not `measurement`. Clearbit
identifies visitors and their companies for enrichment, so c15t treats it as
marketing even though these docs list it with analytics. The `tags.js` script
loads with `referrerpolicy="strict-origin-when-cross-origin"` only while
marketing is allowed. On revocation the helper removes the script element and
calls no Clearbit API.

## Verify Clearbit

Filter DevTools Network by `clearbitscripts.com`. After you allow marketing,
the `tags.js` request carries your publishable key in its path. Allowing
measurement alone loads nothing from Clearbit.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Microsoft Clarity
URL: https://c15t.com/docs/integrations/microsoft-clarity
Load Microsoft Clarity only after measurement consent with the c15t clarity helper, send Consent V2 storage signals and check them in DevTools.

## Configure Microsoft Clarity

Copy the project ID from your Clarity tracking code, where it follows
`https://www.clarity.ms/tag/`. The helper builds the loader URL from it.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { clarity } from '@c15t/integrations/microsoft-clarity';

export const scripts = [clarity({ id: 'YOUR_PROJECT_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Clarity project ID. Surrounding whitespace is trimmed. Unless you set `scriptUrl`, an empty ID logs an error and the script does not load.|
|`defaultConsent`|c15t state|Consent V2 value queued once, before the loader. `true` or `false` sets both channels. An object sets `ad_Storage` or `analytics_Storage`, also accepted as `marketing` and `measurement`; channels you leave out follow c15t. Later updates always follow c15t. `true` grants ad storage even while marketing is denied.|
|`scriptUrl`|`https://www.clarity.ms/tag/<id>`|Loader URL override.|

## Loading and revocation

`clarity` uses the `measurement` category, so Clarity loads only while
measurement is allowed. Before the loader runs, the helper queues
`clarity('consentv2', ...)` with `analytics_Storage` taken from measurement and
`ad_Storage` taken from marketing. While Clarity is on the page, every
permission change sends a new `consentv2` call, so allowing marketing later
grants `ad_Storage` without reloading Clarity.

On measurement revocation the helper keeps the Clarity script and sends
`consentv2` with `analytics_Storage` set to `denied`. If the visitor allows
measurement again before the page reloads, it sends `granted`. A visitor who
turns off the `microsoft-clarity` vendor gets both channels denied. Denied
storage limits what Clarity stores; it does not mean Clarity sends no requests.
See Microsoft's
[Consent V2 API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-consent-api-v2).

## Verify Microsoft Clarity

Allow only marketing first. Clarity does not load, because it waits for
measurement. Then allow measurement. The request to
`www.clarity.ms/tag/<id>` appears without a page reload.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Databuddy
URL: https://c15t.com/docs/integrations/databuddy
Load the Databuddy SDK on every page with the c15t databuddy helper, switch its disabled flag and config from measurement consent, and check both in DevTools.

## Configure Databuddy

Copy the client ID from your Databuddy project. The helper passes it to the
script as `data-client-id`. Remove any existing Databuddy script and any code
that sets `window.databuddyConfig`. The helper seeds that global only when it
is absent, so an existing value overrides your initial state.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { databuddy } from '@c15t/integrations/databuddy';

export const scripts = [
	databuddy({
		clientId: 'YOUR_CLIENT_ID',
		configWhenGranted: { disabled: false },
		configWhenDenied: { disabled: true },
	}),
];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`clientId`|Required|Set as `data-client-id`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`configWhenGranted`|Required|Object set as `window.databuddyConfig` while measurement is allowed.|
|`configWhenDenied`|Required|Object set as `window.databuddyConfig` while measurement is denied.|
|`apiUrl`|`https://basket.databuddy.cc`|Collection endpoint, set as `data-api-url`.|
|`scriptUrl`|`https://cdn.databuddy.cc/databuddy.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`databuddy` uses the `measurement` category with `alwaysLoad`, so the
Databuddy script loads on every page, before the visitor chooses. Before the
script loads, the helper sets `window.databuddyConfig` to `configWhenDenied` or
`configWhenGranted`, unless that global already exists. After the script
loads, the helper sets `window.databuddy.options.disabled` to `true` without
measurement permission and to `false` with it. On each later consent change,
the helper replaces `window.databuddyConfig` with the matching object and
updates `disabled` again. c15t never removes the script.

The Databuddy SDK decides what `disabled` stops. The helper cannot prevent the
script request before consent. If Databuddy must receive no request before
consent, write a
[custom gated integration](/docs/integrations/building-integrations) instead.

## Verify Databuddy

1. In a private window with an opt-in policy, load the page. `databuddy.js`
   loads from `cdn.databuddy.cc` with your `data-client-id`. In the console,
   `window.databuddyConfig` matches `configWhenDenied` and
   `window.databuddy.options.disabled` is `true`.
2. Click Reject, then reload. `disabled` is still `true`, and DevTools Network
   shows no event request to your `apiUrl`.
3. Open Privacy settings and allow measurement. Without a reload, `disabled`
   becomes `false`, `window.databuddyConfig` matches `configWhenGranted`, and
   event requests reach your `apiUrl`.
4. Turn measurement off again and save. c15t reloads the page, and the new
   page starts with `disabled` set to `true`.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation and hosting checks.

# Fathom Analytics
URL: https://c15t.com/docs/integrations/fathom-analytics
Load Fathom Analytics only after measurement consent with the c15t fathomAnalytics helper, set its SPA mode, and check it in DevTools.

## Configure Fathom Analytics

Copy the site ID from your Fathom embed code, where it is the `data-site`
value. If your app changes routes without a full page load, also pass `spa`.
Without it, the helper leaves Fathom's SPA route tracking off.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { fathomAnalytics } from '@c15t/integrations/fathom-analytics';

export const scripts = [fathomAnalytics({ site: 'YOUR_SITE_ID', spa: 'auto' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`site`|Required|Site ID, set as `data-site`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`spa`|None|`'auto'`, `'history'` or `'hash'`, set as `data-spa`. When omitted, the script has no `data-spa` attribute and SPA route tracking stays off.|
|`auto`|None|Sets `data-auto` to `'true'` or `'false'` to control automatic page views. When omitted, Fathom's default applies.|
|`canonical`|None|Sets `data-canonical` to control canonical URL tracking. When omitted, Fathom's default applies.|
|`honorDnt`|None|Sets `data-honor-dnt` to control whether Fathom honors Do Not Track. When omitted, Fathom's default applies.|
|`scriptUrl`|`https://cdn.usefathom.com/script.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`fathomAnalytics` uses the `measurement` category. Fathom sets no cookies, but
the helper still waits for measurement permission. It loads `script.js` with
`defer`. On revocation the helper removes the script element and calls no
Fathom API. It does not call `window.fathom.blockTrackingForMe`.

## Verify Fathom Analytics

After you allow measurement, `script.js` loads from `cdn.usefathom.com` and its
script element carries your `data-site` and `data-spa` values. Change route in
your app and check that it sends one page view, not two. If your code calls
`window.fathom?.trackEvent`, check measurement permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Heap
URL: https://c15t.com/docs/integrations/heap
Load the Heap config script and heap.js only after measurement consent with the c15t heap helper, and check it in DevTools.

## Configure Heap

Copy the environment ID from your Heap installation snippet. The `heap` helper
loads that environment's `heap_config.js`, which then loads the heap.js
runtime. Remove the original Heap snippet.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { heap } from '@c15t/integrations/heap';

export const scripts = [heap({ envId: 'YOUR_ENVIRONMENT_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`envId`|Required|Environment ID. Set as `heap.envId` and `heap.appid`, and used in the default loader URL. The helper trims it. Empty values log an error and the script does not load.|
|`clientConfig`|`{}`|Client configuration set on `heap.clientConfig`. Values must be JSON-serializable with finite numbers; other values throw a `TypeError`. The helper always sets `shouldFetchServerConfig: false` and overrides any value you pass for it.|
|`scriptUrl`|`https://cdn.us.heap-api.com/config/<envId>/heap_config.js`|Config loader URL override. A blank value falls back to the default.|

## Loading and revocation

`heap` uses the `measurement` category. When measurement becomes allowed, the
helper creates `window.heap` with stubs for the heap.js v5 methods, which queue
calls in `window.heapReadyCb`. Then it loads the config script, and heap.js
replays the queued calls once it is ready.

On revocation the helper removes the config script element and calls no Heap
API. It does not call `heap.stopTracking`, so heap.js keeps capturing until the
page unloads. If the visitor allows measurement again before the page reloads,
the helper keeps the methods of the running heap.js instead of replacing them
with queue stubs. If you set `reloadOnConsentRevoked: false`, call
`window.heap.stopTracking()` from the `onConsentChange` callback of a
callback-only script. See
[custom integrations](/docs/integrations/building-integrations).

## Verify Heap

Filter DevTools Network by `heap`. After you allow measurement, the
`heap_config.js` request for your environment ID loads, followed by the heap.js
runtime it selects. `window.heap.envId` holds your environment ID.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Matomo Analytics
URL: https://c15t.com/docs/integrations/matomo-analytics
Load Matomo after measurement consent with the c15t matomoAnalytics helper, or use Matomo's own consent mode, and check each mode in DevTools.

## Configure Matomo Analytics

Copy the site ID and your Matomo URL from the Matomo tracking code. For Matomo
Cloud, pass `cloudId`, for example `'your-site.matomo.cloud'`, instead of
`matomoUrl`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { matomoAnalytics } from '@c15t/integrations/matomo-analytics';

export const scripts = [
	matomoAnalytics({ matomoUrl: 'https://analytics.example.com', siteId: 1 }),
];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`matomoUrl`|None|Self-hosted Matomo base URL. The helper loads `<matomoUrl>/matomo.js` and sends hits to `<matomoUrl>/matomo.php`.|
|`cloudId`|None|Matomo Cloud ID, used when `matomoUrl` is not set. A value ending in `.matomo.cloud` becomes `https://<cloudId>`. Any other value becomes `https://cdn.matomo.cloud/<cloudId>`.|
|`trackerUrl`|`matomo.php` on the Matomo origin|Tracker endpoint override.|
|`scriptUrl`|`matomo.js` on the Matomo origin|Loader URL override. Without `matomoUrl` or `cloudId`, set both `trackerUrl` and `scriptUrl`, or the helper logs an error and the script does not load.|
|`siteId`|`1`|Site ID queued with `setSiteId`.|
|`trackPageView`|`true`|Queues `trackPageView`. The table below shows when.|
|`enableLinkTracking`|`false`|Queues `enableLinkTracking`.|
|`disableCookies`|`false`|Queues `disableCookies`. It does not change when Matomo loads.|
|`defaultConsent`|None|`'required'` or `'given'` switches to Matomo consent mode.|

## Loading and revocation

`matomoAnalytics` uses the `measurement` category. `defaultConsent` picks the
mode:

|`defaultConsent`|Loads|When measurement is allowed|On revocation|
|--|--|--|--|
|Omitted|After measurement is allowed, with `trackPageView` queued|Loads `matomo.js`|Removes the script element and calls no Matomo API|
|`'required'`|On every page, with `requireConsent` queued|Queues `setConsentGiven` and `trackPageView`|Keeps the script and queues `forgetConsentGiven`|
|`'given'`|On every page. With measurement allowed as it loads, `setConsentGiven` and `trackPageView` are queued; otherwise `requireConsent`|Queues `setConsentGiven` and `trackPageView`|Keeps the script and queues `forgetConsentGiven`|

In both consent modes Matomo holds tracking until `setConsentGiven`, and the
helper only queues that call for a visitor who has measurement consent. The
two modes differ for a visitor who already allowed measurement when the page
loads: `'given'` skips the up-front `requireConsent`. The helper queues
another `trackPageView` only when measurement changes from denied to allowed,
so a change to another category, such as allowing marketing, sends no extra
page view. Matomo separates
[tracking consent from cookie consent](https://developer.matomo.org/guides/tracking-consent).

## Verify Matomo Analytics

Without `defaultConsent`, allowing measurement loads `matomo.js`, and a
`matomo.php` request carries the page view.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

With `defaultConsent: 'required'`, Matomo loads before the choice, so test it
separately in a private window with an opt-in policy:

1. Load the page. `matomo.js` loads, and no `matomo.php` request follows.
2. Open Privacy settings and allow measurement. Without a reload, a
   `matomo.php` request carries the page view.
3. Turn measurement off and save. c15t reloads the page, and the new page
   loads `matomo.js` without a `matomo.php` request.

`'given'` behaves the same in this test. Under an opt-out policy, or after the
visitor has allowed measurement, both modes send a `matomo.php` page view as
the page loads. See the
[consent verification guide](/docs/guides/verify-consent) for navigation and
hosting checks.

# Mixpanel
URL: https://c15t.com/docs/integrations/mixpanel-analytics
Load the Mixpanel SDK on every page with the c15t mixpanelAnalytics helper, which switches Mixpanel tracking on and off with measurement consent, and check it in DevTools.

## Configure Mixpanel

Copy the 32-character project token from your Mixpanel installation snippet,
where it is passed to `mixpanel.init`. Remove that snippet.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { mixpanelAnalytics } from '@c15t/integrations/mixpanel-analytics';

export const scripts = [
	mixpanelAnalytics({
		token: '0123456789abcdef0123456789abcdef',
		initOptions: { opt_out_tracking_by_default: true },
	}),
];
```

Mixpanel initializes as soon as its SDK loads, before the helper's first
opt-in or opt-out call. `opt_out_tracking_by_default` starts a visitor who has
not opted in as opted out, so nothing is tracked during that gap. That
includes `track` calls your code queued before the SDK loaded, which replay
during initialization.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`token`|Required|32-character hexadecimal project token. Surrounding whitespace is trimmed. Any other value logs an error and the script does not load.|
|`initOptions`|`{}`|Mixpanel config passed to `init`. Use JSON-serializable values only.|
|`scriptUrl`|`https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js`|Loader URL override.|

## Loading and revocation

`mixpanelAnalytics` uses the `measurement` category with `alwaysLoad`, so the
Mixpanel SDK loads on every page, before any choice. When the SDK loads, the
helper calls `mixpanel.opt_in_tracking()` if measurement is allowed and
`mixpanel.opt_out_tracking()` if not. It calls the matching method again on
each later consent change. The SDK stays on the page after revocation.

Before the SDK loads, the helper queues `track`, `identify`, `reset`,
`register`, `opt_in_tracking` and `opt_out_tracking` on the default instance.
Named instances and `people.*` calls are not queued.

## Verify Mixpanel

1. In a private window with an opt-in policy, load the page. The request to
   `cdn.mxpnl.com` appears before you choose. In the console,
   `mixpanel.has_opted_out_tracking()` returns `true`.
2. Click Reject, then reload. The SDK loads again and still reports opted
   out. Call `mixpanel.track('Test')`; no tracking request goes to Mixpanel.
3. Open Privacy settings and allow measurement. Without a reload,
   `has_opted_out_tracking()` returns `false` and tracking requests appear.
4. Turn measurement off again and save. c15t reloads the page, and the new
   page loads the SDK opted out.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation and hosting checks.

# OneDollarStats
URL: https://c15t.com/docs/integrations/one-dollar-stats
Load the OneDollarStats tracker only after measurement consent with the c15t oneDollarStats helper, forward its data-attribute settings, and check it in DevTools.

## Configure OneDollarStats

OneDollarStats needs no API key. The helper loads the tracker and forwards
each setting you pass as a `data-*` attribute.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { oneDollarStats } from '@c15t/integrations/one-dollar-stats';

export const scripts = [oneDollarStats()];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

Every setting is a string without the `data-` prefix. Setting names use
lowercase letters, digits and hyphens. The helper throws on any other name and
on a non-string value. Unknown names are forwarded, so newer tracker settings
work.

|Option|Default|Behavior|
|--|--|--|
|`hostname`|None|Bare host, optionally with a port. Overrides the event hostname on every host, including production. A scheme, path, query or fragment throws.|
|`devmode`|None|`'true'` records local visits. Local testing needs `hostname` as well.|
|`autocollect`|None|`'false'` turns off automatic page view and click collection.|
|`hash-routing`|None|`'true'` tracks hash routes. `'false'` omits the attribute, because the tracker turns hash routing on whenever it is present.|
|`url`|None|Custom collection endpoint.|

The helper always loads `https://assets.onedollarstats.com/stonks.js` and has
no loader URL option. The tracker follows client-side navigation itself. See
the [vendor reference](https://docs.onedollarstats.com/installation) for its
settings.

## Loading and revocation

`oneDollarStats` uses the `measurement` category. The tracker loads only while
measurement is allowed. On revocation the helper removes the script element
and calls no OneDollarStats API.

The tracker installs history hooks and event listeners that removing its
script cannot undo, so the c15t reload on revocation is what stops it. Keep
`reloadOnConsentRevoked` enabled.

## Verify OneDollarStats

After you allow measurement, the `stonks.js` request appears and its script
element carries the `data-*` settings you passed. Navigate between routes and
check that each one sends a page view.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Hotjar
URL: https://c15t.com/docs/integrations/hotjar
Load Hotjar only after measurement consent with the c15t hotjar helper, and check its loader and recordings in DevTools.

## Configure Hotjar

Copy the site ID from your Hotjar tracking code, where it is the `hjid` value.
Remove the original tracking code.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { hotjar } from '@c15t/integrations/hotjar';

export const scripts = [hotjar({ siteId: 1234567 })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`siteId`|Required|Site ID as a number or string. Set as `window._hjSettings.hjid` and used in the default loader URL. Missing, empty and `0` values log an error and the script does not load.|
|`version`|`6`|Script version, set as `window._hjSettings.hjsv` and the `sv` query parameter of the default loader URL.|
|`scriptUrl`|`https://static.hotjar.com/c/hotjar-<siteId>.js?sv=<version>`|Loader URL override.|

## Loading and revocation

`hotjar` uses the `measurement` category. When measurement becomes allowed,
the helper sets `window._hjSettings` and a queue-backed `window.hj` stub, each
only when the global is undefined, then loads the Hotjar loader.

On revocation the helper removes the loader script element and calls no Hotjar
API. A recording in progress continues until the page unloads, so c15t's
default reload on revocation is what ends it.

## Verify Hotjar

Filter DevTools Network by `hotjar`. After you allow measurement, the
`hotjar-<siteId>.js` request loads from `static.hotjar.com`, and
`window._hjSettings.hjid` holds your site ID. Review a recording of a real
screen in your app to check that Hotjar masks the fields you expect.
`window.hj` still exists after revocation, so check measurement permission
before your own `hj` calls.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Hightouch
URL: https://c15t.com/docs/integrations/hightouch
Load the Hightouch Events browser SDK only after measurement consent with the c15t hightouch helper, and check page events in DevTools.

## Configure Hightouch

Copy the write key from your Hightouch Event Source. Remove the original
Hightouch snippet.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { hightouch } from '@c15t/integrations/hightouch';

export const scripts = [hightouch({ writeKey: 'YOUR_WRITE_KEY' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`writeKey`|Required|Event Source write key passed to `htevents.load`. The helper trims it. Empty values log an error and the script does not load.|
|`apiHost`|None|API host passed in the load options. Without it, the SDK uses `us-east-1.hightouch-events.com`. Set it only for another region or a first-party tracking host. A blank value is dropped.|
|`trackPageView`|`true`|Queues `htevents.page()` after `load`. Set `false` when your router sends page calls.|
|`scriptUrl`|`https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`hightouch` uses the `measurement` category. When measurement becomes allowed,
the helper creates the `window.htevents` queue with the snippet's methods,
stores the write key and load options on it, and queues `load` and, by
default, `page`. Then it loads `events.min.js`, which replays the queue.

On revocation the helper removes the script element and calls no Hightouch API.
An Event Source can forward events to other destinations, so check each
destination's purpose in Hightouch as well.

## Verify Hightouch

Filter DevTools Network by `hightouch`. After you allow measurement,
`events.min.js` loads and a page event reaches your API host. With client-side
routing, check that each route change sends one page event, not two.
`window.htevents` still exists after revocation, so check measurement
permission before your own `htevents.track` calls.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# LogRocket
URL: https://c15t.com/docs/integrations/logrocket
Load LogRocket session replay only after measurement consent with the c15t logRocket helper, including proxied setups, and check it in DevTools.

## Configure LogRocket

Copy the app ID from LogRocket Project Setup. It has the form
`org-slug/app-slug`. Remove the original LogRocket install.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { logRocket } from '@c15t/integrations/logrocket';

export const scripts = [logRocket({ appId: 'your-org/your-app' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`appId`|Required|App ID passed to `LogRocket.init`. The helper trims it. Values that are not two non-empty segments separated by `/` log an error and the script does not load.|
|`initOptions`|`{}`|Second argument to `LogRocket.init`. Use JSON-serializable values only, so functions such as request sanitizers cannot pass through.|
|`scriptUrl`|`https://cdn.logrocket.io/LogRocket.min.js`|Loader URL override. A blank value falls back to the default.|
|`asyncScriptUrl`|None|Proxied URL for LogRocket's logger bundle, set as `window._lrAsyncScript` before the loader runs. Set it only when you proxy LogRocket through your own domain.|

## Loading and revocation

`logRocket` uses the `measurement` category. When measurement becomes allowed,
the helper loads `LogRocket.min.js` with `crossorigin="anonymous"` and calls
`LogRocket.init(appId, initOptions)` after the script loads.

On revocation the helper removes the script element and calls no LogRocket
API, because LogRocket documents no consent or stop-recording call for the web
SDK. Recording continues until the page unloads, so c15t's default reload on
revocation is what stops it. Configure LogRocket's privacy and sanitization
settings before you deploy, so recordings leave out sensitive DOM, input and
network data.

## Verify LogRocket

Filter DevTools Network by `logrocket`. After you allow measurement,
`LogRocket.min.js` loads and `window.LogRocket` exists. With `asyncScriptUrl`,
check that the logger bundle loads from your proxy URL.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Plausible Analytics
URL: https://c15t.com/docs/integrations/plausible-analytics
Load the Plausible Analytics tracker only after measurement consent with the c15t plausibleAnalytics helper, and check it in DevTools.

## Configure Plausible Analytics

Copy the script ID from your Plausible installation snippet. It is the part of
the `pa-<id>.js` file name. Sites that still use the legacy domain-based
snippet can pass `domain` instead of `scriptId`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { plausibleAnalytics } from '@c15t/integrations/plausible-analytics';

export const scripts = [plausibleAnalytics({ scriptId: 'YOUR_SCRIPT_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`scriptId`|None|Script ID for the `pa-<scriptId>.js` loader. Takes precedence over `domain` and `extension`.|
|`domain`|None|Legacy site domain, set as `data-domain`. When neither `scriptId` nor `domain` has a non-empty value, the helper logs an error and the script does not load.|
|`extension`|None|Legacy script extension or array of extensions, such as `['file-downloads', 'outbound-links']`. The helper joins them into `script.<extensions>.js`. Ignored with `scriptId`.|
|`customProperties`|None|Properties sent with each page view.|
|`endpoint`|None|Custom event endpoint. With `domain`, the helper also sets it as `data-api`.|
|`fileDownloads`|None|`{ fileExtensions?: string[] }` for file download tracking.|
|`hashBasedRouting`|None|`true` tracks hash-based routes.|
|`autoCapturePageviews`|None|`false` stops automatic page views.|
|`captureOnLocalhost`|None|`true` records visits on localhost.|
|`scriptUrl`|`https://plausible.io/js/pa-<scriptId>.js`, or `https://plausible.io/js/script.js` with `domain`|Loader URL override.|

The helper passes `customProperties`, `endpoint`, `fileDownloads`,
`hashBasedRouting`, `autoCapturePageviews` and `captureOnLocalhost` as init
options on `window.plausible.o`, which the `scriptId` loader reads. With the
legacy loader, choose features with `extension`.

## Loading and revocation

`plausibleAnalytics` uses the `measurement` category. When measurement becomes
allowed, the helper defines a queueing `window.plausible` stub, unless one
already exists, and then loads the tracker. Calls made before the tracker
finishes loading wait in the stub's queue.

On revocation the helper removes the script element and calls no Plausible
API. Plausible sets no cookies, but c15t still waits for measurement
permission before loading it.

## Verify Plausible Analytics

After you allow measurement, the `pa-<scriptId>.js` request appears, or
`script.js` with your `data-domain` for the legacy loader. A page view request
then goes to `plausible.io/api/event`, or to your `endpoint`. After revocation
`window.plausible` still exists, so if your code sends custom events through
it, check measurement permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# PostHog
URL: https://c15t.com/docs/integrations/posthog
Load PostHog before or after measurement consent with the c15t posthog helper, choose its cookieless behavior, turn off PostHog modules you do not use, and sync consent with an SDK you already initialize.

## Configure PostHog

Use the project token that starts with `phc_`, and the region of your PostHog
project. This example waits for measurement permission before requesting the
SDK, and turns off cookieless capture after a refusal.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	posthog({
		id: 'phc_YOUR_PROJECT_TOKEN',
		region: 'eu',
		loadMode: 'after-consent',
		initOptions: { cookieless_mode: 'never' },
	}),
];
```

The helper initializes PostHog itself. Remove any `posthog-js` initializer,
framework plugin or array snippet that also does, or follow
[use an existing PostHog SDK](#use-an-existing-posthog-sdk) instead.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Project token, starting with `phc_`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`region`|`'eu'`|`'eu'` or `'us'`. Picks the API, UI and loader hosts when you do not set them.|
|`apiHost`|`https://eu.i.posthog.com`|API host for a proxy or self-hosted PostHog. Without `scriptUrl`, the loader URL becomes `<apiHost>/static/array.js`.|
|`uiHost`|The region's UI host|UI host, for example `https://eu.posthog.com`. A custom `apiHost` with no `region` uses the API host.|
|`scriptUrl`|`https://eu-assets.i.posthog.com/static/array.js`|Loader URL override. A blank value falls back to the default.|
|`loadMode`|`'always'`|When the SDK loads. See the table below.|
|`features.surveys`|Unset|`false` sets `disable_surveys: true` and skips `surveys.js`. See [turn off features you do not use](#turn-off-features-you-do-not-use).|
|`features.heatmaps`|Unset, follows the project|Sets `capture_heatmaps`.|
|`features.deadClicks`|Unset, follows the project|Sets `capture_dead_clicks`.|
|`features.webVitals`|Unset, follows the project|Sets `capture_performance: { web_vitals }`. Replay network timing keeps following the project.|
|`features.featureFlags`|Unset, follows the project|`false` sets `advanced_disable_feature_flags: true` and stops `/flags` requests.|
|`initOptions`|`{ cookieless_mode: 'on_reject', defaults: '2026-01-30' }`|Options passed to `posthog.init`, merged over the defaults and `features`. The helper sets `api_host` and `ui_host` after your values, so change hosts with the options above.|

## Loading and revocation

|`loadMode`|When PostHog loads|Consent sync|
|--|--|--|
|`'always'`|On every page, before consent|Calls `opt_in_capturing` or `opt_out_capturing` at load and on every change|
|`'after-consent'`|Only while measurement is allowed|Calls `opt_in_capturing` at load and `opt_out_capturing` on revocation|
|`'disabled'`|Never|None. The helper returns an empty callback-only script|

`posthog` uses the `measurement` category. With the default
`cookieless_mode: 'on_reject'`, PostHog keeps capturing without cookies after a
refusal. That mode needs cookieless server hashing turned on in your PostHog
project; see
[PostHog's cookieless guide](https://posthog.com/tutorials/cookieless-tracking).
Set `cookieless_mode: 'never'`, as in the example, if a refusal must stop
capture.

## Turn off features you do not use

After `array.js` loads, PostHog reads your `posthog.init` options and the
project's remote config, then decides which extra modules to download and
whether to request `/flags`. Set a `features` switch to `false` for each
feature your site does not use:

```ts
posthog({
	id: 'phc_YOUR_PROJECT_TOKEN',
	region: 'eu',
	loadMode: 'after-consent',
	features: {
		surveys: false,
		heatmaps: false,
		deadClicks: false,
		webVitals: false,
		featureFlags: false,
	},
});
```

|Switch|`false` sets|What PostHog skips|
|--|--|--|
|`surveys`|`disable_surveys: true`|`surveys.js`, about 29 KB|
|`heatmaps`|`capture_heatmaps: false`|Heatmap capture. With `deadClicks: false` too, `dead-clicks-autocapture.js`|
|`deadClicks`|`capture_dead_clicks: false`|`dead-clicks-autocapture.js`, about 8 KB, once heatmaps are off too|
|`webVitals`|`capture_performance: { web_vitals: false }`|`web-vitals-with-attribution.js`, about 6 KB|
|`featureFlags`|`advanced_disable_feature_flags: true`|`/flags` requests. The remote config still loads|

Sizes are brotli-compressed, measured from posthog-js 1.436.1.

An unset switch adds nothing to `posthog.init`. For heatmaps, dead clicks, web
vitals and feature flags, PostHog then follows the setting in your PostHog
project. `true` sets the opposite value and overrides the project. For
`surveys` and `featureFlags`, `true` is PostHog's own default, so it behaves
the same as unset.

Surveys work differently. PostHog downloads `surveys.js` whenever the remote
config includes a `surveys` value, even when surveys are off in the project.
`surveys: false` is the only way to skip it.

`initOptions` wins over a switch that sets the same key. A
`capture_performance` value in `initOptions` replaces the whole object that
`webVitals` builds.

### Avoid PostHog's option traps

These rules also apply when you pass PostHog options yourself, in
`initOptions` or in your own `posthog.init`:

* Use `advanced_disable_feature_flags: true` to stop `/flags`, not
  `advanced_disable_flags: true`. The second also stops PostHog loading the
  remote config, so session replay never starts and other features fall back to
  local config.
* With feature flags off, surveys that target a feature flag never show.
  PostHog logs a warning about it. If you need those surveys, leave
  `featureFlags` unset and pass
  `advanced_only_evaluate_survey_feature_flags: true` instead. PostHog still
  requests `/flags`, but evaluates only survey flags.
* While heatmaps are on, in `posthog.init` or in the project, PostHog loads
  `dead-clicks-autocapture.js` whatever `capture_dead_clicks` says. Turn off
  both to skip it.
* `capture_performance: false` turns off web vitals and session replay network
  timing. `{ web_vitals: false }`, which `webVitals: false` sets, leaves network
  timing to the project. `capture_performance: true` forces both on.

Product tours (`product-tours.js`, about 36 KB) and exception autocapture
(`exception-autocapture.js`, about 6 KB) load only when the project turns them
on. To keep them off whatever the project says, pass
`disable_product_tours: true` or `capture_exceptions: false` in `initOptions`.

## Guard your own capture calls

Events your code sends need their own permission check. The `posthog` global
exists before the SDK loads, so its presence does not mean measurement is
allowed:

```ts title="src/track-signup.ts"
export function trackSignupStarted(measurementAllowed: boolean) {
	if (!measurementAllowed) return;
	window.posthog?.capture('signup_started');
}
```

Pass the current measurement permission from your framework, for example
`useConsent('measurement')` in React.

## Use an existing PostHog SDK

If your app already initializes `posthog-js`, keep that setup and register a
callback-only script instead of the helper. Initialize the SDK with
`opt_out_capturing_by_default: true` and `cookieless_mode: 'never'` so it
captures nothing before c15t reports a permission.

```ts title="src/posthog-consent.ts"
import type { Script, ScriptCallbackInfo } from 'c15t/modules/script-loader';

type PostHogConsentApi = {
	opt_in_capturing: () => unknown;
	opt_out_capturing: () => unknown;
};

export function posthogConsent(instance: PostHogConsentApi): Script {
	const sync = ({ hasConsent }: ScriptCallbackInfo) => {
		if (hasConsent) instance.opt_in_capturing();
		else instance.opt_out_capturing();
	};

	return {
		id: 'posthog-sdk-consent',
		category: 'measurement',
		callbackOnly: true,
		alwaysLoad: true,
		onBeforeLoad: sync,
		onConsentChange: sync,
	};
}
```

Add `posthogConsent(posthog)` to the `scripts` you register, passing your
initialized SDK instance. `callbackOnly` means c15t inserts no script element.
`alwaysLoad` makes `onBeforeLoad` run on the first page load even while
measurement is denied, so the SDK is told to opt out. `onConsentChange` runs on
every later change. This does not delay the SDK import or its first request.
`loadMode: 'disabled'` is not a substitute, because it syncs nothing.

`features` belongs to the helper, so it does nothing here. To skip modules you
do not use, pass the PostHog options from
[turn off features you do not use](#turn-off-features-you-do-not-use) to your
own `posthog.init`, for example `disable_surveys: true`.

## Measure opt-in rate

If you run a banner experiment, the backend already counts visitors and
choices per arm. To see the arm in PostHog as well, forward the `onSurfaceShown` and
`onChoiceRecorded` callbacks, which carry `experiment: { id, arm }`. See
[banner experiments](/docs/guides/banner-experiments#send-the-events-to-your-own-analytics-too).

## Verify PostHog

These checks assume `loadMode: 'after-consent'` from the example. After you
allow measurement, `array.js` loads and capture requests to your API host
follow. Trigger one guarded event and check that it is sent.

With `loadMode: 'always'`, `array.js` loads before a choice instead. Check that
no capture request is sent while measurement is denied, unless you chose
cookieless capture.

If you turned features off, allow measurement and filter the DevTools Network
panel by `posthog`. Reload the page. You should see `array.js`, the remote
config and capture requests, but no `/flags` request with `featureFlags: false`
and none of the modules you turned off, such as `surveys.js` or
`dead-clicks-autocapture.js`.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Promptwatch
URL: https://c15t.com/docs/integrations/promptwatch
Load the Promptwatch attribution client only after measurement consent with the c15t promptwatch helper, and check it in DevTools.

## Configure Promptwatch

Copy the project ID from your Promptwatch dashboard. The helper passes it to
the client script as `data-project-id`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { promptwatch } from '@c15t/integrations/promptwatch';

export const scripts = [promptwatch({ projectId: 'YOUR_PROJECT_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`projectId`|Required|Project ID from the Promptwatch dashboard. Empty or whitespace-only values log an error and the script does not load.|
|`scriptUrl`|`https://ingest.promptwatch.com/js/client.min.js`|Loader URL override. Blank values fall back to the default.|

## Loading and revocation

`promptwatch` uses the `measurement` category. The client loads only while
measurement is allowed. On revocation the helper removes the script element
and calls no Promptwatch API.

The helper controls only the browser client. If your server also sends events
to Promptwatch, check the visitor's measurement permission there as well.

## Verify Promptwatch

After you allow measurement, the `client.min.js` request goes to
`ingest.promptwatch.com` and its script element carries your
`data-project-id`.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Pirsch
URL: https://c15t.com/docs/integrations/pirsch
Load Pirsch Analytics only after measurement consent with the c15t pirsch helper, keep custom event bindings working, and check it in DevTools.

## Configure Pirsch

Copy the identification code from your Pirsch installation snippet. The helper
passes it to the script as `data-code`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { pirsch } from '@c15t/integrations/pirsch';

export const scripts = [
	pirsch({ identificationCode: 'YOUR_IDENTIFICATION_CODE' }),
];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`identificationCode`|Required|Set as `data-code`. Empty or whitespace-only values log an error and the script does not load.|
|`domain`|None|Extra dashboard domains, each optionally as `domain:CODE`. An array becomes a comma-separated `data-domain`.|
|`dev`|None|Hostname Pirsch reports instead of localhost, set as `data-dev`. Use it to test locally.|
|`hitEndpoint`|None|Page view endpoint, set as `data-hit-endpoint`.|
|`eventEndpoint`|None|Event endpoint, set as `data-event-endpoint`.|
|`disablePageViews`|None|`true` adds `data-disable-page-views` and stops automatic page views.|
|`extended`|None|`true` loads `https://api.pirsch.io/pirsch-extended.js` instead of `pa.js`.|
|`scriptUrl`|`https://api.pirsch.io/pa.js`|Loader URL override. Blank values fall back to the default.|

Pirsch finds its script element by ID, so the helper sets the element ID to
`pianjs`, or to `pirschextendedjs` with `extended`.

## Loading and revocation

`pirsch` uses the `measurement` category. The script loads only while
measurement is allowed. Pirsch starts its custom event bindings from a
`DOMContentLoaded` listener, which has usually fired by the time a visitor
allows measurement. When the script loads on an already parsed page, the
helper calls `window.pirschInit()` so those bindings still start.

On revocation the helper removes the script element and calls no Pirsch API.

## Verify Pirsch

After you allow measurement, the `pa.js` request appears and the `#pianjs`
script element carries your `data-code`. Allow measurement after the page has
finished loading, then trigger a custom event and check that its request
appears. If your code calls `window.pirsch` directly, check measurement
permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# RudderStack
URL: https://c15t.com/docs/integrations/rudderstack
Load the RudderStack JavaScript SDK after measurement consent with the c15t rudderstack helper, or map c15t categories to destination consent IDs, and check each mode.

## Configure RudderStack

Copy the source write key and the HTTPS data plane URL from your RudderStack
source. Keep control-plane credentials out of the browser.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { rudderstack } from '@c15t/integrations/rudderstack';

export const scripts = [
	rudderstack({
		writeKey: 'YOUR_SOURCE_WRITE_KEY',
		dataPlaneUrl: 'https://your-data-plane.example.com',
	}),
];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`writeKey`|Required|Source write key. Surrounding whitespace is trimmed. An empty value logs an error and the script does not load.|
|`dataPlaneUrl`|Required|Data plane URL. A missing, invalid or non-HTTPS URL logs an error and the script does not load.|
|`consentManagement`|None|`{ mapping }` from c15t categories to RudderStack consent IDs. Switches to destination consent mode.|
|`loadOptions`|`{}`|Third argument to `rudderanalytics.load()`. Use JSON-serializable values only.|
|`trackPageView`|`true`|Queues `rudderanalytics.page()` before the loader.|
|`scriptUrl`|`https://cdn.rudderlabs.com/v3/modern/rsa.min.js`|Loader URL override. A non-HTTPS URL throws; a blank value uses the default.|

## Loading and revocation

`rudderstack` uses the `measurement` category. `consentManagement` picks the
mode:

|Mode|Loads|On consent change|On revocation|
|--|--|--|--|
|Default|After measurement is allowed, with `load` and `page` queued|Nothing|Removes the script element and calls no RudderStack API|
|`consentManagement`|On every page, in RudderStack's pre-consent state|Calls `rudderanalytics.consent()` with the mapped IDs|Keeps the SDK and calls `consent()` with the revoked IDs denied|

## Map destination consent

`consentManagement` loads the RudderStack SDK before the visitor chooses. Use
it only when every destination in your workspace carries a consent ID from the
mapping; c15t cannot check destination settings from the browser. Add the
mapping to the helper call:

```ts
rudderstack({
	writeKey: 'YOUR_SOURCE_WRITE_KEY',
	dataPlaneUrl: 'https://your-data-plane.example.com',
	consentManagement: {
		mapping: {
			measurement: ['YOUR_ANALYTICS_CONSENT_ID'],
			marketing: ['YOUR_ADVERTISING_CONSENT_ID'],
		},
	},
});
```

The helper sets `preConsent.enabled`, buffered event delivery and
`consentManagement.provider: 'custom'` in the load options. Storage defaults to
`{ strategy: 'none' }`; a `preConsent.storage` value in `loadOptions` replaces
it. Before `load`, the helper queues a `consent()` call. IDs of allowed
categories go to `allowedConsentIds` and IDs of denied categories go to
`deniedConsentIds`. A visitor who turns off the `rudderstack` vendor gets every
mapped ID denied. An empty mapping, or a category with no non-blank IDs, throws.

## Verify RudderStack

In the default mode, allowing measurement loads `rsa.min.js` with a
`data-rsa-write-key` attribute, and a page event goes to your data plane URL.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

With `consentManagement`, the SDK loads before the choice, so check your
destinations instead. Test in a private window with an opt-in policy:

1. Load the page. `rsa.min.js` loads before you choose. Destinations whose
   consent IDs map to a denied category receive no events.
2. Open Privacy settings and allow measurement. Without a reload,
   destinations with measurement IDs start receiving events. Destinations
   mapped only to marketing still receive none.
3. Turn measurement off and save. c15t reloads the page, and destinations with
   measurement IDs receive no events from the new page.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation and hosting checks.

# Segment
URL: https://c15t.com/docs/integrations/segment
Load Segment Analytics.js only after measurement consent with the c15t segment helper, guard your own track and identify calls, and check it in DevTools.

## Configure Segment

Copy the write key of your Segment JavaScript source. The helper builds the
loader URL from it.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { segment } from '@c15t/integrations/segment';

export const scripts = [segment({ writeKey: 'YOUR_SOURCE_WRITE_KEY' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`writeKey`|Required|Source write key. Empty or whitespace-only values log an error and the script does not load.|
|`loadOptions`|`{}`|Set as `window.analytics._loadOptions` before the loader runs. Analytics.js reads it on initialization.|
|`trackPageView`|`true`|Queues one `analytics.page()` call before the loader. Set `false` to send page views yourself.|
|`scriptUrl`|`https://cdn.segment.com/analytics.js/v1/<writeKey>/analytics.min.js`|Loader URL override.|

## Loading and revocation

`segment` uses the `measurement` category. Before measurement is allowed, c15t
defines no `window.analytics` and loads nothing from Segment. When measurement
becomes allowed, the helper creates the `window.analytics` queue with `track`,
`page`, `identify`, `group`, `alias` and `reset`, sets the load options,
queues the page view, then loads Analytics.js. On revocation the helper
removes the script element and calls no Segment API.

Segment forwards events to every destination enabled on the source. A
measurement grant does not cover a destination that needs marketing
permission. Configure destination consent in Segment, or load that vendor with
its own c15t helper instead.

## Guard your own Segment calls

The helper sends the first page view. Calls your code makes, such as `track`
and `identify`, need their own check. After revocation `window.analytics`
still exists, so its presence does not mean measurement is allowed. Check the
permission first, then that the queue exists:

```ts title="src/track-signup.ts"
export function trackSignup(measurementAllowed: boolean, plan: string) {
	if (!measurementAllowed || !window.analytics) return;
	window.analytics.track('Signup', { plan });
}
```

Pass the current measurement permission from your framework, for example
`useConsent('measurement')` in React. Analytics.js sends no page view on
client-side route changes, so call `window.analytics.page()` from your router
behind the same check.

## Verify Segment

After you allow measurement, `analytics.min.js` loads from `cdn.segment.com`
with your write key in the path, and a page call goes to `api.segment.io`.
Check that each browser destination on the source loads only under the
permission it needs. Then revoke measurement. Before the reload, calling
`trackSignup` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Sentry
URL: https://c15t.com/docs/integrations/sentry
Configure Sentry's CDN or your own SDK with consent for error monitoring, Session Replay and user data.

## Configure Sentry

Remove any existing Sentry Loader Script or CDN tags, then add this configuration.
Errors run before consent by default; Replay and SDK data collection wait for
`measurement`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { sentry } from '@c15t/integrations/sentry';

export const scripts = [
	sentry({
		dsn: 'https://your-key@o0.ingest.sentry.io/0',
		initOptions: {
			release: 'my-app@1.0.0',
			replaysOnErrorSampleRate: 1,
			replaysSessionSampleRate: 0.1,
			tracesSampleRate: 0.1,
		},
	}),
];
```

The default SDK is 11.4.0 with subresource integrity: `bundle.min.js`, or
`bundle.tracing.min.js` when traces are sampled. `replay.min.js` loads after
consent when a Replay sample rate is above 0.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Use your own Sentry SDK

For `@sentry/*` 10.67.0 or later, pass your SDK's functions instead of `dsn`.
Keep Replay in a separate module so it can load after consent:

```ts title="src/sentry-replay.ts"
import { replayIntegration } from '@sentry/browser';

export const createReplay = () =>
	replayIntegration({ maskAllText: true, blockAllMedia: true });
```

In `src/consent-scripts.ts`, replace the CDN configuration with:

```ts
import { getClient, init, setUser } from '@sentry/browser';

sentry({
	getClient,
	init,
	setUser,
	initOptions: {
		dsn: 'https://your-key@o0.ingest.sentry.io/0',
		replaysSessionSampleRate: 0.1,
		replaysOnErrorSampleRate: 1,
	},
	replay: {
		load: () => import('./sentry-replay').then((m) => m.createReplay()),
	},
});
```

Passing `init` protects startup captures before other SDK integrations run.
Custom initializers must forward the supplied options to `Sentry.init`, including
after a dynamic import. Avoid initialization as an import side effect.

Use named imports from the same Sentry package throughout your app. Next.js and
Vite split dynamically imported Replay into its own chunk; esbuild and Bun keep
it in the main bundle. A main-bundle `Sentry.replayIntegration` reference through
`import * as Sentry` also prevents the split.

### If Sentry already initializes independently

c15t applies filters once it finds the client; it cannot retract earlier data.
For startup protection, disable collection and remove event users in your own
`Sentry.init` call. With SDK 10.67, omit `queues`:

```ts
// Include these options in your app's Sentry.init call.
maxBreadcrumbs: 0,
dataCollection: {
	userInfo: false,
	cookies: false,
	httpHeaders: { request: false, response: false },
	httpBodies: [],
	urlQueryParams: false,
	graphQL: { document: false, variables: false },
	genAI: { inputs: false, outputs: false },
	databaseQueryData: false,
	queues: false,
	stackFrameVariables: false,
	frameContextLines: 0,
},
beforeSend(event) {
	delete event.user;
	delete event.request;
	return event;
},
```

These settings keep collection and event users disabled after consent too.
To restore event users, check effective c15t permission in `beforeSend`. Wait
until the adapter is registered before assigning scope users or capturing logs
and metrics.

## Options

|Option|Default|Behavior|
|--|--|--|
|`dsn`|Required to load Sentry|Your project's DSN. c15t loads the SDK and calls `Sentry.init`. A blank DSN logs an error and the script does not load.|
|`initOptions`|`{}`|Passed to `Sentry.init` with c15t's consent integration first. CDN `integrations` callbacks can access `window.Sentry`.|
|`version`|`'11.4.0'`|SDK version to load. Another version loads without subresource integrity.|
|`tracing`|`true` when traces are sampled|Loads the tracing bundle and adds `browserTracingIntegration()`.|
|`replay`|Loads CDN Replay when sampled|CDN: `{ category, options }` or `false`. SDK: `{ category, load }`.|
|`getClient`|Required for your own SDK|Your SDK's `getClient`. Supports initialization after c15t starts.|
|`setUser`|None|`setUser` from your Sentry SDK. Called with `null` while user data is not allowed. Required with `pii.user`.|
|`init`|None|Your SDK's `init`, called once when `loadMode` allows. Required for SDK mode with `'after-consent'`.|
|`replay.load`|None|With your own SDK, returns a new `replayIntegration()`. Called once, the first time Replay is allowed.|
|`loadMode`|`'always'`|When error monitoring runs. See the table below.|
|`replay.category`|`'measurement'`|Consent condition for Replay. `pii.category` must also be allowed.|
|`pii.category`|`'measurement'`|Consent condition for SDK data collection and user data. `'necessary'` permits it while the Sentry vendor is enabled.|
|`pii.user`|None|Returns the user to set when user data becomes allowed.|
|`onError`|Report to an available Sentry client|Receives CDN and Replay lifecycle failures. Set it to report CDN download failures before Sentry exists.|

Replay's category is registered only with an SDK `replay.load` function or
enabled CDN Replay with a positive sample rate.

## Loading and revocation

|`loadMode`|When Sentry runs|On withdrawal without a reload|
|--|--|--|
|`'always'`|On every page, before consent|Replay stops; errors keep reaching Sentry without user data|
|`'after-consent'`|Only while `measurement` is allowed|Sentry stops sending anything|

Replay needs both `replay.category` and `pii.category`, because recordings
include page URLs with queries and fragments. Keep Replay out of `Sentry.init`:
`replaysOnErrorSampleRate` can buffer recordings before consent. On denial or
final removal, c15t stops Replay without flushing, discards queued uploads and
blocks restarts. Data already sent stays in Sentry; a later grant preserves
the original sampling decision.

While PII is denied, c15t disables supported `dataCollection` settings and IP
inference. Before sending, it removes user fields, feedback contact details,
visitor identifiers in sessions, request data and URL queries/fragments from
supported events, spans, logs, metrics and breadcrumbs, including retained
breadcrumbs. A grant restores your resolved collection settings and allowlists.
Tracing itself is not gated. Custom messages, tags, extras, attachments and
URL paths remain diagnostics, so keep sensitive values out of them.

The vendor slug is `sentry`. Turning it off denies Replay and PII, plus errors
in `'after-consent'` mode. See [vendor consent](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

### Shared clients and configuration changes

Keep callback functions stable across renders. Equal options and callbacks
reuse the SDK bundle and active recording. Changed CDN options initialize a
client with the new DSN and settings, while reusing the page's single Replay
recorder. Its original Replay options and sampling decision last until reload.

Every active configuration targeting one client must allow each feature;
removing a loader releases its restriction and preserves surviving loaders and
downloads. Final removal denies PII and stops Replay, and also disables errors
in `'after-consent'` mode. An app-initiated `Sentry.close()` stays closed after
a grant. Separate clients have separate permissions.

## Content security policy

Allow `worker-src blob:` for Replay and your ingest or tunnel endpoint in
`connect-src`. CDN mode also needs `https://browser.sentry-cdn.com` in
`script-src`. The loader or provider's `nonce` applies to both CDN bundles;
a per-script nonce overrides it.

## Verify Sentry

Test in a private window with an opt-in policy and
`replaysSessionSampleRate: 1`. Filter DevTools Network by `sentry`.

1. Load the page. `bundle.min.js` loads and errors reach Sentry, without `user`.
   No `replay.min.js` or `replay_recording` request is sent. With
   `loadMode: 'after-consent'`, nothing loads.
2. Allow measurement. Without a reload, Replay loads and `replay_recording`
   requests start.
3. Turn measurement off and save. c15t reloads the page, and no replay request
   follows.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation, expiry and hosting checks.

# Rybbit Analytics
URL: https://c15t.com/docs/integrations/rybbit-analytics
Load Rybbit Analytics only after measurement consent with the c15t rybbitAnalytics helper, map its tracking options to data attributes, and check it in DevTools.

## Configure Rybbit Analytics

Copy the site ID from your Rybbit tracking snippet. The helper passes it to
the script as `data-site-id`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { rybbitAnalytics } from '@c15t/integrations/rybbit-analytics';

export const scripts = [rybbitAnalytics({ siteId: 'YOUR_SITE_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

Boolean options become `'true'` or `'false'` data attributes. An option you
leave unset adds no attribute, so Rybbit uses its own default.

|Option|Default|Behavior|
|--|--|--|
|`siteId`|Required|Site ID as a string or number, set as `data-site-id`. Empty or whitespace-only values log an error and the script does not load.|
|`autoTrackPageview`|None|Automatic page views, set as `data-auto-track-pageview`.|
|`trackSpa`|None|Client-side route tracking, set as `data-track-spa`.|
|`trackQuery`|None|Query strings in tracked URLs, set as `data-track-query`.|
|`trackOutbound`|None|Outbound link clicks, set as `data-track-outbound`.|
|`trackErrors`|None|JavaScript errors, set as `data-track-errors`.|
|`sessionReplay`|None|Session replay, set as `data-session-replay`.|
|`webVitals`|None|Web Vitals, set as `data-web-vitals`.|
|`skipPatterns`|None|URL patterns to skip, written as a JSON array to `data-skip-patterns`.|
|`maskPatterns`|None|URL patterns to mask, written as a JSON array to `data-mask-patterns`.|
|`debounce`|None|Page view debounce interval, set as `data-debounce`.|
|`apiKey`|None|Tracking API key, set as `data-api-key`. The key is visible in the page source.|
|`analyticsHost`|None|Self-hosted Rybbit host. The helper loads `<analyticsHost>/script.js`.|
|`scriptUrl`|`https://app.rybbit.io/api/script.js`|Loader URL override. Takes precedence over `analyticsHost`. Blank values are ignored.|

## Loading and revocation

`rybbitAnalytics` uses the `measurement` category. The script loads only while
measurement is allowed, and every feature you turn on, including session
replay and Web Vitals, runs under that one category. On revocation the helper
removes the script element and calls no Rybbit API.

## Verify Rybbit Analytics

After you allow measurement, the `script.js` request goes to `app.rybbit.io`
or your `analyticsHost`, and its script element carries your `data-site-id`.
Each option you set appears as a data attribute, including explicit `'false'`
values. If your code calls `window.rybbit.event` or `window.rybbit.identify`,
check measurement permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Umami Analytics
URL: https://c15t.com/docs/integrations/umami-analytics
Load the Umami Analytics tracker only after measurement consent with the c15t umamiAnalytics helper, point it at a self-hosted instance, and check it in DevTools.

## Configure Umami Analytics

Copy the website ID from your Umami tracking code. The helper passes it to the
script as `data-website-id`. For a self-hosted Umami instance, set `scriptUrl`
to your instance's tracker script.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { umamiAnalytics } from '@c15t/integrations/umami-analytics';

export const scripts = [umamiAnalytics({ websiteId: 'YOUR_WEBSITE_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`websiteId`|Required|Set as `data-website-id`. Empty or whitespace-only values log an error and the script does not load.|
|`hostUrl`|None|Host that receives events, set as `data-host-url`.|
|`autoTrack`|None|`false` sets `data-auto-track="false"` and stops automatic tracking.|
|`domains`|None|Domains to track, set as `data-domains`. Pass a comma-separated string or an array; the helper joins an array with commas.|
|`tag`|None|Tag attached to events, set as `data-tag`.|
|`beforeSend`|None|Name of a global function, set as `data-before-send`. Function values are not supported.|
|`scriptUrl`|`https://cloud.umami.is/script.js`|Loader URL override.|

## Loading and revocation

`umamiAnalytics` uses the `measurement` category. The tracker loads only while
measurement is allowed. On revocation the helper removes the script element and
calls no Umami API. Umami sets no cookies, but c15t still waits for measurement
permission before loading it.

A `beforeSend` hook can change events before Umami sends them. It is not a
consent check. Define the named global before the tracker loads.

## Verify Umami Analytics

After you allow measurement, the tracker script loads with your
`data-website-id`, and a request to `/api/send` goes to Umami or to your
`hostUrl`. If your code calls `window.umami.track`, check measurement
permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Vercel Analytics
URL: https://c15t.com/docs/integrations/vercel-analytics
Load the Vercel Web Analytics script only after measurement consent with the c15t vercelAnalytics helper, choose the debug script, and check it in DevTools.

## Configure Vercel Analytics

Enable Web Analytics for the project in Vercel. Remove the `Analytics`
component or `inject()` call from `@vercel/analytics` so c15t loads the
script once.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { vercelAnalytics } from '@c15t/integrations/vercel-analytics';

export const scripts = [vercelAnalytics()];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`dsn`|None|Project DSN for deployments outside Vercel, set as `data-dsn`.|
|`disableAutoTrack`|None|`true` sets `data-disable-auto-track="1"` and stops automatic page views.|
|`mode`|None|`'development'` loads the debug script. `'auto'` and `'production'` load the production script. The helper does not detect your environment.|
|`debug`|None|`true` loads `https://va.vercel-scripts.com/v1/script.debug.js`.|
|`endpoint`|None|Custom ingestion endpoint, set as `data-endpoint`.|
|`scriptUrl`|`https://va.vercel-scripts.com/v1/script.js`|Loader URL override. Takes precedence over `mode` and `debug`.|

The helper also sets `data-sdkn="c15t"` on the script element.

## Loading and revocation

`vercelAnalytics` uses the `measurement` category. When measurement becomes
allowed, the helper defines the `window.vaq` queue and a `window.va` stub,
unless they exist, then loads the script. Calls to `window.va` made before the
script finishes loading wait in `window.vaq`.

On revocation the helper removes the script element and calls no Vercel API.

## Verify Vercel Analytics

After you allow measurement, `script.js` loads from `va.vercel-scripts.com`
with `data-sdkn="c15t"`, and each client-side navigation sends one page view.
With `debug` or `mode: 'development'` the helper loads `script.debug.js`
instead, so a working debug build does not prove your production settings.
After revocation `window.va` still exists, so if your code sends custom events
through it, check measurement permission before each call.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Crisp
URL: https://c15t.com/docs/integrations/crisp
Load the Crisp chat widget only after functionality consent with the c15t crisp helper, pass its runtime settings and check it in DevTools.

## Configure Crisp

Copy the website ID from your Crisp installation snippet, where it is assigned
to `CRISP_WEBSITE_ID`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { crisp } from '@c15t/integrations/crisp';

export const scripts = [crisp({ websiteId: 'YOUR_WEBSITE_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`websiteId`|Required|Written to `window.CRISP_WEBSITE_ID`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`locale`|None|Widget locale, written to `window.CRISP_RUNTIME_CONFIG.locale`.|
|`sessionMerge`|None|Merges anonymous sessions into token-backed sessions. Written to `CRISP_RUNTIME_CONFIG.session_merge`.|
|`tokenId`|None|Session continuity token, written to `window.CRISP_TOKEN_ID`.|
|`cookieDomain`|None|Cookie domain, written to `window.CRISP_COOKIE_DOMAIN`.|
|`cookieExpiry`|None|Cookie lifetime in seconds, written to `window.CRISP_COOKIE_EXPIRE`.|
|`safeMode`|`false`|Pushes `['safe', true]` to `$crisp` before the loader.|
|`scriptSrc`|`https://client.crisp.chat/l.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`crisp` uses the `functionality` category. The chat widget loads only while
functionality is allowed, so link another support contact for visitors who
deny it. On revocation the helper removes the script element and calls no
Crisp API. The running widget stays until c15t reloads the page.

Before loading, the helper creates `window.$crisp` as an empty array unless
your page already made one. Commands your code pushed onto `$crisp` earlier
stay queued, and Crisp runs them when it loads. They never reach Crisp while
functionality is denied.

## Verify Crisp

After you allow functionality, the request to `client.crisp.chat/l.js` appears
and the chat launcher shows. Before that, `window.CRISP_WEBSITE_ID` is
undefined.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Front Chat
URL: https://c15t.com/docs/integrations/front-chat
Load the Front Chat widget only after functionality consent with the c15t frontChat helper, forward CSP nonces, clear the session on revocation and check it in DevTools.

## Configure Front Chat

Copy the `chatId` from the widget snippet in your Front Chat channel's
**Installation** tab.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { frontChat } from '@c15t/integrations/front-chat';

export const scripts = [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`chatId`|Required|Public chat ID passed to `FrontChat('init')`. Surrounding whitespace is trimmed. An empty value logs an error and the script does not load.|
|`useDefaultLauncher`|`true`|Shows Front's launcher. With `false`, open the widget from your own launcher through Front's [SDK](https://dev.frontapp.com/docs/chat-sdk-reference).|
|`nonce`|None|CSP nonce for the loader and Front's generated scripts. A loader nonce from your consent provider is forwarded to `init` too.|
|`scriptSrc`|`https://chat-assets.frontapp.com/v1/chat.bundle.js`|Loader URL override. A proxy here does not proxy the widget's other requests.|

Front creates more resources for the widget. Follow Front's
[CSP instructions](https://help.front.com/en/articles/2049) for the rest of the
policy.

## Loading and revocation

`frontChat` uses the `functionality` category and appends its loader to
`<body>` once functionality is allowed. After the SDK loads, the helper calls
`FrontChat('init')` with your chat ID. If functionality is revoked while the
SDK is still downloading, the helper skips `init`.

On revocation the helper removes the loader element and calls no Front API.
The running widget stays until c15t reloads the page, so keep
`reloadOnConsentRevoked` enabled.

## Clear the Front session on revocation

The reload removes the widget but keeps the visitor's Front session. To clear
it, call `shutdownFrontChat()` from the `onBeforeConsentRevocationReload`
callback in your consent options:

```ts title="src/consent-callbacks.ts"
import { shutdownFrontChat } from '@c15t/integrations/front-chat';

export const callbacks = {
	onBeforeConsentRevocationReload: ({ preferences }) => {
		if (!preferences.functionality) {
			shutdownFrontChat();
		}
	},
};
```

`shutdownFrontChat` sends `FrontChat('shutdown', { clearSession: true })` when
the SDK has loaded and does nothing otherwise. Front returns no completion
signal, so the reload does not wait for the session to clear.

## Verify Front Chat

After you allow functionality, `chat.bundle.js` loads and the widget connects
to your Front inbox. With `shutdownFrontChat` wired, revoke functionality and
check that the next grant starts a new Front session.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Intercom
URL: https://c15t.com/docs/integrations/intercom
Load the Intercom messenger only after functionality consent with the c15t intercom helper, set its region and check it in DevTools.

## Configure Intercom

Copy the app ID from your Intercom installation snippet, where it is set as
`app_id`. If your workspace is hosted in the EU or Australia, also set
`apiBase`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { intercom } from '@c15t/integrations/intercom';

export const scripts = [intercom({ appId: 'YOUR_APP_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`appId`|Required|Sets `app_id` and the loader URL. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`apiBase`|`https://api-iam.intercom.io`|Regional API base. `INTERCOM_API_BASES` from `@c15t/integrations/intercom` lists `us`, `eu` and `au`.|
|`settings`|None|Extra JSON-serializable settings merged into `window.intercomSettings`. `appId` and `apiBase` override any `app_id` or `api_base` here.|
|`scriptSrc`|`https://widget.intercom.io/widget/<appId>`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`intercom` uses the `functionality` category. Once functionality is allowed,
the helper defines a queueing `window.Intercom` stub, writes
`window.intercomSettings` and loads the messenger. On revocation it removes the
script element and calls no Intercom API, including `shutdown`. The messenger
keeps running until c15t reloads the page.

## Guard your own Intercom calls

The helper writes `settings` once, before the messenger loads. It does not
update them when a user logs in or out, so send identity changes through
Intercom's messenger API yourself. After revocation `window.Intercom` still
exists, so its presence does not mean functionality is allowed. Check the
permission first:

```ts title="src/intercom-user.ts"
export function updateIntercomUser(
	functionalityAllowed: boolean,
	userId: string
) {
	if (!functionalityAllowed || typeof window.Intercom !== 'function') return;
	window.Intercom('update', { user_id: userId });
}
```

Pass the current functionality permission from your framework, for example
`useConsent('functionality')` in React.

## Verify Intercom

After you allow functionality, the request to
`widget.intercom.io/widget/<appId>` appears and the messenger shows. Log in
and out of your app, and check that the messenger never shows the previous
user's conversations.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Klaviyo
URL: https://c15t.com/docs/integrations/klaviyo
Load Klaviyo signup forms and onsite tracking only after marketing and measurement consent with the c15t klaviyo helper, gate your own events, and check it in DevTools.

## Configure Klaviyo

Copy the six-character public API key, also called the site ID, from
**Settings > Account > API keys** in Klaviyo. It appears in every page that
loads Klaviyo, so it is safe in browser code. Never put a private key
(`pk_...`) in the browser. If you pass one, the helper logs an error and
Klaviyo does not load.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { klaviyo } from '@c15t/integrations/klaviyo';

export const scripts = [klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY' })];
```

Remove Klaviyo's own snippet first. On Shopify, BigCommerce, WooCommerce and
the other platforms where Klaviyo installs Klaviyo.js for you, turn that
installation off, or c15t is not the only thing loading it.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`publicApiKey`|Required|Six-letter-or-digit public API key. Surrounding whitespace is trimmed. Any other value, including a missing key, logs an error and the script does not load. Private keys get their own message.|
|`mode`|`'full'`|`'full'` loads forms and web tracking. `'forms-only'` turns Klaviyo's web tracking off before the bundle starts; see [forms-only mode](#forms-only-mode).|
|`category`|`{ and: ['marketing', 'measurement'] }`, or `'marketing'` in forms-only mode|Consent condition that must hold before Klaviyo.js loads. Accepts any category or `and`/`or`/`not` condition.|
|`scriptUrl`|`https://static.klaviyo.com/onsite/js/<publicApiKey>/klaviyo.js`|Loader URL override, such as a first-party proxy. Must be `https:`. A blank value falls back to the default.|

## Why Klaviyo needs two categories

One script, Klaviyo.js, serves both signup forms and Active on Site tracking.
Klaviyo offers no setting or browser API to load one without the other. Forms
grow your marketing lists, and tracking records which identified visitors are
on the site and feeds segments, attribution and automated email and SMS flows.
Klaviyo classifies its `__kla_id` cookie as a targeting cookie.

So by default `klaviyo` loads only when both marketing and measurement are
allowed. With either category alone, or neither, c15t requests nothing from
Klaviyo and Klaviyo writes no storage. Once the second category is allowed,
Klaviyo.js loads without a page reload, once.

If your legal review classifies Klaviyo differently, or your account uses only
part of it, pass your own condition:

```ts
klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY', category: 'marketing' });
```

## Forms-only mode

`mode: 'forms-only'` loads Klaviyo.js once marketing is allowed and sets
Klaviyo's `__kla_off=true` cookie before the bundle runs. Klaviyo documents
this cookie as the switch that keeps forms working while it stops tracking.

```ts
klaviyo({ publicApiKey: 'YOUR_PUBLIC_API_KEY', mode: 'forms-only' });
```

In this mode Klaviyo.js sends no Active on Site events, and `identify` and
`track` calls send nothing. It is not a cookieless mode:

* Klaviyo.js still writes an anonymous `__kla_id` cookie, plus the Web Storage
  keys listed in [storage](#storage-klaviyo-writes).
* Form views and steps are still reported to Klaviyo's form analytics, and
  each report carries the anonymous visitor ID from `__kla_id`.
* Forms cannot target by visitor type, such as hiding a form from existing
  subscribers.
* A submission still creates the profile and records the subscription, but
  the browser stays unidentified, so Klaviyo records no onsite activity for
  that person afterwards.
* The mode is fixed when the page loads. Allowing measurement later does not
  turn tracking on. Switch to `mode: 'full'` in your configuration for that.
* `__kla_off` is a session cookie, and the helper never deletes it, since a
  site or visitor may also set it to opt out. If you move a site from
  forms-only to full mode, visitors who saw the forms-only version keep
  tracking off until they close the browser.

There is no measurement-only mode. Klaviyo cannot suppress published forms
while still tracking visitors.

## Vendor switches, opt-out regions and IAB mode

The helper sets the vendor slug `klaviyo`, so a visitor can allow marketing
and measurement and still switch Klaviyo off. Declare the vendor with a name
and privacy policy URL so your preference UI can show the switch; until then
c15t logs a warning in the console. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

* With the switch off, Klaviyo.js does not load. Switching it off after
  Klaviyo has loaded reloads the page, and the new page loads nothing from
  Klaviyo.
* `clearOnRevocation` runs per category, so switching off only the vendor
  leaves `__kla_id` and Klaviyo's other storage in place. Klaviyo stops reading
  them because it no longer loads.
* In regions whose policy allows marketing and measurement before a choice,
  such as most of the US, Klaviyo.js loads on the first page view. A visitor
  sending Global Privacy Control has both denied, so Klaviyo does not load.
* In IAB TCF mode, vendor switches are ignored. Klaviyo has no TCF vendor ID
  in this helper, so it loads once the TCF purposes behind marketing (2, 3
  and 4) and measurement (7, 8 and 9) are all granted.

## Send your own events only with consent

The helper never calls `identify`, `track` or Klaviyo's Viewed Product and
Added to Cart snippets. Send them from your own code.

Before Klaviyo.js loads, the helper installs the `klaviyo` object from
Klaviyo's onsite snippet. Calls made before the bundle arrives are queued, and
Klaviyo.js replays them. The object exists only after the helper's consent
condition held on this page, so optional chaining drops calls made without
consent:

```ts
window.klaviyo?.track('Added to Cart', {
	ProductName: product.name,
	Price: product.price,
});
```

This check assumes c15t reloads the page on revocation, which it does by
default. With `reloadOnConsentRevoked: false`, the object stays after a
revocation, so check the categories with your framework's consent API before
each call. In forms-only mode, Klaviyo drops these calls even though the
object exists.

## Account settings that change what Klaviyo collects

c15t controls when Klaviyo.js loads. These Klaviyo account settings control
what it does once loaded:

* **Anonymous visitor activity backfill** stores frontend events for
  unidentified visitors in local storage (`kl-post-identification-sync`) for
  up to 14 days, then sends them when the visitor is identified. Klaviyo says
  this needs both analytics and marketing consent. Turn it off under
  **Settings > Account > Data**, *Enable anonymous visitor tracking*.
* **Extended ID** and **First-Party ID** restore an identity after `__kla_id`
  expires; First-Party ID adds a `__kle_id` cookie. Klaviyo recommends
  updating your cookie notice before enabling either.
* **Email and SMS click tracking** identifies visitors who arrive from a
  Klaviyo message through the `_kx` URL parameter. It can only be turned off
  for the whole account.

## Cookie consent is not subscription consent

Your c15t banner asks whether Klaviyo may run in the browser. A Klaviyo signup
form asks whether someone wants your emails or texts. They are separate
records: allowing marketing cookies does not subscribe anyone, and a
subscription does not grant cookie consent. Keep collecting email and SMS
consent in Klaviyo forms, with the wording your channels require.

## Storage Klaviyo writes

Observed with Klaviyo.js in October 2026. Klaviyo can change these names.

|Storage|Names|
|--|--|
|Cookies|`__kla_id` (up to two years after identification), `__kle_id` with First-Party ID, `__kla_off` in forms-only mode, `datadome` after a form submission triggers bot protection|
|Local storage|`klaviyoOnsite`, `__kl_key`, `$referrer`, `$last_referrer`, `kl-post-identification-sync`, `ddSession`|
|Session storage|`klaviyoPagesVisitCountV2`, `klaviyoFormSubmit`, `_kx`, `ddCookieCandidateDomain`|

The `datadome` and `dd*` names come from DataDome, the bot protection Klaviyo
runs on form submissions.

To delete them when a visitor turns either category off, add them to
`clearOnRevocation` under both categories:

```ts
const klaviyoStorage = {
	cookies: ['__kla_id', '__kle_id', 'datadome'],
	localStorage: [
		'klaviyoOnsite',
		'__kl_key',
		'$referrer',
		'$last_referrer',
		'kl-post-identification-sync',
		'ddSession',
	],
	sessionStorage: [
		'klaviyoPagesVisitCountV2',
		'klaviyoFormSubmit',
		'_kx',
		'ddCookieCandidateDomain',
	],
};

const clearOnRevocation = {
	marketing: klaviyoStorage,
	measurement: klaviyoStorage,
};
```

See [clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup)
for where the option goes. In forms-only mode, list the storage under
`marketing` only.

## Content Security Policy

Klaviyo.js appends its modules as new script elements without a nonce. A
popup signup form with default styling used these hosts in testing:

|Directive|Hosts|
|--|--|
|`script-src`|`https://static.klaviyo.com`, `https://static-tracking.klaviyo.com`|
|`connect-src`|`https://a.klaviyo.com`, `https://fast.a.klaviyo.com`, `https://static-forms.klaviyo.com`|
|`style-src`|`https://static.klaviyo.com`, `https://fonts.googleapis.com`|
|`img-src`|`https://d3k81ch9hvuctc.cloudfront.net`|
|`frame-src`|`https://geo.captcha-delivery.com`, for the bot check some submissions get|

When DataDome, the bot protection Klaviyo runs on submissions, challenges a
visitor, it loads its check in a frame. Fonts, images and features differ
between forms, so test each published form under your policy.

## Verify Klaviyo

Filter DevTools Network by `klaviyo`:

1. Allow marketing only. Nothing loads from Klaviyo, and the Application tab
   shows no `__kla_id` cookie.
2. Allow measurement too. `klaviyo.js` loads from
   `static.klaviyo.com/onsite/js/<your key>/`, followed by Klaviyo's modules
   from `static.klaviyo.com` and `static-tracking.klaviyo.com`.
3. In full mode, `await klaviyo.account()` in the console returns your public
   API key. In forms-only mode it returns `null`.
4. A published signup form appears in both modes. The form request goes to
   `static-forms.klaviyo.com/forms/api/v7/<your key>/full-forms`.
5. In forms-only mode, the console shows Klaviyo's warning that tracking is
   disabled, and an `identify` call sends no request to
   `a.klaviyo.com/client/`.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Meta Pixel
URL: https://c15t.com/docs/integrations/meta-pixel
Load the Meta Pixel only after marketing consent with the c15t metaPixel helper, guard fbq event calls, and check it in DevTools.

## Configure the Meta Pixel

Copy the pixel ID from Meta Events Manager. Remove the original pixel snippet,
its `<noscript>` tracking image and any tag-manager entry that loads the same
pixel.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { metaPixel } from '@c15t/integrations/meta-pixel';

export const scripts = [metaPixel({ pixelId: '123456789012345' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID passed to `fbq('init', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`initOptions`|None|Object passed as the third argument to `fbq('init', ...)`.|
|`trackPageView`|`true`|Queues `fbq('track', 'PageView')` after `init`. Set `false` to send page views yourself.|
|`dataProcessingOptions`|None|`{ options, country?, state? }`. Queues `fbq('dataProcessingOptions', ...)` before `init`, for example `{ options: ['LDU'], country: 1, state: 1000 }` for Limited Data Use in California.|
|`scriptSrc`|`https://connect.facebook.net/en_US/fbevents.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`metaPixel` uses the `marketing` category. Before marketing is allowed, c15t
defines no `fbq` function and loads nothing from Meta. When marketing becomes
allowed, the helper queues `fbq('consent', 'grant')`, the optional data
processing options, `init` and `PageView`, then loads `fbevents.js`.

On revocation the helper keeps the pixel script and calls
`fbq('consent', 'revoke')`. If the visitor allows marketing again before the
page reloads, it calls `fbq('consent', 'grant')`.

## Guard your own fbq calls

The helper sends the pixel's page view. Events your code sends, such as
`Purchase` or `Lead`, need their own check. After revocation `window.fbq` still
exists, so its presence does not mean marketing is allowed. Check the
permission first, then that the pixel has loaded:

```ts title="src/track-purchase.ts"
export function trackPurchase(marketingAllowed: boolean, value: number) {
	if (!marketingAllowed || typeof window.fbq !== 'function') return;
	window.fbq('track', 'Purchase', { currency: 'USD', value });
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. `@c15t/integrations/meta-pixel` also exports
typed wrappers: `metaPixelEvent`, `metaPixelCustomEvent`,
`metaPixelSingleEvent` and `metaPixelSingleCustomEvent`. They do nothing while
`window.fbq` is undefined, before the pixel's first setup. They do not check
permission, and after revocation `window.fbq` still exists, so apply the
permission check before calling them.
Their last argument accepts an event ID string for Conversions API
deduplication.

## Verify the Meta Pixel

After you allow marketing, `fbevents.js` loads and a request to
`facebook.com/tr` carries `ev=PageView`. Trigger one guarded event and check
that its `tr` request appears. Then revoke marketing. Before the reload,
calling `trackPurchase` sends nothing. With client-side navigation, check that
each route change sends one page view, not two.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# OpenAI Pixel
URL: https://c15t.com/docs/integrations/openai-pixel
Load the ChatGPT Ads Measurement Pixel only after marketing consent with the c15t openaiPixel helper, guard oaiq conversion calls, and check it in DevTools.

## Configure the OpenAI Pixel

Copy the pixel ID from the conversions tab in OpenAI Ads Manager. Remove the
standalone OpenAI installation snippet, because the helper creates the `oaiq`
queue and initializes the pixel itself.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { openaiPixel } from '@c15t/integrations/openai-pixel';

export const scripts = [openaiPixel({ pixelId: 'YOUR_PIXEL_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID passed to `oaiq('init', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`debug`|`false`|Logs SDK activity, including queued and dropped events, to the browser console.|
|`user`|None|User matching fields passed to `init`: `email_sha256`, `phone_number_sha256`, `external_id_sha256`, `first_name_sha256`, `last_name_sha256`, `country`, `city`, `region` and `postal_code`.|
|`scriptSrc`|`https://bzrcdn.openai.com/sdk/oaiq.min.js`|SDK URL override. A blank value falls back to the default.|

c15t forwards `user` unchanged. Normalize and hash identifiers yourself as
OpenAI's
[user data rules](https://developers.openai.com/ads/measurement-pixel#send-user-data)
describe. If user data arrives after initialization, call
`window.oaiq('init', { pixelId, user })` again with the complete object.

## Loading and revocation

`openaiPixel` uses the `marketing` category. Before marketing is allowed, c15t
defines no `oaiq` function and loads nothing from OpenAI. Measurement
permission alone does not load the pixel. When marketing becomes allowed, the
helper queues `oaiq('consent', false)`, `init` and `oaiq('consent', true)`,
then loads `oaiq.min.js`. The first call overrides the SDK's default consent of
`true`.

On revocation the helper keeps the SDK and calls `oaiq('consent', false)`. If
the visitor allows marketing again before the page reloads, it calls
`oaiq('consent', true)` without reinitializing the pixel. OpenAI drops events
sent while consent is denied and does not replay them later. The SDK can still
send diagnostic pings while consent is denied.

## Guard your own oaiq calls

The helper sends no page view or conversion, so every event comes from your
code. After revocation `window.oaiq` still exists, so its presence does not
mean marketing is allowed. Check the permission first, then that the queue
exists:

```ts title="src/track-order.ts"
export function trackOrder(marketingAllowed: boolean, orderId: string) {
	if (!marketingAllowed || typeof window.oaiq !== 'function') return;
	window.oaiq(
		'measure',
		'order_created',
		{ type: 'contents', amount: 2599, currency: 'USD' },
		{ event_id: orderId }
	);
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. `amount` is an integer in the currency's
minor unit, so `2599` is $25.99. Reuse `event_id` on the server event to
deduplicate it.

`@c15t/integrations/openai-pixel` also exports `openaiPixelEvent`, a typed wrapper
around `oaiq('measure', ...)`. It drops calls made before the queue exists and
does not check permission, so apply the same guard before calling it. A
`custom` event needs `custom_event_name` in its options. To send to one pixel
when you run several, call `window.oaiq('measureSingle', pixelId, ...)`.

## Verify the OpenAI Pixel

Set `debug: true` while you test. After you allow marketing, `oaiq.min.js`
loads from `bzrcdn.openai.com`. Trigger one guarded event and check that a
request to `https://bzr.openai.com/v1/sdk/events` succeeds and the event
appears in Event Stream in Ads Manager. An accepted request confirms delivery,
not attribution to a ChatGPT ad. Then revoke marketing. Until the page
reloads, calling `trackOrder` sends nothing. Turn off `debug` when you finish.

If your site sets a Content Security Policy, allow `https://bzrcdn.openai.com`
in `script-src`, both `https://bzr.openai.com` and `https://bzrcdn.openai.com`
in `connect-src`, and `https://bzr.openai.com` in `img-src`.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Pinterest Tag
URL: https://c15t.com/docs/integrations/pinterest-tag
Load the Pinterest Tag only after marketing consent with the c15t pinterestTag helper, guard pintrk event calls, and check it in DevTools.

## Configure the Pinterest Tag

Copy the numeric tag ID from Pinterest Ads Manager. Remove Pinterest's base
code and its `<noscript>` image. The helper does not emit that image, because
it fires without JavaScript and c15t cannot gate it.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { pinterestTag } from '@c15t/integrations/pinterest-tag';

export const scripts = [pinterestTag({ tagId: '2613654212508' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`tagId`|Required|Tag ID passed to `pintrk('load', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`loadOptions`|None|Object passed as the third argument to `pintrk('load', ...)`, such as `em` or `external_id` for enhanced match. Pass user data only when your app has the permission it needs.|
|`trackPageVisit`|`true`|Queues `pintrk('page')` after `load`. Set `false` to send page visits yourself.|
|`scriptUrl`|`https://s.pinimg.com/ct/core.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`pinterestTag` uses the `marketing` category. Before marketing is allowed, c15t
defines no `pintrk` function and loads nothing from Pinterest. When marketing
becomes allowed, the helper queues `load`, `pintrk('setconsent', true)` and
the page visit, then loads `core.js`.

On revocation the helper keeps the tag and calls
`pintrk('setconsent', false)`, which Pinterest documents as stopping events
and clearing its first-party storage. If the visitor allows marketing again
before the page reloads, the helper calls `pintrk('setconsent', true)`.

## Guard your own pintrk calls

The helper sends the page visit. Events your code sends, such as `checkout` or
`lead`, need their own check. After revocation `window.pintrk` still exists, so
its presence does not mean marketing is allowed. Check the permission first,
then that the tag has loaded:

```ts title="src/track-checkout.ts"
export function trackCheckout(marketingAllowed: boolean, orderId: string) {
	if (!marketingAllowed || typeof window.pintrk !== 'function') return;
	window.pintrk('track', 'checkout', {
		currency: 'USD',
		event_id: orderId,
		order_id: orderId,
		value: 99.99,
		line_items: [{ product_id: '1414', product_quantity: 1 }],
	});
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. Put product details in `line_items`, and
set `event_id` to deduplicate against the Conversions API. Pinterest reports
conversions only for its 20 event types. It keeps other event names for
audience targeting.

`@c15t/integrations/pinterest-tag` also exports `pinterestTagEvent`, a typed wrapper
around `pintrk('track', ...)`. It does nothing until `pintrk` exists and does
not check permission, so apply the same guard before calling it. Its optional
third argument receives Pinterest's `(didInit, error)` result.

## Verify the Pinterest Tag

After you allow marketing, `core.js` loads from `s.pinimg.com` and Pinterest
Tag Helper shows the page visit. Trigger one guarded event and check that Tag
Helper records it. Then revoke marketing. Until the page reloads, calling
`trackCheckout` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Reddit Pixel
URL: https://c15t.com/docs/integrations/reddit-pixel
Load the Reddit Pixel only after marketing consent with the c15t redditPixel helper, guard rdt conversion calls, and check it in DevTools.

## Configure the Reddit Pixel

Copy your Reddit Pixel ID. The helper passes it to `rdt('init', ...)`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { redditPixel } from '@c15t/integrations/reddit-pixel';

export const scripts = [redditPixel({ pixelId: 't2_YOUR_PIXEL_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID passed to `rdt('init', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`trackPageVisit`|`true`|Queues `rdt('track', 'PageVisit')` after `init`. Set `false` to send page visits yourself.|
|`initOptions`|None|Object passed as the third argument to `rdt('init', ...)`. It accepts Reddit's matching fields, such as `email` and `externalId`, `aam` for automatic advanced matching, `optOut`, and the Limited Data Use fields `dpm`, `dpcc` and `dprc`.|
|`disableFirstPartyCookies`|None|When set, overrides `initOptions.disableFirstPartyCookies`.|
|`scriptUrl`|`https://www.redditstatic.com/ads/pixel.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`redditPixel` uses the `marketing` category. Before marketing is allowed, c15t
defines no `rdt` function and loads nothing from Reddit. When marketing becomes
allowed, the helper queues `init` and `PageVisit`, then loads `pixel.js`.

On revocation the helper keeps the pixel and calls
`rdt('disableFirstPartyCookies')`. If the visitor allows marketing again before
the page reloads, it calls `rdt('enableFirstPartyCookies')`. Disabling cookies
does not stop the pixel from sending events, so the reload and your own guard
are what stop tracking.

## Guard your own rdt calls

The helper sends the page visit. Conversions your code sends, such as
`Purchase` or `Lead`, need their own check. After revocation `window.rdt` still
exists, so its presence does not mean marketing is allowed. Check the
permission first, then that the pixel has loaded:

```ts title="src/track-purchase.ts"
export function trackPurchase(marketingAllowed: boolean, orderId: string) {
	if (!marketingAllowed || typeof window.rdt !== 'function') return;
	window.rdt('track', 'Purchase', {
		conversionId: orderId,
		currency: 'USD',
		value: 99.99,
	});
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. Set `conversionId` to deduplicate against
the Conversions API. `@c15t/integrations/reddit-pixel` also exports
`redditPixelEvent`, a typed wrapper around `rdt('track', ...)`. It does nothing
until `rdt` exists and does not check permission, so apply the same guard
before calling it.

## Verify the Reddit Pixel

After you allow marketing, `pixel.js` loads from `www.redditstatic.com` and the
pixel sends one `PageVisit`. Trigger one guarded event and check that its
request appears. Then revoke marketing. Until the page reloads, calling
`trackPurchase` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# TikTok Pixel
URL: https://c15t.com/docs/integrations/tiktok-pixel
Load the TikTok Pixel only after marketing consent with the c15t tiktokPixel helper, guard ttq event calls, and check it in DevTools.

## Configure the TikTok Pixel

Copy your TikTok Pixel ID. The helper adds it to the loader URL as `sdkid`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { tiktokPixel } from '@c15t/integrations/tiktok-pixel';

export const scripts = [tiktokPixel({ pixelId: 'YOUR_PIXEL_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID sent in the loader URL. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`scriptSrc`|`https://analytics.tiktok.com/i18n/pixel/events.js`|Loader base URL override. The helper appends `?sdkid=<pixelId>&lib=ttq`. A blank value falls back to the default.|

## Loading and revocation

`tiktokPixel` uses the `marketing` category. Before marketing is allowed, c15t
defines no `ttq` queue and loads nothing from TikTok. When marketing becomes
allowed, the helper sets up `ttq` the way TikTok's base code does, queues one
`ttq.grantConsent()` and `ttq.page()`, then loads `events.js`.

On revocation the helper keeps the pixel and calls `ttq.revokeConsent()`. If
the visitor allows marketing again before the page reloads, it calls
`ttq.grantConsent()`.

## Guard your own ttq calls

The helper sends the page view. Events your code sends through `ttq.track` or
`ttq.identify` need their own check. After revocation `window.ttq` still
exists, so its presence does not mean marketing is allowed. Check the
permission first, then that the pixel is set up:

```ts title="src/track-purchase.ts"
export function trackPurchase(marketingAllowed: boolean, value: number) {
	if (!marketingAllowed || typeof window.ttq?.track !== 'function') return;
	window.ttq.track('CompletePayment', { currency: 'USD', value });
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. `@c15t/integrations/tiktok-pixel` exports no
event wrapper.

## Verify the TikTok Pixel

After you allow marketing, a request to
`analytics.tiktok.com/i18n/pixel/events.js` carries your pixel ID as `sdkid`,
and the pixel sends one page event. Trigger one guarded event and check that
its request appears. Then revoke marketing. Until the page reloads, calling
`trackPurchase` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# LinkedIn Insight Tag
URL: https://c15t.com/docs/integrations/linkedin-insights
Load the LinkedIn Insight Tag only after marketing consent with the c15t linkedinInsights helper, guard lintrk conversion calls, and check it in DevTools.

## Configure the LinkedIn Insight Tag

Copy the partner ID from LinkedIn Campaign Manager under Data, Signals manager,
Insight Tag. Remove the original Insight Tag snippet and its `<noscript>`
tracking image.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { linkedinInsights } from '@c15t/integrations/linkedin-insights';

export const scripts = [linkedinInsights({ id: 'YOUR_PARTNER_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Partner ID. The helper trims it, sets it as `_linkedin_partner_id` and appends it to `_linkedin_data_partner_ids`. Empty or whitespace-only values log an error and the script does not load.|
|`scriptSrc`|`https://snap.licdn.com/li.lms-analytics/insight.min.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`linkedinInsights` uses the `marketing` category. Before marketing is allowed,
c15t sets no LinkedIn globals and loads nothing from LinkedIn. When marketing
becomes allowed, the helper sets the partner ID globals, defines the `lintrk`
queue, then loads `insight.min.js`.

On revocation the helper removes the script element and calls no LinkedIn API,
so the page reload is what stops the tag. `window.lintrk` stays defined until
then.

## Guard your own lintrk calls

The Insight Tag tracks page views itself. Conversions your code sends through
`lintrk('track', ...)` need their own check, because `window.lintrk` still
exists after revocation. Check the permission first, then that the tag is set
up:

```ts title="src/track-signup.ts"
export function trackSignup(marketingAllowed: boolean) {
	if (!marketingAllowed || typeof window.lintrk !== 'function') return;
	window.lintrk('track', { conversion_id: 1234567 });
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. Use the conversion ID from your LinkedIn
conversion. `@c15t/integrations/linkedin-insights` exports no event wrapper.

## Verify the LinkedIn Insight Tag

After you allow marketing, `insight.min.js` loads from `snap.licdn.com`, and
`window._linkedin_data_partner_ids` in the console contains your partner ID.
Trigger one guarded conversion and check that its request to LinkedIn appears.
Then revoke marketing. Until the page reloads, calling `trackSignup` sends
nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Microsoft UET
URL: https://c15t.com/docs/integrations/microsoft-uet
Load Microsoft Advertising UET on every page with the c15t microsoftUet helper, send ad_storage consent defaults and updates, and verify both in DevTools.

## Configure Microsoft UET

Copy your UET tag ID from Microsoft Advertising. Remove the UET snippet and
any tag-manager entry that loads the same tag, because the helper creates the
`uetq` queue and constructs UET itself.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { microsoftUet } from '@c15t/integrations/microsoft-uet';

export const scripts = [microsoftUet({ id: 'YOUR_UET_TAG_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|UET tag ID, passed to UET as `ti`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`scriptSrc`|`//bat.bing.com/bat.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`microsoftUet` uses the `marketing` category and `alwaysLoad`, so `bat.js`
loads on every page whether or not marketing is allowed. Before the script
loads, the helper calls `uetq.push('consent', 'default', { ad_storage })` with
`granted` or `denied` from the current marketing permission. After `bat.js`
loads, it constructs UET with `enableAutoSpaTracking: true` and pushes
`pageLoad`. This is consent signaling, not a request gate. Microsoft's consent
mode decides what UET does while `ad_storage` is denied.

The helper never removes UET. When marketing changes, it calls
`uetq.push('consent', 'update', { ad_storage })` with the new value. Automatic
SPA tracking sends page loads on client-side navigation, so do not push
`pageLoad` from your router.

## Verify Microsoft UET

1. In a private window with an opt-in policy, load the page. The `bat.js`
   request goes to `bat.bing.com` before you choose, and UET sends its page
   load.
2. Click Reject, then reload. `bat.js` still loads, and the page starts with
   `ad_storage` denied.
3. Open Privacy settings and allow marketing. No second `bat.js` request
   appears, because the helper sends a consent update to the running tag
   instead of reloading it.
4. Navigate to another route in a single-page app. UET sends one page load for
   the route change, not two.
5. Turn marketing off again and save. c15t reloads the page, and the new page
   starts with `ad_storage` denied.

See the [consent verification guide](/docs/guides/verify-consent) for
navigation and hosting checks.

# Snapchat Pixel
URL: https://c15t.com/docs/integrations/snapchat-pixel
Load the Snapchat Pixel only after marketing consent with the c15t snapchatPixel helper, guard snaptr event calls, and check it in DevTools.

## Configure the Snapchat Pixel

Copy the pixel ID from Snapchat Ads Manager. The helper passes it to
`snaptr('init', ...)`.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { snapchatPixel } from '@c15t/integrations/snapchat-pixel';

export const scripts = [snapchatPixel({ pixelId: 'YOUR_PIXEL_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID passed to `snaptr('init', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`initOptions`|None|Object passed as the third argument to `snaptr('init', ...)`, such as `user_email`. Pass user data only when your app has the permission it needs.|
|`trackPageView`|`true`|Queues `snaptr('track', 'PAGE_VIEW')` after `init`. Set `false` to send page views yourself.|
|`scriptUrl`|`https://sc-static.net/scevent.min.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`snapchatPixel` uses the `marketing` category. Before marketing is allowed,
c15t defines no `snaptr` function and loads nothing from Snapchat. When
marketing becomes allowed, the helper queues `init` and `PAGE_VIEW`, then loads
`scevent.min.js`.

On revocation the helper removes the script element and calls no Snapchat API,
so the page reload is what stops the pixel. `window.snaptr` stays defined
until then.

## Guard your own snaptr calls

The helper sends the page view. Events your code sends, such as `PURCHASE` or
`SIGN_UP`, need their own check. After revocation `window.snaptr` still
exists, so its presence does not mean marketing is allowed. Check the
permission first, then that the pixel has loaded:

```ts title="src/track-purchase.ts"
export function trackPurchase(marketingAllowed: boolean, orderId: string) {
	if (!marketingAllowed || typeof window.snaptr !== 'function') return;
	window.snaptr('track', 'PURCHASE', {
		client_dedup_id: orderId,
		currency: 'USD',
		price: 99,
		transaction_id: orderId,
	});
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. Set `client_dedup_id` to deduplicate
against the Conversions API. `@c15t/integrations/snapchat-pixel` also exports
`snapchatPixelEvent`, a typed wrapper around `snaptr('track', ...)`. It does
nothing until `snaptr` exists and does not check permission, so apply the same
guard before calling it.

## Verify the Snapchat Pixel

After you allow marketing, `scevent.min.js` loads from `sc-static.net` and the
pixel sends one `PAGE_VIEW`. If your router also sends `PAGE_VIEW`, check that
the first page sends one, not two. Trigger one guarded event and check that
its request appears. Then revoke marketing. Until the page reloads, calling
`trackPurchase` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# X Pixel
URL: https://c15t.com/docs/integrations/x-pixel
Load the X Pixel only after marketing consent with the c15t xPixel helper, guard twq conversion events, and check it in DevTools.

## Configure the X Pixel

Copy your X Pixel ID. The helper passes it to `twq('config', ...)`. Conversion
event IDs, which look like `tw-xxxx-xxxx`, are separate from the pixel ID.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { xPixel } from '@c15t/integrations/x-pixel';

export const scripts = [xPixel({ pixelId: 'YOUR_PIXEL_ID' })];
```

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`pixelId`|Required|Pixel ID passed to `twq('config', ...)`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`scriptSrc`|`https://static.ads-twitter.com/uwt.js`|Loader URL override. A blank value falls back to the default.|

## Loading and revocation

`xPixel` uses the `marketing` category. Before marketing is allowed, c15t
defines no `twq` function and loads nothing from X. When marketing becomes
allowed, the helper queues `twq('config', pixelId)`, then loads `uwt.js`.

On revocation the helper removes the script element and calls no X API. X
exposes no consent update call, so the page reload is what stops the pixel.
`window.twq` stays defined until then.

## Guard your own twq calls

Conversion events come from your code, and each one needs its own check.
After revocation `window.twq` still exists, so its presence does not mean
marketing is allowed. Check the permission first, then that the pixel has
loaded:

```ts title="src/track-purchase.ts"
export function trackPurchase(marketingAllowed: boolean, orderId: string) {
	if (!marketingAllowed || typeof window.twq !== 'function') return;
	window.twq('event', 'tw-xxxx-xxxx', {
		conversion_id: orderId,
		currency: 'USD',
		value: 99.99,
	});
}
```

Pass the current marketing permission from your framework, for example
`useConsent('marketing')` in React. Set `conversion_id` to deduplicate the
event. `@c15t/integrations/x-pixel` also exports `xPixelEvent`, a typed wrapper
around `twq('event', ...)`. `xPixelEvent` does nothing while `twq` is
undefined, which is the case before marketing is first allowed. It does not
check permission, so apply the same guard before calling it.

## Verify the X Pixel

After you allow marketing, `uwt.js` loads from `static.ads-twitter.com`.
Trigger one guarded event and check that its request to X appears. Then revoke
marketing. Until the page reloads, calling `trackPurchase` sends nothing.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Backend overview
URL: https://c15t.com/docs/self-host/overview
What the c15t consent backend does, and when to use Inth or run @c15t/backend yourself with your own SQL database.

## Start with Inth

[Inth](https://inth.com) is the recommended backend for c15t applications. Use
the endpoint supplied by your project in the [framework quickstart](/docs/frameworks).
You get a backend connection without running the SQL service described in these
guides.

Self-hosting runs `@c15t/backend` in your own server, and your app connects to
it with the same hosted mode it would use for Inth. Choose it when you need to
operate the service yourself. You own database provisioning, migrations,
backups, policy configuration, signing secrets, availability and upgrades.

## What the backend provides

|Capability|How clients use it|
|--|--|
|Reusable configuration|`/manifest` publishes policy rules, translation configuration and IAB metadata for caching and local resolution.|
|Request initialization|`/init` resolves the policy for a request's location, language and privacy signals.|
|Consent persistence|Subject endpoints record confirmed category receipts and retrieve current choices.|
|Identity links|`PATCH /subjects/:id` links a device subject to an external identity, such as a signed-in account.|
|Legal-document versions|An authenticated release endpoint stores the current document identity. Exported helpers sign and verify document snapshots.|

For Next.js request rendering, prefer the cached manifest path described in
[data fetching](/docs/concepts/data-fetching). A browser-only application can use
regular initialization. A static frontend can use either Inth or a separately
deployed self-hosted backend; static hosting does not require offline mode.

## What offline mode changes

`offline()` resolves policy in the browser and keeps choices in browser
storage. It never calls a backend, so no consent records exist and policy lives
in your code. Use it for local development and tests. Not recommended for
production environments. See [choose your setup](/docs/concepts/choose-your-setup).

## Operate your own backend

Start with the [self-hosted quickstart](/docs/self-host/quickstart), then review
[database setup](/docs/self-host/guides/database-setup) and
[configuration](/docs/self-host/api/configuration). Use
[HTTP endpoints](/docs/self-host/api/endpoints) to integrate a custom server
client, and [policy configuration](/docs/self-host/guides/policy-packs) when you
own the policy manifest.

# Self-host the backend
URL: https://c15t.com/docs/self-host/quickstart
Run the c15t consent backend yourself with @c15t/backend, create its database schema with the CLI, mount it in Next.js, TanStack Start, Nuxt, SvelteKit or another server, and point your app at it.

## Before you start

[Inth](https://inth.com) runs this backend for you. Self-host when you need to
operate the service and its database yourself. You then own provisioning,
migrations, backups, policy configuration, signing secrets, availability and
upgrades.

Your c15t app talks to a self-hosted backend exactly as it talks to Inth, through
hosted mode. Only the backend URL changes.

## Install the backend

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/backend@alpha`|
|pnpm|`pnpm add @c15t/backend@alpha`|
|yarn|`yarn add @c15t/backend@alpha`|
|bun|`bun add @c15t/backend@alpha`|

Also install the driver for your database. The backend declares each driver as
an optional peer dependency pinned to one version; install that version.

|Database|Driver|
|--|--|
|PostgreSQL|`@effect/sql-pg`|
|MySQL|`@effect/sql-mysql2`|
|SQLite|`@effect/sql-sqlite-node`|

## Configure it

Create `c15t-backend.config.ts` in the app that will serve the backend:

```ts title="c15t-backend.config.ts"
import { defineConfig, policyRulePresets } from '@c15t/backend';

export default defineConfig({
	database: { dialect: 'sqlite', filename: './consent.db' },
	trustedOrigins: ['localhost'],
	manifest: { policyRules: [policyRulePresets.europeOptIn()] },
});
```

This is a local development configuration. `trustedOrigins` lists the sites
whose browsers may call the backend; add your production host before you
deploy. Keep the SQLite file on persistent storage, because a temporary
filesystem loses consent history. [Database setup](/docs/self-host/guides/database-setup)
covers PostgreSQL and MySQL, and [policy configuration](/docs/self-host/guides/policy-packs)
covers rules for other regions.

## Create the database schema

Run the migration with the same configuration the server uses:

```bash
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --plan
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply
```

Review the plan before you apply it, and back up an existing database first.
[Self-hosted migrations](/docs/cli/commands/self-host) explains the report.

## Mount the request handler

`c15tInstance(options).handler` takes a web `Request` and returns a `Response`.
Mount it on a catch-all route and route `GET`, `POST`, `PUT`, `PATCH` and
`OPTIONS` to it. `PUT` publishes legal-document releases; a route that exports
only `POST` leaves the manifest, `/init` and subject reads unreachable.

Create one instance per server process and reuse it, so requests share its
database connection pool. Set `basePath` to the path prefix of the requests the
handler receives, so `/api/c15t/init` routes to `/init`.

### Next.js App Router

```ts title="app/api/c15t/[[...path]]/route.ts"
import { c15tInstance } from '@c15t/backend';

import config from '../../../../c15t-backend.config';

export const runtime = 'nodejs';
const backend = c15tInstance({ ...config, basePath: '/api/c15t' });

export const GET = (request: Request) => backend.handler(request);
export const POST = GET;
export const PUT = GET;
export const PATCH = GET;
export const OPTIONS = GET;
```

This route needs a Node.js server. A Next.js static export cannot run it; deploy
the backend separately and give the app its absolute URL.

[`examples/self-host`](https://github.com/c15t/c15t/tree/v3/examples/self-host)
runs this route with an in-process PGlite database in development and
PostgreSQL from `DATABASE_URL` when deployed. Its banner calls the backend at
the same-origin path `/api/c15t`.

### TanStack Start

The TanStack Start example mounts the backend at `/api/self-host` as a server
route. Its `getInstance()` creates one `c15tInstance()` on first use and reuses
it:

```ts title="src/routes/api/self-host/$.ts"
const handle = async function handle({ request }: { request: Request }) {
	const instance = await getInstance();
	return instance.handler(request);
};

export const Route = createFileRoute('/api/self-host/$')({
	server: {
		handlers: {
			DELETE: handle,
			GET: handle,
			OPTIONS: handle,
			PATCH: handle,
			POST: handle,
			PUT: handle,
		},
	},
});
```

### Nuxt

The Nuxt example mounts the backend at `/api/self-host` as a Nitro catch-all
route, converting the h3 event with `toWebRequest()`:

```ts title="server/api/self-host/[...all].ts"
export default defineEventHandler(async (event) => {
	const instance = await getInstance();
	return instance.handler(toWebRequest(event));
});
```

### SvelteKit

The SvelteKit example creates its `c15tInstance()` as `backend` in
`src/lib/server/c15t-backend.ts`. The route at `/api/self-host` imports that
module dynamically on the first request and forwards each request to it:

```ts title="src/routes/api/self-host/[...all]/+server.ts"
import type { RequestHandler } from './$types';

// Load the backend on first request, in its own chunk. SvelteKit 3 builds
// with Rolldown, which can otherwise move modules the backend shares with
// lazily loaded chunks into this route's chunk and export them from it, and
// SvelteKit rejects a route that exports anything besides its handlers.
const loadBackend = () => import('#lib/server/c15t-backend.js');

const handleRequest: RequestHandler = async ({ request }) => {
	const { backend } = await loadBackend();
	return backend.handler(request);
};

export const GET = handleRequest;
export const POST = handleRequest;
export const PUT = handleRequest;
export const PATCH = handleRequest;
export const OPTIONS = handleRequest;
```

Keep the import dynamic on SvelteKit 3. A static import lets the build place
modules the backend shares with its lazily loaded chunks in the route's own
chunk, and SvelteKit then fails the build with `Invalid export` for the route.

### Another server

Pass the incoming web `Request` to `handler` and return its `Response`
unchanged, keeping status, body and headers such as CORS and cache headers. If
your framework has its own request type, convert it with the framework's web
request adapter. If a parent router already strips the prefix, leave `basePath`
unset rather than stripping it twice.

Tests and one-off scripts should call `instance.dispose()` when they finish to
close the connection pool. A long-running server does not need to.

## Point your app at the backend

Follow your [framework quickstart](/docs/frameworks) and use your backend's URL,
such as `https://app.example.com/api/c15t`, where it asks for the Inth URL.
Server-side resolution needs an absolute URL. The browser only needs the HTTP
endpoint; keep the config file and database credentials on the server.

The frontend does not have to run the backend. A static site or an edge-rendered
app can call a backend deployed elsewhere, as long as its origin is in
`trustedOrigins`.

## Check the deployment

1. Request `/status` and `/manifest` through the public mount point, for example
   `curl -i https://app.example.com/api/c15t/status`. `/status` returns `200`
   once the database answers and the schema exists. The manifest lists your
   policy rules.
2. Load the app from a trusted origin in a private window. The banner appears
   for a visitor your policy asks to choose.
3. Accept, then check DevTools Network for a `POST` to `/subjects` that returns
   a success status.
4. Reload. The banner stays closed and your choice is still applied.
5. For a cross-origin deployment, check that `/init` goes out without an
   `OPTIONS` preflight and the consent save's `OPTIONS` preflight succeeds. An
   `/init` preflight means something added a custom request header, such as
   the hosted transport's `headers` option.

Neither `/status` nor `/manifest` writes to the database, so only steps 3 and 4
prove that consent writes and reads work. Continue with [configuration](/docs/self-host/api/configuration)
and [HTTP endpoints](/docs/self-host/api/endpoints).

# Upgrade from v2
URL: https://c15t.com/docs/self-host/upgrade-v3
Upgrade a self-hosted c15t backend (@c15t/backend) and the Node.js SDK (@c15t/node-sdk) from v2 to v3. Covers the database config, the schema migration, moved backend options, policy rules and the new createC15tClient() client.

**Upgrade this c15t backend to v3**

Paste into Claude Code, Codex, Cursor or another coding agent at the root of the app that runs your c15t backend.

```prompt
Upgrade this app's self-hosted c15t backend from v2 to v3.

Read [https://v3.c15t.com/docs/self-host/upgrade-v3.md](https://v3.c15t.com/docs/self-host/upgrade-v3.md) first and follow it in order. Do not guess v3 APIs from memory.

1. Find the `@c15t/backend` config and every use of `@c15t/node-sdk`.
2. Install `@c15t/backend@alpha` and the SQL driver for the database, plus `@c15t/node-sdk@alpha` if the app uses it.
3. Run `npx @c15t/cli@alpha codemods backend-config-to-v3 policy-packs-to-policy-rules node-sdk-to-v3 --dry-run --json`. Review the output, then run the same command without `--dry-run`. The codemods leave a `TODO(c15t v3)` comment wherever they need you to finish a change.
4. Replace `adapter` with `database`, split `iab` between `manifest.iab` and `gvl`, and update the other options as the guide describes.
5. Do not run the schema migration yourself. Tell me to back up the database, and give me the `self-host migrate --plan` and `--apply` commands to run.
6. List the client apps that call this backend. They have to move to v3 in the same release.
7. Run the typecheck and build, and resolve every `TODO(c15t v3)` comment.
```

## Upgrade a self-hosted backend

Deploy the v3 backend and the v3 clients in the same release. A v3 client
cannot read a v2 backend's `/init` response. Policy resolution fails, optional
categories stay denied and no banner appears. Upgrade the client apps with the
[Next.js](/docs/frameworks/next/upgrade-v3),
[React](/docs/frameworks/react/upgrade-v3) or
[JavaScript](/docs/frameworks/javascript/upgrade-v3) guide.

1. Install `@c15t/backend@alpha` and the SQL driver for your database.
2. Replace `adapter` with `database` in your config. The Drizzle, Prisma,
   TypeORM and Kysely adapters are gone; point `database` at the same SQL
   database instead. MongoDB has no migration path.
3. Move `policyPacks`, `branding`, `customTranslations`, `i18n` and `appName`
   under `manifest`, and rename `policyPacks` to `policyRules`. Split `iab`
   between `manifest.iab` and `gvl`, as the table below shows.
4. Back up the database, then plan and apply the schema migration:

```bash
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --plan
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply
```

The migrator recognizes the v2 schema, adopts it, and adds the v3 tables and
columns. Apply it before the v3 backend serves traffic: v3 records policy
decisions without the v2 `jurisdiction` label, which the migration makes
nullable. [Database setup](/docs/self-host/guides/database-setup#upgrade-a-v2-backend)
covers the details, and the [backend quickstart](/docs/self-host/quickstart)
shows a complete v3 config and route.

The `backend-config-to-v3` codemod does step 3 for the keys that move as they
are, and leaves a `TODO(c15t v3)` comment on `adapter`, `iab`,
`disableGeoLocation` and the other options in the table below:

```bash
npx @c15t/cli@alpha codemods backend-config-to-v3 policy-packs-to-policy-rules --dry-run --json
```

Preset calls such as `policyRulePresets.europeOptIn()` need no other change.
A hand-written v2 pack uses `consent` and `ui` keys, which v3 rules replace
with flat keys such as `model` and `prompt`. See
[policy configuration](/docs/self-host/guides/policy-packs).

The v3 backend stores timestamps in UTC. Convert rows that a v2 backend wrote
in another time zone before you deploy. Database setup lists the checks.

Other backend options and entries change too:

|v2|v3|
|--|--|
|`tablePrefix`|Removed. The migrator refuses a database with prefixed c15t tables, so rename them first. On PostgreSQL, `database.schema` keeps c15t's tables in their own schema.|
|`iab.vendorIds`, `iab.endpoint`, `cache.adapter`|`gvl: { vendorIds, endpoint, cache }`|
|`iab.enabled`, `iab.cmpId`, `iab.customVendors`|`manifest.iab`|
|`logger`, `telemetry`|`observability`, passed to `c15tInstance()`|
|`background`, `iab.bundled`|Removed|
|`openapi.docsPath`, `openapi.options`, `openapi.customUiTemplate` and the `/docs` page|Removed. The spec is still at `/spec.json`.|
|`policySnapshot.onValidationFailure`|Removed|
|`GET /` as an alias of `/status`|Removed. Call `/status`.|
|`@c15t/backend/define-config`, `/router`, `/types`, `/db/schema`, `/db/adapters/*`, `/db/migrator`, `/edge`|Removed. Import `defineConfig`, `createMigrator` and `policyRulePresets` from `@c15t/backend`.|

### Remove `disableGeoLocation`

v3 removes the top-level `disableGeoLocation` option. Policy rules decide by
country and region. To show every visitor the same banner, configure one rule
with `match: { isDefault: true }`. It applies wherever the visitor is, so the
browser can resolve it without asking the backend for a location.

To test one region's rule from anywhere, set the country in the client's
`overrides`, for example `overrides: { country: 'US' }`. See
[runtime options](/docs/frameworks/javascript/api/runtime).

### Stop reading `jurisdiction`

`/init` responses, session reports and `sessions.onReport` no longer carry a
`jurisdiction` label such as `GDPR`. Read the matched policy from
`policyResolution` instead, or the report's `policy`, `country` and `region`.
The backend still accepts `jurisdiction` in a v2 client's save request and
ignores it.

## Update the Node.js SDK

Install `@c15t/node-sdk@alpha`. The v2 client is gone: create one with
`createC15tClient()` and pass the backend URL and API key yourself.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/node-sdk@alpha`|
|pnpm|`pnpm add @c15t/node-sdk@alpha`|
|yarn|`yarn add @c15t/node-sdk@alpha`|
|bun|`bun add @c15t/node-sdk@alpha`|

```ts
import { createC15tClient } from '@c15t/node-sdk';

const apiKey = process.env.C15T_API_KEY;
if (!apiKey) throw new Error('Set C15T_API_KEY');

const c15t = createC15tClient({
	baseUrl: 'https://app.example.com/api/c15t',
	apiKey,
});

const result = await c15t.consents.check({
	externalId: 'user_123',
	types: ['privacy_policy', 'marketing_communications'],
});
if (result.ok) {
	console.log(result.data.results.privacy_policy.hasConsent);
}
```

|v2|v3|
|--|--|
|`c15tClient(options)`, `new C15TClient(options)`|`createC15tClient(options)`|
|`C15T_API_URL`, `C15T_API_TOKEN` read from the environment|Not read. Pass `baseUrl` and `apiKey`.|
|`token`|`apiKey`|
|`prefix`|Part of `baseUrl`. v2 replaced the base URL's path with `prefix`, so use the origin plus the prefix, such as `https://app.example.com/api/c15t`.|
|`timeout`|`timeoutMs`, per attempt. The default drops from 30 to 10 seconds.|
|`retryConfig`|`retry: { maxRetries, initialDelayMs, maxDelayMs }`, or `false`. `backoffFactor`, `retryableStatusCodes`, `nonRetryableStatusCodes` and `retryOnNetworkError` are gone.|
|`debug`, `C15T_DEBUG`|`onEvent`|
|`client.meta.status()`, `client.status()`|`c15t.status()`|
|`client.meta.init(options)`, `client.init(options)`|`c15t.init({ language, country, region, gpc }, options)`. Per-call options move to the second argument.|
|`getSubject(id, { type: 'a,b' })`, `subjects.get(id, { type: 'a,b' })`|`subjects.get(id, { types: ['a', 'b'] })`|
|`createSubject(input)`|`subjects.create(input)`. `givenAt` also takes a `Date`.|
|`patchSubject(id, input)`, `subjects.patch(id, input)`|`subjects.identify(id, { externalId, identityProvider })`|
|`listSubjects({ externalId })`, `subjects.list({ externalId })`|`subjects.list({ externalId })`, on a client with `apiKey`|
|`checkConsent(query)`, `consent.check({ externalId, type: 'a,b' })`|`consents.check({ externalId, types: ['a', 'b'] })`, on a client with `apiKey`|
|`ResponseContext` with `data: T \|null`|`{ ok: true, data } \|{ ok: false, error }`. Check `ok` first.|
|`unwrap()`, `expect()` on the response|`unwrap(result)`, imported from `@c15t/node-sdk`|
|`unwrapOr()`, `map()` on the response|Check `result.ok`|
|`throw: true`|`unwrap(result)`|
|`onSuccess`, `onError`|Check `result.ok` after the call|
|`C15TError`, `isC15TError()`|`C15tError`, `isC15tError(error, ...codes)`|
|`C15TClient`, `C15TClientOptions`, `RetryConfig`, `FetchOptions`, `ResponseContext` types|`C15tClient`, `C15tClientOptions`, `C15tRetryOptions`, `C15tCallOptions`, `C15tResult`|
|Per-call `timeout`, `retryConfig`|`timeoutMs`, `retry`|
|Per-call `body`, `query`, `method`|Removed. Pass the body and query as the method's arguments.|
|`$fetch`, `fetcher`, `resolveUrl`, `createResponseContext`|Removed. Pass a custom `fetch` to `createC15tClient` if you need one.|
|`createMockClient`, `createMockResponse`, `createMockErrorResponse`|`createMockC15tClient`, `ok`, `err` from `@c15t/node-sdk/testing`|

`patchSubject` returned `{ success, subject }`. `subjects.identify` returns
`{ subject }`, and `subject.identityProvider` is always set. Dates in
responses, such as `givenAt` and `createdAt`, are now `Date` objects rather
than strings.

`consents.check` and `subjects.list` count only verified links. Links made by
v2 don't count until you relink them with `subjects.identify` on a keyed
client, or [with an identity token](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) on the user's next sign-in.

The `node-sdk-to-v3` codemod renames the factory, client options, methods,
types and errors in files that create a client. It turns `type` strings into
`types` arrays, and leaves a `TODO(c15t v3)` comment at each call, because
results are now `{ ok, data }` or `{ ok, error }`. It renames per-call
`timeout` and `retryConfig` too. It also marks `prefix`, `debug`, per-call
`throw`, `onSuccess`, `onError`, `body`, `query` and `method`, and a client
built from environment variables:

```bash
npx @c15t/cli@alpha codemods node-sdk-to-v3 --dry-run --json
```

The new client also adds `manifest()`, `legalDocuments.publish()` and
`experiments.summary()`. The last two need a client with `apiKey`. See the
[Node.js SDK reference](/docs/self-host/api/node-sdk).

# Backend database setup
URL: https://c15t.com/docs/self-host/guides/database-setup
Connect a self-hosted c15t backend to PostgreSQL, MySQL or SQLite, apply migrations, and upgrade a v2 backend database.

## Choose a supported connection

|Database|Configuration|Optional driver|
|--|--|--|
|PostgreSQL|`{ dialect: 'postgres', url }`|`@effect/sql-pg`|
|MySQL|`{ dialect: 'mysql', url }`|`@effect/sql-mysql2`|
|SQLite|`{ dialect: 'sqlite', filename }`|`@effect/sql-sqlite-node`|

Install the driver version listed in your backend release's peer dependencies.
The v3 backend takes `database`, not the old ORM `adapter` configuration.
Applications already using Effect can supply a compatible SQL client layer.

## Keep credentials on the server

```ts
import { defineConfig } from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');
export default defineConfig({ database: { dialect: 'postgres', url } });
```

This fragment only configures storage. Add origins and policy rules as shown in
[backend setup](/docs/self-host/quickstart). Never expose the database URL through
public environment variables or client provider props.

PostgreSQL also supports `schema` for isolating c15t tables. For MySQL, choose the
database through the connection URL. For SQLite, choose a dedicated durable file.
An in-memory database is suitable for disposable tests, not retained history.

## Connect through a PostgreSQL pooler

`@effect/sql-pg` caches named prepared statements on each connection. A pooler
in transaction mode, such as PgBouncer or a provider's pooled connection URL,
can route the next query to a connection that never prepared the statement, and
the query fails. Connect directly, or pass a client layer with prepared
statements turned off:

```ts title="c15t-backend.config.ts"
import { defineConfig } from '@c15t/backend';
import { PgClient } from '@effect/sql-pg';
import { Redacted } from 'effect';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');
export default defineConfig({
	database: PgClient.layer({
		url: Redacted.make(url),
		prepare: false,
		startupParameters: { timezone: 'UTC' },
	}),
});
```

A client layer bypasses the `schema` option and the UTC session that c15t sets
on its own connections. To keep c15t's tables in their own schema, add
`startupOptions: '-c search_path=c15t'` to the layer, and check that your pooler
forwards startup options.

## Store timestamps in UTC

The backend stores every timestamp, including each consent's `givenAt`, as UTC
in columns without a time zone. Connections built from a `database` config set
this up themselves and override any time zone in the URL:

* PostgreSQL sessions use `timezone=UTC`.
* MySQL connections set the mysql2 `timezone` option to `Z`.
* SQLite stores epoch milliseconds, so it has no time zone to set.

A client layer you build yourself needs the same setting. Without it, a server
outside UTC stores every time shifted by its offset. For `PgClient.layer`, pass
`startupParameters: { timezone: 'UTC' }`, as in the pooler example. For
`MysqlClient.layer`, add `timezone=Z` to the connection URL.

A v2 backend writing to the same database stores times in its Node.js process's
time zone. Run it with `TZ=UTC`, or the two backends read different times from
the same rows.

### Convert timestamps written outside UTC

Earlier backends stored times in whatever zone their connection used. Once the
backend reads every timestamp as UTC, rows written in another zone read as
shifted by that zone's offset, and a retried save can be stored twice because
its `givenAt` no longer matches. Convert those rows before deploying this
version if any of these applied to a backend that wrote to the database:

* PostgreSQL, v3: the database session time zone was not UTC. Check with
  `show timezone;` on a connection made the same way as the backend's.
* PostgreSQL or MySQL, v2: the Node.js process ran without `TZ=UTC` on a host
  outside UTC.
* MySQL, v3: the Node.js process ran outside UTC and the URL did not set
  `timezone`.

SQLite needs no conversion. The steps below assume every backend used the same
zone. They cannot fix a database that backends in different zones wrote to,
because a row does not record which backend wrote it.

A zone with daylight saving time repeats an hour when clocks go back, so a
stored time inside that hour matches two instants. The script picks one of
them, and rows saved during the repeated hour can stay an hour off. Check those
rows against another record of the time, such as request logs, before
deploying.

1. Stop every backend that writes to the database, v2 and v3.
2. Back up the database.
3. Run the script for your database, with `Europe/Berlin` replaced by the zone
   the backends used.
4. Deploy this backend version, and start any v2 backend with `TZ=UTC`.

For PostgreSQL, run it with `search_path` set to the `schema` option if you use
one:

```sql
begin;
update "subject" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC',
	"updatedAt" = ("updatedAt" at time zone 'Europe/Berlin') at time zone 'UTC';
update "domain" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC',
	"updatedAt" = ("updatedAt" at time zone 'Europe/Berlin') at time zone 'UTC';
update "consentPolicy" set
	"effectiveDate" = ("effectiveDate" at time zone 'Europe/Berlin') at time zone 'UTC',
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC';
update "consentPurpose" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC',
	"updatedAt" = ("updatedAt" at time zone 'Europe/Berlin') at time zone 'UTC';
update "runtimePolicyDecision" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC';
update "consent" set
	"givenAt" = ("givenAt" at time zone 'Europe/Berlin') at time zone 'UTC',
	"validUntil" = ("validUntil" at time zone 'Europe/Berlin') at time zone 'UTC';
update "auditLog" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC';
commit;
```

A database adopted from the pre-2.0 schema also keeps
`consentPolicy.expirationDate` and the `consentRecord` table. Convert them in the
same transaction, before `commit`:

```sql
update "consentPolicy" set
	"expirationDate" = ("expirationDate" at time zone 'Europe/Berlin') at time zone 'UTC';
update "consentRecord" set
	"createdAt" = ("createdAt" at time zone 'Europe/Berlin') at time zone 'UTC';
```

For MySQL, `convert_tz` returns `NULL` when the server has no time zone tables.
Check that `select convert_tz('2026-01-01 12:00:00', 'Europe/Berlin', '+00:00');`
returns a time before running:

```sql
start transaction;
update subject set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00'),
	updatedAt = convert_tz(updatedAt, 'Europe/Berlin', '+00:00');
update domain set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00'),
	updatedAt = convert_tz(updatedAt, 'Europe/Berlin', '+00:00');
update consentPolicy set
	effectiveDate = convert_tz(effectiveDate, 'Europe/Berlin', '+00:00'),
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00');
update consentPurpose set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00'),
	updatedAt = convert_tz(updatedAt, 'Europe/Berlin', '+00:00');
update runtimePolicyDecision set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00');
update consent set
	givenAt = convert_tz(givenAt, 'Europe/Berlin', '+00:00'),
	validUntil = convert_tz(validUntil, 'Europe/Berlin', '+00:00');
update auditLog set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00');
commit;
```

For a database adopted from the pre-2.0 schema, add these before `commit`:

```sql
update consentPolicy set
	expirationDate = convert_tz(expirationDate, 'Europe/Berlin', '+00:00');
update consentRecord set
	createdAt = convert_tz(createdAt, 'Europe/Berlin', '+00:00');
```

Run the conversion once. A second run shifts every row again.

## Apply and verify migrations

```bash
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --plan
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply
```

Back up existing data first and review the plan. The plan also warns about
schema changes made outside the migrator that the backend depends on, such as a
`runtimePolicyDecision` table without a unique index on `dedupeKey` alone. The
migrator does not repair these; each warning includes the statement to run.

Run the app against the same
database, schema and credentials, or the server can connect to a different,
unmigrated database. A server that starts has not proven that writes and reads
work; save a choice and read it back.

## Run migrations from a deployment script

`createMigrator()` owns a connection pool. Plan before applying, stop when
`blocked` is set, and dispose the pool when the script finishes:

```ts title="scripts/migrate-consent.ts"
import { createMigrator } from '@c15t/backend';

import config from '../c15t-backend.config';

const migrator = createMigrator(config.database);
try {
	const plan = await migrator.plan();
	if (plan.blocked !== undefined) throw new Error(plan.blocked);
	console.log(plan);
	const result = await migrator.apply();
	if (result.blocked !== undefined) throw new Error(result.blocked);
	console.log(result);
} finally {
	await migrator.dispose();
}
```

This script applies the reported migration immediately after planning. Run it as
an intentional deployment step after reviewing a plan against a restored copy
of an existing database. The CLI provides an interactive review instead.

`plan()` is read-only. Reports include `adoption`, `pending`, `retained`,
`blocked`, `applied` and `drift`. `drift` lists schema problems the migrator
found but does not fix. Adoption recognizes supported older SQL schemas before
applying numbered migrations. A blocked report is a refusal to migrate an
unrecognized or unsafe state, not permission to delete the ledger and retry.
The package's `c15t_migrations` ledger tracks applied migrations.

MySQL DDL is not transactional, so migration steps use checkpoints rather than
relying on rolling back the whole batch. Keep backups and inspect a failed run
before retrying. PostgreSQL schema creation belongs to migration; the runtime
and migration configuration must name the same schema.

## Upgrade a v2 backend

Replace the v2 `adapter` option with `database`. The Drizzle, Prisma, TypeORM
and Kysely adapters are gone. Keep your PostgreSQL, MySQL or SQLite database and
point `database` at it with the matching driver. MongoDB has no migration path
to the v3 backend.

The migrator recognizes the v2 schema, adopts it, and then applies the v3
migrations. Run the plan against a restored copy of production first. After
migrating, check a consent write, a subject read and an authenticated
external-identity lookup. `/status` and `/manifest` do not write, so they do not
prove that persistence works.

Deploy the v3 backend together with v3 clients; the
[backend upgrade guide](/docs/self-host/upgrade-v3) explains why.

# Policy configuration
URL: https://c15t.com/docs/self-host/guides/policy-packs
Author and validate the policy rules published by a self-hosted backend manifest.

## Choose where policy is managed

For [Inth](https://inth.com), manage the project's policy in the hosted service.
Importing presets into a browser using `hosted()` does not change that policy.
The examples on this page configure a self-hosted backend. Offline clients use
their own `offline({ policyRules })` configuration instead.

For an explanation of how an existing Next.js app follows a policy, read
[policies](/docs/concepts/policies). A framework
component does not need a database configuration to consume hosted policy.

## Configure `manifest.policyRules`

```ts title="c15t-backend.config.ts"
import {
	defineConfig,
	inspectPolicyRules,
	policyRulePresets,
} from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

const policyRules = [
	policyRulePresets.europeOptIn(),
	policyRulePresets.quebecOptIn(),
	policyRulePresets.usPrivacyStatesOptOut(),
	policyRulePresets.worldOptOutNoPrompt(),
];

const { errors } = inspectPolicyRules(policyRules);
if (errors.length) throw new Error(errors.join('\n'));

export default defineConfig({
	database: { dialect: 'postgres', url },
	trustedOrigins: ['https://app.example.com'],
	manifest: { policyRules },
});
```

This example deliberately chooses opt-out behavior for unmatched known locations.
Review whether that behavior fits your processing before adopting it. Presets
encode consent behavior and geographic matches. They do not decide which laws
apply to your business or establish a legal basis for a vendor's processing.

The authored input is `policyRules`. The generated `/manifest` contains
`policyPacks`; passing that generated field back as configuration is unsupported
and yields `policyFailure`.

## Understand rule selection

A known region match takes precedence over a country match. Array order resolves
ties at the same specificity. A rule with `match.isDefault` handles unmatched
locations. A fallback handles missing inputs; do not assume the default handles
every missing-country or missing-region case.

The Europe preset includes an unknown-location fallback. For custom packs with
subdivision rules, define the intended missing-region behavior. If no country
rule, region fallback or global fallback can resolve a missing subdivision,
resolution can fail with `insufficient-inputs`.

```ts title="consent-policies.ts"
import { policyMatchers, policyRulePresets } from '@c15t/backend';

const us = policyRulePresets.usPrivacyStatesOptOut();
export const usWithMissingState = {
	...us,
	match: policyMatchers.merge(us.match, policyMatchers.regionFallback(['US'])),
};
```

This partial policy adds a fallback for a known US country with a missing state.
It does not expand coverage for known states. Put the resulting rule in your
`manifest.policyRules` array.

## Choose the consent behavior

|Model|Initial optional permissions|UI and rights|
|--|--|--|
|`opt-in`|Wait for a recorded choice.|A choice prompt can request permission.|
|`opt-out`|In-scope processing may start under the rule, subject to privacy signals.|The rule defines notice, opt-out and preference rights.|
|`none`|In-scope categories are allowed by policy.|No consent UI appears unless rights are explicitly configured.|
|`iab`|Follow the IAB policy and client add-on.|Requires matching IAB configuration.|

Effective permission is not an explicit consent receipt. A no-banner rule does
not prove the user accepted anything. Keep any preference controls required by
the selected rule available after the initial page view.

## Available presets

All presets return ordinary policy rule objects. Review their categories,
prompt, rights and matchers in your editor or with `inspectPolicyRules()` before
publishing changes. Prefer opt-in variants when an opt-out preset's processing
assumptions do not fit your application.

|Preset family|Configuration choices|
|--|--|
|Europe|`europeOptIn()`, `europeIab()`|
|US privacy states|`usPrivacyStatesOptIn()`, `usPrivacyStatesOptOut()`|
|California|`californiaOptIn()`, `californiaOptOut()`|
|Québec|`quebecOptIn()`|
|Canada outside Québec|`canadaOptIn()`, `canadaOptOut()`|
|Australia|`australiaOptIn()`, `australiaOptOut()`|
|Japan|`japanOptIn()`, `japanOptOut()`|
|Switzerland|`switzerlandOptIn()`, `switzerlandOptOutNoPrompt()`|
|Restricted statistics profiles|`ukStatistics()`, `malaysiaStatistics()`|
|Other regional opt-in|Singapore, Malaysia, Thailand, Indonesia, Philippines, Vietnam, Brunei, Laos, China, South Korea, India, Brazil, Turkey and more in `policyRulePresets`.|
|Global defaults|`worldNone()`, `worldOptOutNoPrompt()`|

Statistics profiles are scoped configurations, not permission to run arbitrary
analytics or marketing vendors. Inspect their allowed categories and required
rights. Do not substitute them for a full consent configuration based only on a
vendor calling its product analytics.

## Compose custom rules

`policyBuilder.create()` accepts canonical rule fields with flat `countries`,
`regions`, `isDefault` and `fallback` match inputs. `createPack()` preserves the
supplied order. `createPackWithDefault()` appends the explicit default you supply
if none exists. `composePacks()` preserves order and keeps the first occurrence
of each rule ID.

These helpers do not make invalid inputs valid. Validate the final composed
array with `inspectPolicyRules()`. For IAB rules, pass `{ iabEnabled: true }` to
the inspector and configure [IAB support](/docs/self-host/guides/iab-tcf).

## Publish and verify a policy change

Inspect `/manifest` after deployment. Its revision should change when the
configuration changes. Allow for [manifest cache windows](/docs/self-host/guides/caching)
or purge the old revision. Check `/init` for each supported region, an unknown
country and a missing subdivision. Confirm the expected model, prompt and rights.

Invalid rules create a `policyFailure` and a failed resolution, even when the
HTTP response succeeds. Verify the browser's effective permissions, visible
controls and saved receipts after the change. Do not rely only on a banner
screenshot to establish policy behavior.

# Caching
URL: https://c15t.com/docs/self-host/guides/caching
Cache public manifests and vendor lists while keeping request-specific initialization and subject state private.

## Cache the manifest

`GET /manifest` is the reusable configuration endpoint. It does not query consent
records or depend on the visitor's location. The backend generates its revision
from the configuration and returns it as an `ETag`.

Add these options to the [backend configuration](/docs/self-host/api/configuration):

```ts
manifestCache: {
  sMaxAge: 300,
  staleWhileRevalidate: 86400,
},
```

These are the defaults, in seconds. The resulting header is
`public, s-maxage=300, stale-while-revalidate=86400`, sent as both
`Cache-Control` and `CDN-Cache-Control`. Vercel's CDN consumes the shared-cache
directives from a bare `Cache-Control` and strips them before forwarding; the
second header keeps them visible to app servers reading the manifest through
the CDN. A policy change alters the
revision, but a shared cache can continue serving the previous response within
its cache window. Purge the relevant cache or choose shorter durations when your
rollout requires it. A revision is an identity, not a remote cache invalidation
command.

Keep the tenant, backend URL and language query in the cache key. Preserve
`Vary: Origin` when CORS emits it. Do not combine manifests from different
projects just because their endpoint paths match.

## Keep visitor state out of shared caches

`GET /init` and `GET /subjects/:id` return `no-store`.
Do not override that header with a CDN rule. `/init` contains a resolved policy
for request inputs; subject endpoints contain private state.

A server framework can reuse `/manifest` and resolve it locally for each incoming
request. That removes the backend initialization round trip on a manifest cache
hit while preserving per-request policy selection. It does not remove later
consent writes or make request cookies shareable.

The framework adapters honour both directives above in their in-process cache.
After `sMaxAge` seconds they keep serving the cached manifest for up to
`staleWhileRevalidate` seconds while one background request revalidates it with
the `ETag`, and a failed revalidation keeps the cached copy. A shorter
`staleWhileRevalidate` therefore bounds how long an app server can keep serving
an old policy after this backend becomes unreachable, at the cost of blocking
requests on the backend once that window closes.

## Cache the Global Vendor List

GVL caching is separate from manifest HTTP caching. Supply a cache adapter with
your server-side GVL configuration. Concurrent misses share an in-flight fetch,
but persistent reuse requires the configured cache.

```ts title="src/consent-backend.ts"
import { c15tInstance } from '@c15t/backend';
import { createMemoryCacheAdapter } from '@c15t/backend/cache';

import config from '../c15t-backend.config';

export const backend = c15tInstance({
	...config,
	gvl: { cache: createMemoryCacheAdapter(), ttlMs: 86400000 },
});
```

A device can narrow the list per request with `x-c15t-vendors`. That header is
not part of the cache key. The backend caches one document per endpoint,
language, and configured `gvl.vendorIds`, then narrows that document for each
request. What a client sends therefore cannot create cache entries, and cannot
add an upstream fetch. `/init` answers with `Cache-Control: no-store` and lists
the header in `Vary` regardless, because the vendors it names are
request-specific.

The backend loads a GVL only for a matched IAB rule. The GVL TTL uses
milliseconds, unlike `manifestCache`.

|Adapter|Use it when|
|--|--|
|`createMemoryCacheAdapter()`|One long-lived process can keep its own cache. Memory is not shared between instances.|
|`createUpstashRedisAdapter({ url, token })`|Serverless or multiple instances need a shared cache. Install the optional `@upstash/redis` peer.|
|`createUpstashRedisAdapterFromClient(client)`|Your application already owns an Upstash client.|
|`createCloudflareKVAdapter(namespace)`|A compatible runtime supplies a KV namespace. This does not supply a database driver.|

Custom `CacheAdapter` implementations provide `get`, `set`, `delete` and `has`.
`set` receives its optional TTL in milliseconds. Cache operations should fit the
request latency budget. A failed GVL fetch returns no usable list; verify that
behavior with your IAB client rather than assuming a warm cache on every request.

Choose the adapter path in [data fetching](/docs/concepts/data-fetching) or
[Next.js rendering and deployment](/docs/frameworks/next/rendering#choose-how-the-server-gets-the-policy).

# Deployment runtimes
URL: https://c15t.com/docs/self-host/guides/edge-deployment
Choose a backend runtime that supports your SQL driver and deploy static or edge-rendered clients against its HTTP endpoint.

## Choose a runtime for the database driver

The backend has a web-request handler, but that does not make every SQL driver
portable to every edge runtime. The built-in connection descriptions load these
drivers:

|Database configuration|Driver|Deployment requirement|
|--|--|--|
|`dialect: 'postgres'`|`@effect/sql-pg`|A runtime supporting that PostgreSQL driver's networking and dependencies.|
|`dialect: 'mysql'`|`@effect/sql-mysql2`|A runtime supporting the MySQL driver and its connections.|
|`dialect: 'sqlite'`|`@effect/sql-sqlite-node`|Node-compatible SQLite dependencies and a durable filesystem for retained data.|

The [Next.js backend mount](/docs/self-host/quickstart#nextjs-app-router) uses
`runtime: 'nodejs'`. A serverless instance's temporary filesystem is not durable
SQLite storage. Choose a networked database or a deployment with a persistent
volume and a supported driver.

## Run edge clients against a separate backend

Keep the consent backend on a supported server runtime and call it over HTTPS
from edge-rendered or static applications. [Inth](https://inth.com) provides the
managed version of this setup.

A cached manifest can provide policy configuration to server rendering without
running a database driver inside the frontend runtime. Consent writes still go
to the backend. Use an absolute public endpoint, configure the frontend's trusted
origins and preserve request-specific location and privacy signals.

## Bring an Effect SQL layer

`database` also accepts an Effect `SqlClient` layer. This is the extension point
for an application that already owns a supported SQL client or needs another
runtime-specific driver. The layer must supply the SQL dialect and behavior
required by the backend's queries and migrations. A raw database handle, Prisma
client, Cloudflare D1 binding or old v2 ORM adapter is not this interface.

The exported Cloudflare KV cache adapter only supplies caching. It does not add
D1 support or make the built-in Node SQL drivers work on Workers. Validate your
chosen client and runtime with migrations, receipt writes and reads before
using that deployment.

## Operate multiple instances

Run migrations as a deployment step against the same database and schema used by
the service. Reuse one backend instance within each process. Use shared GVL
caching when cold starts would otherwise repeat upstream fetches, and account
for database connection limits as the service scales.

See [database setup](/docs/self-host/guides/database-setup),
[caching](/docs/self-host/guides/caching) and
[request logging](/docs/self-host/guides/observability).

# IAB backend configuration
URL: https://c15t.com/docs/self-host/guides/iab-tcf
Publish an IAB TCF policy and serve a cached Global Vendor List from a self-hosted c15t backend.

## Configure an IAB policy

IAB support needs both an IAB policy in the manifest and the client IAB add-on.
The server options alone do not install a TCF UI or generate a TC String in the
browser.

```ts title="c15t-backend.config.ts"
import { defineConfig, policyRulePresets } from '@c15t/backend';
import { createMemoryCacheAdapter } from '@c15t/backend/cache';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

export default defineConfig({
	database: { dialect: 'postgres', url },
	trustedOrigins: ['https://app.example.com'],
	manifest: {
		policyRules: [policyRulePresets.europeIab()],
		iab: { enabled: true },
	},
	// The matched IAB rule asks for a list; this says where it comes from and
	// which vendors it may name.
	gvl: { cache: createMemoryCacheAdapter(), vendorIds: [3, 7, 41] },
});
```

Set `manifest.iab.cmpId` to the CMP ID your deployment is entitled to use. IAB
Europe assigns one when a company registers as a CMP
([register.consensu.org/CMP](https://register.consensu.org/CMP)); publishers
using a registered CMP do not need their own. Every TC String names the CMP that
wrote it, so a copied or placeholder ID attributes your users' consent records
to another provider and is not a staging-only shortcut.

Left unset, `/init` returns no CMP ID and the browser add-on does not mount, so
nothing writes a TC String. Set to a value outside the encodable range, an
integer from 2 to 4095, and `@c15t/iab` throws instead of encoding a string that
names no registered CMP.

Review the policy's location coverage and add other reviewed regional rules as
needed.

## Understand the two GVL settings

`manifest.iab` publishes IAB metadata and a GVL endpoint to clients that
resolve the manifest themselves. `gvl` controls how the backend loads the list
when `/init` resolves a matched IAB rule. Setting one does not configure the
other. Both endpoints default to `https://gvl.inth.app`; if you run a different
compatible endpoint, set `manifest.iab.endpoint` and `gvl.endpoint`.

Adding a `gvl` block turns on list loading. Every `/init` that matches an IAB
rule then carries the list. Set `gvl.enabled: false` to keep the block but serve the
list from somewhere else. If your rules resolve as IAB and there is no `gvl`
block, the backend serves no list and prints a warning at startup.

`gvl.vendorIds` is the most the backend will serve. It never fetches a wider
list to fill gaps, and it filters whatever the upstream returns, so a vendor
outside the list never reaches a client. Leave `vendorIds` out to serve every
vendor in the published list.

A client can ask for fewer vendors by listing the ones it ships on each init
request:

```bash
curl -i 'http://localhost:3000/api/c15t/init' \
  -H 'x-c15t-country: DE' \
  -H 'x-c15t-vendors: 8, 46, 153'
```

For a matched IAB policy, the `gvl` in the response is the intersection of that
header and `gvl.vendorIds`, so the header can narrow the list but never widen
it. A missing or unreadable header gets the configured list, and a header with
more than 500 IDs is ignored. The backend narrows the list after its cache
lookup, so different app scopes do not add upstream fetches.

Use a [cache adapter](/docs/self-host/guides/caching) to reuse fetched lists.
`gvl.ttlMs` defaults to one day. A failed upstream fetch or an invalid document
gives a null GVL instead of failing `/init`. Check how your client handles that
before you deploy.

## Check the IAB setup

1. Request `/manifest` and confirm it lists the IAB rule and IAB metadata.
2. Call `/init` with a location the rule covers, such as the `curl` request
   above. The policy model is `iab` and the response has a `gvl` field. A client
   that bundles no vendor list gets the list only from this response, so a
   missing `gvl` means that client has no vendors to disclose.
3. Call `/init` with a location outside the rule. The ordinary consent flow
   applies and the response has no list.
4. Send `x-c15t-vendors` and confirm the `gvl` names only those vendors that
   `gvl.vendorIds` also allows.

Connect the browser with the [IAB add-on guide](/docs/frameworks/react/iab),
and keep a persistent link to vendor and purpose choices. A preset and a served
GVL are configuration; they do not prove your site meets the TCF rules.

# Legal-document snapshots
URL: https://c15t.com/docs/self-host/guides/legal-document-snapshot-integration
Publish legal-document versions and sign evidence of the exact document shown by your application.

## Publish the current release

The backend can store the current version and content hash of a legal document.
Synchronize the release from trusted server or deployment code with a configured
API key:

```bash
curl -X PUT 'http://localhost:3000/api/c15t/legal-documents/terms_and_conditions/current' \
  -H "Authorization: Bearer $C15T_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"version":"3.0","hash":"YOUR_DOCUMENT_CONTENT_HASH","effectiveDate":"2026-09-10T00:00:00.000Z"}'
```

From a Node.js deploy script, the [Node.js SDK](/docs/self-host/api/node-sdk#publish-a-legal-document-from-ci)
sends the same request with a client created with `apiKey`:

```ts
const result = await c15t.legalDocuments.publish('terms_and_conditions', {
	version: '3.0',
	hash: 'YOUR_DOCUMENT_CONTENT_HASH',
	effectiveDate: '2026-09-10T00:00:00.000Z',
});

if (!result.ok) {
	throw result.error;
}
```

The SDK retries network errors, timeouts and the statuses listed in
[retries and timeouts](/docs/self-host/api/node-sdk#retries-and-timeouts).
Republishing the same release is safe.

Compute the hash from the exact published document using your application's
chosen content-hashing convention. Keep the same type, version, hash and
effective date when rendering and recording acceptance. A conflicting release
identity returns an error instead of silently changing the existing record.

## Sign a document snapshot

The package exports signing and verification helpers. Call them explicitly from
your server application. Merely setting `legalDocumentSnapshot` on the backend
does not add an HTTP endpoint that issues or consumes these tokens.

```ts title="src/legal-document-snapshot.ts"
import {
	createLegalDocumentSnapshotToken,
	verifyLegalDocumentSnapshotToken,
} from '@c15t/backend';

const signingKey = process.env.LEGAL_DOCUMENT_SIGNING_KEY;
if (!signingKey) throw new Error('Set LEGAL_DOCUMENT_SIGNING_KEY');
const options = { signingKey, ttlSeconds: 86400 };

export async function signTermsSnapshot() {
	return createLegalDocumentSnapshotToken(
		{
			type: 'terms_and_conditions',
			version: '3.0',
			hash: 'YOUR_DOCUMENT_CONTENT_HASH',
			effectiveDate: '2026-09-10T00:00:00.000Z',
			tenantId: 'your-tenant',
		},
		options
	);
}

export async function verifyTermsSnapshot(token: string) {
	return verifyLegalDocumentSnapshotToken(token, options, 'your-tenant');
}
```

Supply release metadata from your trusted document store, rather than accepting
it unverified from a browser. Return the signed token alongside the displayed
document. When the user submits acceptance, verify it on the server, check the
expected document identity and record the accepted document through your
application's consent flow. A valid signature does not establish a user action
or authorize an identity by itself.

## Handle verification failures

Without a signing key, creation returns `undefined`. Verification returns either
`{ valid: true, payload }` or `{ valid: false, reason }`. A missing token or key
uses `reason: 'missing'`; signature, expiry and audience failures use `invalid`.
Do not record verified-document evidence after either failure.

The default issuer is `c15t`. The default audience is scoped by `tenantId`, and
the default lifetime is one day. Use the same trusted tenant during signing and
verification. These helpers use HS256 and need a server-only signing secret.

Legal-document snapshots describe a version and hash. `/init` policy snapshot
tokens describe the policy decision for a visitor. They use separate settings,
audiences and lifetimes; do not interchange the tokens.

# Request logging
URL: https://c15t.com/docs/self-host/guides/observability
Inspect failed backend requests, enable request logs and send events to your existing logging pipeline.

## Choose the request log level

The backend logs rejected and failed requests by default. Successful requests
produce no request log at the default `warn` level. Configure logging directly on
`c15tInstance`, not inside `defineConfig`.

```ts title="src/consent-backend.ts"
import { c15tInstance } from '@c15t/backend';

import config from '../c15t-backend.config';

export const backend = c15tInstance({
	...config,
	observability: {
		level: 'info',
		service: 'consent-backend',
		exclude: ['/status'],
	},
});
```

|Level|Requests logged|
|--|--|
|`silent`|None; no logging middleware is installed.|
|`error`|Server failures with status 500 or higher.|
|`warn`|Rejections and failures with status 400 or higher. Default.|
|`info`|Every request.|
|`inherit`|Use the host application's existing evlog configuration.|

## Use your existing logging pipeline

`observability.drain` receives evlog drain events. `enrich` can add fields before
draining. `include` limits logged route patterns; `exclude` takes precedence.
Automatic redaction is enabled unless explicitly disabled.

The backend's log level and service name configure process-global evlog state.
If several instances share a process, configure evlog once in the host and use
`level: 'inherit'` without a per-instance `service`. Otherwise the most recently
constructed instance can change logging for the others.

## Diagnose a failed save

Correlate the request's HTTP status and error code with its server event. SQL
failures deliberately omit database details from the public response. The
server log records the underlying error. Consent writes include whether the
submission created a record or replayed an existing one, plus receipt and
decision identifiers when present. `consent.decisionSource` is
`snapshot_token_replayed` for a save that arrived after its policy token
expired; see [late saves](/docs/self-host/api/endpoints#late-saves).

A valid HTTP response with a failed policy resolution needs a configuration
check too. Invalid `manifest.policyRules` produce a startup warning and a failed
policy result. Inspect the manifest's `policyFailure` and the response's
`policyResolution` instead of treating a `200` as a matched policy.

Request logs are operational diagnostics. Stored consent records have their
own persistence and are not replaced by a logging drain.

# Backend configuration
URL: https://c15t.com/docs/self-host/api/configuration
Options for a self-hosted c15t backend in c15t-backend.config.ts and c15tInstance, covering SQL storage, trusted origins, policies, signing, script routes and request logging.

## Configure the server

Use [Inth](https://inth.com) when you want managed hosting. These options belong
to a self-hosted `@c15t/backend` instance. Browser `hosted()` options only select
how a client connects; they do not configure the backend's policy.

```ts title="c15t-backend.config.ts"
import { defineConfig, policyRulePresets } from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

export default defineConfig({
	database: { dialect: 'postgres', url, schema: 'c15t' },
	basePath: '/api/c15t',
	trustedOrigins: ['https://app.example.com'],
	manifest: { policyRules: [policyRulePresets.europeOptIn()] },
	ipAddress: { tracking: false },
});
```

The example uses the Europe preset for its matching locations and unknown-location
fallback. Add reviewed rules for other locations in
[policy configuration](/docs/self-host/guides/policy-packs).

## Instance options

|Option|Purpose and default|
|--|--|
|`database`|Required PostgreSQL, MySQL or SQLite connection, or an Effect SQL client layer.|
|`basePath`|Mount prefix to strip before routing. Set it when the handler receives paths such as `/api/c15t/init`.|
|`trustedOrigins`|Hosts whose browsers may call the backend cross-origin, such as `app.example.com` or `*.example.com`. Empty or absent allows none. `GET /init` answers every origin regardless; see [query parameters and CORS](/docs/self-host/api/endpoints#query-parameters-and-cors).|
|`tenantId`|Fixed tenant for this instance's database queries. Omitted uses the single-tenant scope with null tenant IDs. An empty or padded string, or a non-string such as `null`, throws when the instance is built. This is the only tenant setting; `manifest.tenantId` is no longer accepted and throws.|
|`requireTenantId`|Set to `true` when several tenants share one database. The instance throws at construction if `tenantId` is missing, instead of running in the single-tenant scope. Defaults to `false`.|
|`hosting`|Who runs this backend: `'self-hosted'` (the default) or `'inth'`, which only Inth's hosted platform sets. `/init` and `/manifest` report it, and browsers read it as `window.c15t.hosting`. It is not signed, so use it for debugging and support, not as proof of hosting. Any other value throws when the instance is built, and so does `manifest.hosting`.|
|`manifest`|Policy rules, translations, branding and IAB configuration published by `/manifest` and resolved by `/init`.|
|`manifestCache`|Public manifest cache durations in seconds. Defaults to `sMaxAge: 300`, `staleWhileRevalidate: 86400`.|
|`apiKeys`|Keys accepted as `Authorization: Bearer <key>` for administrative endpoints. No keys means no request authenticates.|
|`policySnapshot`|Optional policy decision signing key, issuer, audience and lifetime. Default lifetime is 1,800 seconds when signing is enabled. `replayWindowSeconds` (default 604,800, 7 days) is how long after a token expires a save made while it was valid is still accepted; `0` refuses every late save. See [late saves](/docs/self-host/api/endpoints#late-saves).|
|`identityToken`|`signingKey` of at least 32 bytes, plus optional `issuer` (default `c15t`) and `audience` (default `c15t-identity`), for verifying [identity tokens](/docs/self-host/api/endpoints#verify-identity-links). Without it, only API-key requests verify links. Keep the key secret, one per tenant.|
|`legalDocumentSnapshot`|Legal-document signing configuration type. It does not automatically issue or verify HTTP tokens. Use the [explicit signing helpers](/docs/self-host/guides/legal-document-snapshot-integration); their default lifetime is 86,400 seconds.|
|`gvl`|Server-side Global Vendor List loading and cache configuration. Writing the block is the opt-in: `/init` carries the list for every matched IAB policy. `enabled: false` declines.|
|`ipAddress`|IP recording options. Masking is on unless disabled; `tracking: false` records no IP.|
|`openapi`|Enabled by default at `/spec.json`. Supports `enabled`, `specPath`, `title` and the documented server `basePath`.|
|`script`|Script-tag routes at `/c15t.js`, `/c15t.headless.js` and `/c15t.iab.js`. On by default; see [browser script routes](#browser-script-routes).|
|`version`|Version reported by the status endpoint and OpenAPI document.|
|`observability`|Logging configuration passed directly to `c15tInstance`. Defaults to warning and error requests.|
|`sessions`|`onReport` receives a report for each visitor resolution: framework servers send them to `POST /sessions`, and the backend's own `/init` adds one. Nothing is stored, and a failing sink never fails the request. Pass it to `c15tInstance`, not `defineConfig`.|

`defineConfig()` checks types and returns the supplied object. It does not load
environment variables or run migrations. It deliberately rejects `observability`;
pass logging callbacks when constructing the instance instead.

## Manifest options

|Option|What it changes|
|--|--|
|`policyRules`|Ordered canonical policy rules. Author this field, not the generated manifest's `policyPacks`.|
|`appName`|Application name included in configuration.|
|`branding`|Branding setting, defaulting to `c15t`.|
|`customTranslations`, `i18n`|Translation overrides and locale configuration.|
|`iab`|`enabled`, `cmpId`, `customVendors` and the GVL `endpoint`.|
|`vendors`, `vendorListVersion`|Vendors offered for vendor-level consent outside IAB, returned from `/init` and merged with vendors declared in the client. The version label is shown to the visitor and surfaced to dev tools, never used to force re-consent; a saved vendor decision carries the grant map and its time, not the label.|

## Browser script routes

The backend serves `/c15t.js`, `/c15t.headless.js` and `/c15t.iab.js` by
default, so a self-hosted instance can serve a configured
[script tag](/docs/frameworks/html/quickstart) without a separate bundle
deployment. Turn them off when you do not use the script tag:

```ts
const backend = c15tInstance({ ...config, script: { enabled: false } });
```

The `/c15t.js` route serves the hosted bundle with its backend URL already
configured. It resolves each visitor's policy through `/init`. The headless
and IAB routes inline the public manifest and resolve it in the browser.
Keep secrets out of `script.config`.

`@c15t/backend` installs `@c15t/browser` as a runtime dependency, including its
core, UI, IAB, and DevTools dependencies. Disabling the routes removes the HTTP
endpoints; it does not remove those packages from the installation. Bundle files
load when requested. A missing bundle returns `503`.

With `c15tInstance({ basePath: '/api/c15t', ... })`, a script loaded from
`/api/c15t/c15t.js` calls `/api/c15t/init` and `/api/c15t/subjects`. You do not
need to repeat the mount path in `script.backendURL`.

Pass these options under `script` in the `c15tInstance()` or `defineConfig()` options:

|Option|Default|Behavior|
|--|--|--|
|`enabled`|`true`|Register all three script routes. Set to `false` to remove them.|
|`path`|`/c15t.js`|Path for the ordinary banner and preference UI.|
|`headlessPath`|`/c15t.headless.js`|Path for the runtime without UI.|
|`iabPath`|`/c15t.iab.js`|Path for the optional IAB CMP and preference UI.|
|`backendURL`|Derived from the request origin and configured `basePath`, or the request path when `basePath` is omitted|Backend base URL embedded in the bundle. Set it explicitly when a proxy rewrites the public path or origin.|
|`config`|`{}`|Browser defaults embedded in the response. Page-queued configuration overrides these defaults.|
|`bundles`|Files resolved from `@c15t/browser`|Override filesystem paths by `full`, `headless`, or `iab` key. Requires a runtime with Node filesystem APIs.|

The routes share the `/manifest` cache policy through `manifestCache` and return
ETags for conditional requests. See the [endpoint reference](/docs/self-host/api/endpoints)
and [script-tag guide](/docs/frameworks/html/quickstart) for usage.

## Origins, identity and secrets

A `trustedOrigins` entry matches a hostname on any web scheme. Add a port to
pin one, such as `localhost:3000`. `*.example.com` matches subdomains, and `*`
allows every origin. CORS controls which browser pages can read responses. It is not authentication and does not
prevent a non-browser client from calling a public endpoint. `GET /init` is
open to every origin without credentials, because it returns only public
policy data for the request's location; consent saves and subject reads keep
the allowlist. Keep API keys,
database credentials and signing keys in server environment variables.

A `tenantId` scopes an instance, not an arbitrary incoming header. Construct the
correct tenant instance in trusted application code. Do not choose a tenant from
an unchecked browser value.

When several tenants share one database, set `requireTenantId: true` on every
instance. Without it, an instance whose tenant lookup returned `undefined` starts
in the single-tenant scope. It then writes consents with a null tenant, which
the tenant that owns them never reads, and nothing reports the problem.

```ts title="lib/c15t.ts"
import { c15tInstance, type C15TInstance } from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

// One instance per tenant: each instance owns a connection pool.
const instances = new Map<string, C15TInstance>();

export function instanceFor(tenantId: string | undefined) {
	const key = tenantId ?? '';
	let instance = instances.get(key);
	if (!instance) {
		instance = c15tInstance({
			database: { dialect: 'postgres', url },
			tenantId,
			// Throws here if the tenant lookup returned undefined.
			requireTenantId: true,
		});
		instances.set(key, instance);
	}
	return instance;
}
```

Subject IDs are chosen by the browser and are unique across the whole database,
not per tenant. When a save names a subject ID that another tenant already holds,
the backend answers `409 SUBJECT_CONFLICT` and writes nothing. The c15t client
then generates a new subject ID for that visitor and sends the choice once more.

`ipAddress.ipAddressHeaders` overrides the ordered headers used to record an IP.
Configure the reverse proxy to replace trusted forwarding headers. IP recording
and policy location resolution are separate operations.

See [HTTP endpoints](/docs/self-host/api/endpoints),
[request logging](/docs/self-host/guides/observability) and
[legal-document snapshots](/docs/self-host/guides/legal-document-snapshot-integration).

# HTTP endpoints
URL: https://c15t.com/docs/self-host/api/endpoints
HTTP endpoints of a self-hosted c15t v3 backend for the manifest, /init, session reports, consent saves, identity links, the script tag and legal-document releases.

## Find your API base URL

All paths are relative to the backend's mount point. With
`basePath: '/api/c15t'`, `/manifest` is available at `/api/c15t/manifest`.
The framework adapters call these endpoints for you. Prefer the adapter unless
you are building a custom transport or server integration. For server code,
the [Node.js SDK](/docs/self-host/api/node-sdk) wraps these endpoints with typed
inputs, results and retries.

|Method and path|Purpose|API key|
|--|--|--|
|`GET /status`|Service status and configured version.|No|
|`GET /manifest`|Geo-independent policy configuration, optionally sliced with `?language=en`.|No|
|`GET /init`|Resolve configuration for this request's location, language and privacy signals.|No|
|`POST /sessions`|Report an init a host resolved from a cached manifest. Server-to-server only; nothing is stored.|No|
|`POST /subjects`|Record a consent submission and its category receipts.|No|
|`GET /subjects/:id`|Read this subject's consent status and merged choices. Optional `?type=a,b` filter.|No, the subject ID is the capability|
|`PATCH /subjects/:id`|Link `externalId` and optional `identityProvider`. The link counts in reads by external ID only when [verified](#verify-identity-links).|No|
|`GET /subjects?externalId=...`|Retrieve subjects verifiably linked to an external identity.|Required|
|`GET /consents/check?externalId=...&type=a,b`|Return `hasConsent` and `isLatestPolicy` for every requested type, from verified links only.|Required|
|`GET /experiments/:id/summary?from=...&to=...&domain=...`|Choices per arm of a [banner experiment](/docs/guides/banner-experiments), split by action and surface, with the median time to decision.|Required|
|`PUT /legal-documents/:type/current`|Publish a legal document's current version, hash and effective date.|Required|
|`GET /spec.json`|Discover the enabled OpenAPI routes.|No|

Subject IDs allow public reads of that subject's state. Treat them as private
capabilities. Do not expose administrative API keys to make browser requests.

## Fetch reusable configuration

```bash
curl -i 'http://localhost:3000/api/c15t/manifest?language=en'
```

`/manifest` returns the policy configuration and a revision, with an `ETag` and
public cache headers. It contains no visitor's consent choices. A matching
`If-None-Match` returns `304`. See [caching](/docs/self-host/guides/caching) before
putting a CDN in front of the backend.

## Resolve a request with `/init`

```bash
curl -i 'http://localhost:3000/api/c15t/init' \
  -H 'x-c15t-country: DE' \
  -H 'Accept-Language: en'
```

This development request supplies a location explicitly. In production, use the
framework adapter and trusted deployment headers. `/init` resolves location,
language and GPC against the manifest. Its `policyResolution` distinguishes a
matched rule from an unmatched or failed resolution. A `200` response alone does
not establish that a rule matched.

### Query parameters and CORS

A browser on another origin sends `/init` with no custom request header, so
the request needs no CORS `OPTIONS` preflight before the banner can show. The
client's inputs travel in the query string instead:

|Query parameter|Replaces header|Value|
|--|--|--|
|`v`|`x-c15t-version`|Client package version.|
|`contract`|`x-c15t-policy-contract`|Policy contract the client reads. Any other value than `1` gets an `unsupported-contract` failure.|
|`country`|`x-c15t-country`|Country override.|
|`region`|`x-c15t-region`|Region override.|
|`gpc`|`x-c15t-gpc`|GPC override, `1` or `0`. Other values are ignored.|
|`experiment`|`x-c15t-experiment`|Experiment arm as `<id>=<arm>`, each part URI-encoded.|

The backend reads each parameter first and the header second, so older
clients and server-to-server callers that send the headers keep working.
`Accept-Language` stays a header because browsers send it without a
preflight. The journey parameters `journey`, `journeyScope` and `stored` also
travel in the query string. The backend still reads the `c15tJourney`,
`c15tJourneyScope` and `c15tStored` names that `3.0.0-alpha.8` and `alpha.9`
clients send.

c15t reserves these names on an init URL. If your `initURL` already carries
one, such as `/api/consent/init?country=US`, c15t replaces it with its own
value, so each name appears once. A reserved name c15t does not send on that
request passes through, and the backend reads it as that input.

`/init` answers any origin. A trusted origin gets its own origin back with
`Access-Control-Allow-Credentials: true`, as older clients send `/init` with
cookies. Any other origin gets `Access-Control-Allow-Origin: *` and no
credentials, which is enough for current clients: they send `/init` without
cookies to another origin, and `/init` reads none. Every other route,
including `POST /subjects`, still answers only origins in `trustedOrigins`.

The overrides are visitor-controlled in either form. If your edge strips
incoming `x-c15t-*` headers so visitors cannot choose their own policy rule,
strip `country`, `region` and `gpc` from `/init` too.

### Vendor scope

`x-c15t-vendors` is optional. It takes a comma-separated list of the vendor
IDs an application ships. On a matched IAB rule the `gvl` in
the response is then the intersection of that list and `gvl.vendorIds`, so the
header can shrink the served list and cannot widen it. See
[IAB backend configuration](/docs/self-host/guides/iab-tcf).

Every `/init` and `/manifest` response carries `hosting`: `'self-hosted'`, or
`'inth'` from Inth's hosted platform. Set it with the instance's
[`hosting` option](/docs/self-host/api/configuration#instance-options). Backends
older than this field omit it.

`/init` uses `Cache-Control: no-store`. It can include a signed
`policySnapshotToken` when signing is configured and a policy matched. For
request-time framework rendering, prefer a cached manifest and local resolution
when the adapter supports it. Do not cache one visitor's resolved `/init` result
as shared configuration.

## Report a session

```bash
curl -i 'http://localhost:3000/api/c15t/sessions' \
  -H 'Content-Type: application/json' \
  -H 'X-C15T-Version: 3.0.0' \
  -H 'X-C15T-Client-IP: 203.0.113.42' \
  -H 'User-Agent: Mozilla/5.0' \
  -d '{"source":"route","revision":"…","resolution":"matched","policy":{"id":"eu-opt-in","fingerprint":"…","matchedBy":"country","model":"opt-in"},"country":"DE","region":null,"language":"de","gpc":false}'
```

A framework server that resolves consent from a cached manifest never calls
`/init`, so it reports each resolution here instead. The framework adapters send
the report server-to-server after responding to the visitor. The backend
applies its `ipAddress` settings, passes the report to `sessions.onReport`,
logs it, and answers `204`. It writes nothing to the database.

The route rejects requests a browser could send. A request with an `Origin`
header, or without the `X-C15T-Version` header, gets `400`. The visitor's user
agent travels as `User-Agent`, and the visitor's address as `X-C15T-Client-IP`,
because a platform in front of the backend rewrites `X-Forwarded-For`.

The body follows `consentSessionReportSchema` from `@c15t/schema`. `source` is
`route` for an init route and `render` for a server-rendered page. `init` is
reserved for the backend's own `/init`, which emits the same report. Prefetches,
prerenders and `HEAD` requests send no report.

A report is one resolution, not one visitor. A page view can produce a `render`
and a `route` report. When the client sends a journey, the reports and the
save's `POST /subjects` carry the same `journey.id`
([details](/docs/concepts/data-fetching#link-an-init-to-the-save-that-follows)).
Without one, group reports by address and user agent within a time window; that
count is approximate.

## Serve the script tag

`GET /c15t.js` serves the hosted [script-tag build](/docs/frameworks/html/quickstart)
of the consent banner. A queued `config` call sets the backend URL, hosted
mode and the defaults from `script.config`. The client resolves the
visitor's policy through `/init`; this route does not inline a manifest.

`GET /c15t.headless.js` serves the build with no UI. `GET /c15t.iab.js` serves
the optional IAB CMP and preference UI. Both routes keep their queued
manifest configuration. Use `script.iabPath` to change the IAB route's path
and `script.config.iab` to set CMP options.

|Query|What it does|
|--|--|
|`language`|Override the language used by the hosted `/c15t.js` client. On headless and IAB routes, slice the inlined manifest's translations to one language.|

Cached like `/manifest`: `Cache-Control: public, s-maxage=…` and an `ETag` that answers `If-None-Match` with `304`. `@c15t/backend` installs `@c15t/browser`, which provides the bundles; `script.bundles` overrides their file paths. Set `script.enabled: false` to remove all three routes.

## Save and read choices

The v3 client sends `POST /subjects` with a domain, policy type, `preferences`,
`givenAt` timestamp and the per-category receipts confirmed by the action. Let the
client construct this payload so effective permissions are not mistaken for an
explicit grant. Hydration, a dismissed notice and a GPC signal are not consent
submissions.

The response includes `subjectId`, `consentId`, `appliedPreferences` and `givenAt`.
Read `GET /subjects/:id` to inspect merged category choices. A type filter changes
which consent records are returned and how `isValid` is calculated; it does not
filter away the subject's cookie-banner choice state.

When the client declares vendors, a save also carries `vendorChoice`: the complete
per-vendor grant map with one confirmation time. The backend stores it as sent on
the consent row, including vendors the client declared in code rather than in the
manifest, and returns `subjectVendorChoice`: the most recent act decides every
vendor it names, and a vendor an earlier act decided but the latest one omits
keeps that earlier grant. The aggregate's `confirmedAt` is the time of the oldest
decision still in it, so a retained grant is never presented as newer than it is. A map that omits a vendor the manifest declares is
stored too: the client saw an older manifest, so its silence about that vendor
is not a decision. A vendor no act ever named follows its category.
Retrying the same act with a different map is a `CONFLICT`, like a retry with
different receipts, and so is any retry against a stored map that cannot be
read. Migration `4-vendor-choice` adds the column.

### Late saves

A browser that can't deliver a save keeps it and sends it again on the next
page load or when it comes back online, for up to 7 days. The replay carries
the original `givenAt` (the click time) and the `policySnapshotToken` from the
`/init` the visitor saw. Tokens expire after `ttlSeconds` (30 minutes by
default), so a replay often arrives with an expired token.

With signing configured, the backend accepts such a save when all of these
hold:

* The token's signature, issuer and tenant audience verify.
* The token was valid at `givenAt`: `givenAt` is between the token's issue
  time and its expiry, with 10 minutes of slack for the visitor's clock.
* The request arrives no later than `policySnapshot.replayWindowSeconds` after
  the token expired (7 days by default).
* The manifest still has the policy the token names under the same
  fingerprint.

The record keeps `givenAt` as sent, `createdAt` is when the backend received
it, and `runtimePolicySource` is `snapshot_token_replayed` instead of
`snapshot_token`. The request's wide event carries the same value as
`consent.decisionSource`. A save that arrived before its token expired is
unchanged. Retrying a save that already landed returns the existing record.

The backend refuses these, and the c15t client drops them from its replay
queue instead of retrying:

|Response|When|
|--|--|
|`409 POLICY_SNAPSHOT_EXPIRED`|`givenAt` is outside the token's lifetime, or the request arrived after the replay window|
|`409 POLICY_SNAPSHOT_INVALID`|The token doesn't verify, or its claims are incomplete|
|`422 STALE_POLICY`, reason `policy-changed`|The policy the token names is no longer in the manifest under that fingerprint. The visitor saw the old text, so the choice is not recorded against the new one.|
|`409 CONFLICT`|This act was already recorded with different receipts, purposes or vendor grants. The earlier record stands.|
|`409 SUBJECT_CONFLICT`|Another tenant on the same database already holds the save's `subjectId`. The client generates a new subject ID and sends the choice once under it; the save is dropped only if that also fails.|

A refused save stays recorded in the visitor's browser only. `givenAt` is
supplied by the client. A late save can only claim a time inside the lifetime
of a token this backend signed, for a policy that is still current, but within
that range the backend can't tell a genuine click time from a chosen one.

The backend does not store GPC as a standing opt-out. `/init` reads `Sec-GPC`
on each request, and the client applies the signal live in the browser.

## Verify identity links

`GET /subjects?externalId=` and `GET /consents/check` count a subject only when
its link to the external ID was verified: the `POST /subjects` or
`PATCH /subjects/:id` that made it carried an API key, or an `identityToken`
signed with [`identityToken.signingKey`](/docs/self-host/api/configuration).
Unverified links are stored but skipped by those reads.

Mint tokens with [`createIdentityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser). From
another language, sign an HS256 JWT with `sub` set to the external ID, `aud`
`c15t-identity`, `iss` `c15t`, an `exp`, and optionally `idp` matching
`identityProvider`.

|Response|Cause|
|--|--|
|`401 IDENTITY_TOKEN_INVALID`|`PATCH` only. The token doesn't verify, has expired, or names another external ID or provider. Nothing changes.|
|`409 IDENTITY_CONFLICT`|`PATCH` only. The subject's current link is verified and this request isn't, so it can't replace it. Sending the same identity again succeeds.|

`POST /subjects` never refuses a consent because of its token: a bad token
leaves the link unverified, and the token only applies when the save creates
the subject. Verify an existing subject with `PATCH /subjects/:id`.

## Make an administrative request

Use a server environment variable containing a configured API key:

```bash
curl 'http://localhost:3000/api/c15t/subjects?externalId=customer-123' \
  -H "Authorization: Bearer $C15T_API_KEY"
```

From Node.js, `subjects.list` in the [Node.js SDK](/docs/self-host/api/node-sdk#export-a-users-records)
makes the same request.

Missing or invalid keys return `401` on protected routes. Invalid input returns
an error body containing `message` and `cause.code`; individual validation paths
can return `400` or `422`. Inspect both the HTTP status and error code. Database
errors return a generic failure to the client, with details available through
[server logging](/docs/self-host/guides/observability).

The OpenAPI document lists available routes and security declarations. Use the
published `@c15t/schema` contracts and client adapters for complete payload types;
the generated document does not describe every field accepted by each handler.

# Node.js SDK
URL: https://c15t.com/docs/self-host/api/node-sdk
Call the c15t consent API from server code with @c15t/node-sdk. Check consent before sending email, link users after sign-in, export a user's records, publish legal documents from CI and read experiment results.

## When to use the SDK

`@c15t/node-sdk` is a typed client for the [HTTP endpoints](/docs/self-host/api/endpoints)
of a c15t backend, hosted on Inth or self-hosted. Use it in server code:

* Check `consents.check` before you send a marketing email to a signed-in
  user.
* Read a visitor's banner categories with `subjects.get` before you send a
  server-side analytics event.
* Link a visitor's consent records to your user ID after sign-in with
  `subjects.identify`.
* Export everything recorded for one user with `subjects.list`, for a data
  access request.
* Publish a new privacy policy or terms release from CI with
  `legalDocuments.publish`.
* Read per-arm counts for a [banner experiment](/docs/guides/banner-experiments)
  with `experiments.summary`.

Do not use it in the browser. The framework adapters already call the backend
for the banner, and four methods need an API key that must stay on the server.

## Install

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/node-sdk@alpha`|
|pnpm|`pnpm add @c15t/node-sdk@alpha`|
|yarn|`yarn add @c15t/node-sdk@alpha`|
|bun|`bun add @c15t/node-sdk@alpha`|

The client needs Node.js 20.19 or later, or another runtime with `fetch`,
`AbortSignal.any` and `crypto.randomUUID`. It is ESM only.

## Create a client

Pass the URL where the backend is mounted, path included. The client reads no
environment variables, so pass every value explicitly.

```ts title="src/lib/c15t-client.ts"
import { createC15tClient } from '@c15t/node-sdk';

export const c15t = createC15tClient({
	baseUrl: process.env.C15T_API_URL || 'http://localhost:5173/api/self-host',
});
```

This SvelteKit example reads the URL from its own `C15T_API_URL` variable and
falls back to the demo's local backend. `baseUrl` keeps its path: with `https://app.example.com/api/c15t`, `status()`
requests `https://app.example.com/api/c15t/status`. For Inth, use the URL from
your project, such as `https://your-project.inth.app`.

A client without `apiKey` has no `consents.check`, `subjects.list`,
`experiments.summary` or `legalDocuments.publish`. Those four endpoints require
a key. Create a second
client with one where you need them:

```ts title="src/lib/server/c15t-admin.ts"
import { createC15tClient } from '@c15t/node-sdk';

const apiKey = process.env.C15T_API_KEY;
if (!apiKey) throw new Error('Set C15T_API_KEY');

export const c15tAdmin = createC15tClient({
	baseUrl: 'https://app.example.com/api/c15t',
	apiKey,
});
```

A self-hosted backend accepts the keys listed in its
[`apiKeys` option](/docs/self-host/api/configuration). The client sends the key
as `Authorization: Bearer <key>`. Check that the key is set before you pass it,
as above. With a `string | undefined` key, TypeScript cannot tell which client
you get, and the key-only methods are not callable until you narrow it. Called
on a client without a key, they return `MISSING_API_KEY` and send nothing.

|Option|Default|What it does|
|--|--|--|
|`baseUrl`|Required|Backend URL, path included. A query string or fragment is rejected.|
|`apiKey`|None|Sent as `Authorization: Bearer`. Adds the key-only methods.|
|`fetch`|`globalThis.fetch`|`fetch` implementation, for tracing, proxies or tests.|
|`headers`|`{}`|Headers sent with every request.|
|`timeoutMs`|`10000`|Deadline for one attempt, reading the response body included. An integer from `1` to `2147483647` milliseconds.|
|`retry`|`{ maxRetries: 2, initialDelayMs: 200, maxDelayMs: 5000 }`|[Retry settings](#retries-and-timeouts), or `false` to never retry.|
|`onEvent`|None|Called for each request, response and retry.|

`createC15tClient` checks every option and throws one `C15tConfigurationError`
listing all the problems, with each in `error.issues`. It is the only error the
SDK throws. Create the client at module scope, so a bad option fails at
startup rather than on the first request.

The client refuses an `http:` URL together with an API key, because the key
would travel in the clear. `http:` with a key is accepted only for `localhost`,
`127.0.0.1` and `[::1]`.

## Handle results

Every method resolves to a result object and never rejects. Check `ok` before
reading `data`:

```ts
const result = await c15t.subjects.get(subjectId);

if (!result.ok) {
	switch (result.error.code) {
		case 'NOT_FOUND':
			return null;
		default:
			throw result.error;
	}
}

return result.data.consents;
```

|Field|On|What it holds|
|--|--|--|
|`ok`|Both|`true` for success, `false` for failure|
|`data`|Success|The response body. Dates are `Date` objects.|
|`status`|Success|HTTP status|
|`requestId`|Success|The `x-request-id` the call sent|
|`headers`|Success|Response `Headers`|
|`error`|Failure|A `C15tError`|

`error.code` is typed per method. `subjects.get` can fail with `NOT_FOUND` or
`DATABASE_ERROR` from the backend, plus the client codes every method shares.
TypeScript flags a `case` for a code the method cannot return.

|Client code|When|
|--|--|
|`INVALID_INPUT`|The input or call options failed validation. Nothing was sent. `error.issues` lists each problem with a `path`.|
|`MISSING_API_KEY`|The method needs an API key and the client has none. Nothing was sent.|
|`NETWORK_ERROR`|The request failed before a response arrived.|
|`TIMEOUT`|One attempt took longer than `timeoutMs`.|
|`ABORTED`|Your `signal` aborted the call.|
|`UNEXPECTED_RESPONSE`|A response the endpoint does not document, such as a proxy's HTML error page or a body without the documented shape. An undocumented backend code is kept in `error.serverCode`.|

Every `C15tError` also has `message`, `status` (when a response arrived),
`requestId` (when something was sent) and `retryable`. `retryable` says whether
the same call could succeed later; the client has already retried by the time
you see it. A `STALE_POLICY` error carries `reason`: `policy-changed`,
`decision-mismatch` or `incomplete-inputs`. An unrecognized reason from the
backend is `undefined`. `error.toJSON()` gives a plain object for logs.

### Throw instead with `unwrap`

`unwrap(result)` returns `data` or throws the `C15tError`. Use it where a failure
should stop the surrounding work, such as a job with its own retry.
`isC15tError(error, ...codes)` checks a caught value and narrows its code:

```ts
import { isC15tError, unwrap } from '@c15t/node-sdk';

try {
	const { subjects } = unwrap(await c15tAdmin.subjects.list({ externalId }));
	await writeExport(subjects);
} catch (error) {
	if (isC15tError(error, 'UNAUTHORIZED')) {
		// error.code is 'UNAUTHORIZED': the key is wrong or revoked
	}
	throw error;
}
```

To name a method's types elsewhere, use `C15tDataOf` and `C15tErrorCodeOf`:

```ts
import type { C15tDataOf, C15tErrorCodeOf } from '@c15t/node-sdk';

type Subject = C15tDataOf<typeof c15t.subjects.get>;
type SubjectError = C15tErrorCodeOf<typeof c15t.subjects.get>;
```

## Methods

|Method|Endpoint|API key|
|--|--|--|
|`consents.check({ externalId, types })`|`GET /consents/check`|Required|
|`subjects.identify(id, { externalId, identityProvider, identityToken })`|`PATCH /subjects/:id`|No, but [verifies](#link-a-user-after-sign-in) only with a key or token|
|`subjects.get(id, { types })`|`GET /subjects/:id`|No|
|`subjects.create(input)`|`POST /subjects`|No|
|`subjects.list({ externalId })`|`GET /subjects`|Required|
|`legalDocuments.publish(type, { version, hash, effectiveDate })`|`PUT /legal-documents/:type/current`|Required|
|`experiments.summary(id, { from, to, domain })`|`GET /experiments/:id/summary`|Required|
|`status()`|`GET /status`|No|
|`init({ language, country, region, gpc })`|`GET /init`|No|
|`manifest({ language, ifNoneMatch })`|`GET /manifest`|No|

Every method also takes [call options](#call-options) as its last argument.
`createIdentityToken` is a separate export, not a client method; see
[Verify a link made in the browser](#verify-a-link-made-in-the-browser).
The examples below use the `c15t` and `c15tAdmin` clients from
[Create a client](#create-a-client).

### Check consent before sending email

`consents.check` reports, for each requested policy type, whether the user has
a consent record of that type and whether one of those records is for the
current policy version. The user is your own ID. Only subjects with a
[verified link](#link-a-user-after-sign-in) to it count, and the method needs
an API key.

```ts
const result = await c15tAdmin.consents.check({
	externalId: user.id,
	types: ['marketing_communications'],
});

if (result.ok && result.data.results.marketing_communications.hasConsent) {
	await sendNewsletter(user);
}
```

`results` has a key for every type you request, so
`results.marketing_communications` needs no `?`. A type with no record, or one
the backend does not know, comes back as
`{ hasConsent: false, isLatestPolicy: false }`. A response missing a requested
type or containing non-boolean consent flags returns `UNEXPECTED_RESPONSE`.

`hasConsent` means a record of that type exists. The check does not read the
record's `preferences`, so record a `marketing_communications` consent only
when the user opts in. Treat a failed check as no consent.

`types` must be a non-empty array. Each type is one entry; a type containing a
comma returns `INVALID_INPUT`.

### Gate a server-side event on a banner category

`consents.check` reports `hasConsent: true` for `cookie_banner` after a reject
too, because a reject is also a recorded choice. To send a server-side analytics event only
when the visitor allowed measurement, read the category from `subjects.get`:

```ts
const result = await c15t.subjects.get(subjectId);
const measurement = result.ok
	? result.data.subjectChoice?.categories.measurement
	: undefined;

if (measurement?.value === true) {
	await trackPurchase(order);
}
```

`subjectChoice.categories` holds the latest receipt for `measurement`,
`marketing`, `functionality` and `experience`, each with `value` and
`confirmedAt`. A category with no receipt is absent. `subjectChoice` is `null`
when the subject has no usable choice.

### Link a user after sign-in

`subjects.identify` links a subject, the ID the c15t client stores in the
visitor's browser, to your user ID. After a verified link, `consents.check` and
`subjects.list` find the subject's records by your ID.

```ts
const result = await c15tAdmin.subjects.identify(subjectId, {
	externalId: user.id,
	identityProvider: 'auth0',
});
```

A client with an API key verifies every link it makes. Call
`subjects.identify` this way when your server handles sign-in and the frontend
sends the subject ID with the request. `identityProvider` is optional; the
backend stores `external` without it. `data.subject` holds `id`, `externalId`
and `identityProvider`. An unknown subject ID returns `NOT_FOUND`. Linking the
same user again changes nothing.

Without a key or an identity token the link is stored but unverified, and
`consents.check` and `subjects.list` ignore it. It also can't replace a
verified link; that returns `IDENTITY_CONFLICT`.

### Verify a link made in the browser

The browser adapters link the subject themselves when you call their
`identify()` after sign-in. To verify that link, sign an identity token on
your server and pass it to `identify()`. Set the same key as the backend's
[`identityToken.signingKey`](/docs/self-host/api/configuration):

```ts title="src/lib/server/identity.ts"
import { createIdentityToken } from '@c15t/node-sdk';

const signingKey = process.env.C15T_IDENTITY_SIGNING_KEY;
if (!signingKey) throw new Error('Set C15T_IDENTITY_SIGNING_KEY');

export function identityTokenFor(userId: string) {
	return createIdentityToken({ externalId: userId }, { signingKey });
}
```

Render the token into the signed-in page and pass it to `identify()`. A `user`
passed when creating the client only links a subject that the next save
creates, so call `identify()` for a visitor who consented before signing in:

```ts
await identify({ externalId: user.id, identityToken });
```

The token expires after `ttlSeconds`, one hour by default, so mint one per page
load. If you pass `identityProvider`, the browser must send the same one. A
failed token makes `identify()` return `IDENTITY_TOKEN_INVALID`, but never
blocks the first consent save; that link just stays unverified. See
[verify identity links](/docs/self-host/api/endpoints#verify-identity-links)
for the full rules.

### Export a user's records

`subjects.list` returns every subject verifiably linked to one of your user
IDs, each with its consents. It needs an API key.

```ts
const result = await c15tAdmin.subjects.list({ externalId: user.id });

if (result.ok) {
	for (const subject of result.data.subjects) {
		console.log(subject.id, subject.createdAt.toISOString());
		for (const consent of subject.consents) {
			console.log(consent.type, consent.givenAt, consent.preferences);
		}
	}
}
```

`createdAt`, `givenAt` and `policyEffectiveDate` are `Date` objects. Each
consent also has `isLatestPolicy`, `policyVersion` and `policyHash` where they
apply.

### Read one subject

`subjects.get` reads one subject by ID. Pass `types` to return only consents of
those policy types:

```ts
const result = await c15t.subjects.get(subjectId, { types: ['cookie_banner'] });
```

`data` holds `subject`, `consents`, `isValid` and `subjectChoice`, the latest
category choices across the subject's cookie-banner consents. The filter
changes which consent records come back and how `isValid` is calculated. It
does not filter `subjectChoice`. Anyone with a subject ID can read it, so treat
subject IDs as private.

### Record a consent

`subjects.create` records a consent and creates the subject if it does not
exist. Leave cookie-banner saves to the browser client, which builds the
receipts for each category. Use this method for consents your server
collects, such as terms accepted in a sign-up form:

```ts
const result = await c15t.subjects.create({
	type: 'terms_and_conditions',
	subjectId,
	domain: 'app.example.com',
	givenAt: new Date(),
	externalSubjectId: user.id,
	policyHash: termsHash,
});
```

`subjectId` uses the `sub_` format that `generateSubjectId()` from `c15t`
produces. `givenAt` takes a `Date` or epoch milliseconds. `type` decides which
other fields apply: `cookie_banner` requires `preferences`, and legal-document
types accept `policyHash`, `policyId` or `documentSnapshotToken`. Sending the
same consent again returns the existing record. `data` holds `subjectId`,
`consentId`, `givenAt` and `appliedPreferences`.

### Publish a legal document from CI

`legalDocuments.publish` stores a document release as the current version, so
new consents of that type record it. Run it from the job that ships the
document, with an API key:

```ts title="scripts/publish-privacy-policy.ts"
import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';

import { createC15tClient, unwrap } from '@c15t/node-sdk';

const apiKey = process.env.C15T_API_KEY;
if (!apiKey) throw new Error('Set C15T_API_KEY');

const c15t = createC15tClient({
	baseUrl: 'https://app.example.com/api/c15t',
	apiKey,
});

const document = await readFile('legal/privacy-policy.md');
const hash = `sha256:${createHash('sha256').update(document).digest('hex')}`;

const { policy } = unwrap(
	await c15t.legalDocuments.publish('privacy_policy', {
		version: '2026-10-01',
		hash,
		effectiveDate: '2026-10-01T00:00:00.000Z',
	})
);

console.log(`Published ${policy.type} ${policy.version} as ${policy.id}`);
```

`type` is `privacy_policy`, `dpa` or `terms_and_conditions`, or one of them
with a suffix such as `terms_and_conditions_b2b`. `effectiveDate` takes a
`Date` or an ISO 8601 string. Impossible calendar dates such as `2026-02-30`
return `INVALID_INPUT` before publishing. Publishing the same hash again with the same
version and date changes nothing, so a rerun job is safe. The same hash with a
different version or date returns `CONFLICT`. See
[legal-document snapshots](/docs/self-host/guides/legal-document-snapshot-integration)
for signing the document a user saw.

### Read an experiment summary

`experiments.summary` counts choices per arm of a banner experiment. It needs an
API key.

```ts
const result = await c15tAdmin.experiments.summary('banner-shape', {
	from: '2026-09-01',
	to: '2026-09-30',
});

if (result.ok) {
	for (const arm of result.data.arms) {
		console.log(arm.arm, arm.choices, arm.byAction.accept_all);
	}
}
```

`from` and `to` take a `Date` or an ISO 8601 string. A date without a time
covers the whole day in UTC, so the example covers all of September. `domain`
narrows to one domain. The response's own `from` and `to` are strings, or
`null` when unbounded. [Read the summary from your backend](/docs/guides/banner-experiments#read-the-summary-from-your-backend)
explains each field.

### Status, init and manifest

```ts
const status = await c15t.status();
// status.data: { version, timestamp, client }

const init = await c15t.init({ country: 'DE', language: 'de', gpc: true });
// Sent as x-c15t-country, Accept-Language and x-c15t-gpc

const manifest = await c15t.manifest({ language: 'en', ifNoneMatch: etag });
if (manifest.ok && manifest.data.status === 'modified') {
	cache.set(manifest.data.manifest, manifest.data.etag);
}
```

`init` resolves the banner for one visitor. Pass `country`, `region`,
`language` and `gpc` from the request you are handling; otherwise the backend
sees your server's location. `manifest` returns
`{ status: 'modified', manifest, etag }`, or `{ status: 'not-modified', etag }`
when `ifNoneMatch` matches the current manifest. A response missing the required
manifest fields or using an unsupported schema version or branding value returns
`UNEXPECTED_RESPONSE`. Prefer the framework adapters
for rendering the banner; see [data fetching](/docs/concepts/data-fetching).

## Call options

Every method takes these as its last argument:

|Option|What it does|
|--|--|
|`signal`|Aborts the call, including a pending retry. The result is `ABORTED`.|
|`timeoutMs`|Overrides the client's per-attempt timeout.|
|`headers`|Merged over the client's headers for this call.|
|`retry`|Overrides the client's retry settings, or `false` for none. Omitted fields keep the client's values.|
|`requestId`|`x-request-id` to send. Defaults to a random UUID.|

```ts
const result = await c15t.consents.check(
	{ externalId: user.id, types: ['marketing_communications'] },
	{
		requestId: request.headers.get('x-request-id') ?? undefined,
		timeoutMs: 2000,
	}
);
```

Pass the ID of the request you are handling as `requestId` to match your logs
with the backend's. The client owns `Accept`, `Authorization`, `Content-Type`,
`x-request-id`, `x-c15t-version` and `x-c15t-policy-contract`; a header you pass
with one of those names is replaced. An invalid call option returns
`INVALID_INPUT` instead of throwing. Request bodies that cannot be serialized
as JSON, such as metadata containing a bigint or circular reference, also
return `INVALID_INPUT` before sending.

## Retries and timeouts

The client retries a call when the attempt fails with `NETWORK_ERROR`,
`TIMEOUT`, or HTTP 408, 429, 500, 502, 503 or 504. It retries only idempotent
endpoints, and every current endpoint is one: the backend returns the existing
record when it receives the same consent, link or release twice.

* With the defaults, a call makes up to 3 attempts.
* Each wait is random, up to `initialDelayMs` doubled per retry and capped at
  `maxDelayMs`: under 200 ms, then under 400 ms.
* A `Retry-After` header, in seconds or as an HTTP date, replaces the backoff.
  A `Retry-After` longer than `maxDelayMs` stops retrying and returns the error.
* Every attempt sends the same `x-request-id`.
* `maxRetries` can be 0 to 10.

`initialDelayMs` and `maxDelayMs` must be integers from `0` to `2147483647`
milliseconds. `timeoutMs` must be an integer from `1` to `2147483647`. Larger
values can overflow Node.js timers to 1 ms, so the client rejects them.

`timeoutMs` applies to each attempt, reading the response body included. The
default worst case is three 10-second attempts plus the waits. To cap the whole
call, pass a signal; the result is then `ABORTED`:

```ts
const result = await c15t.consents.check(
	{ externalId: user.id, types: ['marketing_communications'] },
	{ signal: AbortSignal.timeout(3000) }
);
```

`onEvent` reports each attempt for logging and metrics. An error it throws is
ignored.

```ts
const c15t = createC15tClient({
	baseUrl: 'https://app.example.com/api/c15t',
	onEvent: (event) => {
		if (event.type === 'retry') {
			logger.warn('c15t retry', {
				path: event.path,
				attempt: event.attempt,
				delayMs: event.delayMs,
				code: event.error.code,
				requestId: event.requestId,
			});
		}
	},
});
```

`request` events carry `method`, `path`, `requestId` and `attempt`, counted
from 0. `response` events add `status` and `durationMs`.

## Test code that uses the client

`@c15t/node-sdk/testing` exports `createMockC15tClient`, `ok` and `err`. The
mock is a full client whose methods call the handlers you pass. Handlers are
typed from the client, so wrong data, or an error code the method cannot
return, is a type error. A method without a handler rejects with an error that
names it, so a test fails when the code calls something unexpected.

Write the code under test to take the client as a parameter:

```ts title="src/newsletter.ts"
import type { C15tClient } from '@c15t/node-sdk';

export async function canEmail(c15t: C15tClient, userId: string) {
	const result = await c15t.consents.check({
		externalId: userId,
		types: ['marketing_communications'],
	});
	return result.ok && result.data.results.marketing_communications.hasConsent;
}
```

```ts title="src/newsletter.test.ts"
import { createMockC15tClient, err, ok } from '@c15t/node-sdk/testing';
import { expect, test } from 'vitest';

import { canEmail } from './newsletter';

test('emails a user who opted in', async () => {
	const c15t = createMockC15tClient({
		consents: {
			check: () =>
				ok({
					results: {
						marketing_communications: {
							hasConsent: true,
							isLatestPolicy: true,
						},
					},
				}),
		},
	});
	expect(await canEmail(c15t, 'user_123')).toBe(true);
});

test('does not email when the check fails', async () => {
	const c15t = createMockC15tClient({
		consents: { check: () => err('DATABASE_ERROR') },
	});
	expect(await canEmail(c15t, 'user_123')).toBe(false);
});
```

`ok(data, { status, requestId, headers })` and
`err(code, { message, status, reason, retryable, issues })` take optional
fields for the rest of the result.

## Upgrade from v2

The v2 `c15tClient()` and its flat methods are gone. See
[Upgrade from v2](/docs/self-host/upgrade-v3#update-the-nodejs-sdk) for the mapping.

# CLI overview
URL: https://c15t.com/docs/cli/overview
Run the c15t CLI from @c15t/cli to add c15t to an app, migrate v2 code, manage Inth projects and migrate a self-hosted database.

## Run the CLI

The CLI ships as `@c15t/cli`. Its v3 release uses the `alpha` dist-tag, like the
other c15t packages. Run it without installing:

```bash
npx @c15t/cli@alpha --help
```

`bunx @c15t/cli@alpha`, `pnpm dlx @c15t/cli@alpha` and `yarn dlx @c15t/cli@alpha`
work the same way. Keep `@alpha`; without it, npm resolves the v2 CLI.

To pin the version in your repository, install it as a development dependency
and run the `c15t` executable:

|Package manager|Command|
|:--|:--|
|npm|`npm install -D @c15t/cli@alpha`|
|pnpm|`pnpm add -D @c15t/cli@alpha`|
|yarn|`yarn add -D @c15t/cli@alpha`|
|bun|`bun add -D @c15t/cli@alpha`|

```bash
npx c15t --help
```

The package also installs the executable under its older name, `cli`.

## Commands

|Command|Purpose|
|--|--|
|`setup`|Add c15t to a Next.js or React app, or generate framework files for any supported framework. `generate` is an alias.|
|`codemods`|Rewrite `useConsentManager()` calls for v3, or run the v1 to v2 transforms.|
|`login`, `logout`, `status`|Sign in to Inth in a browser or by email approval, sign out of the shared Inth session, and check local session status. See [hosted projects](/docs/cli/commands/hosted).|
|`projects list`, `projects select`, `projects create`|Manage Inth projects and the application project preference used by setup. `instances` is an alias.|
|`self-host migrate`|Plan and apply database migrations for a self-hosted backend.|
|`skills`|Install c15t agent skills through the external skills CLI.|
|`docs`, `changelog`, `github`|Open the URL in a browser, or print it when there is no terminal.|

`setup --codex` hands frontend integration to your installed Codex CLI.
`generate` keeps deterministic file generation.

Run `npx @c15t/cli@alpha <command> --help` for a command's options.

## Pick the right command for your framework

`setup` edits an existing app layout for Next.js App Router, Next.js Pages Router
and React apps with a recognizable root component. It also writes configuration
for plain JavaScript. See [setup](/docs/cli/commands/setup).

For TanStack Start, Vue, Nuxt, Svelte, SvelteKit, Solid and Astro, `setup` with
`--framework` writes integration files and wiring instructions, and leaves your
entry point unchanged. See [framework boilerplate](/docs/cli/commands/boilerplate).

Remix and Gatsby have no CLI support. Follow the
[React guide](/docs/frameworks/react/quickstart); see
[Choose your setup](/docs/concepts/choose-your-setup) for the rendering mode.

## Next steps

* [Quickstart](/docs/cli/quickstart): plan and apply setup in an existing app.
* [Codemods](/docs/cli/commands/codemods): migrate `useConsentManager()` to v3 hooks.
* [Agents and automation](/docs/cli/automation): JSON results and calling the CLI from code.

# CLI quickstart
URL: https://c15t.com/docs/cli/quickstart
Use the c15t CLI to plan, review and apply c15t setup in an existing Next.js or React app, connected to an Inth backend.

## Plan the setup

Run setup from the app directory with your Inth backend URL. Replace
`https://your-project.inth.app` with the URL from your Inth project, including
any path prefix:

```bash
npx @c15t/cli@alpha setup hosted --backend-url https://your-project.inth.app --plan --json
```

`--plan` writes nothing and installs nothing. The JSON result lists each file
the CLI would create or change under `data.edits`, with its current and
proposed contents, and the packages it would install under
`data.dependencies`. Pass `--cwd path/to/app` to run from another directory.

With `--backend-url`, setup does not sign in to Inth, so it works on every
platform. To choose a project from your Inth account instead, sign in with
`c15t login` and see [hosted projects](/docs/cli/commands/hosted).

## Apply the setup

When the plan looks right, apply it:

```bash
npx @c15t/cli@alpha setup hosted --backend-url https://your-project.inth.app --apply
```

For a Next.js App Router app, setup adds a client provider component under
`components/consent-manager/` and wraps `{children}` in your root layout with it.
The provider renders the stock banner and preferences dialog.

Setup installs the c15t packages it needs, such as `c15t` and
`@c15t/integrations`, from the CLI's own release line, so `@c15t/cli@alpha`
installs `c15t@alpha`. It keeps packages
that are already in `package.json`. Add `--skip-install` when your workspace
tooling installs dependencies, and install `c15t@alpha` yourself.

Setup refuses to overwrite a generated component that you have edited. To
change an existing integration, edit its files rather than running setup again.

## Answer prompts instead

```bash
npx @c15t/cli@alpha setup
```

In a terminal, setup asks for the backend mode, UI style, theme and scripts.
Without a terminal, pass the mode and inputs as flags; the CLI does not guess
missing values. See [setup](/docs/cli/commands/setup) for every flag.

## Setup with Codex

Let your installed Codex CLI adapt the integration to an existing application:

```bash
npx @c15t/cli@alpha setup --codex hosted --backend-url https://your-project.inth.app
```

Replace the URL with your Inth project's backend URL. The agent receives the
c15t v3 frontend task, installs required packages from `@alpha`, and reads their
bundled docs. Add `--plan` to inspect the prompt before launching Codex. See
[agent setup](/docs/cli/automation#agent-setup-and-v3-migration-workflow).

## Check the result

1. Run your app's typecheck and build.
2. Open the app in a private window. The banner appears for a visitor your Inth
   policy asks to choose.
3. Replace any integration ID placeholders the CLI left in the provider, then
   check in DevTools Network that those vendor requests wait until you accept.
4. Reject, reload, and confirm the banner stays closed and the vendor requests
   stay absent.

The [verification guide](/docs/guides/verify-consent) covers the full release
checklist. For server rendering and other recipes, continue with your
[framework quickstart](/docs/frameworks).

# Agents and automation
URL: https://c15t.com/docs/cli/automation
Read JSON results from the c15t CLI, call it from another program with runCli, and give a coding agent a v3 setup or migration task.

## Read JSON results

```bash
npx @c15t/cli@alpha setup offline --plan --json --no-telemetry
```

`--json` writes one JSON document to stdout. Human diagnostics go to stderr. Check `success` before consuming `data`; a completed process alone does not mean the command succeeded.

```json
{
  "schemaVersion": 1,
  "success": false,
  "command": "setup",
  "exitCode": 1,
  "error": {
    "code": "INPUT_REQUIRED",
    "message": "Required command input is missing"
  }
}
```

Commands return their own data under `data`, such as generated edits, hosted projects, or a migration report. Do not parse terminal messages for those values.

## Call the CLI from code

```ts
import { runCli } from '@c15t/cli';

const result = await runCli(['setup', 'offline', '--plan', '--json'], {
	cwd: projectDirectory,
});

if (!result.success) {
	throw new Error(result.error?.message);
}
```

Importing the package does not execute a command. `runCli` returns a result without changing process arguments, the working directory, or the exit status. Prompts and telemetry are disabled by default for library callers. Supply a `logger` to route diagnostics into the host CLI. The executable adapter owns JSON serialization and process exit status.

CommonJS callers on Node versions that support `require(esm)` can use `const { runCli } = require('@c15t/cli')`.

For Inth or another host, use explicit project inputs and inspect the returned result. Standalone account commands delegate to the pinned Inth executable and use Inth's existing session and organization context. The runner never reads Inth credentials. Hosts that already own account operations should use the independent frontend exports below.

## Reuse generation in another CLI

Install `@c15t/cli@alpha` in the host project. Import the generation entry point to create a framework's quickstart files without loading the interactive runner:

```ts
import { generate, runGenerateCommand } from '@c15t/cli/generate';

const plan = generate({
	framework: 'react',
	mode: 'hosted',
	backendURL: projectBackendURL,
	scripts: ['google-tag'],
});

// Forward arguments after `inth c15t generate`:
const forwardedPlan = runGenerateCommand([
	'hosted',
	'--framework',
	'react',
	'--backend-url',
	projectBackendURL,
]);
```

Both functions return `{ files, merge, dependencies, instructions }` synchronously. `files` maps paths relative to the project root to the contents a project without them gets, such as `.env`, `c15t.config.ts`, `next.config.ts` and `app/layout.tsx` for `next-app`. They are the files of the framework's quickstart. Hosted mode writes the backend URL to `.env` under the framework's public env var, such as `NEXT_PUBLIC_C15T_BACKEND_URL` or `VITE_C15T_BACKEND_URL`. No other file holds the URL, and no file is a `.gitignore`.

`merge` says how to apply a file the project already has: `env` adds the generated `KEY=value` lines to an existing `.env` and keeps its other keys, but skips a `*_C15T_BACKEND_URL` line when the file already sets the matching `*_INTH_PROJECT_URL`, `insert` adds a snippet such as the privacy settings link to an existing `index.html`, and `keep` leaves the file alone. `mergeFile(existing, generated, merge)` applies one. Replace other existing files only when the user asks.

`dependencies` contains installation arguments on the CLI's release line, such as `c15t@alpha` from an alpha CLI or `c15t@3` from a stable v3 CLI. `getInstallSpecifier` applies the same rule as the CLI's own installs to bare c15t package names and preserves explicit specifiers and external package names. The published source records the CLI version it shipped with, so vendored source keeps that release line. `generateBoilerplateTemplate` exposes the lower-level template with bare dependency names.

The host CLI owns writing files, checking existing contents and symlinks, installing dependencies, diagnostics, and authentication. These functions do not read the application, detect its framework, prompt, write files, install packages, or access the network. Use the project's provisioned backend URL for hosted mode.

`runGenerateCommand` accepts `hosted` or `offline`, `--framework`, and optional `--backend-url` and `--scripts` values. Value flags accept `--flag value` or `--flag=value`. A second argument supplies host defaults for these inputs. Without defaults, mode and framework are required. Explicit arguments override defaults; selecting offline clears an inherited backend URL. Repeated flags are rejected. `parseGenerateOptions` exposes the same parser without generating files. It supports the [quickstart framework targets](./commands/boilerplate). Hosted mode requires an absolute HTTP or HTTPS URL without embedded credentials, whitespace or control characters. Offline mode rejects a backend URL. Invalid frameworks, integrations and flags, including the removed `--output`, throw an `Error`. Runner flags such as `--apply`, `--json`, and `--package-source` belong to the host rather than this parser.

For Node hosts that need the full CLI command metadata and actions, `import { commands } from '@c15t/cli/commands'` exports the same registry used by the runner. Actions accept a c15t `CliContext`; use `runCli` when you need the runner to create that context.

## Frontend commands with host state

Use `@c15t/cli/frontend` when Inth or another host owns authentication and the selected project. The dispatcher accepts arguments after the `c15t` namespace and returns `{ command, data }` synchronously:

```ts
import { runFrontendCommand } from '@c15t/cli/frontend';

const result = runFrontendCommand(['setup', '--framework', 'react'], {
	generation: { backendURL: projectBackendURL },
});
```

`setup` and `generate` return the standalone file plan. The frontend dispatcher defaults to hosted mode. Supply a framework through arguments or `generation.framework`; no detection runs. Explicit flags override `generation` defaults. `setup offline` ignores the host's inherited backend URL, while an explicit offline `--backend-url` is an error.

A host can supply its already-fetched projects and current selection instead of a backend URL:

```ts
import { runFrontendCommand } from '@c15t/cli/frontend';

const context = {
	generation: { framework: 'react' as const },
	projects: availableProjects,
	selectedProject: selectedProjectId,
};

const plan = runFrontendCommand(['generate'], context);
const selection = runFrontendCommand(
	['projects', 'select', 'organization/project'],
	context
);
```

Projects use `{ id, name, organizationSlug?, status, url }`. `status` is `active`, `pending`, or `inactive`; `url` is the provisioned consent backend URL. Generation resolves the selected ID or unambiguous `organization/name` and rejects an unavailable or invalid backend. An explicit backend URL takes precedence over the selected project.

|Command|Returned `data`|Host responsibility|
|--|--|--|
|`setup`, `generate`|`{ files, dependencies, instructions }`|Review and write files, handle conflicts and symlinks, install dependencies, wire the application.|
|`projects`, `projects list`|`{ projects, selectedProject }`|Fetch projects using the host's authenticated client.|
|`projects select <id\|organization/name>`|`{ project, selectedProject }`|Persist the returned project ID and refresh the generation context.|
|`status`|`{ authenticated, status, expiresAt?, origin?, selectedProject? }`|Resolve session state and expiry in the host.|

`status` requires `context.authentication` with `isLoggedIn` and `isExpired`. Optional metadata is limited to `expiresAt`, `origin`, and `selectedProject`. It never returns access or refresh tokens. Project commands require `context.projects`, including an empty array when there are no projects. Missing host state is an error rather than a network request or implicit login.

The host owns prompts, project creation, login, logout, token refresh, and persistence. Selection returns data and does not update the context. These commands have no database dependencies. Codemods, self-hosting commands, and runner flags such as `--apply` or `--json` are rejected by the frontend dispatcher. The standalone Node CLI uses the same project resolver, backend URL validation, and account status logic with its own runtime adapters.

## Plan and apply frontend files

Use `@c15t/cli/frontend/runtime` when the host needs filesystem operations and
dependency installation. It uses Node built-ins supported by scriptc 0.2.0:

```ts
import { runGenerationWorkflow } from '@c15t/cli/frontend/runtime';

const result = await runGenerationWorkflow(
	['generate', '--framework', 'react', '--apply'],
	{ generation: { backendURL: projectBackendURL } },
	{
		cwd: projectDirectory,
		packageManager: 'bun',
		signal: abortController.signal,
	}
);
```

The application directory must exist and contain a regular `package.json`.
Generation defaults to a plan without writes or installation. `--plan` and
`--dry-run` make that choice explicit. `--apply` creates files and requires a
host-supplied package manager or `--skip-install`. These flags belong to the
runtime; the pure frontend dispatcher continues to reject them. The host still
owns help, `--json`, working-directory options, framework detection, authentication
and application wiring.

The result contains `{ command, applied, created, installed, plan, recovered }`.
`plan` contains the canonical application `root`, `files` with `path`, `content`
and `exists`, release-line `dependencies`, and `instructions`. Existing files
must already match, except files the plan merges: when an existing `.env` or
`index.html` lacks the generated lines, the runtime leaves it alone and adds an
instruction with the lines to add. Apply checks the reviewed files again before
writing and refuses conflicts, symlink targets and symlink ancestors, including
dangling symlinks.
The application root itself resolves to its real directory.

Files stage in `.c15t-native-generation` and publish with exclusive hard links.
Where hard links are unavailable, apply creates each file exclusively, so existing
files are never replaced, and records the copy's identity after writing it. A
copied file that the filesystem cannot tell apart from an identical replacement
may be removed during recovery and written again on resume. An interrupted
apply blocks further generation. Use `--resume --apply` with the original command
to recover and regenerate. Recovery checks every record and generated file before
removing files it published. Files it cannot prove it published, including
replacements with identical contents, stay in place. Edited generated files,
unexpected staging contents, and malformed records stop recovery for inspection.
Recovery removes generated directories only when they are empty. This supports
process interruption; it does not promise recovery from filesystem corruption or
power loss. Without a journal, recovery deletes leftover staged files and leaves
application files untouched. A partial journal with staged files requires
inspection. The Node runner's `.c15t-generation.json` uses its own recovery
path and cannot be resumed by this runtime.

Dependency installation runs after file apply commits. npm, pnpm, yarn, and Bun
run in the application directory with installer output on stderr. Cancellation
stops the direct installer process. Cancellation before or during installation
reports that generated files remain, and workflow errors list the created files.
Installer failure leaves generated files in
place and reports a retry command; package-manager changes to manifests, lockfiles
and `node_modules` do not roll back. For manual installation, use `--skip-install`
and the returned dependencies. `planGeneration`, `applyGeneration`,
`recoverGeneration`, `installGenerationDependencies`, and
`parseGenerationWorkflowArguments` expose the same steps separately.

Native dependency installation is supported on macOS and Linux. On Windows,
use `--skip-install` and install the returned dependencies manually. A workflow
that requests installation on Windows fails before writing application files.

## Compile native frontend commands with scriptc

The published package includes dependency-free generation and frontend TypeScript sources. With scriptc 0.2.0, copy both source directories into the host's vendor directory before compilation. scriptc treats imports under `node_modules` as npm dependencies, so directly importing the npm entry points does not establish static native compilation.

Create `scripts/vendor-c15t.mjs` in the host project and run it with Node during the build:

```js
import { cpSync, mkdirSync, rmSync } from 'node:fs';
import { createRequire } from 'node:module';
import { dirname, resolve } from 'node:path';

const require = createRequire(import.meta.url);
for (const entry of ['generate', 'frontend']) {
	const source = dirname(require.resolve(`@c15t/cli/${entry}/source`));
	const destination = resolve(`vendor/c15t/${entry}`);
	mkdirSync(dirname(destination), { recursive: true });
	rmSync(destination, { recursive: true, force: true });
	cpSync(source, destination, { recursive: true });
}
```

Copy both complete directories and keep them as siblings. Preserve the source contents; NodeNext hosts may add explicit `.ts` or `/index.ts` extensions to relative import specifiers during vendoring. The frontend source imports the generation source through a relative path. Regenerate them when updating the locked `@c15t/cli@alpha` dependency. The published source paths exist for this build step. Generation-only hosts can copy just the generation directory.

In the host's `cli.ts`, route the generation subcommand to the vendored parser. This example prints the plan; integrate it with Inth's own plan/apply and installation behavior to create application files:

```ts
import { runGenerateCommand } from './vendor/c15t/generate/index.ts';

try {
	const args = process.argv.slice(2);
	if (args[0] !== 'c15t' || args[1] !== 'generate') {
		throw new Error('Usage: inth c15t generate <mode> --framework <framework>');
	}
	const plan = runGenerateCommand(args.slice(2));
	process.stdout.write(`${JSON.stringify(plan)}\n`);
} catch (error) {
	process.stderr.write(
		`${error instanceof Error ? error.message : String(error)}\n`
	);
	process.exitCode = 1;
}
```

Build with scriptc 0.2.0 in its default static mode, without `--dynamic`:

```bash
node scripts/vendor-c15t.mjs
scriptc build cli.ts --out inth
./inth c15t generate hosted --framework react --backend-url https://your-project.inth.app
```

Replace the example URL with the exact endpoint provisioned for the project. The result contains the generated source and release-line installation arguments. To route the frontend command set, import `runFrontendCommand` from `./vendor/c15t/frontend/index.ts`, forward arguments after the `c15t` namespace, and supply the host context described above. Native verification covers hosted and offline boilerplate for all targets, generation defaults, project list/select, account status, filesystem apply, conflicts, symlinks, recovery, and release-line installer arguments. Import `runGenerationWorkflow` from `./vendor/c15t/frontend/runtime/index.ts` to plan and apply standalone frontend files natively. Interactive application-root editing, codemods, and database migrations continue to use the Node runner.

## Agent setup and v3 migration workflow

Launching Codex through the CLI is supported on macOS and Linux. On Windows,
use `--plan` to copy the prompt and run it in Codex manually.

Use `c15t setup --codex --plan` to print the setup prompt and copy it to your
clipboard without launching Codex. The prompt goes to stdout as plain text.
The copy confirmation or failure notice is diagnostic output, so
`c15t setup --codex --plan > prompt.txt` saves only the prompt. On Linux the
CLI tries `wl-copy`, `xclip` and `xsel`, then `clip.exe` under WSL. `--dry-run`
does the same. Add `--json` to export the prompt without clipboard access.

Launch your installed Codex CLI from the application directory:

```bash
c15t setup --codex
c15t setup --codex hosted --backend-url https://your-project.inth.app
```

Replace the example URL with the provisioned consent backend URL. With an Inth
connection, `--project <id|name>` resolves that project's backend URL.
Use either `--project` or `--backend-url`. `--framework` and `--scripts` provide
optional hints. Explicitly select `offline` or `custom` when needed. Without a
mode, the task asks the agent to confirm it with you. The prompt includes a
public inputs section only when you supply configuration.

Codex receives the default c15t v3 frontend task and named public inputs. The
agent inventories the application and its analytics, pixels and embeds, then
takes the install, upgrade or replace path. It resolves exact package versions
from the CLI's npm dist-tag, reads the version-matched bundled docs, runs the
upgrade guide's codemods, moves every tool behind consent, and verifies consent
in a browser. Docs links in the task point at the site for the CLI's release
line: `https://v3.c15t.com` for v3 prereleases, `https://c15t.com` otherwise.
It does not provision a backend or migrate a database. The prompt includes the parsed
backend URL, and setup rejects URLs containing whitespace or control
characters. Review the resulting diff and the agent's verification report
before deploying.

Launch requires an interactive terminal and a `codex` executable on `PATH`.
When Codex cannot start, setup fails with `AGENT_NOT_STARTED` and leaves the
project unchanged. `AGENT_FAILED` means Codex ran and exited unsuccessfully, so
review its edits.
The CLI inherits Codex's approval and sandbox settings; `--yes` does not
change them. A successful exit means the agent session ended successfully,
not that the CLI independently verified the application's behavior. Interrupting
setup stops the direct child process and leaves any edits for review.

Preview or export the complete task without launching an agent:

```bash
c15t setup --codex --plan
c15t setup --codex --plan --json
```

`--dry-run` also previews the task. Live agent launch rejects `--json` and
`--non-interactive`. Scaffold options such as `--boilerplate`, `--overwrite`,
`--apply`, `--resume`, and `--skip-install` are not supported with `--codex`.
Discuss styling, SSR, proxying, and other frontend preferences in the agent
session. `generate` retains deterministic generation and rejects `--codex`.

Hosts can reuse the same prompt and launcher:

```ts
import {
	createAgentSetupPlan,
	launchAgentSetup,
} from '@c15t/cli/frontend/agent';

const plan = createAgentSetupPlan({ backendURL: provisionedBackendURL });
// Show plan.prompt for review, or hand it to another coding agent.
const exitCode = await launchAgentSetup(projectDirectory, plan, abortSignal);
```

`createAgentSetupPlan` performs no file or network operations. Its options are
`mode`, `backendURL`, `framework`, and `scripts`; it copies only those fields
into the task. Hosts keep authentication and project selection in their own
code. The module also exports `DEFAULT_C15T_SETUP_PROMPT`, `AgentSetupOptions`,
and `AgentSetupPlan`.

Hosts that write their own task can reuse the c15t steps alone.
`createC15tSetupInstructions` returns the inventory, install, upgrade and
replace paths, consent-gating rules, browser checks and handoff as Markdown,
without account or backend provisioning steps:

```ts
import { createC15tSetupInstructions } from '@c15t/cli/frontend/agent';

const task = `${hostAccountSteps}\n\n${createC15tSetupInstructions({
	firstStep: 4,
	mode: 'hosted',
})}`;
```

Its options are `origin`, the docs site the agent reads; `distTag`, the npm
dist-tag it resolves exact versions from; `mode`, which is `hosted`, `offline`
or `custom`, or omitted so the agent asks; and `firstStep`, the number of the
first c15t step when the host puts its own steps first. Steps refer to each
other by name, so renumbering them breaks no reference. `origin` and `distTag`
default to the CLI's release line. Invalid values throw.

`createC15tIntegrationGuidance({ origin })` returns only the rules for moving
analytics, pixels, tag managers and embeds behind consent, including the
replacements for framework vendor packages such as `@next/third-parties` and
`@nuxt/scripts`. Use it to embed those rules in another prompt or skill.

A missing executable produces an installation hint;
`launchAgentSetup` returns the agent's exit code and rejects on caller
cancellation or launch failure. `isAgentNotStartedError` identifies rejections
raised before Codex ran.

For a scriptc host, vendor both source directories as described above and
import from `./vendor/c15t/frontend/agent/index.ts`. The prompt and launcher
compile statically with scriptc 0.2.0 without `--dynamic`. This compiles the
handoff; Codex still needs its own installed executable, authentication, and
network access to perform the task.

For v3, source code and installed documentation determine the migration work. The legacy codemod collection targets v2, apart from the named `use-consent-manager-to-hooks` and `scripts-to-integrations` transforms. It does not update dependencies, convert a v2 backend configuration to v3, or migrate a database.

`skills` delegates to an external interactive installer and does not support JSON output. Use installed bundled docs directly when building unattended automation.

Environment-file edits in setup results contain only `path`, `operation` (`create` or `update`), and `redacted: true`. This also applies when either a symlink's name or its target is an environment file. Their original and proposed contents stay out of JSON output. Setup keeps the full contents internally to apply edits and restore files if generation fails.

# setup
URL: https://c15t.com/docs/cli/commands/setup
Flags and file handling for c15t setup, which plans and applies c15t integration files in Next.js, React and JavaScript apps.

## Plan and apply

```bash
npx @c15t/cli@alpha setup hosted --backend-url https://your-project.inth.app --plan --json
npx @c15t/cli@alpha setup hosted --backend-url https://your-project.inth.app --apply --skip-install
```

Replace `https://your-project.inth.app` with the backend URL from your Inth
project. Any explicit flag makes setup non-interactive and returns a read-only
plan, even in a terminal. Add `--apply` or `--yes` to write files.

Setup installs missing c15t packages from the CLI's release line. A prerelease
CLI uses its dist-tag, so `@c15t/cli@alpha` installs `c15t@alpha`. A stable CLI
uses its major version, such as `c15t@3`. A c15t package already in
`package.json` stays as it is when its range can resolve to that release line.
A range on another major, such as `^2`, is installed again from the CLI's
line.

For TanStack Start, Vue, Nuxt, Svelte, SvelteKit, Solid and Astro, pass
`--framework`. That selects [framework boilerplate](/docs/cli/commands/boilerplate),
which has its own options.

## Setup with Codex

Use `setup --codex` to give your installed Codex CLI the default c15t v3
frontend task. Add `--plan --json` to inspect the prompt without launching it.
With `--plan` or `--dry-run`, the CLI prints the prompt to stdout as plain
text, copies it to your clipboard and confirms the copy. If clipboard access
fails, copy the printed prompt or redirect it with `> prompt.txt`; status
messages stay out of the redirected file. `--json` exports the prompt without
accessing the clipboard.
See [agent setup](/docs/cli/automation#agent-setup-and-v3-migration-workflow)
for inputs and requirements. `generate` keeps the deterministic setup workflow.

## Choose the mode and backend

Pass the mode as the first argument or with `--mode`:

|Mode|Backend|
|--|--|
|`hosted`|Inth or a [self-hosted backend](/docs/self-host/overview). Requires `--backend-url`, or an Inth project through `--project` or the application preference set by `projects select`.|
|`offline`|No backend. Choices stay in the browser. Not recommended for production environments.|
|`custom`|Your own transport.|

The older mode names `c15t` and `self-hosted` map to `hosted`. Setup refuses an
Inth project that is still provisioning, because it has no backend URL yet.

## Options

|Option|Purpose|
|--|--|
|`--plan`, `--dry-run`|Return the proposed file edits without writing files or installing packages.|
|`--apply`|Write the file edits and install missing packages.|
|`--skip-install`|Write the file edits without running a package manager.|
|`--backend-url <url>`|Use this HTTP or HTTPS backend URL.|
|`--project <id, name or organization/name>`|Use the backend URL of a signed-in Inth project.|
|`--proxy`|Add a Next.js rewrite to the hosted backend. Hosted Next.js only.|
|`--ssr`|Start consent resolution on the server in a hosted Next.js App Router app. The wrapper passes the pending result to the provider, so pages render without waiting for the backend and the banner follows in a later chunk, before hydration.|
|`--devtools`|Include c15t DevTools.|
|`--ui-style prebuilt` or `expanded`|Use the stock components or their compound parts. React and Next.js only.|
|`--theme none`, `minimal`, `dark` or `tailwind`|Apply a theme preset. React and Next.js only.|
|`--scripts <ids>`|Add consent-aware vendor scripts, as a comma-separated list. An unknown ID returns the list of valid IDs.|
|`--resume`|Recover an interrupted setup.|
|`--debug`|Log setup state transitions.|

Without flags for them, non-interactive setup uses the stock components, no
theme, no scripts, and no proxy, server resolution or DevTools. Replace the
placeholder IDs in generated script configuration before you deploy.

## Set up styles and Tailwind CSS

React and Next.js components render their own styles by default. Setup leaves
your global CSS unchanged with Tailwind CSS 4 or without Tailwind.

When you choose a theme preset, the generated provider renders `ConsentTheme`
to apply the tokens in `theme.ts`. Passing `theme` in the provider options alone
does not generate CSS. The None preset keeps c15t's default styles.

Put a global reset such as `* { padding: 0; margin: 0; }` in `@layer base`.
An unlayered reset outranks c15t's layered component styles and removes the
banner and dialog spacing. Setup leaves those rules alone. Keep intentional
component overrides outside that layer.

Setup recognizes Tailwind CSS 3 version ranges, including `>=3.4.17 <4`.
With Tailwind CSS 3, setup imports c15t's `styles.css` in your global CSS and
sets `styles: false` in the generated provider. Tailwind's PostCSS build must
process the external stylesheet. Setup follows local CSS imports in the
application entrypoint, including semicolon-free imports and aliases from
`tsconfig.json` or `jsconfig.json`, then checks conventional global stylesheet
paths. Aliases outside the project are skipped. If setup cannot find a
stylesheet, it warns you to add the import yourself. Setup also:

* Puts the import above the `@tailwind` directives, and replaces a
  `styles.tw3.css` import from an earlier setup.
* Adds the plugin from the package it installed, such as
  `c15t/postcss-tailwind3`, before `tailwindcss` in your PostCSS config. It
  edits one `postcss.config.*` or `.postcssrc*` file, in either the object or
  the array form, and leaves a config that already runs a c15t
  `postcss-tailwind3` plugin alone.
* Uses important modifiers in the Tailwind preset, such as `hover:!bg-blue-700`,
  so the generated utilities override c15t's component styles. Tailwind CSS 4
  uses ordinary utilities instead.

Setup prints the PostCSS change to make by hand when it finds no config, finds
several config files, finds the config in the `postcss` key of `package.json`,
or cannot edit the plugin list, such as a YAML file. A non-interactive run
logs these warnings and lists them in `warnings` in its result.
[Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3) shows the
finished setup.

Create React App ignores PostCSS config files, so Tailwind 3 cannot run the
plugin and the build fails on c15t's stylesheet. Setup warns about
this. Add the plugin before `tailwindcss` through CRACO, eject, or move the app
to Vite.

## How setup changes files

The plan holds each file's current and proposed text. When applying, setup
checks that each file still matches the current text before writing it. If
writing fails, setup restores the files it already changed and reports any file
it could not restore. It never overwrites a change another process made after
the plan.

Symlinks are allowed when their targets stay inside the project. Planning
rejects dangling symlinks and symlinks that point outside the project.

Installing packages is a separate step from writing files. If the install
fails, setup restores the generated files, but changes the package manager made
to `package.json`, the lockfile or `node_modules` can remain.

An interrupted apply leaves a `.c15t-generation.json` recovery file. `--resume`
restores the files from it and plans again. If a file changed since the
interruption, recovery stops so you can review it. A non-interactive resume
needs `--apply` or `--yes`, and cannot be combined with `--plan` or `--dry-run`.

# Framework boilerplate
URL: https://c15t.com/docs/cli/commands/boilerplate
Generate the c15t quickstart files for Next.js, Nuxt, TanStack Start, Astro, React, JavaScript, a script tag, Vue, Svelte, SvelteKit or Solid with the c15t CLI.

## Generate files for your framework

Pass `--framework` to `setup` to write your framework's quickstart: the same
files the [framework quickstarts](/docs/frameworks) show, at the same paths.

```bash
npx @c15t/cli@alpha setup hosted --framework react --backend-url https://your-project.inth.app --plan --json
npx @c15t/cli@alpha setup hosted --framework react --backend-url https://your-project.inth.app --apply
```

Run it from the app directory, which must contain a `package.json`, or pass
`--cwd path/to/app`. Pick the mode explicitly. `hosted` takes `--backend-url`,
the URL from your Inth project or self-hosted backend, and writes it to `.env`
under the framework's public env var. Offline mode resolves the recommended
policy in the browser, writes no `.env`, and records nothing on a server. Not
recommended for production environments.

|`--framework`|Generated files|
|--|--|
|`next-app`|`.env`, `next.config.ts`, `c15t.config.ts`, `app/layout.tsx`|
|`next-pages`|`.env`, `next.config.ts`, `c15t.config.ts`, `pages/_app.tsx`, `pages/api/c15t/[...c15t].ts`, `pages/index.tsx`|
|`nuxt`|`.env`, `nuxt.config.ts`, `app/app.vue`, and `app/app.config.ts` with `--scripts`|
|`tanstack-start`|`.env`, `vite.config.ts`, `src/routes/__root.tsx`|
|`astro`|Server output: `.env`, `astro.config.mjs`, `src/layouts/base.astro`, and `src/c15t.client.ts` with `--scripts`|
|`astro-static`|Static output, with `hosted()`: the same files as `astro`|
|`react`|React with Vite: `.env`, `vite.config.ts`, `src/consent.tsx`, `src/main.tsx`|
|`javascript`|`.env`, `vite.config.ts`, `src/main.ts`, and a privacy settings link in `index.html`|
|`html`|The `c15t.js` script tag and a privacy settings link in `index.html`. Hosted mode only.|
|`vue`|Vue with Vite: `.env`, `vite.config.ts`, `src/main.ts`, `src/App.vue`|
|`svelte`|Svelte with Vite: `.env`, `vite.config.ts`, `src/App.svelte`|
|`sveltekit`|`.env`, `vite.config.ts`, the locals type in `src/app.d.ts`, `src/hooks.server.ts`, `src/routes/+layout.server.ts`, `src/routes/+layout.svelte`|
|`solid`|`src/consent/`: an app-owned runtime and a basic custom consent interface, without IAB or modal UI|

|Env var|Frameworks|
|--|--|
|`NEXT_PUBLIC_C15T_BACKEND_URL`|`next-app`, `next-pages`|
|`NUXT_PUBLIC_C15T_BACKEND_URL`|`nuxt`|
|`PUBLIC_C15T_BACKEND_URL`|`astro`, `astro-static`, `sveltekit`|
|`VITE_C15T_BACKEND_URL`|`tanstack-start`, `react`, `javascript`, `vue`, `svelte`|

When the project's `.env` already sets the matching Inth variable, such as
`VITE_INTH_PROJECT_URL`, the CLI leaves the c15t variable out. The
integrations read either, and the c15t one would win over the project URL
the file already names.

Use `--boilerplate` without `--framework` to detect the framework from
`package.json`. An Astro project with a server adapter gets `astro`, and one
without gets `astro-static`. A Next.js project needs an existing router layout
to pick `next-app` or `next-pages`; when its layout is under `src/`, the `app/`
and `pages/` files go there too. Pass `--framework` when the CLI cannot tell.

## Existing files

An identical file is left alone. An existing `.env` keeps its other keys: the
CLI adds the backend URL, or updates that one key if it is already set. The
CLI never creates or edits `.gitignore`. In an existing `index.html` it adds
the script tag or privacy settings link, and in an existing `src/app.d.ts` the
locals type. An existing `pages/index.tsx` is left alone; add
`getServerSideProps` to the pages that need it.

Any other existing file with different contents, such as your own
`vite.config.ts` or root layout, stops generation before anything is written.
The error lists those files. Merge the quickstart into them by hand, or pass
`--overwrite` to replace them.

## Install the packages

Generation never installs packages. The result lists them under
`data.dependencies`, with each c15t package pinned to the CLI's release line.
From `@c15t/cli@alpha`, that is the `alpha` dist-tag, for example for React:

|Package manager|Command|
|:--|:--|
|npm|`npm install c15t@alpha`|
|pnpm|`pnpm add c15t@alpha`|
|yarn|`yarn add c15t@alpha`|
|bun|`bun add c15t@alpha`|

`data.instructions` lists the remaining steps. They can mention
`--package-source`; skip that step unless you are testing a local c15t checkout.

## Options

|Option|Purpose|
|--|--|
|`--framework <target>`|Generate files for this target.|
|`--boilerplate`|Generate files for the detected framework.|
|`--scripts <ids>`|Add vendor script examples, as a comma-separated list such as `posthog,google-tag-manager`. Replace the placeholder IDs before you run the app.|
|`--overwrite`|Replace existing files whose contents differ from the quickstart.|
|`--plan`, `--dry-run`|Return the files and instructions without writing them.|
|`--apply`, `--yes`|Write the files.|
|`--resume`|Restore an interrupted apply, then plan and apply again. Requires `--apply` or `--yes`.|
|`--package-source <dir>`|Point dependencies at prepared packages from a local c15t checkout. For c15t contributors.|

Files stay inside the project. `--output` was removed: every file goes to its
quickstart path. Setup flags for themes, UI style, DevTools, proxy and server
resolution do not apply here; change those in the generated source. JSON
results show `.env` edits without their contents.

## Check the result

Run the app's typecheck and build. In a private window, reject optional
categories, reload, and confirm the banner stays closed and optional vendor
requests stay absent in DevTools Network. Open privacy settings, allow a
category, and confirm its vendor requests start.

## Test a local c15t checkout

To try unreleased changes, build the packages the plan lists, prepare local
snapshots from the checkout root, then pass the checkout with
`--package-source`:

```bash
bun turbo run build --filter=@c15t/cli --filter=c15t...
bun scripts/prepare-cli-packages.ts c15t
node packages/cli/dist/bin.mjs setup offline --framework react --cwd /path/to/app --package-source "$PWD" --apply
```

The plan then includes `package.json` edits that point at the snapshots.
Install from the app directory afterwards. Keep the snapshot directory while
the app references it, and prepare again after changing package source.

# Codemods
URL: https://c15t.com/docs/cli/commands/codemods
Migrate source from c15t v2 to v3 with the c15t CLI codemods command, covering package imports, the provider, transports, moved exports, dev tools, policy presets, CSS variables, Tailwind CSS 3, callbacks, the Node.js SDK and backend config, and run the v1 to v2 source transforms.

## Run the v3 codemods

The v3 codemods run only when you name them; `--all` never selects them.
Preview every change first, then run the same command without `--dry-run`:

```bash
npx @c15t/cli@alpha codemods packages-to-c15t consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks callbacks-to-v3 policy-packs-to-policy-rules --dry-run --json
```

Name several codemods in one command and they run in a fixed order, whatever
order you name them in, each seeing the previous one's edits.
`codemods --list` prints that order. Codemods that can't finish a change
leave a `TODO(c15t v3)` comment next to it. Most also leave the v2 code in
place, so type-checking fails at each one until you resolve it.

|ID|Rewrites|Leaves a `TODO(c15t v3)` for|
|--|--|--|
|`packages-to-c15t`|`@c15t/react` and `@c15t/nextjs` imports to `c15t/react`, `c15t/next` and their subpaths, and removes `styles.css` imports|Stylesheet imports Tailwind CSS 3 or a cascade layer needs, and `components/integrations` imports|
|`consent-provider-options`|`ConsentManagerProvider`, `ConsentManagerOptions` and `ConsentManagerProviderProps` to the `ConsentProvider` names; `mode: 'hosted'` with `backendURL`, `headers` and `customFetch` to `mode: hosted({ backendURL, headers, fetch })`; `mode: 'offline'` with `offlinePolicy.policyPacks` to `mode: offline({ policyRules })`; `iframeBlockerConfig` to `iframeBlocker`|`mode: 'custom'` with `endpointHandlers`, a `mode` set from a variable, `retryConfig`, other `offlinePolicy` keys and hand-written policy packs|
|`root-exports-to-subpaths`|Imports of names that left the `c15t/react`, `c15t/next`, `@c15t/react` and `@c15t/nextjs` roots, moved to `/headless`, `/consent-dialog-trigger`, `/types` or `/components/consent-banner`|Removed names such as `useConsentScript`, `YouTubeEmbed` and `ConsentButton`|
|`use-consent-manager-to-hooks`|`useConsentManager()` fields to one hook each|Fields with no one-call replacement|
|`scripts-to-integrations`|`@c15t/scripts` imports to `@c15t/integrations`|Nothing|
|`dev-tools-to-c15t`|`@c15t/dev-tools/react` and `@c15t/dev-tools/tanstack` imports to `c15t/next/devtools` or `c15t/react/devtools`, and removes the `namespace` prop|Removed store helpers such as `getC15tStore`|
|`policy-packs-to-policy-rules`|`policyPackPresets` to `policyRulePresets` and `worldNoBanner()` to `worldOptOutNoPrompt()`|Nothing|
|`css-variables-to-v3`|`--consent-widget-*` to `--consent-manager-*` and `--frame-*` to `--consent-gate-*`|`--consent-widget-accordion-*`|
|`postcss-tailwind3`|Adds the c15t Tailwind CSS 3 plugin before `tailwindcss` in `postcss.config`|Nothing; prints a warning for configs it can't edit|
|`callbacks-to-v3`|`onConsentChanged` to `onChoiceRecorded`|The `onChoiceRecorded` payload, `onConsentSet` and `onBannerFetched`|
|`theme-to-consent-theme`|`theme.slots.consentDialogFooter` to `consentWidgetFooter`|Theme tokens, which need `ConsentTheme` or `generateThemeCSS()`, and `theme.slots.frame`|
|`iab-option-to-iab-provider`|Nothing|The `iab` provider option, which moves to `IABProvider`|
|`node-sdk-to-v3`|`c15tClient()` and `new C15TClient()` to `createC15tClient()`, client and per-call options, method names, type and error names|Each call site, `prefix`, `debug`, dropped retry options, and per-call `throw`, `onSuccess`, `onError`, `body`, `query` and `method`|
|`backend-config-to-v3`|`policyPacks` (as `policyRules`), `branding`, `customTranslations`, `i18n` and `appName` into `manifest`|`adapter`, `disableGeoLocation`, `iab`, `cache`, `logger`, `telemetry`, `tablePrefix`, `background` and removed entries|

v2 still accepted the deprecated `translations` option, and v3 removes it.
The v1 to v2 transform `translations-to-i18n` moves it to `i18n`; name it to
run it on a v2 app.

The codemods edit `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs` and
`.cjs` files. `packages-to-c15t` and `css-variables-to-v3` also edit `.css`,
`.scss`, `.sass` and `.less` files. None of them edit `package.json`,
lockfiles, or `.vue`, `.svelte` and `.astro` files.

### Package imports

`packages-to-c15t` runs first, so the other codemods see the `c15t` entries.
It moves `@c15t/react` to `c15t/react` and `@c15t/nextjs` to `c15t/next`,
keeping the subpath: `@c15t/react/headless` becomes `c15t/react/headless`.
When `package.json` lists `next` or `@c15t/nextjs`, the `@c15t/react` root
moves to `c15t/next`, which re-exports the React components and hooks. The
v2 `@c15t/react/cookie-banner` alias becomes
`c15t/react/components/consent-banner`. It rewrites imports, including
`import x = require()`, re-exports, import types, and `import()`, `require()`,
`vi.mock()` and `jest.mock()` calls with a string literal. It leaves
`c15t/react`, `@c15t/integrations` and other packages alone. In a
PostCSS config, it points the `@c15t/react/postcss-tailwind3` and
`@c15t/nextjs/postcss-tailwind3` plugins at `c15t/postcss-tailwind3`, whether
the config names them as a `plugins` object key, computed keys such as
`['@c15t/react/postcss-tailwind3']` included, or in `require()`.

c15t ships ESM only from v3. `require()` loads it only on Node.js 20.19+ or
22.12+, which load ESM through `require()` by default. Each `require()` call
and `import x = require()` the codemod rewrites gets a TODO, and the run lists
every such file with its count. To support older runtimes, convert those files
to `import`, or a PostCSS config to `postcss.config.mjs`. The codemod doesn't
convert CommonJS for you.

It removes `@c15t/react/styles.css` and `@c15t/nextjs/styles.css` imports,
including the `iab/` variants, because v3 components add their own styles. It
reads each stylesheet `@import` whole, so one that spans lines or takes Less
options such as `(css)` is handled too. In Sass it treats `@use` and
`@forward` the same way as `@import`, and a `pkg:` URL such as
`pkg:@c15t/react/styles.css` the same way as the bare one, keeping the
`pkg:` prefix when it rewrites it. In a Sass import that lists several
targets, such as `@import 'theme', '@c15t/react/styles.css';`, it handles
each target on its own and keeps the others. When `package.json` lists
`tailwindcss` 3 in any dependency field, the import is a `.tw3.css` variant, a
stylesheet `@import` has a `layer()`, `supports()` or media condition, or a
Sass `@use` or `@forward` has an `as`, `with()`, `show` or `hide` clause, it
keeps the import, points it at `styles.css` from the `c15t` entry, and leaves a
`TODO(c15t v3)` comment to set `styles: false`. For a `tailwindcss` version
that isn't a semver range, such as a catalog, a `link:`, `file:` or git
specifier, or `latest`, or a range over several majors such as `workspace:*`
or `^3 || ^4`, it reads the installed `tailwindcss`. If it still can't tell
the version, it keeps the import the same way and prints a warning.

If `package.json` lists `@c15t/react` or `@c15t/nextjs` but not `c15t` v3, it
leaves the scoped imports and prints a warning. For a `c15t` version that
isn't a semver range, such as `catalog:`, or a range over several majors, it
reads the installed `c15t`, and keeps the scoped imports when nothing is
installed. While those packages are v2, it
leaves their stylesheet imports and mocks as they are too, since v2 components
don't add their own styles. For a version that isn't a semver range, such as
`catalog:`, it reads the installed package, and treats the package as v2 when
nothing is installed. At v3, it still removes the stylesheet imports.
Replace the packages with `c15t@alpha` and run it again.

### Provider, transports and options

`consent-provider-options` finds option objects passed to the provider's
`options` prop, variables typed as `ConsentManagerOptions` or
`ConsentProviderOptions`, and objects passed to `getOrCreateConsentRuntime()`
from `c15t`. It imports `hosted` or `offline` from the entry the provider
comes from. A provider from `c15t/next` or `c15t/tanstack-start` gets them
from `c15t/react`, and one from `@c15t/nextjs` or `@c15t/tanstack-start`
from `@c15t/react`: those framework entries export `hosted()` as plain data
for `defineConsentConfig`, and `ConsentProvider` needs the transport. A
hosted mode without `backendURL` gets v2's default,
`hosted({ backendURL: '/api/c15t' })`. A `mode` set from a variable or expression
gets a `TODO(c15t v3)` comment, unless it already holds a transport such as
`manifest()` or `hosted()`. A module that re-exports
`ConsentManagerProvider` keeps that name as an alias, so its importers still
resolve.

`callbacks-to-v3`, `theme-to-consent-theme` and `iab-option-to-iab-provider`
read the same option objects. Options built in another file, or spread from
another object, are not found; search for the old keys by hand.

### Moved exports

`root-exports-to-subpaths` keeps the framework you import from where v3 has a
matching entry: `useHeadlessConsentUI` from `c15t/next` moves to
`c15t/next/headless`. Trigger atoms, token types and flat banner parts exist
only on the React entries, so imports of them from `c15t/next` move to
`c15t/react/...`, and from `@c15t/nextjs` to `@c15t/react/...`. Types such as
`AllConsentNames` move to `c15t`, or `@c15t/core` for scoped packages.
With `import * as c15t from 'c15t/react'`, it rewrites `c15t.useColorScheme`
to `useColorScheme` imported from its new entry, and leaves a
`TODO(c15t v3)` comment when that name is already taken. It also marks
`export * from` a framework root, which no longer re-exports the moved names.

`policy-packs-to-policy-rules` moves `policyPackPresets` imports from React
and Next.js entries to `c15t`, or `@c15t/core` for scoped packages, because
the v3 React and Next.js entries don't export presets. Calls to presets need
no other change. Hand-written policy packs use a different format in v3;
`consent-provider-options` and `backend-config-to-v3` flag them.

`dev-tools-to-c15t` picks `c15t/next/devtools` when `package.json` lists
`next` or `@c15t/nextjs`, and `c15t/react/devtools` otherwise. If
`package.json` lists the scoped packages but not `c15t` v3, it uses
`@c15t/nextjs/devtools` or `@c15t/react/devtools`. It reads the `c15t`
version the same way as `packages-to-c15t`.

### Styles

`css-variables-to-v3` renames only the variables v2 defined, so your own
variables such as `--frame-width` stay as they are. It renames them in
stylesheets and in string and template literals, including inline `style`
objects.

`postcss-tailwind3` runs when `package.json` lists `tailwindcss` 3 and c15t.
For a version that isn't a semver range, such as a catalog, a `link:`, `file:`
or git specifier, or `latest`, or a range over several majors such as
`workspace:*` or `^3 || ^4`, it reads the installed `tailwindcss`, and prints a
warning if it still can't tell.
It adds `'c15t/postcss-tailwind3': {}`, or the
`@c15t/nextjs/postcss-tailwind3` or `@c15t/react/postcss-tailwind3` plugin
when the app uses scoped packages without `c15t` v3, to an object-form
`postcss.config.{js,cjs,mjs,ts}`. It leaves an array-form config unchanged.
When the array doesn't list a c15t plugin, it prints a warning; add the plugin
by hand as [Tailwind CSS 3](/docs/customization/tailwind#set-up-tailwind-css-3)
shows.

### Node.js SDK and backend

`node-sdk-to-v3` follows clients created in the same file, including class
properties, parameters typed as `C15TClient`, and clients made through
`import * as sdk from '@c15t/node-sdk'`. It rewrites client options written
in the call or in a variable in the same file; options from anywhere else
get a `TODO(c15t v3)` comment. It turns `type: 'a,b'`
strings into `types: ['a', 'b']`, and moves a v2 `init(options)` argument to
`init(undefined, options)`. In per-call options it renames `timeout` to
`timeoutMs` and `retryConfig` to `retry`. Call options passed as a variable
or spread get a `TODO(c15t v3)` comment. A file that receives the client
from another module keeps its old method names; search for them by hand.

`backend-config-to-v3` reads objects passed to `defineConfig()` or
`c15tInstance()` from `@c15t/backend`, and variables typed as `C15TOptions`.
It merges the moved keys into an existing `manifest` object, and rewrites
imports from the removed `@c15t/backend/define-config` entry.

## Migrate `useConsentManager()` to v3 hooks

v3 removed `useConsentManager()`. The `use-consent-manager-to-hooks` codemod
replaces each destructured field with the hook that reads it:

```bash
npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
```

Review the before and after contents in the JSON result, then run the same
command without `--dry-run` to write the files.

The codemod reads imports from `c15t/react`, `c15t/next`,
`c15t/tanstack-start`, `@c15t/react`, `@c15t/nextjs`, `@c15t/tanstack-start`
and their `/headless` entries. For each `useConsentManager()` destructuring, it:

* Replaces fields that map to one hook, such as `activeUI` with
  `useActiveUI() ?? 'none'`.
* Turns `has('marketing')` calls with a literal category into
  `useConsent('marketing')`.
* Turns `saveConsents('all')`, `saveConsents('necessary')` and
  `saveConsents('custom')` into `saveCustomPreferences('all')`,
  `saveCustomPreferences('none')` and `saveCustomPreferences()` from
  `useHeadlessConsentUI()`.
* Moves draft fields such as `selectedConsents` and `setSelectedConsent` to
  `useConsentDraft()`, and adds a `TODO(c15t v3)` comment where components now
  need a shared `ConsentDraftProvider`.
* Leaves fields it cannot rewrite on a `useConsentManager()` call under a
  `TODO(c15t v3)` comment that names the replacement. The import no longer
  exists, so the build fails at each place that needs manual work.

The [Next.js](/docs/frameworks/next/upgrade-v3#replace-useconsentmanager) and
[React](/docs/frameworks/react/upgrade-v3#replace-useconsentmanager) upgrade
guides map every field.

## Rename `@c15t/scripts` imports

v3 renames the vendor package `@c15t/scripts` to `@c15t/integrations`. The
`scripts-to-integrations` codemod rewrites imports and re-exports in
JavaScript and TypeScript files, including literal dynamic imports, `require()`
calls, `require` functions made with Node's `createRequire()`, and import
types. It scans `.mts`, `.cts`, `.mjs` and `.cjs` files too:

```bash
npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
```

It does not edit `package.json`, lockfiles, or imports inside `.vue`, `.svelte`
or `.astro` files. Update those by hand, as the upgrade guides for
[Next.js](/docs/frameworks/next/upgrade-v3#rename-the-integrations-dependency),
[React](/docs/frameworks/react/upgrade-v3#rename-the-integrations-dependency)
and [JavaScript](/docs/frameworks/javascript/upgrade-v3#rename-the-integrations-dependency)
describe.

## Run the v1 to v2 transforms

The other transforms migrate v1 source to the v2 API. Run them before you
upgrade a v1 app to v3.

```bash
npx @c15t/cli@alpha codemods --list --json
npx @c15t/cli@alpha codemods --all --from 1.9.0 --to 2.0.0 --dry-run --json
```

|ID|Change|
|--|--|
|`active-ui-api`|`showPopup` and `isPrivacyDialogOpen` to `activeUI`|
|`component-renames`|`CookieBanner`, `ConsentManagerDialog` and `ConsentManagerWidget` to the v2 names|
|`gdpr-types-to-consent-categories`|`gdprTypes` and `initialGDPRTypes` to `consentCategories`|
|`ignore-geo-location-to-overrides`|`ignoreGeoLocation` to `overrides` with `country: 'DE'`|
|`mode-c15t-to-hosted`|`mode: 'c15t'` to `mode: 'hosted'`|
|`react-options-to-top-level`|`react.theme`, `colorScheme` and `disableAnimation` to top-level options|
|`tracking-blocker-to-network-blocker`|Tracking blocker configuration to network blocker rules|
|`translations-to-i18n`|`translations` to the v2 `i18n` shape|
|`add-stylesheet-imports`|Styled c15t imports moved into the app's CSS entry point|

`--all` picks the transforms that apply to the version you start from. Without
`--from`, it reads the `c15t` or framework package version declared in
`package.json`, or the installed version for a specifier such as `catalog:`
that names none. If you already upgraded the dependency but the source still
uses v1, pass the old version with `--from 1.9.0` or name the transforms. v2
prereleases such as `2.0.0-rc.4` count as v2, so `--all` skips every v1
transform for them.

Component renames follow imported symbols and keep local aliases. The hosted
mode rename only changes options passed to a c15t API it can identify, so check
custom wrappers by hand.

## Review before writing

`--dry-run` reports each file's original and proposed contents in JSON. The
stylesheet transform reports paths and a summary instead. Transforms in one run
share a parser, so later transforms see earlier proposed changes.

The command fails if a transform reports file errors. Writing is not a single
transaction across transforms. If a later transform fails, earlier ones may
already have saved files, so review the working tree before running again.

# Hosted projects and authentication
URL: https://c15t.com/docs/cli/commands/hosted
Use Inth authentication and provisioning from the c15t setup workflow.

`@c15t/cli` includes a pinned `@inth/cli` dependency. c15t delegates login,
logout, account status, and hosted project operations to Inth's native
executable. A separate global Inth installation is not required.

```bash
c15t login
c15t projects list --json
```

Inth owns browser sign-in, saved connections, credential storage, organization
selection, and token refresh. An existing Inth session works with c15t, and
signing in through c15t also signs in the standalone `inth` CLI. c15t never
reads or returns Inth's access tokens, refresh tokens, or API keys.

## Sign in without a browser on this machine

Browser login needs an interactive terminal. Agents, remote shells, and anyone
approving on another device can sign in by email instead:

```bash
c15t login --email you@example.com
```

c15t prints an approval link and a code, then waits until the person approves
in their browser. The link asks for permission to read organizations and manage
projects.

Agents that need the link before the wait finishes use two JSON calls:

```bash
c15t login --email you@example.com --json
c15t login --complete --json
```

The first call returns `data.verificationUri` and `data.userCode` right away.
Show both to the person, then start the second call in the background. It waits
for approval and finishes sign-in. `--timeout <seconds>` sets the wait, from 1 to
3600 seconds; the default is 600. If the wait times out, run
`c15t login --complete --json` again to keep waiting.

In CI, set `INTH_TOKEN` to an organization API key instead of signing in. c15t
passes its environment to Inth, so `c15t status` reports the key as signed in.
`--no-browser` asks Inth to print the browser login URL instead of opening it.

## Account status and logout

```bash
c15t status --json
c15t logout
```

Status reads the local session without contacting the server. A browser session
stays `logged-in` after its short-lived access token expires, because Inth
refreshes it on the next request. Status reports `expired` only when the session
cannot be renewed, such as an email sign-in past its one-hour approval window.

Logout signs out of the Inth session that c15t shares with the `inth` CLI,
including a pending email sign-in. It does not affect `INTH_TOKEN`; unset the
variable to stop using an API key.

Earlier c15t versions stored their own session in `~/.c15t/config.json`. That
file is no longer read. `status`, `login`, and `projects` mention it when you
have no Inth session, and `c15t logout` deletes it. Control-plane and connection
configuration now belong to Inth; `CONSENT_URL` no longer configures account
operations.

## Select a project

```bash
c15t projects select <project-id> --json
```

Inth resolves the organization from its nearest application link or selected
account default. c15t lists all project pages in that organization. Select an
ID or an unambiguous name. Selection saves only the public project ID in
`.c15t/project.json` inside the directory selected by `--cwd` or the current
working directory. It applies to that application, not the entire account.
Run project selection from the same application directory you use for setup.

Use `--project` in setup to override this preference. Explicit
`--backend-url` and offline setup do not require Inth account access.

## Create a project

```bash
c15t projects create my-project --organization <organization-id> --region <region-id> --json
```

Interactive creation asks for a project name, organization, and available
region. An explicit organization may be its ID or slug. c15t invokes Inth's
current `project create` command with c15t branding and selects the returned
project for this application. Region discovery has no legacy v2 filtering.

A newly created project's consent backend may still be pending. Setup requires
`consent.backendUrl` from the project response. It never substitutes a dashboard
URL. Project data and account errors stay within c15t's versioned JSON result.

## Supported platforms

Hosted account commands (`login`, `logout`, `status`, and `projects`) run Inth's
native executable. `@inth/cli` 0.0.4 ships executables for:

* macOS on Apple silicon (arm64)
* Linux arm64 and x64 with glibc
* Windows x64

Intel Macs, musl-based Linux such as Alpine, and other platforms have no Inth
executable. On those platforms, hosted account commands fail with
`INTH_UNSUPPORTED_PLATFORM`. `INTH_TOKEN` does not help there, because the key is
used by the executable. Pass `--backend-url` to `c15t setup` with the backend URL
from the Inth dashboard, or use offline setup. Neither needs Inth.

On supported platforms, install optional dependencies so the matching
`@inth/cli-<platform>-<arch>` package is present. Yarn Plug'n'Play cannot run an
executable from its zip cache: mark the platform package as `unplugged` in
`dependenciesMeta`, or use `nodeLinker: node-modules`. c15t reports both cases as
`INTH_UNAVAILABLE` with the package name.

The shared c15t generation and agent modules do not import or execute Inth;
embedded hosts continue to supply their own configuration.

# Self-hosted migrations
URL: https://c15t.com/docs/cli/commands/self-host
Plan and apply database migrations for a self-hosted c15t backend with the c15t CLI self-host migrate command.

## Plan a migration

```bash
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --plan --json
```

The CLI reads the `database` option from the config file, loading `.env` from
the file's directory, and reports what it would change. `--plan` changes no
schema. Without `--config`, the CLI looks for `c15t-backend.config.ts`; in a
terminal it can help you create one.

A v2 config that only has `adapter` fails with a message naming the field.
Replace it with `database`, as the
[database setup guide](/docs/self-host/guides/database-setup#upgrade-a-v2-backend)
shows.

## Apply it

```bash
npx @c15t/cli@alpha self-host migrate --config ./c15t-backend.config.ts --apply --json
```

`--apply` is the only flag that writes. Without `--plan` or `--apply`, a
terminal shows the plan and asks before applying; a script must pass one of
them. `--json` alone never applies a migration.

The result reports planned, applied, already current or cancelled work. A
database the migrator does not recognize fails with an explanation instead of
being changed. The CLI closes its database connection when it finishes, also on
failure.

Back up the database before applying against existing data, and run the
migration against the same database and schema the server uses. Codemods do
not migrate a database.

# Global flags
URL: https://c15t.com/docs/cli/global-flags
Flags every c15t CLI command accepts, for JSON output, the project directory, prompts and telemetry, plus exit codes.

## Flags for every command

```bash
npx @c15t/cli@alpha projects list --json --no-telemetry
```

|Flag|Behavior|
|--|--|
|`--help`, `-h`|Show help and the options supported by a command.|
|`--version`, `-v`|Report the installed CLI version.|
|`--cwd <directory>`|Resolve the command's project directory without changing the caller's working directory.|
|`--logger <level>`|Choose the diagnostic log level.|
|`--yes`, `-y`|Accept confirmation prompts. Does not supply missing names, modes, or URLs.|
|`--non-interactive`|Fail when required input would need a prompt.|
|`--json`|Return one versioned JSON result on stdout and disable prompts.|
|`--no-telemetry`|Disable telemetry.|
|`--telemetry-debug`|Enable telemetry diagnostics.|

String options accept both `--name value` and `--name=value`. Unknown commands, unknown flags, missing flag values, and flags used with the wrong command return a failure.

`--json` controls presentation. It does not grant permission to apply a setup plan or database migration. Use the command's explicit application option.

## Telemetry

Set `C15T_TELEMETRY_DISABLED=1` or `C15T_TELEMETRY_DISABLED=true` to disable telemetry for executable invocations. `--no-telemetry` also disables it. Telemetry is off by default when calling the JavaScript library.

## Exit status

Successful commands return `0`. Failed commands return `1`. Command cancellation returns `130`. JSON results include the corresponding `exitCode`, `success`, and error details.

# Compare c15t with consent tools and custom code
URL: https://c15t.com/docs/comparisons
Compare c15t with consent platforms, browser libraries and custom code. See its strengths, setup requirements and the features its packages do not include.

## Choose c15t for consent your product team can own

c15t is our recommended choice for product teams that need native framework integration, control of the consent interface and ownership of the backend. You can review consent behaviour with the application that depends on it.

The strongest reason to choose c15t is this combination of control and integration. Other tools also have APIs, custom styles, service controls or consent records.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## See what c15t includes

|Requirement|c15t status|What that means|
|--|--|--|
|Native web integration|**Included**|React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start, plus browser and headless JavaScript options|
|Your own consent interface|**Included**|Themes, component parts and headless APIs|
|Consent-aware application features|**Included**|Read policy permissions, explicit choices and vendor state|
|Category and vendor controls|**Included with configuration**|Apply rules to registered scripts, requests and embeds|
|Server-resolved consent|**Supported by framework**|Next.js offers streamed, awaited and browser paths|
|Remote consent records|**Hosted by Inth**|Inth, the team behind c15t, runs the backend and stores consent records in a database. Self-hosting is optional|
|Google Consent Mode|**Integration available**|Follow the Google tag or GTM guide. Inspect actual requests|
|IAB Transparency and Consent Framework|**Add-on available**|TCF 2.4 through `@c15t/iab`. Configure the relevant policy|
|Banner experiments|**Included with configuration**|Compare presentation and theme while policy and policy text stay fixed|
|Legal-document versions and snapshots|**Backend helpers available**|Supply your legal text and build the acceptance flow|
|Automatic website scans|**Not included in the packages**|Use a separate discovery and inventory process|
|Generated privacy and cookie policies|**Not included**|Supply or get the legal documents separately|
|Full privacy operations suite|**Not included**|Data-subject case management, enterprise data discovery and assessments are separate requirements|

See [framework setup](/docs/frameworks), [custom interfaces](/docs/frameworks/react/headless), [vendor controls](/docs/frameworks/react/vendor-consent), [banner experiments](/docs/guides/banner-experiments) and [backend features](/docs/self-host/overview).

The release covered here is currently an alpha. Review the [upgrade guide](/changelog/3.0.0#upgrading) before you change a current installation.

## Compare c15t with code you build yourself

[c15t vs building consent yourself](/docs/comparisons/build-your-own) compares the full implementation. It also covers AI-assisted code.

Choose c15t to reuse the consent engine, framework components and backend while you keep control of the interface. The guide covers what your team still owns and when custom code can make sense.

## Compare c15t with consent platforms

Choose c15t when application integration and source ownership drive the decision. Check the separate operational services that you would still need.

|Provider|Why choose c15t|What the other provider also offers|
|--|--|--|
|[Cookiebot](/docs/comparisons/cookiebot)|Native components, explicit vendor rules and control over package releases|Hosted configuration, scans and automatic blocking|
|[Usercentrics](/docs/comparisons/usercentrics)|Native application state and an engine and backend you can change|Website operations, records and plan-dependent experiments|
|[OneTrust](/docs/comparisons/onetrust)|Own the implementation as well as the interface|A headless server API, scans and broader privacy operations|
|[Didomi](/docs/comparisons/didomi)|Framework components and experiments in your product workflow|React integration, a notice console, APIs and A/B tests|
|[iubenda](/docs/comparisons/iubenda)|Control the interface, vendor code and record backend|Generated legal documents, scans and managed consent|
|[Osano](/docs/comparisons/osano)|Inspect and change consent behaviour in your application|Classification, managed records and contractual services|
|[CookieYes](/docs/comparisons/cookieyes)|Broader native framework coverage, individual vendor choices and a supplied backend|Open-source React and Next.js SDKs, plus hosted scans and policies|
|[Ketch](/docs/comparisons/ketch)|Own the web components, consent engine and backend|Identity services, mobile SDKs and connected privacy operations|
|[Ethyca](/docs/comparisons/ethyca)|Native web consent components and a deployable backend|Fides source and wider Janus consent services. Check current deployment and support scope|
|[Enzuzo](/docs/comparisons/enzuzo)|Build consent into the product and control its record backend|Hosted scans, legal policies, data-request tools and an Enterprise headless mode|
|[Cookie Control](/docs/comparisons/cookie-control)|Native components, individual vendor choices and backend ownership|Premium scans and account configuration. v9 code configuration and APIs|
|[Axeptio](/docs/comparisons/axeptio)|Own the application interface, consent engine and backend|Visual consent editor, service APIs, scans and A/B tests|
|[Termly](/docs/comparisons/termly)|Native product controls and a backend you can run|Policy generators, scans, hosted records and consent APIs|
|[CookieScript](/docs/comparisons/cookiescript)|Own the full engine and record service|Site scans, developer controls and a downloadable banner file|
|[CookieHub](/docs/comparisons/cookiehub)|Broader native web integration and backend ownership|React components, APIs, automatic scans and managed logs|
|[consentmanager](/docs/comparisons/consentmanager)|Native web components and an engine and backend you can change|Central operations, scans, custom interfaces, experiments and connected-TV tools|
|[TrustArc](/docs/comparisons/trustarc)|Control consent inside the product and choose its backend|React integration, tracker discovery, reports and wider privacy operations|
|[CookieFirst](/docs/comparisons/cookiefirst)|Broader native web integration and a deployable backend|React support, custom interfaces, service choices, scans and cookie-policy tools|
|[Sourcepoint by Didomi](/docs/comparisons/sourcepoint)|Own consent inside a custom web application|Publisher campaigns, vendor controls, records and connected-TV support|

Each linked page cites the provider's own sources. A wider privacy suite can be the better fit when that wider scope is the main requirement.

## Compare c15t with CMS plugins

Choose c15t when your product needs consent beyond a CMS. These alternatives have useful native workflows for the platforms they support.

|Provider|Why choose c15t|What the other provider also offers|
|--|--|--|
|[Complianz](/docs/comparisons/complianz)|Native web components and a backend independent of WordPress|WordPress scans, legal tools and records. A separate Shopify app|
|[Borlabs Cookie](/docs/comparisons/borlabs-cookie)|Consent across custom web frameworks with a separate backend|Local visitor data, service controls, scans and consent logs within WordPress|

Platform scope matters. A WordPress feature does not establish the same support in a Shopify app or a custom frontend.

## Compare c15t with browser libraries

Choose c15t when you want the framework integration and consent backend together. A smaller library can be enough when your team already owns the other infrastructure.

|Library|Why choose c15t|What to recognise in the alternative|
|--|--|--|
|[CookieConsent v3](/docs/comparisons/cookieconsent-v3)|Native state and a supplied record backend|Category and service controls. Callbacks can connect to your backend|
|[Klaro](/docs/comparisons/klaro)|Dedicated framework adapters and a deployable backend|Open-source client. Hosted plans also have records and scans|
|[react-cookie-consent](/docs/comparisons/react-cookie-consent)|Policy, preferences and vendor controls beyond a React bar|A small component for an application that supplies the rest|
|[Silktide Consent Manager](/docs/comparisons/silktide-consent-manager)|Regional policy, framework state and remote records|A free browser manager with scripts and Consent Mode support|
|[tarteaucitron.js](/docs/comparisons/tarteaucitron)|Connect service choices to application state and backend records|Individual service controls. Separate Pro automation|

These tools are also open source. c15t's advantage is the combined application and backend workflow.

## Know the limits before you choose

c15t controls the integrations and targets that you configure. A visible banner does not automatically stop every script already on the site.

Some integrations load before consent and receive denied signals. Withdrawal normally reloads the page. Optional cleanup cannot remove all vendor data.

A local choice is not proof of a successful save.

The software has no licence fee. Inth, infrastructure, implementation and any separate site scans or legal services still have costs.

These comparisons cover the c15t packages and their documented backend options. The open-source software does not include every commercial Inth service.

## Prove the advantage in your application

Start with [Inth and a framework guide](/docs/frameworks). Use a test deployment and one owner for consent.

1. Register one analytics vendor and one embed.
2. Check their expected behaviour under the selected policy.
3. Reject, reload, accept and later withdraw consent.
4. Inspect actual requests, the interface and the saved record.
5. Compare the code, infrastructure and operational work needed by each option.

Follow the [verification guide](/docs/guides/verify-consent). For Next.js, also check the selected [rendering path](/docs/frameworks/next/rendering).

Sources checked on 6 October 2026. Recommendations reflect application integration and ownership.

We did not benchmark these products or assess legal compliance. We mark documented limits separately from features that the reviewed sources do not establish.

# c15t vs building consent yourself
URL: https://c15t.com/docs/comparisons/build-your-own
Keep your own consent design without building every layer from scratch. Compare c15t with a custom implementation, including AI-assisted code.

## Keep your design. Reuse the consent system.

Choose c15t when your team wants a custom consent experience with a supplied engine, framework components and backend. Your developers can focus on how consent fits the product.

A custom implementation can match these features. The difference is which parts your team must design, test and support. This comparison includes code written by people or with AI assistance.

The release covered here is currently an alpha. Evaluate its APIs and [upgrade path](/changelog/3.0.0#upgrading) before production use.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the work your team owns

|What you need|With c15t|With your own implementation|
|--|--|--|
|Show a consent interface|Use framework components or build a custom UI through headless APIs|Build the banner, preference controls and application state|
|Separate permissions from choices|A shared consent model distinguishes the two|Define what each state means and which events record a choice|
|Offer category and vendor choices|Configure the supplied preference controls and vendor rules|Design the choice model and connect it to each vendor|
|Control scripts, requests and embeds|Register supported integrations and explicit rules|Build or adopt controls for each way that a vendor can run|
|Resolve policy for a visitor|Configure policy rules and the fallback for unknown locations|Build policy selection, fallback behaviour and policy updates|
|Store remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Build or adopt record storage, delivery and recovery from failures|
|Support server output|Follow the selected framework's server or browser path|Handle initial state, hydration and saved choices in each framework|
|Handle withdrawal|Use the runtime's withdrawal flow and configured cleanup|Define how each vendor stops and which data your code can remove|
|Support future changes|Review c15t updates and test your integrations|Own updates across the implementation and its dependencies|

The c15t column still needs setup and tests. It describes reusable software, not a completed consent deployment.

## Can I vibe code a consent banner?

AI can help you write a banner, a custom consent system or an integration with c15t. Your team still owns the design decisions and checks the result.

The useful comparison is the complete visitor flow. A button that saves a cookie covers only part of it.

Check a fresh visit, a saved refusal, a later change of mind and a failed backend save. Also check navigation, policy changes and each vendor's behaviour.

For example, a banner can save a refusal while a separate analytics script still runs. Both a custom implementation and c15t need that unconditional loader removed.

Use AI to build your product's interface on c15t's [headless APIs](/docs/frameworks/react/headless). You keep control of the design and reuse the consent model underneath it.

## Reuse the parts that must agree

The banner, settings screen, script controls and backend record need to describe the same decision. c15t connects them through one [consent model](/docs/concepts/how-consent-works).

A permission under a policy is not always an explicit grant from a visitor. Your application must preserve that distinction when it decides what can run and what to record.

[Vendor consent](/docs/frameworks/react/vendor-consent) also lets a visitor refuse one named service within an accepted category. Your registered integrations can use that choice.

The [framework guides](/docs/frameworks) supply the integration path. For Next.js, choose the [response behaviour](/docs/frameworks/next/rendering) that fits the application. The App Router's default streamed path does not include the banner in initial HTML.

c15t's source is open under Apache-2.0. Your team can inspect it, pin package versions and change it when necessary.

## What c15t does not include

* **Automatic control of every tracker.** Your team must register integrations and remove duplicate or unconditional loaders.
* **A website scanner or legal-policy generator.** The packages do not supply these tools. Your team must supply the inventory and legal text separately.
* **A guarantee that no request occurs before consent.** Some integrations load with denied signals. Check the selected policy and actual network behaviour.
* **Automatic deletion of all vendor data.** Withdrawal normally reloads the page. Optional cleanup cannot remove every cookie or erase data already sent elsewhere.
* **Remote records without a backend.** A local choice is not proof that a backend received it.
* **An end to maintenance.** Your team still owns configuration, dependency updates, accessibility checks and production tests. Self-hosting also includes database operations and availability.

The software has no licence fee, but Inth, infrastructure and implementation still have costs.

Neither approach establishes legal compliance by itself. Choose the applicable policy and legal text for your organisation.

## When your own implementation can make sense

Custom code can fit a narrow requirement when your team already has the policy, vendor controls, record service and tests. It can also fit constraints that c15t does not support.

Compare that work honestly. An interface on infrastructure you already operate is a different task from a new consent system.

c15t is our recommended choice when you need those layers together. You can still own the interface and, if needed, the backend.

## Prove the choice with one vendor

1. Choose one analytics vendor and one embed in a test application.
2. Connect c15t with [Inth and the correct framework guide](/docs/frameworks).
3. Test refusal, acceptance, reload and withdrawal in a production build.
4. Inspect actual requests and the backend record after each choice.
5. Simulate a backend failure and inspect the result after recovery.
6. Compare the custom implementation against the same cases and name an owner for future changes.

Use the [verification guide](/docs/guides/verify-consent) and [cleanup limits](/docs/frameworks/react/clear-on-revocation) as the review checklist.

Reviewed against c15t on 6 October 2026. This comparison describes implementation responsibilities. We did not benchmark AI tools or measure implementation time.

# c15t vs Axeptio
URL: https://c15t.com/docs/comparisons/axeptio
Choose c15t to own your consent interface, application behaviour and backend. Compare Axeptio's visual editor, vendor APIs, scans and banner experiments.

## Keep control of the experience and the code

c15t is the stronger fit when your product team wants to own the consent interface and the code behind it. Use your framework's components, connect consent to product features, and choose where records live.

Axeptio suits teams that want a visual editor for branded consent experiences. It also has developer APIs, service choices and banner experiments.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Axeptio|
|--|--|--|
|Design the interface|Themes, component parts and headless APIs in your application|Visual banner editor with custom text, design and interactions|
|Connect consent to features|Native framework state and declared integrations|JavaScript SDK, callbacks and service consent methods|
|Check a named service|Category and vendor state|SDK methods to check or ask for consent to a service|
|Choose the record service|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed consent collection|
|Find trackers|**No automatic scanner in the packages**|Cookie and tracker scanner|
|Test banner designs|Presentation and theme experiments with fixed policy and policy text|Built-in analytics and A/B tests|
|Manage legal acceptance|Backend version and snapshot helpers. Build the acceptance flow|Separate terms product with document publication and a consent registry|

Sources: [Axeptio products](https://www.axept.io/) and [JavaScript SDK](https://support.axeptio.eu/en/articles/274036-about-axeptio-s-javascript-sdk).

## Put privacy controls inside your product

With c15t, an account screen, video placeholder and consent dialog can use the same consent state. Your team owns their markup and behaviour.

Use the [framework components](/docs/frameworks) or [headless APIs](/docs/frameworks/react/headless). Keep consent changes in the same review process as the product features that depend on them.

Axeptio also supports contextual consent through its SDK. Its service methods let developers check a choice or open a consent flow. c15t's advantage is the combination of native web components, an editable engine and a deployable backend.

## Choose who controls changes

Choose c15t when your developers need to review package upgrades, change the engine or operate the record service. Your team takes responsibility for those changes.

Choose Axeptio when a business team needs to change the consent experience through a visual editor. Its hosted tools can reduce the custom work for scans and consent design.

Both products support experiments. With c15t, [banner experiments](/docs/guides/banner-experiments) keep policy and policy text fixed while presentation changes.

## What c15t does not include

* The packages do not include automatic site scans or a visual campaign console.
* Legal-document helpers do not write legal text or build the full acceptance flow.
* Vendor controls need configuration. A banner does not stop every script already on the site.
* A browser choice does not prove that the backend saved it.

Some integrations load with denied consent signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Budget for setup, Inth or your own servers, and continued checks after product changes.

## Try the product flow you need

Start with the [framework guide](/docs/frameworks). Add a consent control to one product feature and register its vendor.

Test refusal, acceptance, reload and withdrawal. Check the actual requests and saved record with the [verification guide](/docs/guides/verify-consent).

Compare the work needed to change that flow in code with the work needed in Axeptio's editor and SDK.

Sources checked on 6 October 2026. This comparison assesses documented workflows, not measured speed or legal compliance.

# c15t vs Borlabs Cookie
URL: https://c15t.com/docs/comparisons/borlabs-cookie
Choose c15t for consent beyond WordPress, with native web components and a separate backend. Compare Borlabs Cookie's local records, service controls and scanner.

## Keep control when your product extends beyond WordPress

c15t is the stronger fit when your team needs consent in a custom web application. Its framework components and backend let you own the consent system independently of WordPress.

Borlabs Cookie is a WordPress product with local visitor data, individual service controls and developer tools. Self-hosting alone does not distinguish c15t from Borlabs.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Borlabs Cookie|
|--|--|--|
|Build outside WordPress|Native web framework adapters, browser and headless options|WordPress only|
|Control the interface|Themes, component parts and headless APIs|Dialog settings, custom content placeholders and JavaScript API|
|Let visitors choose services|Category and individual vendor state|Service groups with individual service choices|
|Control scripts and embeds|Declared rules for scripts, requests and embeds|Script, style and content controls|
|Keep records on your servers|Deploy the supplied c15t backend|Consent logs within the WordPress setup. Visitor data stays on your server|
|Use a managed backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Consent runs within your WordPress installation|
|Discover services|**No automatic scanner in the packages**|Scanner with suggested service packages|
|Operate within WordPress|Developer setup. No bundled WordPress wizard|Setup assistant, package library, WP CLI and Composer support|

Sources: [Borlabs product and platform scope](https://borlabs.io/), [feature list](https://borlabs.io/borlabs-cookie/features/) and [JavaScript API](https://borlabs.io/docs/javascript-api-v3/).

## Connect consent to your application

Borlabs already covers several reasons teams choose a consent tool: local data, service choices, embeds and consent logs. Its API also supports custom integrations.

c15t adds a [native workflow across web frameworks](/docs/frameworks). Your team can put privacy controls into a product screen and connect them to shared consent state.

Use [headless APIs](/docs/frameworks/react/headless) for your markup. Declare [vendors](/docs/frameworks/react/vendor-consent) beside the integrations they control.

The backend is a separate service that can run with your chosen database. That separation helps when the application frontend and consent service need their own deployment lifecycle.

## Choose where administration belongs

Choose c15t when your main product is a custom web application or extends beyond a WordPress site. Keep consent in the product's code review and release process.

Borlabs can be the better fit when your team wants consent administration inside WordPress. Its scanner and package library can reduce the manual configuration of supported plugins and services.

With either product, your team must check new integrations and consent changes. Local data storage does not remove the work of updates, backups and operational checks.

## What c15t does not include

* The packages do not include a WordPress administration screen, setup assistant or automatic service scanner.
* They do not generate privacy policies or manage wider legal-document work.
* Vendor rules cover configured targets. They do not discover every tag or CMS plugin automatically.
* A browser choice does not prove that the backend saved the record.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Include setup and backend operation when you compare the total work and cost.

## Test the application boundary

Follow the [framework guide](/docs/frameworks). Connect one vendor and one embed that your product needs outside WordPress.

Test refusal, acceptance, reload and withdrawal with the [verification guide](/docs/guides/verify-consent). Check requests and records. Check any tags that the CMS still supplies too.

Sources checked on 6 October 2026. This comparison credits the local data, service choices and developer APIs in both products.

# c15t vs Complianz
URL: https://c15t.com/docs/comparisons/complianz
Choose c15t for consent across custom web applications. Compare Complianz's WordPress plugin and Shopify app, with clear differences in scans, records and legal tools.

## Keep consent with your application as it grows

c15t is the stronger fit when your product needs consent across custom web frameworks. Your team can own the interface, engine and backend independently of a CMS plugin.

Complianz has a WordPress plugin and a separate Shopify app. Its WordPress product combines consent controls, scans and legal-document tools. The platform matters when you compare features.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Complianz|
|--|--|--|
|Build a custom web application|Native adapters for the documented web frameworks|Native WordPress plugin and separate Shopify app|
|Create your own interface|Themes, component parts and headless APIs|WordPress banner settings, custom CSS and HTML templates|
|Control services|Declared categories and vendors for scripts, requests and embeds|WordPress Script Center, service choices and content placeholders|
|Choose the record service|Inth hosts the backend and stores records in its database. Self-hosting is optional|WordPress Premium includes Records of Consent|
|Discover cookies|**No automatic scanner in the packages**|WordPress cookie scan and service detection|
|Generate legal documents|**Not included**|WordPress legal-document tools, with plan-dependent scope|
|Test banner designs|Presentation and theme experiments with fixed policy and policy text|WordPress Premium lists A/B tests|
|Configure CMS plugins|Developer setup in your application|WordPress plugin and service integrations|

Sources: [Complianz platforms](https://complianz.io/), [WordPress features](https://complianz.io/features/), [plan differences](https://complianz.io/help/wordpress/faq/complianz-pricing-faqs/) and [developer integrations](https://complianz.io/help/wordpress/configuration/developers-guide-for-third-party-integrations/).

The WordPress features above do not establish the same feature set in the Shopify app. Check its separate plan and integration requirements.

## Use native consent outside the CMS

c15t's [framework components](/docs/frameworks) suit a product built with React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro or TanStack Start. The browser and headless options cover other JavaScript setups.

Your account settings, embeds and consent dialog can use the same state. Use [headless APIs](/docs/frameworks/react/headless) when your product needs different markup.

Complianz also has developer hooks and custom integration controls. c15t's advantage is a native application workflow and backend that can run independently of WordPress.

This distinction matters for a headless CMS frontend or a product that spans different web frameworks. Plan the migration of service rules and records explicitly.

## Choose the right operational scope

Complianz can be the better fit when a WordPress team wants consent, plugin detection and legal documents in its administration screen.

Choose c15t when consent belongs inside custom product code and your team wants control of the engine and backend. Keep a separate process for site scans and legal documents.

Check individual consent records separately from snapshots of a policy or configuration. Complianz [distinguishes Proof of Consent from Records of Consent](https://complianz.io/definition/what-is-proof-of-consent/). Check the evidence your deployment saves, not only its label.

## What c15t does not include

* The packages do not include a WordPress setup wizard, plugin discovery or an automatic cookie scanner.
* They do not generate privacy policies or include the wider WordPress legal-document suite.
* Vendor controls need configuration. CMS plugins and tags already on the site need separate checks.
* Browser state does not prove a successful remote save.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Budget for setup and Inth or your own servers. Add separate scan and legal services where you need them.

## Test the frontend you run

Use the [framework guide](/docs/frameworks) for your application. Register one analytics vendor and one embed from the site inventory.

Test refusal, acceptance, reload and withdrawal. Follow the [verification guide](/docs/guides/verify-consent) to check requests and records. Check tags that the CMS adds too.

Sources checked on 6 October 2026. This comparison separates platform scope from measured performance and legal compliance.

# c15t vs consentmanager
URL: https://c15t.com/docs/comparisons/consentmanager
Choose c15t to own consent inside your web application. Compare consentmanager's site operations, custom interfaces, scans, experiments and connected-TV tools.

## Own consent where your application needs it

c15t is the stronger fit when your developers need native web components and control of the consent engine and backend. You can review consent behaviour with the application features that depend on it.

consentmanager suits teams that need central operations across websites, apps and connected TVs. Its product also includes scans, experiments and customisation options.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|consentmanager|
|--|--|--|
|Integrate with a web application|Native framework components and reactive state|Website code, CMS plugins and developer APIs|
|Build a custom interface|Themes, component parts and headless APIs|Custom HTML and CSS on listed plans. CTV API supports custom interfaces|
|Choose the backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed platform with plan-dependent own-domain delivery|
|Control vendors|Declared category and vendor rules|Vendor and purpose settings, plus automatic script controls|
|Discover cookies|**No automatic scanner in the packages**|Cookie crawler and classification|
|Test banner designs|Presentation and theme experiments with fixed policy and policy text|Plan-dependent A/B tests and automatic design selection|
|Cover connected TVs|**No bundled connected-TV SDK**|HbbTV and CTV SDKs on listed plans|
|Manage teams and reports|Build around your chosen backend|Plan-dependent user roles, reports and exports|

Sources: [consentmanager feature comparison](https://www.consentmanager.net/en/features/) and [CTV API guide](https://help.consentmanager.net/books/cmp/page/ctv-api-integration).

## Keep the consent rules beside your product code

With c15t, privacy controls can live inside an account screen or feature. Use the [framework components](/docs/frameworks) or create the markup with [headless APIs](/docs/frameworks/react/headless).

Declare [vendor choices](/docs/frameworks/react/vendor-consent) with the integrations they control. Your team can check the code path from a visitor's action to the saved choice.

consentmanager also supports custom interfaces and developer APIs. c15t's advantage is the combined native web workflow and source code for the engine and backend.

An own-domain delivery option does not establish that you can deploy the entire record backend yourself. Check the exact hosting scope when you compare proposals.

## Choose the operations you need

Use c15t when your main requirement is consent inside a web product. Its [banner experiments](/docs/guides/banner-experiments) let your team test presentation while policy and policy text stay fixed.

consentmanager can be the better fit when one team needs scans, reports and campaign operations across sites and connected TVs. Check which features belong to the selected plan.

These workflows carry different responsibilities. With c15t, your team supplies site inventories and operates the backend if it chooses self-hosting.

## What c15t does not include

* The packages do not include a website crawler or a central campaign operations console.
* They do not include a connected-TV SDK or generated legal policies.
* Vendor controls cover configured targets. A visible banner does not stop every tag already on the site.
* Local consent state does not prove a successful write.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Include setup, Inth or your own servers, and separate operational tools in the budget.

## Compare your actual deployment

Use the [framework guide](/docs/frameworks) to connect one vendor and one embed. Test refusal, acceptance, reload and withdrawal.

Check requests and backend records with the [verification guide](/docs/guides/verify-consent). Evaluate connected-TV and central operations requirements separately from the web consent flow.

Sources checked on 6 October 2026. This comparison does not measure performance or promise legal compliance.

# c15t vs Cookie Control
URL: https://c15t.com/docs/comparisons/cookie-control
Choose c15t for native web components, individual vendor choices and backend ownership. Compare CIVIC's Cookie Control Premium and v9 accurately.

## Choose c15t for consent your application team can shape

c15t is the stronger fit when consent must share your product's components, state and release process. Your team can design the interface, review vendor rules and choose the backend.

Cookie Control is CIVIC's consent product. Premium offers scan-based setup and a hosted configuration wizard. Its v9 edition uses a JavaScript configuration that developers manage.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Cookie Control|
|--|--|--|
|Integrate with application code|Native framework components and reactive state|JavaScript module and APIs. v9 also has WordPress, Drupal and Joomla plugins|
|Build your own interface|Themes, component parts and headless APIs|Banner appearance, text and category customisation|
|Review configuration in code|Consent components and integration rules in your application|v9 supports code configuration. Premium publishes configuration from an account|
|Control vendor activity|Category and individual vendor rules for registered targets|Category controls. Premium adds automatic script and iframe controls|
|Keep consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Hosted consent log dashboard and downloads|
|Find cookies automatically|**Not included in the c15t packages**|Premium scans. v9 scan scope depends on licence and add-ons|
|Generate privacy policies|**Not included**|Listed in Premium plans|
|Budget for traffic|No software licence fee. Backend costs remain|Unlimited pageviews on Premium. Scan limits vary by tier|

Sources: [Premium overview](https://cookiecontrol.com/docs/premium), [Premium API](https://cookiecontrol.com/docs/premium/api-reference), [v9 setup](https://cookiecontrol.com/docs/v9/getting-started) and [edition and plan comparison](https://cookiecontrol.com/pricing).

## Use the same components and state as your product

With c15t, the banner, account settings and embedded content can share one consent state. Your team can test these interactions with the rest of the application.

The [framework guides](/docs/frameworks) cover React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, TanStack Start and plain websites.

Use the supplied UI or build it with [headless APIs](/docs/frameworks/react/headless). A product-specific interface does not need to depend on a hosted banner editor.

Cookie Control also exposes code interfaces. Premium's API includes callbacks for acceptance and withdrawal. The distinction is c15t's native component model and editable engine.

## Give visitors control of individual vendors

A c15t visitor can accept a category and refuse one named vendor within it. The [vendor controls](/docs/frameworks/react/vendor-consent) connect that choice to registered scripts, requests and embeds.

Cookie Control's reviewed Premium API uses category callbacks. Its scan and script tools help teams manage those categories with less manual setup.

For Next.js applications, c15t also offers explicit [server and browser response paths](/docs/frameworks/next/rendering). The App Router's default streamed path does not include the banner in initial HTML.

Your team can pin the c15t packages and review releases. Cookie Control v9 also documents versioned scripts and code configuration, so that control is not unique to c15t.

## What c15t does not include

c15t does not supply Premium's website scanner, configuration wizard or privacy policy generator. Your team must supply discovery and legal documents separately.

c15t does not automatically find and stop every tracker already on the site. Register the scripts, requests and embeds that need controls.

Withdrawal normally reloads the page. Optional cookie cleanup cannot delete every vendor cookie or remove data that a vendor already received.

The software has no licence fee. Backend operations and implementation still cost money. The release covered here is currently an alpha.

## Try the difference in your application

1. Start with [Inth and your framework guide](/docs/frameworks).
2. Register two vendors in one category.
3. Accept the category and refuse one vendor.
4. Check the interface, actual requests and backend record.
5. Compare the work with the Cookie Control edition that your team would use.

Use the [verification guide](/docs/guides/verify-consent) to check acceptance, refusal and withdrawal. Choose c15t when native product integration and backend control matter most.

Sources checked on 6 October 2026. Premium and v9 differ in setup and scan features. The cited [v9 documentation](https://cookiecontrol.com/docs/v9) describes its versioned script options.

# c15t vs Cookiebot
URL: https://c15t.com/docs/comparisons/cookiebot
Choose c15t for native application components, explicit vendor controls and backend ownership. Compare Cookiebot's scan-based setup and the gaps c15t leaves.

## Choose c15t when your team owns the application

c15t is the stronger fit when consent must work inside your product's code, design system and release process. Your team can build the interface, review vendor rules and choose where consent records stay.

Cookiebot is a strong option for teams that want a hosted banner with automatic website scans. c15t gives application teams direct control over the implementation.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Cookiebot|
|--|--|--|
|Integrate with application code|Native framework components and reactive consent state|Hosted script with JavaScript methods, events and callbacks|
|Build your own interface|Themes, component parts and headless APIs|Banner customisation and SDK controls|
|Choose the Next.js response|Stream consent, await it on the server, or resolve it in the browser|Client-side banner SDK. Server-side cookie use also documented|
|Control vendor code|Declare categories and vendors on scripts, requests and embeds|Scan-based automatic blocking or manual script tags|
|Choose the runtime version|Version the open-source packages with your application|Cookiebot's CMP script must load from its service|
|Keep consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed consent log and data export|
|Discover cookies automatically|**Not included in the c15t packages**|Website scans and scan reports|
|Budget for the service|No software licence fee. Backend costs remain|Domain and subpage tiers. No pageview charge|

Sources: [Cookiebot SDK](https://www.cookiebot.com/en/developer/), [automatic blocking](https://support.cookiebot.com/hc/en-us/articles/11438730619804-How-does-auto-blocking-work), [service scope](https://www.cookiebot.com/en/terms-of-service/) and [pricing](https://www.cookiebot.com/us/pricing/).

## Make consent part of the product

With c15t, a video placeholder, privacy settings screen and analytics integration can use the same consent state. Your developers can review them in the same pull request.

Use the supplied interface or build your own through [headless APIs](/docs/frameworks/react/headless). The [framework guides](/docs/frameworks) cover React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, TanStack Start and plain websites.

Cookiebot also exposes APIs. c15t's advantage is the native application components and the source code that your team can change.

## Keep control of vendor rules and releases

Declare each vendor through [c15t integrations](/docs/integrations/overview). Review its consent category and behaviour with the feature that introduces it.

A visitor can accept a category but refuse one named vendor. These [vendor controls](/docs/frameworks/react/vendor-consent) work outside the IAB consent framework too.

Your team can pin a c15t package version, test an update and release it with the application. Cookiebot's automatic-blocking guide specifies its hosted script and describes service updates.

For Next.js, choose [when consent resolves](/docs/frameworks/next/rendering). The App Router's default streamed path shows the page first. It does not include the banner in initial HTML.

## What c15t does not include

* **An automatic cookie scanner.** Keep a separate inventory process for vendors added through the app, CMS or tag manager.
* **Automatic control of every current tag.** Move those tags into registered integrations or explicit consent rules.
* **Free backend operations.** Pay for Inth or run the database, backups and updates yourself.
* **A speed guarantee.** Rendering choices give you control. They do not prove that c15t is faster on your site.

Some integrations load before consent and receive denied signals. Check each vendor's documented behaviour before you expect zero requests.

## Start with one real vendor

Choose c15t if application ownership is the priority. Keep Cookiebot on the shortlist if automated website inventory is the main job.

In a test deployment, use [Inth and your framework guide](/docs/frameworks). Move one analytics vendor and one embed, then remove their old loaders.

Check rejection, acceptance, reload, withdrawal and the saved record with the [verification guide](/docs/guides/verify-consent). Map purposes and policy versions before you reuse any previous consent.

Sources checked on 6 October 2026. The release covered here is an alpha.

This comparison covers documented features. We did not measure relative speed or cost.

# c15t vs CookieConsent v3
URL: https://c15t.com/docs/comparisons/cookieconsent-v3
Choose c15t when your application needs native consent state and a record backend. Compare CookieConsent's browser controls and the extra setup each approach needs.

## Choose c15t to connect the interface, rules and records

c15t is the stronger fit when your application needs more than browser preferences. It connects framework components, consent rules, vendor integrations and a backend for records.

CookieConsent is a capable browser library with granular controls and custom styles. It installs as `vanilla-cookieconsent`. It is a separate project from c15t.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you need to assemble

|What you need|c15t|CookieConsent v3|
|--|--|--|
|Use consent in framework components|Native adapters and reactive state|Browser library with framework setup recipes|
|Show preferences|Category and vendor controls|Category controls and individual service switches|
|Resolve consent in Next.js|Server, streamed and browser paths|Browser setup. Its React example starts in an effect|
|Keep remote consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Send records to your own backend through callbacks|
|Change the interface|Themes, component parts and headless APIs|Modal options, CSS and custom content|
|Control scripts|Registered integrations, request rules and embeds|Script attributes and service callbacks|
|Clear cookies after withdrawal|Optional category rules. Vendor-only refusal needs separate cleanup|Category and service cookie cleanup|
|Use Google Consent Mode|Documented Google tag and GTM integrations|Documented Consent Mode implementation|
|Pay for software|No licence fee. Backend costs remain|No licence fee. Any record backend is your responsibility|

Sources: [setup](https://cookieconsent.orestbida.com/essential/getting-started.html), [configuration](https://cookieconsent.orestbida.com/reference/configuration-reference.html), [consent records](https://cookieconsent.orestbida.com/advanced/consent-logging.html), [script controls](https://cookieconsent.orestbida.com/advanced/manage-scripts.html) and [Google Consent Mode](https://cookieconsent.orestbida.com/advanced/google-consent-mode.html).

## Use a backend that already understands consent

CookieConsent's record guide leaves the request to your own backend. That route works, but your team must supply storage, delivery and retrieval.

c15t gives you a [backend protocol and implementation](/docs/self-host/overview). The interface can use that consent state without a separate record system designed from scratch.

Check browser state and saved records separately. c15t applies a visitor's choice locally before the backend confirms it. Failed submissions have retry and expiry limits.

See the [consent state guide](/docs/concepts/consent-state) for those conditions.

## Fit consent to the application

Your c15t preference controls and gated content can use the same framework state. Use the supplied interface or build one with [headless APIs](/docs/frameworks/react/headless).

In Next.js, you can [choose how consent resolves](/docs/frameworks/next/rendering). The App Router's default streamed path shows the page first and sends the banner in a later chunk, before hydration. An awaited path sends the page and the banner together.

CookieConsent supports service switches, cookie cleanup and framework integration. c15t's stronger case is the integrated framework and backend workflow.

## What c15t does not include

* **A production record service with no setup or cost.** Configure Inth or deploy a backend.
* **Automatic vendor discovery.** Your team still needs to register the site's scripts and embeds.
* **Service-cookie cleanup for every vendor refusal.** The built-in cleanup follows categories. A vendor-only denial needs explicit cleanup.
* **Stable status for this release.** The version covered here is alpha.

If a local browser library covers the whole job, CookieConsent can need less infrastructure.

## Test the full choice lifecycle

Choose c15t when the product needs a common model for UI, vendor behaviour and remote records. Start with [Inth and the framework guide](/docs/frameworks).

Accept one category and reject another. Reload, reopen preferences and withdraw the first choice.

Check both vendor requests and backend records with the [verification guide](/docs/guides/verify-consent). Do not treat a visible banner as proof that the integration works.

Sources checked on 6 October 2026. The release covered here is an alpha. We did not compare measured bundle size or speed.

# c15t vs CookieFirst
URL: https://c15t.com/docs/comparisons/cookiefirst
Choose c15t for native web framework coverage and a backend you can run. Compare CookieFirst's React support, service choices, scans and cookie-policy tools.

## Own consent across your web application

c15t is the stronger fit when your team wants native consent components across web frameworks and control of the backend. You can change the interface and engine with the product that uses them.

CookieFirst combines hosted consent, scans and cookie-policy tools. Its React package and public API also support custom application flows.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|CookieFirst|
|--|--|--|
|Use native web integration|React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start|Official React component, browser script and platform integrations|
|Build a custom interface|Themes, component parts and headless APIs|Public consent API and a stealth mode without the supplied banner|
|Let visitors choose services|Category and individual vendor state|Category or service consent, under the configured policy|
|Control vendor code|Declared rules for scripts, requests and embeds|Third-party script settings and Autoblock|
|Choose the record service|Inth hosts the backend and stores records in its database. Self-hosting is optional|Hosted consent logs and plan-dependent audit trails|
|Discover cookies|**No automatic scanner in the packages**|Cookie scans|
|Generate a cookie policy|**Not included**|Cookie-policy generator|
|Handle withdrawal|Page reload by default, with optional cleanup|API clears consent, records the change and reloads the page|

Sources: [CookieFirst platform](https://cookiefirst.com/consent-management-platform/), [React setup](https://support.cookiefirst.com/hc/en-us/articles/13992449777437-How-to-add-CookieFirst-to-a-React-site) and [public API](https://support.cookiefirst.com/hc/en-us/articles/360011568738-Cookie-Banner-Public-API-documentation).

## Compare the full developer workflow

CookieFirst supports more than a standard banner. Its API exposes accepted categories and services. Stealth mode renders no consent interface. Its docs mark only the preference-centre methods as unavailable in that mode, so test whether its consent methods cover the custom controls you need.

Its service methods follow the selected policy. Under a category policy, a service action applies to the relevant category. Check that setting before you compare individual choices.

c15t combines [native framework components](/docs/frameworks), [vendor state](/docs/frameworks/react/vendor-consent) and a backend you can deploy. Your team can change the system from the interface through to record storage.

That combination is the reason to choose c15t when consent is part of the product's code and release process.

## Choose how much work stays with your team

CookieFirst can fit when scans, cookie-policy updates and managed banner settings are the main needs. Its developer tools can extend that setup.

Choose c15t when you need broader native web coverage and backend ownership. Use [headless APIs](/docs/frameworks/react/headless) for product-specific markup and Inth when you want managed backend operation.

Both products need checks for consent changes and vendor behaviour. A reload can stop active code. It cannot remove every trace of data already sent or stored.

## What c15t does not include

* The packages do not scan the site or generate cookie and privacy policies.
* They do not supply a visual website administration console.
* Script and vendor controls need configuration. They do not discover tags already on the site automatically.
* A local choice does not prove that a backend saved the record.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Include setup, backend costs and any separate scan or legal services in your comparison.

## Test a service choice through to its record

Start with the [framework guide](/docs/frameworks). Register two vendors in one category and check individual choices under the selected policy.

Test refusal, acceptance, reload and withdrawal. Use the [verification guide](/docs/guides/verify-consent) to check requests and saved records.

Sources checked on 6 October 2026. This comparison credits the React support, custom interfaces and service choices in both products.

# c15t vs CookieHub
URL: https://c15t.com/docs/comparisons/cookiehub
Choose c15t for native web framework coverage and backend ownership. Compare CookieHub's React components, consent APIs, automatic scans and hosted logs.

## Keep your consent system under product-team control

c15t is the stronger fit when you want native consent components across web frameworks and control of the backend. Your team can review and change the engine with the application.

CookieHub combines managed banners, scans and consent logs. It also has React components and developer APIs, so framework integration is an overlap.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|CookieHub|
|--|--|--|
|Use native web components|React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start|React package plus browser and CMS integrations|
|Connect application features|Reactive state, vendor choices and headless APIs|JavaScript methods, events and category controls|
|Control scripts and embeds|Declared categories and vendors for scripts, requests and embeds|Automatic controls plus React script, analytics and video components|
|Choose the record backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed consent log, enabled per domain|
|Find cookies|**No automatic scanner in the packages**|Website scanner|
|Handle regional rules|Backend policy and framework configuration|Managed region settings|
|Build a custom interface|Themes, component parts or your own markup|Banner settings and JavaScript controls|

Sources: [CookieHub overview](https://docs.cookiehub.com/), [React integration](https://www.cookiehub.com/react), [JavaScript API](https://www.cookiehub.com/javascript-api) and [consent log](https://docs.cookiehub.com/dashboard/consent-log).

## Compare framework depth and source ownership

CookieHub's React package can control scripts, analytics and video embeds. Its events let an application respond when a visitor changes a category choice.

c15t combines [native framework adapters](/docs/frameworks) with an engine and backend that your team can change. Use its components or build product-specific controls with [headless APIs](/docs/frameworks/react/headless).

This is useful when your product uses different web frameworks or when consent changes need code review. The benefit is control of the full system.

For Next.js, c15t also documents [server, streamed and browser paths](/docs/frameworks/next/rendering). The App Router's default streamed path does not put the banner in the initial HTML. Choose and test the path your application needs.

## Check what a saved record means

CookieHub's log can contain consent actions and session entries. A session entry does not carry a consent status. Turn on its log before you start collection, as its docs explain.

With c15t, connect to Inth to store consent records in its database. Check successful writes separately from the choice shown in the browser.

Choose CookieHub when the managed scanner and dashboard fit your workflow. Choose c15t when your developers need broader native integration and control of the record backend.

## What c15t does not include

* The packages do not include automated cookie discovery or a CMS plugin management console.
* They do not generate privacy policies or include a full privacy operations suite.
* Script, request and embed rules need configuration. A banner does not cover every tag already on the site.
* A browser choice does not prove that the backend saved a remote record.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Include setup, backend operation and any separate scans in your cost comparison.

## Test a real application route

Start with the [framework guide](/docs/frameworks). Add one analytics vendor and one embed, then navigate between application routes.

Test refusal, acceptance, reload and withdrawal. Use the [verification guide](/docs/guides/verify-consent) to check actual requests and saved records.

Sources checked on 6 October 2026. Framework coverage does not establish a measured performance or compliance advantage.

# c15t vs CookieScript
URL: https://c15t.com/docs/comparisons/cookiescript
Choose c15t to own the consent engine, framework components and backend. Compare CookieScript's scans, developer controls and self-hosted banner option.

## Own the consent system from interface to backend

c15t is the stronger fit when you want control of the consent engine and record service as well as the banner. Its native components and headless APIs connect consent to your application.

CookieScript combines banner settings, site scans and hosted consent records. Paid plans also let you download and host the banner's JavaScript file.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|CookieScript|
|--|--|--|
|Integrate with your application|Native framework components and state|Browser script with custom functions and events|
|Create a custom interface|Themes, component parts and headless APIs|Banner design settings and programmatic controls|
|Host frontend code yourself|Packages in your application|Downloadable banner JavaScript on paid plans|
|Run the record backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Hosted consent records. Banner download does not establish a deployable record backend|
|Control scripts|Declared category and vendor rules|Automatic script controls and manual setup|
|Discover cookies|**No automatic scanner in the packages**|Website scans and cookie declarations|
|Update a local installation|Review and deploy package upgrades|Download the banner file again after account changes|

Sources: [CookieScript plans](https://cookie-script.com/pricing), [self-hosted banner guide](https://cookie-script.com/download-and-host-javascript-files.html) and [custom functions](https://help.cookie-script.com/en/articles/30246-custom-functions).

## Compare what self-hosting gives you

CookieScript's local file option is useful when your team needs to control asset delivery. Its guide also notes manual file updates and unavailable geo-targeting on that path.

c15t gives your team another level of control: the framework components, consent engine and backend source. You can change the code and run the backend with your own database.

That control brings work. Your team owns deployment, updates and operations when it runs the service itself. Inth remains the recommended managed path.

Do not treat a locally hosted banner file and a complete backend deployment as the same requirement. Check where choices go and who operates that service.

## Keep consent beside the features it controls

Use c15t's [framework components](/docs/frameworks) to connect product settings, embeds and vendor choices to one consent state. Use [headless APIs](/docs/frameworks/react/headless) when you need different markup.

CookieScript also has functions to read consent state and events for banner actions. c15t's advantage is the combined application and backend workflow.

Choose CookieScript when site scans and banner administration are the main tasks. Choose c15t when your developers need to own the full consent system.

## What c15t does not include

* The packages do not scan the site or generate cookie declarations automatically.
* They do not generate privacy policies or replace a legal review.
* Vendor controls cover the targets you configure. Tags already on the site need separate checks.
* A local choice does not prove a successful remote save.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. The software has no licence fee. Setup, Inth or your own servers still have costs.

## Test the ownership you need

Set up c15t with the [framework guide](/docs/frameworks). Add one vendor and one embed, then test refusal, acceptance, reload and withdrawal.

Check requests and saved records with the [verification guide](/docs/guides/verify-consent). Compare a package upgrade with CookieScript's hosted and downloaded-file workflows.

Sources checked on 6 October 2026. Self-hosting details describe the documented options, not a measured speed advantage.

# c15t vs CookieYes
URL: https://c15t.com/docs/comparisons/cookieyes
Choose c15t for broader framework support, individual vendor choices and a supplied consent backend. Compare CookieYes SDKs and hosted services fairly.

## Choose c15t for one consent system across your applications

c15t is the stronger fit when your products span multiple web frameworks and need individual vendor choices alongside category consent. Your team can use native components, own the interface and choose where policy and records live.

CookieYes offers both a hosted service and open-source SDKs. Its SDKs include React components, Next.js server support, headless primitives and a JavaScript core. Both tools offer these features.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|CookieYes|
|--|--|--|
|Use native framework components|React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro and TanStack Start|Documented SDKs for React, Next.js and core JavaScript|
|Build your own interface|Themes, component parts and headless APIs|SDK themes, parts, hooks and headless primitives. Hosted banner customisation too|
|Resolve consent on the server|Next.js streamed, awaited and browser paths|Next.js SDK documents server-rendered consent UI|
|Control vendor activity|Category and individual vendor rules for registered scripts, requests and embeds|SDK category gates and configured network rules. Hosted script controls|
|Store records on your server|Supplied backend with policy and record services|SDK sends records to an endpoint that you build and operate|
|Use managed records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Hosted consent log with CSV export|
|Find cookies automatically|**Not included in the c15t packages**|Hosted website scanner|
|Generate legal policies|**Not included**|Hosted privacy and cookie policy generators|

Sources: [CookieYes SDK overview](https://developers.cookieyes.com/docs), [React APIs](https://developers.cookieyes.com/docs/react/getting-started/installation), [self-hosted records](https://developers.cookieyes.com/docs/nextjs/getting-started/self-hosted), [network rules](https://developers.cookieyes.com/docs/react/network-blocking) and [hosted features](https://www.cookieyes.com/features/).

## Keep consent consistent across your products

Use c15t's [framework guides](/docs/frameworks) to connect each application to the same consent model. A Vue product and a React account page can each use native components.

With [vendor consent](/docs/frameworks/react/vendor-consent), a visitor can accept a category but refuse one named vendor. The interface and registered integrations can use that choice.

CookieYes also offers reactive state and category controls. Its reviewed network rules use categories. The cited guides do not establish an equivalent individual-vendor preference model outside TCF.

This distinction matters when two services serve the same purpose but a visitor wants only one of them. Test that case in both tools.

## Choose a backend without building the record service first

c15t supplies the backend as well as the client. Use Inth to manage it, or deploy the open-source service with your own database.

CookieYes's self-hosted SDK guide describes record delivery, retries and a sample receiver. Your team supplies durable storage and operates that endpoint.

Both approaches can keep records under your control. c15t gives you a supplied policy and record service for this path.

CookieYes's hosted service offers managed logs instead. Its [consent guide](https://www.cookieyes.com/documentation/cookieyes-for-gdpr-cookie-compliance/) documents exports, scans and policy tools. Compare that service separately from its SDK.

## What c15t does not include

c15t does not include CookieYes's hosted website scanner or legal policy generators. Your team must supply those services or processes separately.

c15t controls the scripts, requests and embeds that you configure. It does not automatically discover every tracker already on the site.

Withdrawal normally reloads the page. Optional cleanup cannot remove every vendor cookie or erase data already sent to a vendor.

The software has no licence fee, but implementation and backend operations still cost money. The release covered here is currently an alpha.

## Try the difference in your application

1. Start with [Inth and your framework guide](/docs/frameworks).
2. Register two vendors in one consent category.
3. Accept the category and refuse one vendor.
4. Check the interface, actual requests and backend record.
5. Repeat the flow with CookieYes and compare the code and services required.

Use the [verification guide](/docs/guides/verify-consent) for acceptance, refusal and withdrawal checks. Check the [Next.js response options](/docs/frameworks/next/rendering) if you need server output.

Sources checked on 6 October 2026. This comparison separates CookieYes SDK features from hosted services. It does not claim measured performance or legal compliance.

# c15t vs Didomi
URL: https://c15t.com/docs/comparisons/didomi
Choose c15t for native framework components, open-source consent logic and backend ownership. Compare Didomi's SDKs, notice console and experiments.

## Choose c15t for consent that follows your product workflow

c15t is the stronger fit when your developers want to own the consent interface, vendor rules and backend implementation. Changes can follow the same code review and release process as the application.

Didomi combines a shared notice console with SDKs, APIs and consent analytics. It also supports React and custom interfaces, so developer access is common to both products.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the work your team controls

|What you need|c15t|Didomi|
|--|--|--|
|Integrate with application code|Native adapters across web frameworks|Hosted Web SDK and a React component|
|Build a custom interface|Themes, component parts and headless APIs|Notice customisation and APIs for your own UI|
|Read vendor and purpose choices|Framework state and vendor controls|Web SDK methods and events|
|Choose the Next.js response|Streamed, awaited or browser paths|Hosted SDK integration. Test the required server flow separately|
|Run the backend yourself|Open-source backend with your own database|Didomi platform and consent APIs|
|Keep consent evidence|Inth hosts the backend and stores records in its database. Self-hosting is optional|Consent events and history|
|Compare banner variants|Presentation experiments with your flags or built-in assignment|A/B tests and consent analytics|
|Publish notices from a shared console|Inth service workflow. No equivalent business console bundled in the packages|Console for marketing, legal and engineering teams|

Sources: [Didomi platform](https://www.didomi.io/consent-management-platform), [Web SDK and React setup](https://developers.didomi.io/cmp/web-sdk/getting-started), [JavaScript API](https://developers.didomi.io/cmp/web-sdk/reference/api) and [custom-UI consent events](https://developers.didomi.io/api-and-platform/consents/events).

## Use one consent state across the product

c15t lets your privacy controls, gated content and registered vendors use the same state. A designer can change the interface while a developer checks its behaviour in application tests.

Start with the supplied components or build a [headless interface](/docs/frameworks/react/headless). Use [vendor controls](/docs/frameworks/react/vendor-consent) to connect an individual service to the visitor's choices.

Didomi's React component loads its SDK and receives notice configuration from the Console. c15t gives you native components plus source code for the consent engine.

## Keep experiments in your current release process

Use your feature-flag tool to assign c15t [banner variants](/docs/guides/banner-experiments). The variant travels with impressions and choices, so you can compare outcomes.

The experiment changes presentation and theme. The policy, categories and policy text stay fixed.

Didomi also has A/B tests. c15t's advantage for application teams is the ability to define the experiment in product code and choose the record backend.

## What c15t does not include

* **Didomi's complete business console.** The open-source packages do not bundle the same notice publication and team administration workflow.
* **A ready-made cross-device rollout.** Backend identity links need an application flow. Do not assume full parity with Didomi's service.
* **An automatic record migration.** Your team must map vendor identifiers, purposes, policy versions and previous choices.
* **A legal guarantee for an experiment.** Presentation checks flag some issues. They do not certify a layout.

In the Next.js App Router, the default streamed [rendering path](/docs/frameworks/next/rendering) sends the banner in the server response, before hydration, without holding the page.

## Test the workflow you will use each week

Choose c15t when native UI and source ownership are central to the product. Didomi is a strong option when a shared operational console is the main requirement.

Build a trial with [Inth and the framework guide](/docs/frameworks). Change one notice translation and one vendor rule, then check when a visitor with saved choices sees the result.

Compare the review, deployment and record workflow. Finish with the [consent verification checks](/docs/guides/verify-consent).

Sources checked on 6 October 2026. The release covered here is an alpha. Compare commercial terms for the same properties, traffic and support needs.

# c15t vs Enzuzo
URL: https://c15t.com/docs/comparisons/enzuzo
Choose c15t for native consent components, custom product interfaces and backend ownership. Compare Enzuzo's hosted scans, legal policies and privacy operations.

## Choose c15t when consent belongs inside your product

c15t is the stronger fit when your developers need direct control of consent behaviour, interface and records. You can review consent changes beside the application features that use them.

Enzuzo is a strong option for teams that want banners, scans, legal policy tools and data-request operations in one hosted service. It also offers APIs and custom script controls.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Enzuzo|
|--|--|--|
|Integrate with application code|Native framework components and reactive state|Hosted script, platform integrations and API access|
|Build your own interface|Themes, component parts and headless APIs|Banner editor and plan-dependent custom CSS. Enterprise lists a headless mode|
|Choose the record backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed consent logs. Reviewed sources do not establish a deployable equivalent backend|
|Control vendor code|Declared category and vendor rules for scripts, requests and embeds|Automatic script controls and attributes for custom scripts|
|Find cookies automatically|**Not included in the c15t packages**|Website scans and cookie classification|
|Generate legal policies|**Not included**|Policy and terms generators|
|Manage data requests|**No bundled case management suite**|DSAR tools with plan-dependent limits|
|Run banner experiments|Presentation and theme experiments with fixed policy and policy text|Enzuzo lists A/B tests on its Enterprise tier|

Sources: [Enzuzo consent platform](https://www.enzuzo.com/consent-management-software), [plans and features](https://www.enzuzo.com/pricing), [privacy policy generator](https://www.enzuzo.com/privacy-policy-generator) and [data-request product](https://www.enzuzo.com/dsar-software).

## Build consent controls where people need them

With c15t, privacy settings can live inside an account screen, video placeholder or product feature. Each part can read the same consent state.

Use the supplied [framework components](/docs/frameworks), adapt their parts, or build the interface with [headless APIs](/docs/frameworks/react/headless). Your application owns the markup and interaction.

Enzuzo offers customisation and APIs too. Its Enterprise tier lists a headless mode. c15t's advantage is the native component workflow and source code that your team can change.

Your developers can also run [banner experiments](/docs/guides/banner-experiments) as part of the product. These experiments change presentation or theme while the policy and policy text stay fixed.

## Keep vendor choices and records under your control

Declare vendors alongside their integrations. [Vendor consent](/docs/frameworks/react/vendor-consent) lets a visitor accept a category but refuse one named service within it.

Use Inth to manage the backend, or run the c15t service with your own database. Your team can inspect the code that applies rules and sends records.

Enzuzo's managed service combines consent logs with operational tools. Its product page also documents script attributes for cases that need developer control.

Compare the full cost of the services you need. Enzuzo's pages show different traffic and domain allowances. Confirm the selected plan's current limits before you buy.

## What c15t does not include

c15t does not include Enzuzo's website scanner, legal policy generators or data-request dashboard. Use separate tools or processes for those tasks.

c15t does not automatically inventory trackers already on the site. Your team must register the relevant scripts, requests and embeds.

Some integrations load before consent and receive denied signals. Check their actual behaviour under your selected policy. Withdrawal normally reloads the page.

A browser choice is not proof of a completed save.

The software has no licence fee, but implementation and backend operations have costs. The release covered here is currently an alpha.

## Try the difference in your application

1. Start with [Inth and your framework guide](/docs/frameworks).
2. Build privacy settings inside an account screen.
3. Register one vendor and one embed.
4. Refuse, accept and withdraw consent. Inspect requests and the saved record.
5. Compare the application work and any separate scan, policy or data-request services required.

Follow the [verification guide](/docs/guides/verify-consent). Choose c15t when control of the application and backend drives your decision.

Sources checked on 6 October 2026. Enzuzo features depend on the plan. This comparison does not assume that source availability makes c15t faster, cheaper or automatically compliant.

# c15t vs Ethyca
URL: https://c15t.com/docs/comparisons/ethyca
Choose c15t for native web consent components and a deployable backend. Compare Ethyca's Fides code and Janus platform without confusing their scope.

## Choose c15t for consent that fits your web product

c15t is the stronger fit when your team needs consent components, vendor choices and backend records inside a web product. You can build the interface in your framework and review its behaviour with the application.

Ethyca addresses a wider set of privacy and data governance tasks. Its current Janus product offers consent APIs across web, mobile and backend systems.

Ethyca also publishes Fides source code. This comparison distinguishes that code from current commercial products and services.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Ethyca|
|--|--|--|
|Build consent into a web product|Native components across the supported web frameworks|Janus offers headless APIs and SDKs|
|Build a custom interface|Themes, component parts and headless APIs|Custom applications through Janus APIs. Fides includes a Privacy Center|
|Inspect source code|Apache-2.0 client and backend source|Fides source is Apache-2.0. Check commercial product scope separately|
|Operate the backend yourself|Supplied c15t service with your own database|Fides documents local deployment. Ethyca archived its public repository|
|Control application vendors|Category and vendor rules for registered scripts, requests and embeds|Janus describes consent enforcement across connected systems|
|Carry choices across devices and systems|Application and backend integration required|Janus describes persistent consent state across devices and downstream services|
|Fulfil data-subject requests|**No bundled case management or fulfilment suite**|Fides includes request workflows. Ethyca also offers automated DSR products|
|Discover data and assess risks|**Not included in the c15t packages**|Broader Ethyca governance products|

Sources: [Janus consent product](https://www.ethyca.com/janus), [Fides repository](https://github.com/ethyca/fides), [Ethyca open source](https://www.ethyca.com/open-source) and [Ethyca platform](https://www.ethyca.com/).

## Give your product team one consent workflow

c15t connects the banner, privacy settings and vendor integrations through application state. Your team can change them in the same release.

Use [native framework components](/docs/frameworks) or build the interface through [headless APIs](/docs/frameworks/react/headless). The guides cover React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, TanStack Start and plain websites.

The [vendor controls](/docs/frameworks/react/vendor-consent) let a visitor refuse one named vendor within an accepted category. Registered scripts, requests and embeds can respect that choice.

For Next.js, choose the [consent response path](/docs/frameworks/next/rendering). The App Router's default streamed path shows the page first and does not include the banner in initial HTML.

Ethyca also supports headless consent. Choose c15t for its documented web component workflow and the backend that accompanies it.

## Compare the actual deployment options

Both c15t and Fides publish source code. Open source alone is not a reason to claim that only c15t offers control.

Ethyca archived the public Fides repository on 28 August 2026. Its README still describes local deployment and privacy request workflows.

That status does not establish the support terms or release process for commercial Janus. Confirm those separately before you choose a Fides deployment.

The release covered here is currently an alpha. Evaluate its [upgrade path](/changelog/3.0.0#upgrading), required integrations and operational work before production use.

## What c15t does not include

c15t does not replace Ethyca's wider governance products. The packages do not include enterprise data discovery, risk assessments or automated data-subject request fulfilment.

c15t also does not supply an equivalent native mobile SDK suite or automatic consent propagation across an enterprise's complete data estate.

Your team must configure the application integrations. A banner does not automatically stop every tracker already on the site, and withdrawal cannot erase data already sent elsewhere.

The software has no licence fee. Hosting, maintenance and implementation still cost money.

## Try the difference in your application

1. Start with [Inth and your framework guide](/docs/frameworks).
2. Add a consent control to a product screen.
3. Register a vendor and test a refusal inside an accepted category.
4. Inspect the requests, interface and backend record.
5. List any wider governance workflows that still need a separate system.

Follow the [verification guide](/docs/guides/verify-consent). Choose c15t when the web consent workflow is the main requirement.

Sources checked on 6 October 2026. We did not benchmark either product or check commercial deployment terms. Archived Fides source is not evidence of every current Janus capability.

# c15t vs iubenda
URL: https://c15t.com/docs/comparisons/iubenda
Compare c15t and iubenda to choose how much control you need over consent, your application, and your records.

## Keep control of consent in your product

c15t is the stronger fit when your product team wants to own the consent interface, vendor rules and record backend. Your developers can change its open-source code. They can build consent into the application they already build.

Choose iubenda if you want consent tools, website scans, and legal documents in one managed package. Its [plans](https://www.iubenda.com/en/pricing/) combine these products with different features and usage limits.

This page covers the current alpha release. Check the [upgrade guide](/changelog/3.0.0#upgrading) before you change a current installation.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Choose the control your team needs

IAB TCF means the IAB Transparency and Consent Framework. It defines rules for consent to vendors and purposes.

|What you need|c15t|iubenda|
|--|--|--|
|Use your application framework|Native adapters for web frameworks|A hosted script and integrations for site platforms|
|Read consent in your code|Reactive state through framework hooks|Browser functions and callbacks|
|Send the banner from your server|Supported when your server waits for consent resolution|The web guide uses a hosted banner script|
|Match your product design|Themes, components, or your own interface|Custom styles and banner content|
|Set when vendors run|Category and vendor rules for scripts and embeds|Automatic blocking, manual tags, and tag-manager integrations|
|Give visitors vendor choices|Vendor switches outside IAB TCF, plus IAB controls|Purpose categories and IAB vendor controls|
|Choose where records stay|Inth hosts the backend and stores records in its database. Self-hosting is optional|A managed consent service|
|Keep evidence of consent|Records in the selected backend|Consent logs in all current plans|
|Manage legal documents|Your documents, with helpers for versions and signed snapshots|Generated policies and other legal tools|
|Discover cookies automatically|**Not included in the c15t packages**|Website scans|
|Get help from an assistant|Docs and skills in installed packages|A Claude and ChatGPT connector|

iubenda sources: [integration guide](https://www.iubenda.com/en/help/1205-how-to-configure-your-cookie-solution-advanced-guide-2/), [automatic blocking](https://www.iubenda.com/en/help/133036-prior-blocking-of-cookies-automatic-blocking-auto-blocking-2/), [consent logs](https://www.iubenda.com/en/help/45718-cookie-preference-log/), and [assistant connector](https://www.iubenda.com/en/help/222393-how-to-connect-iubenda-to-claude-and-chatgpt/).

## Make the consent interface match your product

Build the consent interface you want while c15t handles consent state. Start with the c15t banner and preference centre. Change the theme, replace component parts, or build the interface yourself.

c15t supports React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, and TanStack Start. A script-tag package serves sites without these frameworks.

Your video placeholders, vendor scripts, and privacy controls can use the same consent state. Framework hooks let application code read changes to that state.

Your team can review those changes with the rest of the product code. See the guides for [custom styles](/docs/frameworks/react/customize) and [your own interface](/docs/frameworks/react/headless).

iubenda also has custom styles and browser functions. c15t adds native framework components that your developers can compose into the application.

## Choose what the page waits for

You can choose whether the page waits for consent resolution. In Next.js, c15t supports these paths:

* **Show the page first.** Stream the consent state after the page starts. The banner appears after the browser applies that state.
* **Send the banner from the server.** Wait for consent resolution before the server sends the banner. This adds a wait to that response.
* **Keep static pages.** Resolve consent in the browser. Do not put one visitor's consent state in a page that other visitors share.

Scripts configured to wait for consent stay blocked while consent resolves. The consent rules then decide which scripts can run.

Your server can reuse a consent manifest, a public document with consent rules. This avoids a separate policy lookup at the backend for each application request when the cache is warm. Cache refreshes and consent saves still need the backend.

See [page behaviour by deployment](/docs/frameworks/next/rendering) and [how c15t gets consent rules](/docs/concepts/data-fetching).

iubenda documents [ways to optimise script delivery](https://www.iubenda.com/en/help/3834-cache-and-optimisation-of-the-iubenda-cookie-solution/). It also offers [server-side tracking](https://www.iubenda.com/en/server-side-tracking/), which processes measurement events.

Those features serve different tasks from consent resolution in your application. We did not benchmark the two products, so this page makes no claim that c15t is faster.

## Decide which vendor code can run

You can review each vendor's consent rules with the feature that adds it. Declare the vendor through [c15t integrations](/docs/integrations/overview). Set its consent category and vendor identifier in code.

A visitor can accept a category but reject one vendor in that category. For example, the visitor can accept analytics but reject a named analytics service.

These vendor switches work outside IAB TCF. IAB TCF uses separate controls for vendors and purposes. See [vendor consent](/docs/frameworks/react/vendor-consent).

Some integrations intentionally load before consent. Google Consent Mode integrations, for example, receive denied signals instead of a complete block. Check each integration before you assume that it sends no requests.

iubenda can block scripts from site-scan results, policy categories, known trackers, and custom domain rules. This can reduce manual work on a site.

c15t gives your developers explicit rules to review and test. The banner alone does not take control of every tag already on the site.

## Set what happens after consent withdrawal

You can define which browser data c15t removes after a visitor revokes a category. Its optional [clear-on-revocation rules](/docs/frameworks/react/clear-on-revocation) remove declared cookies and browser-storage keys.

c15t normally reloads the page after withdrawal to stop vendor code that already ran. A vendor-only refusal does not trigger category cleanup. Browser code cannot delete another origin's cookies or `HttpOnly` cookies.

Check these limits against the vendors on your site. Do not treat a consent change as proof that all vendor data is gone.

## Choose who runs the backend

You can use Inth now and keep the option to run the c15t backend yourself. Both paths use the [same backend protocol](/docs/self-host/overview).

The [Apache-2.0 licence](https://github.com/c15t/c15t/blob/v3/LICENSE.md) lets your team read, change, and run the source code. Your team can trace how the application saves a visitor's choice.

If you run the backend, you own its database, backups, updates, and availability. Inth is the recommended path if you do not want that operational work.

iubenda also keeps consent records. Its [Cookie and Consent Preference Log](https://www.iubenda.com/en/help/45718-cookie-preference-log/) comes with every current plan, even the free plan.

c15t gives you the additional choice to run the record system yourself. That choice matters when your organisation needs its own servers or database.

## Keep evidence of the document you show

You can tie your consent flow to a specific legal-document version. The c15t backend can store that document's version and content hash.

A content hash is a value that identifies document content. The [snapshot helpers](/docs/self-host/guides/legal-document-snapshot-integration) let your server sign and check that document identity in an acceptance flow.

Your developers must connect those helpers to the flow. A signed snapshot does not prove that a visitor accepted the document. c15t does not write the legal text.

iubenda generates privacy and cookie policies. It is a broader fit if you need document generation as part of the same package.

## Compare layouts before a wider release

You can compare consent layouts without a different policy for each group. c15t [banner experiments](/docs/guides/banner-experiments) change the presentation and theme. The policy, categories, and policy text stay the same.

Use your feature-flag tool to assign each visitor a variant, or let c15t assign variants by weight. Impressions and choices carry the variant identifier. Backend summaries show choices and time to decision for each variant.

Presentation checks flag some design choices for review. They do not certify that an experiment meets legal requirements.

iubenda's [Ultimate plan](https://www.iubenda.com/en/pricing/) includes detailed consent analytics. Check the experiment workflow that you need in a product trial.

## Pay for the scope you need

You can choose c15t without a software licence fee. Budget separately for Inth or the servers and work to run your own backend.

iubenda bundles consent administration with legal documents and website scans. Its plans differ by pageviews, scan frequency, languages, and other features. Check its [current prices](https://www.iubenda.com/en/pricing/) for extra pageviews and form-consent services.

Both products support Google Consent Mode, IAB workflows and [Global Privacy Control](https://www.iubenda.com/en/help/162529-global-privacy-control/), a browser signal for privacy preferences.

Choose c15t when you want native framework code, your own interface, and control over the backend. Choose iubenda when its broader managed package matches your needs.

## What c15t does not include

* **Generated privacy and cookie policies.** Supply your legal text. Document snapshot helpers do not write it.
* **Automatic website scans.** Keep a separate process to discover and classify the services on your site.
* **The whole iubenda legal suite.** Form-consent products and wider legal administration need their own scope review.
* **A free managed backend.** Budget for Inth or the database and service that your team operates.
* **Automatic migration of previous choices.** Map purposes, vendor identifiers and policy versions before you reuse records.

These limits refer to the c15t packages. Evaluate any additional Inth services separately.

## Check the fit before you switch

A small trial lets your team check the work before a wider move. Use a test deployment for the trial. Keep one owner for consent so two systems do not compete.

1. Start with [Inth and the framework setup guide](/docs/frameworks).
2. List the tags that iubenda currently controls.
3. Move one analytics vendor and one embed into c15t.
4. Remove their old loaders.
5. Check a fresh visit, rejection, acceptance, reload, and withdrawal.
6. Check the network requests, consent interface, and saved records.

Do not assume that an iubenda cookie maps directly to a c15t record. Map the purposes, policy version, and saved choices before any transfer.

You can keep iubenda-generated documents with c15t as the consent runtime. Follow the [consent checks](/docs/guides/verify-consent) before the public release.

We reviewed the sources on 6 October 2026. The c15t claims refer to the alpha release reviewed here. The iubenda claims refer to the linked public docs.

If those docs do not list a feature, that does not prove that iubenda lacks it.

# c15t vs Ketch
URL: https://c15t.com/docs/comparisons/ketch
Choose c15t to own consent components, vendor rules and the backend. Compare Ketch's connected privacy platform and the services c15t does not supply.

## Choose c15t when your product team owns consent

c15t is the stronger fit when your main task is consent inside a web application. Your team can change the components, review vendor rules and release the consent code with the product.

Ketch serves a broader need: consent across identities and connected systems, with privacy operations in the same platform. It also offers APIs, SDKs and custom interfaces.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Ketch|
|--|--|--|
|Integrate with web application code|Native framework components and reactive consent state|Web APIs and SDKs. Ketch also advertises React support|
|Build your own interface|Themes, component parts and headless APIs|Visual editor, SDKs and custom integration APIs|
|Choose the backend|Inth, or the Apache-2.0 backend on your own infrastructure|Managed platform. Reviewed public sources do not establish a deployable equivalent backend|
|Review vendor behaviour|Explicit rules for registered scripts, requests and embeds|Tag controls and connectors to other systems|
|Keep consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed records tied to the visitor and connected systems|
|Find trackers automatically|**Not included in the c15t packages**|Tracker scans and related analysis|
|Manage data-subject requests and assessments|**Not included as a privacy operations suite**|Broader platform products|
|Support native mobile apps|**No equivalent native mobile SDKs in this comparison**|iOS and Android SDKs|

Sources: [Ketch consent platform](https://www.ketch.com/platform/consent-management), [product documentation](https://docs.ketch.com/), [plans](https://www.ketch.com/pricing) and [Android SDK](https://github.com/ketch-com/ketch-android).

## Keep consent changes in the product review

With c15t, your banner, account settings and embedded content can use the same consent state. Your developers can review those changes beside the features that use them.

The [framework guides](/docs/frameworks) cover React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, TanStack Start and plain websites. Use [headless APIs](/docs/frameworks/react/headless) when the supplied interface does not fit.

Declare each integration and its consent rules in application code. [Individual vendor choices](/docs/frameworks/react/vendor-consent) let a visitor refuse one vendor within an accepted category.

Ketch also connects consent to application code. c15t's advantage for this task is the combined framework interface, inspectable engine and deployable backend.

## Control the software and its release

Your team can pin c15t package versions, test a change and release it with the application. You can inspect and change the Apache-2.0 source.

The backend gives you a choice between a managed service and your own deployment. Self-hosting also makes your team responsible for updates, storage and availability.

Ketch publishes open-source SDKs. An open SDK does not, by itself, give you the whole service to deploy. Confirm the deployment and API terms for your Ketch plan.

Ketch's identity and system connectors can help when choices must travel across a wider data estate. c15t does not supply that entire platform.

## What c15t does not include

c15t does not bundle Ketch's tracker scans, data mapping, assessment workflows or data-subject request operations. It does not supply Ketch's native mobile SDK coverage.

The c15t packages also do not include an equivalent system that resolves identities across devices and forwards every privacy choice to enterprise tools.

Your team must register scripts, request rules and embeds. c15t cannot automatically control every vendor already on the site.

A choice in the browser is not proof of a successful backend save.

Withdrawal normally reloads the page. The software has no licence fee, but implementation and backend operations still have costs. The release covered here is currently an alpha.

## Try the difference in your application

1. Start with [Inth and a framework guide](/docs/frameworks).
2. Build a consent control inside a product screen.
3. Register one analytics vendor and one embed.
4. Refuse, accept and withdraw consent. Inspect requests and the saved record.
5. Compare the application work with the separate privacy operations that your business needs.

Follow the [verification guide](/docs/guides/verify-consent). Choose c15t when ownership of this application workflow is the priority.

Sources checked on 6 October 2026. Some detailed Ketch documentation needs sign-in.

This comparison uses public product pages and SDK sources. Unavailable details do not establish that a feature is absent.

# c15t vs Klaro
URL: https://c15t.com/docs/comparisons/klaro
Choose c15t for native framework state and a backend you can run. Compare Klaro's open-source service controls, hosted records and scanning.

## Choose c15t for consent built into framework code

c15t is the stronger fit when your product needs native components and an integrated path from consent state to backend records. Your developers can own both the interface and the engine.

Klaro also has an open-source client and a hosted service. Its hosted plans include records and scans, so neither open source nor managed consent is exclusive to c15t.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the integration model

|What you need|c15t|Klaro|
|--|--|--|
|Integrate with application UI|Native framework components and reactive state|JavaScript consent manager with an API and state watchers|
|Control individual services|Category and vendor rules for declared targets|Service configuration and annotated resources|
|Change the interface|Themes, component parts and headless APIs|Open-source client and configurable styles|
|Choose the Next.js response|Server resolution, streamed state or browser resolution|Browser integration in the reviewed setup guide|
|Keep remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Hosted plans include managed records|
|Run the frontend yourself|Apache-2.0 packages|Open-source client that you can host|
|Run the record backend yourself|Deployable open-source backend|Reviewed commercial pages describe a hosted record service|
|Discover site services|**No scanner in the c15t packages**|Hosted plans include URL scans|

Sources: [Klaro setup](https://klaro.org/docs/getting-started), [JavaScript API](https://klaro.org/docs/api/js_api), [configuration](https://klaro.org/docs/integration/annotated-configuration) and [hosted plans](https://www.klaro.org/pricing).

## Keep application features on the same consent state

c15t lets a privacy control, vendor script and video placeholder use the same state. Your team can change them with the rest of the application.

Use [native components or headless APIs](/docs/frameworks/react/headless) to match your design. Register vendors through [integration helpers](/docs/integrations/overview) or a custom integration.

Klaro's JavaScript API also exposes consent state and change notifications. c15t adds dedicated framework adapters and a backend implementation in the same project.

## Keep service choices precise

Both products can represent individual services. A migration must preserve those choices. Do not convert one service permission into consent for a whole category.

With c15t, a visitor can accept a category but refuse one vendor. Its [vendor rules](/docs/frameworks/react/vendor-consent) apply to the scripts, requests and embeds that you declare.

A vendor-only refusal does not trigger category cookie cleanup. Configure any additional cleanup your vendors need.

## What c15t does not include

* **Klaro's hosted website scans.** The c15t packages do not discover every service already on a site.
* **A drop-in Klaro configuration importer.** Map the services, categories and previous choices explicitly.
* **A managed backend at no cost.** Compare Inth terms with Klaro's hosted scope, or budget for your own operations.
* **Automatic control of unregistered scripts.** Remove old loaders and connect their replacements to consent state.

A manually configured Klaro client remains a reasonable choice for a site that needs browser service controls only.

## Try a feature added after navigation

Choose c15t when framework integration and backend ownership matter most. Start with [Inth and the framework guide](/docs/frameworks).

Test one script in the initial page and another added after navigation. Check rejection, acceptance and withdrawal for both.

Use the [verification guide](/docs/guides/verify-consent) to check requests and records. Compare hosted services separately from the free client libraries.

Sources checked on 6 October 2026. The release covered here is an alpha. A capability absent from the reviewed Klaro guides is not proof that no commercial option exists.

# c15t vs OneTrust
URL: https://c15t.com/docs/comparisons/onetrust
Choose c15t to own the consent engine, framework components and backend. Compare OneTrust's headless API, cookie scans and broader privacy operations.

## Choose c15t to own the engine as well as the interface

c15t is the stronger fit when your product team wants consent in its codebase and control over the backend. Its open-source engine, native components and vendor integrations work together.

OneTrust offers extensive consent operations and a server-side API for custom interfaces. The reason to choose c15t is control of the implementation, not exclusive access to headless consent.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the features that matter

|What you need|c15t|OneTrust|
|--|--|--|
|Build application consent UI|Native components, themes and headless APIs|Web CMP UI and a headless Server-Side CMP API|
|Resolve consent on the server|Framework helpers and cached public policy|Server-Side CMP API|
|Read or change consent in code|Reactive framework state and actions|JavaScript methods and consent-change callbacks|
|Control vendor execution|Declared integrations, request rules and embeds|Automatic blocking, tag-manager integrations and script controls|
|Own the backend implementation|Apache-2.0 backend that you can deploy|OneTrust platform and APIs|
|Store consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Consent transaction database|
|Scan authenticated or hidden pages|**Not included in the c15t packages**|Documented website scans|
|Compare banner layouts|Presentation experiments with your feature flags|A/B tests and template targeting|
|Run a wider privacy programme|**No complete privacy operations suite in c15t**|Separate OneTrust products extend the consent scope|

Sources: [Cookie Consent](https://www.onetrust.com/products/cookie-consent/), [JavaScript methods](https://developer.onetrust.com/onetrust/docs/javascript-api) and [Server-Side CMP API](https://developer.onetrust.com/onetrust/docs/server-side-cmp-api-introduction).

## Keep the implementation under your team's control

Your developers can read, change and version c15t's [Apache-2.0 source](https://github.com/c15t/c15t/blob/v3/LICENSE.md). The consent interface can use the same components and release process as the product.

A privacy settings screen can read the same state that controls a video embed or analytics integration. Use [headless APIs](/docs/frameworks/react/headless) when the stock interface does not fit.

OneTrust's headless API also lets teams build their own UI. c15t adds an engine and backend implementation that your team can run and change.

## Choose how consent affects the page

With c15t, a server can cache a public consent manifest, the document that contains the policy rules. A warm cache lets it resolve visitor inputs without a separate policy lookup for each page request.

Backend refreshes and consent saves still need a connection. See [data fetching](/docs/concepts/data-fetching).

In the Next.js App Router, the default streamed path lets the page appear first and sends the banner in a later chunk, before hydration. Await consent when the page and the banner must arrive together. That choice adds a wait.

These [rendering options](/docs/frameworks/next/rendering) let your team choose the tradeoff. Neither an API nor server rendering proves a speed advantage without a comparable test.

## What c15t does not include

* **OneTrust's website inventory service.** c15t does not crawl authenticated routes or automatically discover every tracker.
* **A full privacy operations platform.** Data-subject request case management, data discovery and organisation-wide assessments are outside the c15t packages.
* **A replacement for every current consent workflow.** Check identity, record retention, administrative access and migration needs separately.
* **Backend operations at no cost.** Inth has service terms. Your own deployment needs a database, backups and maintenance.

c15t's [document snapshot helpers](/docs/self-host/guides/legal-document-snapshot-integration) let your server check a legal-document version. They do not generate legal text or prove acceptance without an implemented acceptance flow.

## Start with the part of consent your product owns

Choose c15t when the project needs application control and backend ownership. OneTrust can be the better overall fit when a wider privacy programme is the main requirement.

Build a trial with [Inth and the framework guide](/docs/frameworks). Use a signed-in route that adds a vendor after a user action.

Register that vendor, then check rejection, acceptance, withdrawal and the saved record. Use the [verification guide](/docs/guides/verify-consent), and cost any separate inventory service that you still need.

Sources checked on 6 October 2026. The release covered here is an alpha. This page makes no claim of certification parity or a lower total price.

# c15t vs Osano
URL: https://c15t.com/docs/comparisons/osano
Choose c15t for native consent components and control of vendor code and records. Compare Osano's classification, managed operations and service guarantees.

## Choose c15t for control your developers can inspect

c15t is the stronger fit when your product team needs to understand and change how consent affects the application. Its components, vendor rules and backend are open source.

This page compares Osano's commercial consent platform. Its separate open-source Cookie Consent project has a [different licence scope](https://www.osano.com/cookieconsent/documentation/license/).

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the implementation and the service

|What you need|c15t|Osano commercial CMP|
|--|--|--|
|Integrate with application code|Native framework components and hooks|Hosted CMP with JavaScript functions and events|
|Match your interface|Themes, component parts or headless UI|Banner editor and custom CSS|
|Control vendor execution|Registered integrations and explicit consent rules|Cookie classification and configured tag blocking|
|Choose the Next.js response|Server, streamed or browser consent resolution|Hosted script integration|
|Keep consent records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed records with consent search|
|Change and run the engine|Apache-2.0 source and a deployable backend|Commercial platform|
|Classify site cookies automatically|**Not included in the c15t packages**|AI-assisted cookie classification|
|Get a contractual fines guarantee|**Not included with the open-source software**|Advertised guarantee with conditions|
|Budget for the service|No software licence fee. Backend costs remain|Contracted traffic based on delivery of Osano.js|

Sources: [Osano CMP](https://www.osano.com/solutions/consent-management-platform), [JavaScript API](https://docs.osano.com/en-US/osano/article/4iKPKFqX-developer-documentation-consent-javascript-api), [consent search](https://docs.osano.com/en-US/osano/article/rtirm0V6-cookie-consent-consent-search) and [traffic definition](https://docs.osano.com/en-US/osano/article/7Xe6qqNl-how-does-osano-price-for-consent-management).

## Review consent with the feature that needs it

With c15t, your team declares a vendor beside the application feature that introduces it. The [integration](/docs/integrations/overview) connects that vendor to consent state.

The same state can drive a privacy settings screen or a blocked video placeholder. Use [headless APIs](/docs/frameworks/react/headless) when your design needs different markup.

Osano also has a JavaScript API. c15t gives you native framework state and the implementation behind that state, so your team can trace behaviour through its own code.

## Keep the backend choice open

With Inth, you do not need to run a database. If your requirements change, the c15t backend is available for your team to deploy and change.

That choice is useful when your organisation needs its own infrastructure or record access. It also makes your team responsible for availability, migrations and backups.

Osano has consent records and a search workflow. c15t's distinction is control of the record system, not the existence of consent evidence.

## What c15t does not include

* **Automatic cookie discovery or AI classification.** Keep the vendor inventory and configure the relevant integrations.
* **Osano's wider privacy operations.** Subject-rights case management and enterprise data discovery are outside the c15t packages.
* **A promise to pay regulatory fines.** The open-source licence does not include that commercial guarantee.
* **Automatic control of every current tag.** A banner alone cannot stop code loaded elsewhere.

Some c15t integrations use denied consent signals while the vendor code still loads. Check the integration's behaviour before you expect zero requests.

## Prove control on the tags you run

Choose c15t when application control and backend ownership are the priorities. Osano can fit better when you need managed privacy operations and contractual services.

Start with [Inth and your framework guide](/docs/frameworks). Test a direct vendor and a vendor inside your tag manager.

Remove duplicate loaders, then check rejection, acceptance, reload, withdrawal and the saved record. Follow the [verification guide](/docs/guides/verify-consent).

Sources checked on 6 October 2026. The release covered here is an alpha. Compare service quotes based on each provider's traffic definition.

# c15t vs react-cookie-consent
URL: https://c15t.com/docs/comparisons/react-cookie-consent
Choose c15t when a React application needs consent rules, vendor controls and backend records beyond an accept-and-decline banner.

## Choose c15t when consent controls product behaviour

c15t is the stronger fit when consent determines which vendors and features can run. It combines the banner, preferences, policy state and vendor integrations with a record backend.

react-cookie-consent gives you a customisable React bar, cookie helpers and callbacks. It is a useful small component when your application already owns the rest of the consent system.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what your team must build

|What you need|c15t|react-cookie-consent|
|--|--|--|
|Show a consent banner|Policy-aware framework components|Configurable React bar|
|Offer category and vendor preferences|Built-in controls|Build the rest of the preference flow|
|Decide whether a feature can run|Effective permissions and vendor state|Connect callbacks and the cookie value to your own rules|
|Control vendor scripts|Registered integrations and consent rules|Build the loader behaviour around callbacks|
|Keep remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Build a backend integration|
|Handle policy changes|Policy resolution and recorded choices|Supply your own policy logic|
|Reopen preferences|Preference dialog and persistent access|Visibility and cookie-reset helpers|
|Customise presentation|Themes, component parts or headless UI|Styles, classes, content and button props|

Sources: [README](https://github.com/Mastermindzh/react-cookie-consent) and [npm package](https://www.npmjs.com/package/react-cookie-consent).

Custom application code can extend the component. Those extensions are work that the component itself does not supply.

## Connect the choice to the vendor

With c15t, your team can read whether a feature can run from the same state that drives the consent interface. Register analytics or embeds through [c15t integrations](/docs/integrations/overview).

This gives the application a shared model for first visits, saved choices and later withdrawal. You still need to remove unconditional loaders.

A callback that starts analytics after acceptance also needs to handle rejection, reload and withdrawal. c15t supplies those integration points as part of its consent runtime.

## Keep permission separate from a recorded choice

c15t distinguishes the permissions allowed by a policy from what the visitor explicitly chose. Your application can read both without a false record of consent.

That distinction matters for regional policies, stored choices and privacy signals. See the [consent model](/docs/concepts/how-consent-works).

The backend can store confirmed choices. Browser state changes first, so check the actual record after a save. A failed request is not a completed record.

## What c15t does not include

* **Setup as small as a standalone bar.** Production policy and records need an Inth connection or your own backend.
* **Automatic control of current analytics code.** Move it from old callbacks into registered integrations or explicit rules.
* **A safe automatic conversion of a boolean cookie.** Review what visitors previously accepted before you create category or vendor grants.
* **Legal-policy generation or a website scanner.** These are outside the c15t packages.

If you only need a bar and already have the other consent infrastructure, react-cookie-consent can be enough.

## Replace one acceptance callback first

Choose c15t when you want the consent infrastructure as well as the React interface. Follow the [React quickstart](/docs/frameworks/react/quickstart) with [Inth](https://inth.com).

For a Next.js application, use its [router guide](/docs/frameworks/next/quickstart). Find the old `onAccept` loader, register its c15t replacement and remove the duplicate.

Test a fresh visit and a visitor who previously rejected consent. Finish with the [verification guide](/docs/guides/verify-consent).

Sources checked on 6 October 2026. The release covered here is an alpha. The comparison covers the published component, not every system that someone could build around it.

# c15t vs Silktide Consent Manager
URL: https://c15t.com/docs/comparisons/silktide-consent-manager
Choose c15t for native application state, regional policy and backend records. Compare Silktide's free browser manager and the setup c15t adds.

## Choose c15t when consent needs to reach the application

c15t is the stronger fit when your product needs consent state across components, vendor rules and backend records. It gives your team a common model for the interface and the code behind it.

Silktide Consent Manager is a free, open-source browser manager. It supports preference controls, consent-based script injection and Google Consent Mode. It is more than a decorative banner.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the scope beyond the banner

|What you need|c15t|Silktide Consent Manager|
|--|--|--|
|Use consent in application components|Native framework adapters and reactive state|Browser configuration and callbacks|
|Choose policy by visitor context|Backend policy resolution and regional rules|Configure consent types and defaults in the browser setup|
|Show preference controls|Category and vendor choices|Configurable consent types and preference modal|
|Control vendor scripts|Integration helpers, request rules and embeds|Script injection per consent type and callbacks|
|Use Google Consent Mode|Google tag and GTM integrations|Consent Mode updates and GTM events|
|Handle withdrawal|Reload by default. Optional declared data cleanup|Reload after the visitor revokes consent for injected scripts|
|Keep remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|No managed record service documented with the browser library|
|Customise the interface|Themes, component parts and headless APIs|Configurable text, appearance and source code|
|Budget for use|No licence fee. Production backend costs remain|Free browser tool without traffic or domain limits|

Sources: [Silktide product scope](https://silktide.com/consent-manager/) and [configuration and source](https://github.com/silktide/consent-manager).

## Give the product one consent model

With c15t, a settings screen can read the same state that controls a vendor or video embed. Your developers can test that behaviour with the rest of the application.

Use [framework components](/docs/frameworks) or a [headless interface](/docs/frameworks/react/headless). The backend supplies policy and receives consent records.

That gives you a defined route beyond local browser preferences. A visitor's local choice and a confirmed backend record remain separate events.

## Choose how the page receives consent

For Next.js, c15t supports [streamed, awaited and browser paths](/docs/frameworks/next/rendering). In the App Router, use the default streamed path to let the page appear before consent resolves.

The banner follows in a later chunk of the same response, before hydration. To send the page and the banner together, use an awaited path. That adds a wait, so measure the effect on your application.

Silktide's published setup runs in the browser. c15t's advantage here is its documented framework and server workflow, not a measured speed claim.

## What c15t does not include

* **A free managed record service.** Inth and self-hosted operations have costs beyond the software licence.
* **The same account-free production workflow.** The recommended c15t setup connects to a backend.
* **Automatic discovery of every site script.** Register the relevant vendors and remove their old loaders.
* **A zero-request guarantee from Consent Mode.** Some integrations run with denied signals before consent.

If local preferences and a free browser manager cover the requirement, Silktide remains a reasonable choice. c15t is the stronger choice when policy and records must be part of the application.

## Check signals and actual requests

Build a trial with [Inth and the framework guide](/docs/frameworks). Use the [Google tag](/docs/integrations/google-tag) or [GTM guide](/docs/integrations/google-tag-manager) for your setup.

Inspect the initial signals, acceptance, rejection and later withdrawal. Check the requests made by the tags inside the container too.

Use the [verification guide](/docs/guides/verify-consent) to compare browser behaviour with saved records.

Sources checked on 6 October 2026. The release covered here is an alpha. Silktide's wider paid website platform is outside this comparison.

# c15t vs Sourcepoint
URL: https://c15t.com/docs/comparisons/sourcepoint
Choose c15t for consent inside a web product that your team owns. Compare Sourcepoint by Didomi's publisher campaigns, vendor controls, records and TV support.

## Keep web consent in your product workflow

c15t is the stronger fit when your developers need native web components and control of the consent backend. You can build privacy choices into the product and review their behaviour in code.

Sourcepoint suits publishers and teams with consent campaigns across websites, apps and connected TVs. It has developer APIs as well as managed operations.

Sourcepoint is part of Didomi after the [announced acquisition](https://www.didomi.io/blog/didomi-sourcepoint). This guide covers Sourcepoint's product and docs. See the separate [Didomi comparison](/docs/comparisons/didomi) for that product.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Sourcepoint|
|--|--|--|
|Connect consent to a web product|Native framework components and reactive state|Web integration, SDKs and consent callbacks|
|Build the interface|Themes, component parts and headless APIs|Message builder, custom CSS and campaign flows|
|Control vendors|Declared category and vendor rules|Vendor lists, consent actions and third-party tag controls|
|Store consent history|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed history by vendor and legal basis|
|Discover vendor activity|**No automatic scanner in the packages**|Scans and separate compliance monitoring tools|
|Test consent designs|Presentation and theme experiments with fixed policy and policy text|Campaign reports and A/B tests|
|Cover connected TVs|**No bundled connected-TV SDK**|OTT and CTV support|
|Manage publisher campaigns|Build product flows in application code|Property groups and reusable campaign scenarios|

Sources: [Sourcepoint CMP](https://sourcepoint.com/cmp-2/), [third-party tag controls](https://docs.sourcepoint.com/hc/en-us/articles/42043114660755-Overview-Manage-3rd-party-tags-web) and [consent callbacks](https://docs.sourcepoint.com/hc/en-us/articles/4405397484307-Event-callbacks-CMP).

## Build the flow your application needs

c15t's [framework adapters](/docs/frameworks) let your team connect product screens to shared consent state. Use [headless APIs](/docs/frameworks/react/headless) for your own markup and [vendor controls](/docs/frameworks/react/vendor-consent) for individual services.

Sourcepoint also supports custom code and callbacks when consent becomes available or a visitor takes an action. Its developer tools deserve credit in the comparison.

c15t's advantage is the combination of native web components and source code for both the engine and backend. Your team can change and deploy those parts together.

## Match the choice to your publisher needs

Choose c15t when application control is the main requirement and your team owns the consent workflow. Its backend option keeps record storage under your control.

Sourcepoint can be the better fit when campaign operations, connected-TV support and vendor assessment are central requirements. Those needs go beyond an application consent engine.

For either product, check the actual vendor list, policy and deployment. Support for a consent framework does not prove that the site's configuration is correct.

## What c15t does not include

* The packages do not include automated vendor discovery or a publisher campaign console.
* They do not include a connected-TV SDK or a full privacy operations suite.
* Vendor rules cover configured targets. A visible banner does not stop every tag already on the site.
* Local state alone does not prove a successful write.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Budget for setup, backend operation and any separate publisher services.

## Test one web flow before a wider migration

Start with the [framework guide](/docs/frameworks). Register one vendor and one embed under the intended policy.

Test refusal, acceptance, reload and withdrawal with the [verification guide](/docs/guides/verify-consent). Check requests and saved records, then assess campaign and connected-TV requirements separately.

Sources checked on 6 October 2026. This comparison does not claim measured performance gains or publisher feature parity.

# c15t vs tarteaucitron.js
URL: https://c15t.com/docs/comparisons/tarteaucitron
Choose c15t for native framework state and a deployable record backend. Compare tarteaucitron.js service controls and its separate Pro service.

## Choose c15t to connect service choices to product code

c15t is the stronger fit when consent must drive your application's components, vendor behaviour and records. Your team can own the interface and the backend implementation.

tarteaucitron.js is an open-source manager with individual service controls and integration definitions. Its separate Pro service adds automatic detection, an online dashboard and consent statistics.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare the application workflow

|What you need|c15t|tarteaucitron.js|
|--|--|--|
|Use consent in framework components|Native adapters and reactive state|Browser service manager|
|Give visitors service choices|Category and individual vendor controls|Individual service preferences|
|Control configured vendors|Integration helpers, request rules and embeds|Service definitions and content placeholders|
|Change the interface|Themes, component parts and headless APIs|Configurable banner, service panel and open source|
|Choose the Next.js response|Server, streamed or browser resolution|Browser integration in the reviewed guide|
|Keep remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|No equivalent record backend established for the open-source library|
|Use Google Consent Mode|Documented Google tag and GTM integrations|Documented Consent Mode integrations|
|Discover services automatically|**Not included in the c15t packages**|Separate Pro service|
|Pay for software|No licence fee. Backend costs remain|Free library. Pro has a separate fee|

Sources: [open-source project](https://github.com/AmauriC/tarteaucitron.js) and [Pro service](https://tarteaucitron.io/en/).

## Keep the service rule with the feature

Your c15t consent state can control a video placeholder, analytics integration and privacy settings screen. The same product team can review each change.

Register vendors through [c15t integrations](/docs/integrations/overview). Use a [custom integration](/docs/integrations/building-integrations) when the vendor needs behaviour beyond a current helper.

tarteaucitron.js also controls individual services and supported embeds. c15t's advantage is the native framework workflow and the backend that your team can deploy.

## Use a backend built for consent records

c15t supplies endpoints for policy resolution and recorded choices. Use Inth to run them, or operate the database and backend yourself.

Your team can inspect how a choice moves from the interface to the record. Check backend confirmation separately from browser state.

The tarteaucitron.js guide documents browser service controls. Pro consent statistics do not, by themselves, establish an equivalent per-visitor record API. Confirm that scope if you need it.

## What c15t does not include

* **The Pro service's automatic detection workflow.** c15t needs explicit vendor integration.
* **A direct replacement for every service definition.** Check each vendor's options and add a custom loader where needed.
* **An automatic transfer of previous choices.** Map services to categories and preserve individual refusals.
* **Complete deletion of vendor data after withdrawal.** Declared cleanup follows category changes and browser permissions.

A vendor-only refusal does not trigger c15t's category cleanup. A browser cannot delete another origin's cookies or `HttpOnly` cookies.

## Move one service before the whole site

Choose c15t when native application integration and backend ownership are the priorities. A site focused on the current service catalogue or Pro automation can need less change with tarteaucitron.

Start with [Inth and the framework guide](/docs/frameworks). Pick one service, register its replacement and remove the old loader.

Test a refusal, later acceptance and withdrawal after the vendor ran. Use the [verification guide](/docs/guides/verify-consent) to check requests and saved records.

Sources checked on 6 October 2026. The release covered here is an alpha. The free library and Pro service are distinct products.

# c15t vs Termly
URL: https://c15t.com/docs/comparisons/termly
Choose c15t for native application consent and control of your backend. Compare Termly's policy generators, site scans, hosted records and consent APIs.

## Make consent part of the application you own

c15t is the stronger fit when your developers need consent inside product features and control over the record backend. You can change the interface and engine with the rest of your application.

Termly suits teams that want consent and legal-policy tools in one hosted product. Its scanner, banner settings and policy generators address work outside the c15t packages.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|Termly|
|--|--|--|
|Connect to application code|Native framework components and reactive state|Hosted script, browser events and consent APIs|
|Own the interface|Themes, component parts and headless APIs|Custom banner layouts, languages and display settings|
|Control vendor code|Declared category and vendor rules for scripts, requests and embeds|Auto Blocker with custom rules and manual controls|
|Read choices on the server|Backend APIs and framework server paths|Consent API for category and cookie choices|
|Store records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Termly's hosted consent records|
|Find cookies|**No automatic scanner in the packages**|Site scans and classification|
|Generate legal documents|**Not included**|Privacy, cookie policy and other document generators|
|Collect privacy requests|**No bundled case management suite**|Embeddable data-subject request form|

Sources: [Termly consent platform](https://termly.io/products/consent-management-platform/), [consent data flow](https://support.termly.io/hc/en-us/articles/50231234862865-How-Consent-Data-Flows-from-the-Website-Banner-to-Termly) and [Consent API](https://support.termly.io/hc/en-us/articles/30710543895697-Consent-API-documentation).

## Control the behaviour behind each choice

With c15t, consent can control an embed, an analytics integration or an application feature. Declare the relevant categories and vendors beside the code that uses them.

The [headless APIs](/docs/frameworks/react/headless) let your team build privacy controls into product screens. [Vendor consent](/docs/frameworks/react/vendor-consent) supports a choice about one service within a category.

Termly also exposes consent state and events. Its server API can retrieve a visitor's category and cookie choices. Developer access alone is not a reason to prefer c15t.

c15t adds a native component workflow and source code for both the engine and backend. That combination matters when your team needs to change how the system works.

## Separate consent code from legal-document work

c15t gives you control of the consent system. It does not generate your privacy policy or discover the cookies already on your site.

Termly can be the better fit when one team wants scans, generated policies and banner administration together. Check the selected plan and the site's custom integrations.

Choose c15t when application ownership is the main requirement and you have a separate process for site inventories and legal documents.

## What c15t does not include

* The packages do not include a cookie scanner, policy generator or privacy-request case management.
* Script and vendor rules need configuration. They do not automatically cover every tag already on the site.
* Backend helpers do not prove that a visitor accepted a legal document without an acceptance flow.
* Local state alone is not a saved remote record.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Include setup, backend operation and separate legal services in your cost comparison.

## Compare one complete consent flow

Follow the [framework guide](/docs/frameworks). Register one analytics vendor and one embed, then test refusal, acceptance, reload and withdrawal.

Use the [verification guide](/docs/guides/verify-consent) to check requests and record storage. Compare the application changes and continued operational work for both products.

Sources checked on 6 October 2026. This comparison does not claim measured performance gains or automatic legal compliance.

# c15t vs TrustArc
URL: https://c15t.com/docs/comparisons/trustarc
Choose c15t for consent that your product team can change and host. Compare TrustArc's React integration, tracker scans, managed records and privacy operations.

## Give your product team control of consent

c15t is the stronger fit when your developers need to own the consent interface, engine and backend. You can connect choices to product features and review changes with application code.

TrustArc suits organisations that need managed cookie operations within a broader privacy programme. It also supplies developer APIs and a React integration.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare what you get

|What you need|c15t|TrustArc|
|--|--|--|
|Connect a web application|Native framework components and reactive state|React components, hosted scripts and CMS integrations|
|Own interface markup|Themes, component parts and headless APIs|Custom banner settings and supplied integration components|
|Choose the backend|Inth hosts the backend and stores records in its database. Self-hosting is optional|Managed consent records and reports|
|Control vendor code|Declared rules for scripts, requests and embeds|Tracker controls, tag-manager integrations and automatic controls|
|Find trackers|**No automatic scanner in the packages**|Cookie and tracker discovery, also on protected pages|
|Manage privacy operations|**No bundled enterprise privacy suite**|Wider products for data mapping, assessments and individual rights|
|Use APIs for reports|Backend APIs. Build the reports you need|Consent reporting API and dashboards|

Sources: [TrustArc Cookie Consent Manager](https://trustarc.com/products/consent-consumer-rights/cookie-consent-manager/), [React integration](https://trustarchelp.zendesk.com/hc/en-us/articles/41699369644691-Cookie-Consent-Manager-React-Framework-Integration) and [reporting API guide](https://trustarchelp.zendesk.com/hc/en-us/sections/36065296349971-Cookie-Consent-Manager-Reporting-API-Guide).

## Own the behaviour behind the interface

TrustArc's React components mount its scripts and banner. Its guide also lists Next.js among the tested frameworks. A comparison that treats TrustArc as unable to work with React would be wrong.

c15t gives your team [native adapters across web frameworks](/docs/frameworks), an editable engine and a backend you can deploy. Use [headless APIs](/docs/frameworks/react/headless) to put privacy controls into product screens.

For example, an account setting and a video placeholder can read the same consent state. Your developers own the markup and the integration rules.

This control matters when a standard banner integration does not cover the product flow you want to build.

## Buy the operational scope you need

Choose c15t when consent is primarily an application requirement. Your team can use Inth for backend operation and retain the option to run the open-source service.

TrustArc can be the better fit when scans, central reports and broader privacy operations drive the decision. Those products cover work beyond the c15t packages.

Compare the actual services and support in each proposal. Open-source software removes the package licence fee. Setup and service costs remain.

## What c15t does not include

* The packages do not include automated tracker discovery or enterprise data mapping.
* They do not replace privacy assessments, legal-document services or individual-rights case management.
* Vendor controls need configuration. They do not automatically cover all tags already on the site.
* A choice in the browser is not proof of a successful remote save.

Some integrations load with denied signals. Withdrawal normally reloads the page, and optional cleanup cannot remove all vendor data.

The release covered here is an alpha. Check the required deployment and support scope before you replace a current service.

## Evaluate the product and operations separately

Start with the [framework guide](/docs/frameworks). Build one product consent control and connect one vendor and one embed.

Test refusal, acceptance, reload and withdrawal with the [verification guide](/docs/guides/verify-consent). Check actual requests and record storage, then compare the separate scan, report and support needs.

Sources checked on 6 October 2026. This comparison does not establish measured performance, legal compliance or support equivalence.

# c15t vs Usercentrics
URL: https://c15t.com/docs/comparisons/usercentrics
Choose c15t for native framework components and control of the consent engine. Compare Usercentrics Web CMP features, service scope and costs.

## Choose c15t for consent your developers can own

c15t is the stronger fit when your team wants native components, consent state in application code and an open-source backend. You can change the interface and the engine that drives it.

This page compares Usercentrics Web CMP. Its App CMP, CTV CMP and other services have separate scope. [Cookiebot has its own comparison](/docs/comparisons/cookiebot).

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

## Compare control and service scope

|What you need|c15t|Usercentrics Web CMP|
|--|--|--|
|Use application consent state|Native framework hooks and components|Browser UI APIs and events|
|Create a custom interface|Themes, component parts and headless APIs|Banner customisation. Headless Browser SDK for the earlier version, plus a headless SDK for the current version in beta|
|Choose the Next.js response|Server resolution, streamed state or browser resolution|Web script integration. Confirm the required SDK version|
|Own the consent engine|Apache-2.0 source and a deployable backend|Commercial managed service|
|Keep remote records|Inth hosts the backend and stores records in its database. Self-hosting is optional|Central consent log|
|Compare banner variants|Presentation experiments with your flags or built-in assignment|A/B tests, subject to plan or add-on|
|Discover site technologies|**No scanner in the c15t packages**|Automated website scans|
|Budget for use|No software licence fee. Backend costs remain|Session and domain allowances, with plan-dependent features|

Sources: [Usercentrics pricing and features](https://usercentrics.com/pricing/), [developer documentation](https://usercentrics.com/docs/), [earlier Browser SDK](https://usercentrics.com/docs/web/features/v2/browser_sdk/browser_sdk/) and [current-version headless SDK](https://www.npmjs.com/package/@usercentrics/cmp-web-sdk).

## Build consent into your own interface

c15t lets the consent banner, video placeholders and privacy controls use the same application state. Your team can change those components through its normal review and test process.

Start with the stock components, then use [custom styles](/docs/frameworks/react/customize) or a [headless interface](/docs/frameworks/react/headless). You control the markup and can build the interface that your product needs.

Usercentrics also supports custom UI. Its documented headless Browser SDK targets the earlier version, and a headless SDK for the current version is in beta. Confirm support for the edition you plan to use.

Choose c15t for the combination of native adapters and source ownership. Custom colours or API access alone do not distinguish the products.

## Keep experiments and deployment in your workflow

c15t [banner experiments](/docs/guides/banner-experiments) can use your current feature flags. Compare layouts and themes while the policy, categories and policy text stay fixed.

Usercentrics also offers A/B tests. With c15t, your developers can define the experiment with the application and choose the backend that receives the records.

In the Next.js App Router, [choose when the page waits for consent](/docs/frameworks/next/rendering). The default streamed path sends the banner in the server response, before hydration.

## What c15t does not include

* **Automated website scans or a generated library of legal clauses.** These are separate from the c15t consent packages.
* **Every Usercentrics administration workflow.** Do not assume that the open-source backend includes its bulk changes, approval process or enterprise account controls.
* **Automatic migration of current choices.** Map services, purposes and policy versions before you reuse records.
* **A free managed service.** Compare current Inth terms with the Usercentrics plan for your actual traffic.

The c15t backend supports identity links, but that alone does not establish parity with Usercentrics' cross-device workflow. Test the account and device flow that you need.

## Prove the fit on one property

Choose c15t when your application team wants control over the interface, runtime and backend. Usercentrics remains a strong fit for centrally managed website operations.

Start with [Inth and a framework guide](/docs/frameworks). Test one direct vendor and one tag-manager vendor, then check withdrawal and saved records.

Check each property's policy, language and origin configuration before a wider rollout. Use the [verification guide](/docs/guides/verify-consent) to confirm the actual requests.

Sources checked on 6 October 2026. The release covered here is an alpha. Prices and service inclusions depend on the selected plan.

# Contribute to c15t documentation
URL: https://c15t.com/docs/contributing
Edit the MDX source, validate both rendered and agent-readable outputs, and submit a focused change.

## Work from the source

Edit `docs/**/*.mdx` in the c15t repository. Leadtype uses this source for the
website and version-matched package Markdown. Do not edit generated package
`docs/`, `AGENTS.md` or `SKILL.md` files.

Read the repository's `AGENTS.md`, contributing guide and
`.agents/skills/writing-docs/SKILL.md` before editing. Check current exports and
tests for v3 behavior; the published site and `origin/main` may describe v2.

## Validate a documentation change

```bash
bun run lint:docs
bun run fmt:docs
bun run generate:package-docs
```

Inspect the diff because the remark commands currently rewrite files. Check
links and metadata with the installed leadtype linter. Read the generated
Markdown to confirm code, include content and explanations survive conversion.
Test runnable examples against the target adapter.

The website uses a separate private docs template. Contributors can edit the
public MDX source and use the pull request preview when available. A successful
Markdown build does not verify the host's components, canonical URLs or iframes.

## Keep changes useful

Prefer a working recipe with prerequisites, expected results and failure cases.
Use real component screenshots with their source configuration. Keep essential
instructions outside interactive previews so agents and offline readers receive
the same implementation guidance.

# Open source
URL: https://c15t.com/docs/oss/why-open-source
Which parts of c15t are open source, the Apache-2.0 license, where the code lives, and how the hosted Inth backend relates to the self-hostable c15t backend.

## What is open source

Every c15t package is open source. That covers the consent engine (`c15t`),
the framework adapters, the stock UI, the vendor helpers in
`@c15t/integrations`, the IAB TCF addon, the CLI and the consent backend,
`@c15t/backend`. The code and the source of these docs live in
[c15t/c15t on GitHub](https://github.com/c15t/c15t).

## Why consent code should be readable

A consent manager decides when analytics and ad scripts may run and what gets
recorded about a visitor. With the source public, you can check how c15t
stores a choice, which requests it sends before and after consent, and how it
maps categories to Google Consent Mode or IAB TCF purposes. You can also run
the same code in your own tests instead of trusting a vendor's description of
it.

## Hosted and self-hosted backends

The consent backend serves policies and stores consent records.
[Inth](https://inth.com) runs it for you, and the guides use it. You can also
run `@c15t/backend` on your own server with your own database; your app talks
to it the same way it talks to Inth, with a different URL. See the
[backend overview](/docs/self-host/overview) to decide.

## License

c15t is licensed under the Apache License, Version 2.0. You can use, modify and
distribute it, including in commercial products, as long as you keep the
license and notices. See [License](/docs/oss/license).

## Contribute

Read [Contribute to c15t](/docs/oss/contributing) before opening a pull
request, and the [code of conduct](/docs/oss/code-of-conduct).

# Contribute to c15t
URL: https://c15t.com/docs/oss/contributing
Open an issue, set up the c15t monorepo with Bun, branch from canary, run the checks and add a Tegami release note for package changes.

## Open an issue first

Search the [issues](https://github.com/c15t/c15t/issues) and
[pull requests](https://github.com/c15t/c15t/pulls) before you start, then open
an issue for your change.

New features, large refactors and architecture changes carry the
`needs-approval` label. Wait for a maintainer to remove it before you write
code. Bug fixes, documentation, performance improvements, security fixes and
tests can start right away.

## Set up the repository

The repository uses Bun 1.3.11. Fork it and create your branch from `canary`,
the default branch that pull requests target:

```sh
git clone https://github.com/your-username/c15t.git
cd c15t
git switch -c my-change
bun install
```

`bun install` also installs a Lefthook pre-commit hook that formats staged
files with Oxfmt.

## Run the checks

```sh
bun run build         # build every package with Turborepo
bun run test          # Vitest for packages your branch changed, and their dependents
bun run check-types   # TypeScript, after a build
bun run lint          # Oxlint
bun run fmt           # Oxfmt
```

Tests run with Vitest, not `bun test`. Browser tests for React, Next.js and
TanStack Start need Chromium: run `bunx playwright@1.58.2 install` once.
`bun run test:full` runs every package. For documentation changes, run
`bun run lint:docs` and `bun run fmt:docs`.

Add or update tests with your change. For a bug fix, add a test that fails
without the fix.

## Open the pull request

Target `canary`. Fill in the pull request template, link the issue and add
screenshots for UI changes. Write commit messages as
[Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`,
`docs:`, `chore:`, `refactor:` or `test:`.

CI picks its checks from the files you changed: package builds, tests, type
checks, linting, docs generation and, for runtime changes, browser and bundle
checks. autofix.ci pushes formatting fixes to your branch, so pull before you
add more commits.

## Add a release note

Changes to published packages need a `.tegami/*.md` release note. Run
`RELEASE_BRANCH=v3 bun run tegami`, replacing `v3` with your pull request's
target branch. Give explicit package bumps and a Markdown heading, and write
the body as the changelog entry:

```md
---
packages:
  '@c15t/core': patch
---

### Fix consent persistence

Keep saved preferences after reloading the page.
```

Do not edit package `CHANGELOG.md` files or the publish lock; Tegami generates
them. The `release.yml` workflow runs CI, and Tegami opens a version pull
request. Merging it publishes the packages and creates GitHub releases. `main`
publishes stable releases, `v3` publishes alphas and `2.0.0` publishes release
candidates. Pushes to `canary` publish commit-specific snapshots under the
`canary` npm tag without a version pull request. The
[release guide](https://github.com/c15t/c15t/blob/v3/.tegami/README.md) covers
versioning rules and npm trusted publishing.

## Edit the documentation

Edit the MDX source in `docs/`. Package `README.md` files, the `docs/` folders
inside packages and their `AGENTS.md` files are generated; change
`docs/**/*.mdx` or the package's `readme.json` instead.

## License

By contributing, you agree that your contributions are licensed under the
[Apache License, Version 2.0](/docs/oss/license), the license c15t uses.

# c15t Community Code of Conduct
URL: https://c15t.com/docs/oss/code-of-conduct
Guidelines for fostering an inclusive, respectful, and collaborative open-source community

## Our Commitment

At c15t, we are committed to creating an open, welcoming, and inclusive environment for all contributors, regardless of:

* Age
* Body size
* Disability (visible or invisible)
* Ethnicity
* Gender identity and expression
* Experience level
* Nationality
* Personal appearance
* Race
* Religion
* Sexual orientation

Our goal is to build a community that is diverse, supportive, and focused on collaborative innovation.

## Our Standards

### Positive Behaviors We Encourage

* **Empathy and Kindness**: Treat each other with compassion and understanding
* **Respect for Diversity**: Value different perspectives, experiences, and backgrounds
* **Constructive Communication**:
  * Provide thoughtful, actionable feedback
  * Receive feedback with an open mind
* **Accountability**:
  * Own your mistakes
  * Learn and grow from constructive criticism
* **Community-First Mindset**: Prioritize the collective success of the project over individual interests

### Behaviors We Do Not Tolerate

* Sexualized language or imagery
* Trolling, insulting, or derogatory comments
* Personal or political attacks
* Public or private harassment
* Sharing private information without explicit consent
* Any conduct that would be considered inappropriate in a professional setting

## Enforcement Responsibilities

### Community Leaders Commit To:

* Clarify and enforce community standards
* Provide fair and consistent moderation
* Communicate the rationale behind moderation decisions
* Protect the privacy and safety of all community members

### Reporting Misconduct

If you experience or witness unacceptable behavior, please report it to:

* **Email**: [conduct@c15t.dev](mailto:conduct@c15t.dev)
* **GitHub Issues**: Use the "Conduct Violation" template in our repository

All reports will be:

* Reviewed promptly
* Handled with confidentiality
* Addressed objectively

## Enforcement Guidelines

### 1. Correction

**Impact**: Unprofessional or unwelcoming behavior

**Response**:

* Private written warning
* Clear explanation of the violation
* Opportunity for improvement

### 2. Warning

**Impact**: Repeated or significant inappropriate interactions

**Response**:

* Formal warning
* Temporary restrictions on community interactions
* Specified period of no direct communication

### 3. Temporary Ban

**Impact**: Serious or sustained inappropriate behavior

**Response**:

* Temporary suspension from community spaces
* No public or private interactions
* Clear path to reinstatement

### 4. Permanent Ban

**Impact**: Repeated violations or severe misconduct

**Response**:

* Permanent removal from all community spaces
* No further interaction permitted

## Our Pledge

We believe that **diversity is our strength**. By maintaining an inclusive environment, we:

* Encourage innovation
* Foster learning
* Build better software together

## Attribution

This Code of Conduct is inspired by the [Contributor Covenant](https://www.contributor-covenant.org), adapted to reflect the unique values and spirit of the c15t community.

**Last Updated**: 2025-09-08

## Questions?

If you have questions about this Code of Conduct, please [open an issue](https://github.com/c15t/c15t/issues) or email [conduct@c15t.dev](mailto:conduct@c15t.dev).

# License
URL: https://c15t.com/docs/oss/license
Apache License 2.0 applies to c15t open source packages and this repository.

## Overview

c15t and its published SDKs and packages in this repository are
licensed under the **Apache License, Version 2.0**.

By contributing to this project, you agree that your contributions will be licensed
under the same terms.

## Third-party notices

This distribution may include third-party components. See the `NOTICE` file in the
repository root for attribution.

## Full license text

The complete license is in
[`LICENSE.md`](https://github.com/c15t/c15t/blob/main/LICENSE.md) on GitHub.

Read more about Apache 2.0 on
[Choose a License](https://choosealicense.com/licenses/apache-2.0/).

# Cookie Policy
URL: https://c15t.com/docs/legals/cookie-policy
Which cookies and similar technologies c15t.com uses, why, and how to manage them.

## Introduction

This Cookie Policy explains how and why Consent Management Inc (“we,” “us,” “our”) uses cookies and similar tracking technologies on our Website, [c15t.com](https://c15t.com) (“Website”). By using our Website, you consent to our use of cookies in accordance with this policy.

## What Are Cookies?

Cookies are small data files placed on your device when you visit a Website. They help the Website remember your actions and preferences (such as login details or language settings) over a period of time, so you do not have to re-enter them during each visit.

## Types of Cookies We Use

### 1. Essential Cookies

* These cookies are necessary for the Website to function and cannot be disabled. They include cookies that enable you to log in securely.

### 2. Analytics Cookies

* We use analytics cookies, including those deployed by PostHog, to collect data on how you interact with our Website. This non-personally identifiable data is used to improve the Website’s functionality and user experience.

### 3. Functionality and Preference Cookies

* These cookies allow the Website to remember choices you make (such as your preferred language) and provide a more personalized experience.

## Managing Cookies

Most browsers allow you to control cookies through their settings. You can:

* Block or delete cookies via your browser settings.
* Opt-out of specific cookies or tracking technologies when such options are provided on the Website.

Please note that disabling cookies may affect the functionality of this Website and your overall user experience.

## Third-Party Cookies

We may allow third parties (for example, analytics providers like PostHog) to place cookies on our Website. These third parties have their own privacy policies and we do not control the cookies they may use.

## Changes to This Cookie Policy

We may update the Cookie Policy periodically to reflect changes in our practices or for operational, legal, or regulatory reasons. The current version will always be posted on our Website with an updated effective date.

## Contact Us

For questions about this Cookie Policy, please contact us at:

> **Consent Management Inc**\
> 2261 Market Street STE 86311
> San Francisco, CA 94114\
> Email: [support@c15t.com](mailto:support@c15t.com)

# Privacy Policy
URL: https://c15t.com/docs/legals/privacy-policy
How Consent Management Inc collects, uses, shares and protects personal information on c15t.com, and how to contact us about it.

## Introduction

Consent Management Inc (“we,” “us,” “our”) operates the website [c15t.com](https://c15t.com) (“Website”). This Privacy Policy describes how we collect, use, disclose, and protect your personal information. By accessing or using the Website, you agree to the practices described in this policy. If you do not agree with these practices, please do not use our Website.

## Applicable Laws and Scope

This policy is designed for a Delaware-based company and informs users worldwide. When you are located in jurisdictions with additional privacy requirements (for example, under the GDPR or CCPA), certain rights and protections may apply. Please refer to the relevant sections below and consult applicable laws for your jurisdiction.

## Information We Collect

### 1. Personal Data

* We may collect personal data that you voluntarily provide when interacting with our Website (for example, your name, email address, and telephone number).

### 2. Automatically Collected Data

* We automatically collect non-personally identifiable information through technologies like cookies and web beacons. This may include IP addresses, browser types, and device identifiers.

### 3. Analytics Data

* We use PostHog to track analytics on our Website. PostHog may collect information such as usage behavior, page views, and interaction data. This information is used solely for enhancing website performance and user experience. For more details, please review PostHog’s own privacy practices on their website.

## How We Use Your Information

We use your personal information to:

* Provide and improve our Website and services.
* Analyze website traffic and usage trends.
* Communicate with you regarding inquiries and updates (subject to your consent where applicable).
* Comply with legal and regulatory requirements.

## Legal Basis for Processing (For Users in Jurisdictions Requiring It)

Where required by law (for example, under the GDPR), our processing is based on:

* Your consent for analytics and marketing purposes.
* Our legitimate interests in operating and improving our Website.
* Any contractual obligations you have with us.

## Information Sharing and Disclosure

We do not sell or rent your personal information. We may share your personal data with:

* **Third-party service providers:** for example, analytics providers like PostHog, who process data on our behalf. These service providers are contractually obligated to maintain the confidentiality and security of your data.
* **Legal authorities:** if required by law or to protect our rights and interests.
* **Other parties:** only with your explicit consent.

## International Data Transfers

Since we serve a worldwide audience, your personal data may be transferred to—and maintained on—servers located outside your state, country, or other jurisdiction (including the United States). We take appropriate steps to ensure that your data is treated securely in accordance with this Privacy Policy and applicable laws.

## Data Retention and Security

* **Data Retention:** We retain personal data only as long as necessary to fulfill its intended purposes or as required by applicable law.
* **Security Measures:** We implement reasonable administrative, technical, and physical safeguards to protect your personal information.

## Your Rights

Depending on your jurisdiction, you may have the right to:

* Access, correct, or delete your personal data.
* Object to or restrict certain processing.
* Withdraw consent.

To exercise these rights, please contact us using the details provided below.

## Children's Privacy

Our Website is not directed to children under 13 years of age. We do not knowingly collect personal information from children. If you believe that we have inadvertently collected such information, please contact us immediately.

## Policy Updates

We may update this Privacy Policy occasionally. If we make material changes, we will update the effective date at the top of the policy and notify you by any required means.

## Contact Us

For questions or concerns regarding this Privacy Policy or our practices, please contact us at:

> **Consent Management Inc**\
> 2261 Market Street STE 86311
> San Francisco, CA 94114\
> Email: [support@c15t.com](mailto:support@c15t.com)

# v1.1.1 — Bundle Reduction Update
URL: https://c15t.com/changelog/1.1.1
Performance-focused release achieving a massive 58.9% bundle size reduction while introducing a new headless package for custom implementations. Removed framer-motion and Tailwind variants for faster load times with zero UX compromise.

## Major Changes

This release focuses on **massive bundle size reduction** and introduces a new **headless package** for maximum flexibility and performance.

## 🚀 Performance Revolution

### Bundle Size Optimization

* **MASSIVE**: Reduced package size from **84.2 kB → 34.6 kB** (gzip) — a **58.9% reduction**
* Removed framer-motion dependency for lighter bundle
* Replaced Tailwind variants with native transitions and utility classes
* **Zero compromise** on UX while achieving faster load times

### Performance Metrics

```
Before: 84.2 kB (gzip)
After:  34.6 kB (gzip)
Reduction: 58.9% smaller bundle
```

## 🧠 Introducing @c15t/react/headless

### For Teams Who Need Full Control

* **NEW**: Introduced `@c15t/react/headless` for teams who don't need the built-in cookie banner
* **Ultra-lightweight**: Only **12.5 kB (gzip)** footprint
* Perfect for custom implementations and design systems
* Complete access to consent logic without built-in UI components

### Headless Usage Example

```jsx
import { 
  ConsentManagerProvider,
  type ConsentManagerOptions
} from '@c15t/react/headless';

export default function Layout({ children }: { children: ReactNode }) {
  const options: ConsentManagerOptions = {
    mode: 'c15t', 
    backendURL: process.env.NEXT_PUBLIC_C15T_URL,
  };

  return (
    <ConsentManagerProvider options={options}>
      {children}
    </ConsentManagerProvider>
  );
}
```

## 📦 Package Structure

### Bundle Analysis

```
@c15t/react (standard):     34.6 kB (gzip) - Full UI components
@c15t/react/headless:       12.5 kB (gzip) - Logic only
```

### Dependency Optimization

* Removed framer-motion: **-15.2 kB**
* Optimized Tailwind usage: **-8.4 kB**
* Tree-shaking improvements: **-26.0 kB**
* **Total savings: -49.6 kB (58.9% reduction)**

## 🎯 Use Cases

### Standard Implementation

```jsx
// Full-featured with built-in UI (34.6 kB)
import { ConsentManagerProvider, CookieBanner } from '@c15t/react';

<ConsentManagerProvider options={options}>
  <CookieBanner />
  {children}
</ConsentManagerProvider>
```

### Headless Implementation

```jsx
// Custom UI with consent logic only (12.5 kB)
import { ConsentManagerProvider, useConsent } from '@c15t/react/headless';

function CustomBanner() {
  const { consents, setConsent } = useConsent();
  return (
    <div className="my-custom-banner">
      {/* Your custom implementation */}
    </div>
  );
}
```

## 🚀 Performance Impact

### Load Time Improvements

* **58.9% smaller bundle** = significantly faster initial page load
* **Better caching** = reduced repeat load times
* **Tree-shaking friendly** = only load what you use
* Faster Time to Interactive (TTI)
* Improved Core Web Vitals scores

### Network Efficiency

* Fewer bytes over the wire
* Better compression ratios
* Enhanced performance on slower connections

## ✨ What's Changed

Published via commit [cef8df2](https://github.com/c15t/c15t/commit/cef8df2) by [@BurnedChris](https://github.com/BurnedChris)

Whether you're optimizing for performance, custom UI, or just want to plug into our consent logic — c15t is now **leaner and more flexible than ever**.

<ContributorBlock usernames={["BurnedChris"]} />

# v1.1.2 — Optimistic UI & Bundle Optimization
URL: https://c15t.com/changelog/1.1.2
Performance-focused release introducing optimistic UI updates for instant user feedback, massive 58.9% bundle size reduction, and a new headless package for custom implementations with improved event handling.

## Major Changes

This release introduces **optimistic UI updates** and achieves **massive bundle size reduction** while adding a new **headless package** for maximum flexibility.

## 🔧 Fixes & Improvements

### @c15t/react@1.1.2

#### Improved UX responsiveness for banner and dialog interactions:

* UI now updates immediately on user interaction (e.g., closing modals, accepting/rejecting consent), with consent saved in the background
* This ensures a smoother experience, especially on slower connections or when network requests are delayed

#### Improved event handling for ConsentButton:

* Rewritten logic to separate UI updates from consent persistence
* Custom onClick handlers now receive the full MouseEvent, enabling better control and integration

#### Cleaner store logic:

* Refactored setShowPopup and saveConsents methods to better separate UI vs network logic
* More consistent behavior around locale changes and popup visibility

### c15t@1.0.5

#### ⚙️ Under the Hood:

* Improved consent flow by decoupling UI updates from async network calls — UI now responds instantly, with API sync happening in the background
* Fixed an edge case where popup visibility or dialog state could behave inconsistently due to dependency timing
* Minor cleanup and better error handling in consent persistence logic

## 🚀 Performance Revolution

### Bundle Size Optimization

* **MASSIVE**: Reduced package size from **84.2 kB → 34.6 kB** (gzip) — a **58.9% reduction**
* Removed framer-motion dependency for lighter bundle
* Replaced Tailwind variants with native transitions and utility classes
* **Zero compromise** on UX while achieving faster load times

## 🧠 New Headless Package

### @c15t/react/headless

* **NEW**: Introduced `@c15t/react/headless` for teams who need full UI control
* **Ultra-lightweight**: Only **12.5 kB (gzip)** footprint
* Perfect for custom implementations and design systems
* Complete access to consent logic without built-in UI components

## ✨ What's Changed

* feat: Optimistic UI updates by [@BurnedChris](https://github.com/BurnedChris) in [#184](https://github.com/c15t/c15t/pull/184)

**Full Changelog**: [1.1.1...1.1.2](https://github.com/c15t/c15t/compare/1.1.1...1.1.2)

## 📋 Implementation Details

### Optimistic Consent Flow

```js
// Optimistic consent flow
const handleConsent = async (choice) => {
  // 1. Update UI immediately (optimistic)
  updateUIState(choice);
  
  // 2. Save to backend (background)
  try {
    await saveConsent(choice);
  } catch (error) {
    // 3. Revert UI if needed
    revertUIState();
  }
};
```

### Enhanced Event Handling

```jsx
<ConsentButton 
  onClick={(event: MouseEvent) => {
    // Full access to mouse event
    // Custom logic before/after consent handling
    handleCustomAnalytics(event);
  }}
>
  Accept Cookies
</ConsentButton>
```

## 🧪 Testing

### Test Plan

✅ **Scenario 1**: Clicking the "Accept All" button on cookie banner

* Expected: Banner immediately disappears, consent is saved in the background

✅ **Scenario 2**: Testing on slow networks

* Using Chrome DevTools to simulate slow 3G connection
* Expected: UI updates immediately regardless of network speed

### Edge Cases

* Error handling: If the network request fails, the UI is already updated, and errors are logged
* Performance: Significant improvement in perceived performance on all device types

This release makes c15t **leaner, faster, and more flexible than ever** while maintaining full backward compatibility and enhancing the user experience through optimistic UI updates.

<ContributorBlock usernames={["BurnedChris"]} />

# v1.1.3 — Enhanced Theming & Callback Improvements
URL: https://c15t.com/changelog/1.1.3
Major release introducing comprehensive theming support with dark/light/system detection, improved consent callbacks with structured data, and enhanced color scheme integration. Includes breaking changes for theme system and callback data structure.

## Minor Changes

This release introduces **enhanced theme flexibility** and significantly **improved consent callbacks** with structured data responses.

## ✨ New Features

### Comprehensive Theming Support

* `useColorScheme` now detects themes via the `.dark` class on `document.documentElement`
* Optional `colorScheme` parameter improves integration with existing theme systems
* Full test suite added to validate dark/light/system theme switching
* Theme system now uses `@layer base` for better CSS encapsulation

### Improved Consent Callbacks

* Callbacks now return structured and useful consent data
* Works consistently across offline, c15t, and backend-connected modes
* Callback responses now reflect user-selected preferences more clearly

## 🐛 Bug Fixes

* **[#203](https://github.com/c15t/c15t/issues/203)** [4d47e21](https://github.com/c15t/c15t/commit/4d47e2109bfc894f1666b19f4ff40d7398f10c57) – fix(core): callbacks not working in c15t mode. Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)!
* Fixed callbacks not firing in alternate modes (e.g., c15t)
* `useColorScheme` now correctly responds to:
  * System preference changes
  * Document class changes (via MutationObserver)
* Improved error handling for environments missing `matchMedia`
* Removed unnecessary localStorage dependency for theme persistence

## 🏗️ Refactors

* Theme-related CSS is now consistently structured using `@layer base`
* Refined internal theme types to allow better extension/customization
* Simplified theme config to support nested object structure for banners and widgets

## 📚 Documentation

* Fixed broken example in offline mode – [#187](https://github.com/c15t/c15t/issues/187)
* Updated configuration types to document new theme and colorScheme options
* Added detailed callback payload examples and behavior notes across client modes
* Enhanced API references and docs for:
  * `onSetConsent` and other lifecycle callbacks
  * Banner fetch event handler

## 🧪 Tests

### Color Scheme Tests:

* System preference override
* Explicit theme override
* Document class detection

### Callback Tests:

* Triggering across client modes
* Payload accuracy and structure

## 💥 Breaking Changes

* Removed localStorage theme fallback — rely on system preference or class
* Misconfigured theme props in c15t config may need to be adjusted
* Some fields (e.g., `id`) removed from callback data objects — now accessible via the response object

## 🔄 Migration Guide

### Theme System Changes

localStorage theme fallback has been removed:

```js
// Before: Manual localStorage theme management
localStorage.setItem('theme', 'dark');

// After: Use system preference or class-based detection
document.documentElement.classList.add('dark');
```

### Callback Data Structure

Some fields have been moved in callback responses:

```js
// Before
onSetConsent(({ id, consents }) => {
  // id was directly available
});

// After
onSetConsent(({ consents, response }) => {
  // id is now in response object
  const id = response.id;
});
```

## 📦 Version Packages

Published via [#205](https://github.com/c15t/c15t/pull/205) by @github-actions

This release significantly enhances the **theming capabilities** and **callback reliability** of c15t, providing a more robust foundation for custom UI implementations and better integration with existing design systems.

<ContributorBlock usernames={["KayleeWilliams", "burnedchris"]} />

# v1.1.4 — Translation System Fixes & Core Improvements
URL: https://c15t.com/changelog/1.1.4
Patch release addressing critical translation functionality issues across core and react packages. Introduces better modularity, improved fallback behavior, comprehensive test coverage, and enhanced translation utility functions.

## Patch Changes

This release addresses a **critical issue with translation functionality** across the core and react packages, introducing better modularity, improved fallback behavior, and robust test coverage.

## 🆕 New Features

* Exposed additional translation utility functions for external use
* Added support for initializing the consent manager store with a translation configuration
* Introduced a utility to streamline translation configuration preparation

## 🐛 Bug Fixes

* **[#207](https://github.com/c15t/c15t/issues/207)** [2d81c9f](https://github.com/c15t/c15t/commit/2d81c9f) – fix(core, react): translations not working. Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)!
* Improved language detection and translation merging logic, ensuring more accurate language selection and fallback behavior
* Fixed an issue where translations were not working in the core and react packages

## 🧪 Tests

* Added comprehensive tests for translation utilities and the translation hook
* Expanded test coverage to include both `.ts` and `.tsx` files

## 🧹 Refactor

* Moved translation utilities from the react package to core for better reusability
* Simplified translation configuration logic in the consent manager provider for easier maintenance

## ✨ What's Changed

* feat(docs): re-added theme switcher, added color scheme docs by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#206](https://github.com/c15t/c15t/pull/206)
* fix(core, react): translations not working by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#207](https://github.com/c15t/c15t/pull/207)
* Version Packages by [@github-actions](https://github.com/features/actions) in [#209](https://github.com/c15t/c15t/pull/209)

**Full Changelog**: [c15t@1.1.3...c15t@1.1.4](https://github.com/c15t/c15t/compare/c15t@1.1.3...c15t@1.1.4)

## 📦 Releases

### @c15t/cli@1.0.7

**Patch Changes**

* Updated dependencies \[2d81c9f]:
  * @c15t/react@1.1.4
  * c15t@1.1.4

### c15t@1.1.4

**Patch Changes**

* [#207](https://github.com/c15t/c15t/pull/207) [2d81c9f](https://github.com/c15t/c15t/commit/2d81c9f) Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)! - fix(core, react): translations not working

### @c15t/react@1.1.4

**Patch Changes**

* [#207](https://github.com/c15t/c15t/pull/207) [2d81c9f](https://github.com/c15t/c15t/commit/2d81c9f) Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)! - fix(core, react): translations not working
* Updated dependencies \[2d81c9f]:
  * c15t@1.1.4

### @c15t/dev-tools@1.1.4

**Patch Changes**

* Updated dependencies \[2d81c9f]:
  * c15t@1.1.4

Published via commit [21eb1a3](https://github.com/c15t/c15t/commit/21eb1a3) by [@github-actions](https://github.com/features/actions)

This release **restores critical translation functionality** and establishes a solid foundation for international deployments with comprehensive testing and improved developer experience.

<ContributorBlock usernames={["KayleeWilliams"]} />

# v1.1.5 — Tailwind CSS v3 Compatibility & Style Fixes
URL: https://c15t.com/changelog/1.1.5
Patch release fixing critical Tailwind CSS v3 compatibility issues by removing CSS layers and improving noStyle theme handling. Ensures proper style application and prevents conflicts with modern Tailwind configurations.

## Patch Changes

This release addresses **critical Tailwind CSS v3 compatibility issues** and improves theme handling for components with custom styling requirements.

## 🐛 Bug Fixes

### Tailwind CSS v3 Compatibility

* **[#218](https://github.com/c15t/c15t/issues/218)** [1652d02](https://github.com/c15t/c15t/commit/1652d02) – fix(react): removed layers to fix collision with Tailwind 3. Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)!
* **[#208](https://github.com/c15t/c15t/issues/208)** [41bfb71](https://github.com/c15t/c15t/commit/41bfb71) – fix(react): no style component theme not removing default classes. Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)!

### Key Fixes

* **Removed CSS layering wrappers** that caused conflicts with Tailwind CSS v3
* **Fixed noStyle theme handling** to properly exclude default component styles when `noStyle` flag is set
* Ensured theme-level `classNames` and `styles` are still applied even with `noStyle: true`

## 🔧 Technical Details

### CSS Layer Removal

* Removed `@layer` wrappers from multiple components to prevent Tailwind CSS v3 collisions
* This change maintains functionality while ensuring compatibility with modern Tailwind configurations

### Enhanced noStyle Theme Support

* Added proper checks for `noStyle` flag in component themes
* When `noStyle` is enabled, only theme-level styling is applied
* Default component styles are correctly excluded

## ⚠️ Breaking Changes

### Custom Class Priority

With the removal of CSS layers, you may need to add `!important` to custom classes for proper specificity:

```css
/* Before */
.my-custom-banner {
  border: 1px solid red;
}

/* After - if styles don't apply */
.my-custom-banner {
  border: 1px solid red !important;
}
```

Or use Tailwind's important prefix:

```jsx
// Before
<div className="border-red-500">

// After - if needed
<div className="!border-red-500">
```

## 🎯 Use Cases

### NoStyle Theme Implementation

```jsx
// Theme with noStyle flag
const customTheme = {
  noStyle: true,
  classNames: "my-custom-styles",
  styles: { backgroundColor: "blue" }
};

// Only theme-level styles applied, no default component styles
<CookieBanner theme={customTheme} />
```

### Tailwind CSS v3 Compatibility

```jsx
// Now works seamlessly with Tailwind CSS v3
import { CookieBanner } from '@c15t/react';

// No more layer conflicts
<CookieBanner className="border-2 border-blue-500 rounded-lg" />
```

## 🧪 Testing

### Test Coverage

* ✅ Added comprehensive test cases for `noStyle` flag behavior
* ✅ Verified CSS layer removal doesn't break existing functionality
* ✅ Enhanced test descriptions for clarity
* ✅ Added coverage for mixed theme formats (strings and objects)

### Validation Scenarios

* **Theme with noStyle**: Ensures only theme-level styles are applied
* **Tailwind CSS v3**: Confirms no layer conflicts in modern Tailwind setups
* **Mixed theme formats**: Validates both string and object theme configurations

## ✨ What's Changed

Published via commit [0d421be](https://github.com/c15t/c15t/commit/0d421be) by [@github-actions](https://github.com/features/actions)

* fix(react): removed layers to fix collision with Tailwind 3 by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#218](https://github.com/c15t/c15t/pull/218)
* fix(react): no style component theme not removing default classes by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#208](https://github.com/c15t/c15t/pull/208)

**Full Changelog**: [@c15t/react@1.1.4...@c15t/react@1.1.5](https://github.com/c15t/c15t/compare/@c15t/react@1.1.4...@c15t/react@1.1.5)

This release ensures **seamless Tailwind CSS v3 compatibility** while providing more robust theme customization options through improved `noStyle` handling.

<ContributorBlock usernames={["KayleeWilliams"]} />

# v1.2.0 — Backend Architecture Overhaul & Translation System Refactor
URL: https://c15t.com/changelog/1.2.0
Major release introducing a complete backend refactor to oRPC client/server architecture with OpenAPI support, CORS middleware, and streamlined translation system with common strings consolidation. Includes breaking changes for translation structure.

## Minor Changes

This release represents a **major architectural shift** with a complete backend refactor to oRPC and significant improvements to the translation system.

## 🏗️ Backend Architecture Overhaul

### Complete oRPC Migration

* **[#224](https://github.com/c15t/c15t/issues/224)** [838a9b5](https://github.com/c15t/c15t/commit/838a9b5) – Refactored backend to be a new orpc client / server. Thanks [@BurnedChris](https://github.com/BurnedChris)!
* Migrated from traditional REST API to **oRPC (Open RPC)** architecture
* Improved type safety and contract-driven development
* Enhanced client-server communication with better error handling

### OpenAPI Integration

* **Comprehensive OpenAPI middleware** for automatic API specification generation
* **Swagger UI integration** for interactive API documentation
* **Contract-based client creation** in Node SDK
* Configurable documentation UI through environment variables

### Enhanced CORS Support

* **Flexible CORS middleware** with advanced origin validation
* **Wildcard pattern support** for dynamic origin matching
* **Enhanced security handling** with proper configuration options
* Optimized validation for minimal performance impact

## 🌐 Translation System Refactor

### Consolidated Common Translations

* **[#222](https://github.com/c15t/c15t/issues/222)** [b1de2ba](https://github.com/c15t/c15t/commit/b1de2ba) – fix(core, react): added "common" translations, removed widget translations. Thanks [@KayleeWilliams](https://github.com/KayleeWilliams)!
* **NEW**: Introduced shared `common` translations section
* Consolidated frequently used strings like "Accept All", "Reject All", "Customize", "Save"
* **Removed widget translations** (no longer used)
* Simplified translation management across components

### Translation Structure Changes

```js
// Before: Duplicated across components
{
  cookieBanner: {
    acceptAll: "Accept All",
    rejectAll: "Reject All",
    // ... other strings
  },
  dialog: {
    acceptAll: "Accept All", // Duplicated
    rejectAll: "Reject All", // Duplicated
    // ... other strings
  }
}

// After: Centralized common strings
{
  common: {
    acceptAll: "Accept All",
    rejectAll: "Reject All",
    customize: "Customize",
    save: "Save"
  },
  cookieBanner: {
    // Only banner-specific strings
  },
  dialog: {
    // Only dialog-specific strings
  }
}
```

## 🐛 Bug Fixes

### Consent Banner Logic

* **Fixed consent banner display logic** to ensure consistent behavior
* Banner now displays for **all countries**, including non-regulated jurisdictions
* Improved user experience with standardized banner behavior

### Enhanced Error Handling

* Standardized error handling across all new features
* Improved logging throughout the codebase
* Enhanced telemetry utilities with better error reporting

## 🚀 New Features

### API Documentation

* **Automatic OpenAPI specification generation**
* **Interactive Swagger UI** for API exploration
* **Contract-driven development** workflow
* Enhanced developer experience for API integration

### Advanced CORS Configuration

```js
// Enhanced CORS with wildcard support
const corsConfig = {
  origins: ['*.example.com', 'https://app.mysite.com'],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE']
};
```

### Improved Node SDK

* **Contract-based client creation** using OpenAPI specifications
* Additional utility scripts for development
* Enhanced integration capabilities

## 💥 Breaking Changes

### Translation Structure Migration Required

The translation system has been restructured to use common strings:

```js
// Migration Required
// OLD: Widget translations (removed)
{
  widget: {
    acceptAll: "Accept All"
  }
}

// NEW: Common translations
{
  common: {
    acceptAll: "Accept All",
    rejectAll: "Reject All",
    customize: "Customize",
    save: "Save"
  }
}
```

### Migration Steps

1. **Remove widget translations** from your c15t configuration
2. **Move common strings** from cookie banner & dialog to the new `common` section
3. **Update custom translations** to use the new structure

### Backend API Changes

* **oRPC architecture** may require client integration updates
* **Enhanced CORS validation** might affect cross-origin requests
* **OpenAPI contract** provides better type safety but may require adaptation

## 🧪 Testing & Validation

### CORS Middleware Tests

```js
// Wildcard pattern validation
const result = isOriginTrusted('https://sub.example.com', ['*.example.com']);
expect(result).toBe(true);
```

### Consent Banner Tests

```js
// Banner display for non-regulated countries
const result = checkJurisdiction('US');
expect(result.showConsentBanner).toBe(true);
```

### Translation Tests

* ✅ Comprehensive tests for new common translation structure
* ✅ Validation of translation consolidation logic
* ✅ Coverage for shared translation functionality

## 📦 Package Updates

### Core Packages

* **c15t@1.2.0**: Backend refactor + translation improvements
* **@c15t/react@1.2.0**: Translation structure updates
* **@c15t/backend@1.2.0**: Complete oRPC architecture

### Supporting Packages

* **@c15t/node-sdk@1.2.0**: OpenAPI contract integration
* **@c15t/cli@1.2.0**: Backend architecture support
* **@c15t/dev-tools@1.2.0**: Updated dependencies

## 🔧 Technical Improvements

### Performance Optimizations

* **Optimized CORS validation** for minimal performance impact
* **Streamlined domain validation** in consent schema
* **Enhanced telemetry** with better logging efficiency

### Code Organization

* **Centralized CORS and OpenAPI logic** into dedicated middleware
* **Modularized architecture** for better maintainability
* **Improved error handling** patterns throughout codebase

## ✨ What's Changed

Published via commit [54b03d4](https://github.com/c15t/c15t/commit/54b03d4) by [@github-actions](https://github.com/features/actions)

* feat(api): add c15t instance API route with OpenAPI support by [@BurnedChris](https://github.com/BurnedChris) in [#224](https://github.com/c15t/c15t/pull/224)
* fix(core, react): added "common" translations, removed widget translations by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#222](https://github.com/c15t/c15t/pull/222)

**Full Changelog**: [c15t@1.1.5...c15t@1.2.0](https://github.com/c15t/c15t/compare/c15t@1.1.5...c15t@1.2.0)

This release establishes a **modern, scalable foundation** for c15t with improved developer experience, better performance, and streamlined translation management.

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.2.1 — API Architecture Hardening, Translations Cleanup, and Tailwind v3 Fix
URL: https://c15t.com/changelog/1.2.1
Patch release refining the new API architecture with oRPC + OpenAPI, consolidating translations into common keys, fixing Tailwind v3 layer collision, and improving schema validation and configuration defaults. Introduces a type-safe Node.js SDK and centralized routing.

## Summary

This release delivers a major refactor and architecture upgrade across the API system, along with enhanced translation handling, styling fixes, and groundwork for future CLI and dashboard features. It introduces a type-safe Node.js SDK, centralized routing, and better configuration defaults — paving the way for production-ready scaling.

## 🚀 New Features

* Introduced a **Node.js SDK** for type-safe client access to the C15T API
* Added **OpenAPI** support for backend contracts
* New **contract-based routing** for consent and meta endpoints
* Support for **common translation strings** across UI components
* Early support for **dev vs prod** instance logic and origin handling

## 🐛 Bug Fixes

* Fixed Tailwind CSS v3 layer collision by removing unused `@layer` wrappers
* Improved schema validation for `setConsent`
* Fixed environment variable parsing for trusted origins
* Improved fallback handling for translations and jurisdiction detection

## 🧪 Tests

* Added test coverage for new consent contracts and schema validation
* Extended coverage for translations, error handling, and Node.js SDK
* Cleaned up outdated tests and fixtures

## 🧹 Refactor

* Migrated backend from H3 to **oRPC** for improved type safety
* Consolidated translation logic and **removed widget-specific translations**
* Introduced a **unified logger** utility
* Simplified consent manager configuration and routing structure

## 🔒 Closed Issues

* [#222](https://github.com/c15t/c15t/issues/222) — duplicate/overlapping translation keys between dialog and widget (resolved by consolidation to `common`)
* [#217](https://github.com/c15t/c15t/issues/217) / [#218](https://github.com/c15t/c15t/issues/218) — Tailwind v3 `@layer base` collision (fixed by removing layer wrappers)

## ✨ What's Changed

* refactor(api): switch to oRPC and unified contract routing by [@BurnedChris](https://github.com/BurnedChris) in [#213](https://github.com/c15t/c15t/pull/213)
* feat(sdk): introduce Node.js client with OpenAPI support by [@BurnedChris](https://github.com/BurnedChris) in [#214](https://github.com/c15t/c15t/pull/214)
* fix(styles): remove Tailwind layer to avoid collision by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#217](https://github.com/c15t/c15t/pull/217)
* refactor(translations): consolidate into common + remove widget keys by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#219](https://github.com/c15t/c15t/pull/219)
* fix(schema): improve `setConsent` validation by [@KayleeWilliams](https://github.com/KayleeWilliams)
* Version Packages by [@github-actions](https://github.com/features/actions) in [#220](https://github.com/c15t/c15t/pull/220)

Published via commit [f82e56a](https://github.com/c15t/c15t/commit/f82e56a) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.2.0...c15t@1.2.1](https://github.com/c15t/c15t/compare/c15t@1.2.0...c15t@1.2.1)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.3.0 — Translations Package, SSR Consent, CLI Telemetry, and Next.js Restructure
URL: https://c15t.com/changelog/1.3.0
Minor release introducing the new @c15t/translations package with 8 languages, server-side consent initialization, CLI telemetry and onboarding upgrades, and a Next.js package restructuring that removes middleware exports. Includes backend translation support, improved schemas, and infrastructure/tooling updates.

## Minor Changes

This release represents a major step forward in internationalization support, developer experience, and architectural refinements across the entire c15t ecosystem.

## 🌍 New Translations Package

* NEW: Added `@c15t/translations` with comprehensive i18n support
* 8 languages: English, German, Spanish, Finnish, French, Italian, Dutch, Portuguese
* Covers consent banners, dialogs, and common phrases
* Replaces former middleware-centric translation handling

## 🔧 CLI Enhancements

* NEW: Telemetry system with framework and package manager detection
* NEW: Enhanced onboarding flow with better framework detection (React, Next.js, etc.)
* NEW: Automatic package manager detection (pnpm, yarn, npm)
* NEW: `--telemetry-debug` flag for debugging telemetry
* Improved error handling and setup UX
* Better file generation across storage modes and configurations

## 🎯 Backend Updates

* NEW: Server-side translation support in consent banner handling
* Accept-Language header parsing for language detection
* Consent banner contracts updated with translation schemas
* Enhanced jurisdiction checking with better defaults
* User-Agent and IP address handling now default to `null` instead of "unknown"

## ⚛️ React Package Changes

* Integrated translation support throughout components
* `ConsentManagerProvider` now supports initial translation configuration
* Removed dependency on middleware package
* Store enhanced with translation capabilities

## 🔄 Next.js Package Restructuring

* BREAKING: Removed middleware exports and functionality
* NEW: `ConsentManagerProvider` for server-side rendering
* NEW: Server-side consent banner detection with jurisdiction mapping
* Support for extracting consent-relevant headers
* Updated to work with the new translations system

## 🏗️ Core Package Updates

* Integrated translation configuration system
* Offline client includes default translations
* Consent banner fetching enhanced with translation support
* Improved store management with initial data handling

## 🔄 Infrastructure & Tooling

* NEW: GitHub Actions workflow for canary releases
* NEW: Branch synchronization workflow (main → canary)
* Updated BiomeJS configuration with comprehensive lint rules
* Enhanced build configurations across packages

## 📦 Package Management

* Updated dependencies and added peer dependencies where appropriate
* Improved module exports and build configs
* Enhanced TypeScript configs for better type safety

## 📋 Detailed Change Breakdown

### New Features

* Multi-language consent banners (de, es, fi, fr, it, nl, pt)
* SSR consent initialization for Next.js
* CLI telemetry and onboarding upgrades; `--telemetry-debug` flag

### Improvements

* Consent banner responses include translation structures and jurisdiction info
* Translations utilities and types centralized in `@c15t/translations`
* Unified onboarding file generation for client config and env files
* Enhanced telemetry with async tracking and debug logging

### Bug Fixes

* Fixed consent banner logic for US jurisdiction and fallback scenarios
* Improved CLI telemetry and onboarding error handling

### Refactor

* Removed legacy middleware exports and Node SDK re-exports from Next.js/middleware packages
* Consolidated jurisdiction and consent banner logic into Next.js provider modules
* Async CLI context creation with richer environment metadata and logging
* Storage modes refactored to delegate file generation and unify cancellation handling

### Tests

* Extensive coverage for banner display, jurisdiction detection, language parsing, translation selection
* Removed deprecated tests for deleted middleware/jurisdiction modules

### Chores

* Version bumps, dependency updates, and new canary workflows
* Metadata/build config updates for consistency and tooling

## 💥 Breaking Changes

* `@c15t/nextjs`: Removed middleware exports and functionality in favor of server-side provider-based initialization

## ✨ What's Changed

* refactor(api): switch to oRPC and unified contract routing by [@BurnedChris](https://github.com/BurnedChris) in [#213](https://github.com/c15t/c15t/pull/213)
* feat(sdk): introduce Node.js client with OpenAPI support by [@BurnedChris](https://github.com/BurnedChris) in [#214](https://github.com/c15t/c15t/pull/214)
* fix(styles): remove Tailwind layer to avoid collision by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#217](https://github.com/c15t/c15t/pull/217)
* refactor(translations): consolidate into common + remove widget keys by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#219](https://github.com/c15t/c15t/pull/219)
* Version Packages by [@github-actions](https://github.com/features/actions) in [#249](https://github.com/c15t/c15t/pull/249)

Published via commit [3eadfd5](https://github.com/c15t/c15t/commit/3eadfd5) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.2.1...c15t@1.3.0](https://github.com/c15t/c15t/compare/c15t@1.2.1...c15t@1.3.0)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} title="Translations & DX team" />

# v1.3.1 — Next.js Data Fetching Refinements, Docs Fixes, and zh Translations
URL: https://c15t.com/changelog/1.3.1
Patch release refining Next.js initial data fetching in c15t mode, fixing quickstart links, improving core fallbacks, and adding Chinese (zh) translations. Includes dependency updates across packages.

## Patch Changes

* 7fecb81: refactor(nextjs): fetch initial data from backend in `c15t` mode instead of duplicate logic
* fix: incorrect link to quickstart
* fix(issue-274): include Next.js externals in `rslib`
* fix(core): fall back to API call if `initialData` promise is empty
* chore: add translation for `zh`

## Updated Dependencies

* For `@c15t/nextjs@1.3.1`: `@c15t/translations@1.3.1`, `@c15t/react@1.3.1`
* For `@c15t/dev-tools@1.3.1`: `c15t@1.3.1`
* For `@c15t/cli@1.3.1`: `@c15t/backend@1.3.1`, `@c15t/react@1.3.1`
* For `@c15t/backend@1.3.1`: `@c15t/translations@1.3.1`

Published via commit [5f5b01a](https://github.com/c15t/c15t/commit/5f5b01a) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.3.0...c15t@1.3.1](https://github.com/c15t/c15t/compare/c15t@1.3.0...c15t@1.3.1)

<ContributorBlock usernames={["KayleeWilliams"]} />

# v1.3.2 — Next.js Relative URL Fix
URL: https://c15t.com/changelog/1.3.2
Patch release fixing a relative URL error in the Next.js integration.

## Patch Changes

* fix(nextjs): resolved relative URL error

## ✨ What's Changed

* fix(nextjs): resolved relative URL error in Next.js integration

Published via commit [31fafe7](https://github.com/c15t/c15t/commit/31fafe7b158843e53bad1b2c2fd89d9e71263e6a) by [@github-actions](https://github.com/features/actions)

**Release**: [`@c15t/nextjs@1.3.2`](https://github.com/c15t/c15t/releases/tag/%40c15t%2Fnextjs%401.3.2)

**Full Changelog**: [c15t@1.3.1...c15t@1.3.2](https://github.com/c15t/c15t/compare/c15t@1.3.1...c15t@1.3.2)

<ContributorBlock usernames={["KayleeWilliams"]} />

# v1.3.3 — GTM Support, CookieBanner Focus Toggle, Next.js URL Validation
URL: https://c15t.com/changelog/1.3.3
Patch release adding Google Tag Manager support in core, allowing trapFocus={false} in CookieBanner, improving URL validation in Next.js, and updating React dependency.

## Patch Changes

* b4d53be: feat(core): added Google Tag Manager support
* fix(react): allow `trapFocus={false}` in `CookieBanner`
* fix(nextjs): improved URL validation

## Updated Dependencies

* Updated dependencies \[b4d53be]
  * `@c15t/react@1.3.3`

## Usage Notes

* Google Tag Manager (GTM) support is opt-in. Ensure your configuration provides the correct container ID and that GTM events are only dispatched after consent is given.
* Experimental: GTM integration is currently experimental and not recommended for production. See the Next.js guide: [Google Tag Manager](https://c15t.com/docs/frameworks/next/google-tag-manager).
* You can now disable focus trapping in the cookie banner when embedding in modals or constrained layouts:

```tsx
<CookieBanner trapFocus={false} />
```

* Next.js URL validation is stricter. Use a valid URL for any configuration values (e.g., backend URL). Environment variables should contain absolute URLs (https preferred) or valid relative paths depending on your deployment.

```ts
export const c15tConfig = {
  backendURL: process.env.NEXT_PUBLIC_C15T_URL,
};
```

## Technical Details

* Core adds GTM integration hooks that respect consent categories before dispatching events.
* React `CookieBanner` now supports `trapFocus={false}` without side effects on keyboard navigation outside the banner.
* Next.js performs additional checks to prevent malformed URLs from being used at runtime.

## Migration

* No breaking changes.
* If your app relied on loosely formatted URLs, update them to valid absolute/relative URLs to pass the new validation.

## 🧪 Tests

* Added assertions around GTM gating based on consent state.
* Verified focus behavior with `trapFocus={false}` to maintain accessibility expectations.
* Expanded URL validation scenarios for Next.js configuration inputs.

## ✨ What's Changed

* feat(core): add Google Tag Manager support by [@BurnedChris](https://github.com/BurnedChris) in [#283](https://github.com/c15t/c15t/pull/283)
* fix(react): allow `trapFocus={false}` in `CookieBanner` by [@KayleeWilliams](https://github.com/KayleeWilliams) in [#291](https://github.com/c15t/c15t/pull/291)
* fix(nextjs): improved URL validation by [@BurnedChris](https://github.com/BurnedChris) in [#284](https://github.com/c15t/c15t/pull/284)
* Version Packages by [@github-actions](https://github.com/features/actions) in [#293](https://github.com/c15t/c15t/pull/293)

Published via commit [b4d53be](https://github.com/c15t/c15t/commit/b4d53be) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.3.2...c15t@1.3.3](https://github.com/c15t/c15t/compare/c15t@1.3.2...c15t@1.3.3)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.4.0 — Ignore Geo, Provider DX, Store Config, A11y, CLI Fixes
URL: https://c15t.com/changelog/1.4.0
Minor release improving developer experience with ignoreGeoLocation and consentCategories, adding a debug-friendly store config prop, enhancing accessibility, and fixing CLI onboarding issues.

## Minor Changes

* feat(core, react): added `ignoreGeoLocation` to provider and store to allow showing the cookie banner during development regardless of geo. Also improved provider props with a new `consentCategories` option (DX-friendly alias for `store.initialGDPRTypes`). ([c7b4ad5](https://github.com/c15t/c15t/commit/c7b4ad5be23baba27c8f97af8c5aec85527986a3))
* feat(core): added `config` prop on the store for better debugging and inspection. ([6eb9a8d](https://github.com/c15t/c15t/commit/6eb9a8d044ecb3cc74fa8e70f60bb9dfac6318bb))

## Patch Changes

* fix(react): add `aria-label` to the cookie banner component to improve accessibility. ([ed5092e](https://github.com/c15t/c15t/commit/ed5092edbc65d1762a1ada37bf50ab61dc8d6046))
* fix(cli): remove unnecessary env import during onboarding for Next.js config generation. ([6eb9a8d](https://github.com/c15t/c15t/commit/6eb9a8d044ecb3cc74fa8e70f60bb9dfac6318bb))
* fix(cli): resolved duplicate package manager prompt during setup. ([37ef4c5](https://github.com/c15t/c15t/commit/37ef4c53c511eb74e3faa4de68ad7876158fa807))
* chore(core/react): small cleanup and provider/store prop alignment. ([e30ffaf](https://github.com/c15t/c15t/commit/e30ffafe872eefe883384d07e1da07ae81660e23))
* chore: additional housekeeping and consistency updates. ([169de72](https://github.com/c15t/c15t/commit/169de720fcd745e5759685f694dbb9a373dbcc96))

## Updated Dependencies

* Updated dependencies \[6eb9a8d]
  * `@c15t/react@1.4.0`

## Usage Notes

* To force the cookie banner to appear during local development outside of regulated regions, enable `ignoreGeoLocation`.
* Prefer `consentCategories` over `store.initialGDPRTypes` for a clearer provider-level configuration.

```tsx
<ConsentManagerProvider
  options={{
    mode: 'c15t',
    backendURL: process.env.NEXT_PUBLIC_C15T_URL,
    ignoreGeoLocation: true,
    consentCategories: ['necessary', 'analytics', 'marketing'],
  }}
/>
```

* Use the store `config` prop to inspect or log runtime settings for debugging.

```ts
createConsentManagerStore({
  config: { verbose: true },
});
```

## ✨ What's Changed

* feat(core, react): added ignoreGeoLocation / provider props improvements — [c7b4ad5](https://github.com/c15t/c15t/commit/c7b4ad5be23baba27c8f97af8c5aec85527986a3)
* fix(cli): remove env import — [6eb9a8d](https://github.com/c15t/c15t/commit/6eb9a8d044ecb3cc74fa8e70f60bb9dfac6318bb)
* fix(react): add aria label to cookie banner — [ed5092e](https://github.com/c15t/c15t/commit/ed5092edbc65d1762a1ada37bf50ab61dc8d6046)
* fix(cli): asks for pkg manager twice — [37ef4c5](https://github.com/c15t/c15t/commit/37ef4c53c511eb74e3faa4de68ad7876158fa807)
* chore(core/react): provider/store cleanup — [e30ffaf](https://github.com/c15t/c15t/commit/e30ffafe872eefe883384d07e1da07ae81660e23)
* misc: housekeeping — [169de72](https://github.com/c15t/c15t/commit/169de720fcd745e5759685f694dbb9a373dbcc96)

Published via commit [e0026b4](https://github.com/c15t/c15t/commit/e0026b4) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.3.3...c15t@1.4.0](https://github.com/c15t/c15t/compare/c15t@1.3.3...c15t@1.4.0)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.4.1 — Next.js: Custom c15t Headers for Initial Fetch
URL: https://c15t.com/changelog/1.4.1
Patch release adding custom c15t headers to Next.js initial data fetch, enabling backend provider overrides and more reliable initialization.

## Patch Changes

* 34d2a46: fix(nextjs): add custom c15t headers to initial data fetch

## Updated Dependencies

* `@c15t/react@1.4.1`

## ✨ What's Changed

* fix(nextjs): add custom c15t headers to initial data fetch in Next.js by [@github-actions](https://github.com/features/actions) in [#307](https://github.com/c15t/c15t/pull/307)

Published via commit [6d4ccf1](https://github.com/c15t/c15t/commit/6d4ccf1) by [@github-actions](https://github.com/features/actions)

**Full Changelog**: [c15t@1.4.0...c15t@1.4.1](https://github.com/c15t/c15t/compare/c15t@1.4.0...c15t@1.4.1)

<ContributorBlock usernames={["KayleeWilliams"]} />

# v1.4.2 — Indonesian Translations, Provider Render Fixes, URL Normalization
URL: https://c15t.com/changelog/1.4.2
Patch release adding Bahasa Indonesia translations, improving provider rendering to prevent duplicate requests, normalizing URLs to remove trailing slashes, correcting consent logic, and refining banner animations. Includes dependency updates, caching improvements, and expanded tests.

## New Features

* Added Bahasa Indonesia (ID) translations for consent and privacy-related UI.

## Bug Fixes

* Improved provider rendering to prevent duplicate requests.
* Fixed URL normalization to consistently remove trailing slashes.
* Corrected consent logic to grant consent when none is required.
* Enhanced cookie banner animation timing for smoother transitions.

## Chores

* Updated multiple dependencies to latest canary versions.
* Improved internal caching for consent managers and stores.
* Added utility to clear consent manager cache for testing.

## 🧪 Tests

* Expanded coverage for URL normalization and consent manager behavior.
* Ensured test isolation by clearing caches before each test.

## ✨ What's Changed

* See related PRs: [#311](https://github.com/c15t/c15t/pull/311), [#312](https://github.com/c15t/c15t/pull/312), [#309](https://github.com/c15t/c15t/pull/309)

**Full Changelog**: [c15t@1.4.1...c15t@1.4.2](https://github.com/c15t/c15t/compare/c15t@1.4.1...c15t@1.4.2)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.4.3 — Theme Inheritance Fixes for Provider-Scoped Themes
URL: https://c15t.com/changelog/1.4.3
Patch release ensuring provider-level themes set in ConsentManagerProvider are correctly inherited by CookieBanner, ConsentManagerDialog, and ConsentManagerWidget for consistent styling.

## Patch Changes

* fix(react): ensure provider `theme` is applied to `ConsentManagerWidget` and `ConsentManagerDialog` ([357dcd7](https://github.com/c15t/c15t/commit/357dcd7648ff3adb4799b06fe788de06a529f1c8))
* fix(react): ensure `CookieBanner` correctly inherits provider `theme` and global `classNames`/`styles` ([c463eda](https://github.com/c15t/c15t/commit/c463eda67126d7aefa483ea46ffdd7aa24462559))

## Usage Notes

* No changes required for apps already passing a `theme` to `ConsentManagerProvider` — components now consistently inherit the provider theme.

```tsx
<ConsentManagerProvider
  options={{
    mode: 'c15t',
    backendURL: process.env.NEXT_PUBLIC_C15T_URL,
    theme: {
      classNames: 'rounded-lg shadow-md',
      styles: { '--c15t-accent': '#4f46e5' },
    },
  }}
>
  <CookieBanner />
  <ConsentManagerDialog />
  <ConsentManagerWidget />
</ConsentManagerProvider>
```

## ✨ What's Changed

* Theme inheritance fixes in React components: [357dcd7](https://github.com/c15t/c15t/commit/357dcd7648ff3adb4799b06fe788de06a529f1c8), [c463eda](https://github.com/c15t/c15t/commit/c463eda67126d7aefa483ea46ffdd7aa24462559)

**Full Changelog**: [c15t@1.4.2...c15t@1.4.3](https://github.com/c15t/c15t/compare/c15t@1.4.2...c15t@1.4.3)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.4.4 — Theme Inheritance Stability and Maintenance Updates
URL: https://c15t.com/changelog/1.4.4
Patch release fixing theme inheritance in ConsentManager and related components, plus dependency updates and stronger tests to prevent regressions.

## Bug Fixes

* Ensure `ConsentManager` and related components correctly inherit theme properties from `ConsentManagerProvider` for consistent styling.

## Chores

* Updated internal dependencies for compatibility and performance.

## 🧪 Tests

* Enhanced test coverage for theme inheritance to prevent regressions.

## ✨ What's Changed

* Theme inheritance fixes and maintenance updates:
  * [e9ecfa5](https://github.com/c15t/c15t/commit/e9ecfa5cd9035fa8903fc6f1e7b13f3552c3e819)
  * [c44c22a](https://github.com/c15t/c15t/commit/c44c22a79f32ec9d3900856535a2256a9328463c)
  * [e3b9caf](https://github.com/c15t/c15t/commit/e3b9caf36611582f4955921ca3fb65c1ecbc4b1e)
  * [f6a3e5f](https://github.com/c15t/c15t/commit/f6a3e5fe6948fbf4b4a3d02fb3f09adca180bca2)

**Full Changelog**: [c15t@1.4.3...c15t@1.4.4](https://github.com/c15t/c15t/compare/c15t@1.4.3...c15t@1.4.4)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.5.0 — Next.js Pages Support, GDPR Button Order, Backend Enhancements
URL: https://c15t.com/changelog/1.5.0
Minor release adding Next.js Pages Directory support and updating cookie banner button order for GDPR guidance, alongside backend and integration improvements.

## New Features

* Next.js: Added support for the **Pages Directory** to integrate consent components in classic Next.js apps.
* React: Updated cookie banner button order to give equal prominence to Accept and Reject for GDPR alignment.

## Package Updates

* `@c15t/nextjs@1.5.0`: pages support, SSR-ready components, and type-safe client integrations.
* `@c15t/backend@1.5.0`: internal improvements across adapters and APIs.

## ✨ What's Changed

* Commits included in this release:
  * [35f052c](https://github.com/c15t/c15t/commit/35f052c8d758322f26a6bd7f93fdf4da20bb093f)
  * [35b5fc3](https://github.com/c15t/c15t/commit/35b5fc3bfd512aacfa295893be8ac129cac0679d)
  * [5decee3](https://github.com/c15t/c15t/commit/5decee32b91168bd85aefe45f25f9ed0b519312d)
  * [230f749](https://github.com/c15t/c15t/commit/230f74917265927b9ae2a5c52c2e083aec5e90a5)
  * [bacff72](https://github.com/c15t/c15t/commit/bacff72be07e26f7c597b5f700cf389e058e5807)

**Full Changelog**: [c15t@1.4.4...c15t@1.5.0](https://github.com/c15t/c15t/compare/c15t@1.4.4...c15t@1.5.0)

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams"]} />

# v1.6.0 – New Docs, Rebuilt Self-Hosting Backend, Better Callbacks, and More
URL: https://c15t.com/changelog/1.6.0
Minor release with a rebuilt self-hosting backend, a brand new docs site, improved consent checking, and callback improvements.

## ✨ New Features

### Better Docs, Better Consent

You did not consent to bad docs. Over the last six months we have been moving incredibly fast, and it felt like the right moment to invest in making sure our documentation lives up to the same standard.

The new site comes with improved navigation, better search, and comprehensive guides for every package and framework. We have also surfaced a lot of hidden features and design details that were easy to miss before.

### Rebuilt Self-Hosting Backend

The old backend was showing its age and could be difficult to implement. We have rebuilt the self-hosting backend from the ground up and moved from our own database adapters to [FumaDB](https://github.com/fuma-nama/fumadb).

This unlocks support for more databases and ORMs such as TypeORM, Microsoft SQL Server, and MongoDB, with more coming soon.

If you have an existing backend v1 implementation, review the current [self-host quickstart](/docs/self-host/quickstart) and [database setup guide](/docs/self-host/guides/database-setup).

⚠️ **Heads-up:** support for the old backend will be removed in the next major release.

### Improved Consent Checking

We’ve added a new `has()` method to the API for checking consent. It is available across all frameworks and supports both simple and complex checks.

```ts
// Simple check
const hasAnalytics = has('measurement');
const hasMarketing = has('marketing');

// Complex check
const hasAnalyticsAndMarketing = has({
  and: ['measurement', 'marketing'],
});

const hasEitherAnalyticsOrMarketing = has({
  or: ['measurement', 'marketing'],
});
```

See the [API documentation](/docs/frameworks/javascript/api/checking-consent) for full details.

**Deprecated:** `hasConsentFor()` and `getEffectiveConsents()`. These will be removed in the next major release.

### Better Callbacks

We’ve overhauled the callback system to make it simpler and faster, while removing unused callbacks.

Current callbacks are:

* `onBannerFetched`
* `onConsentSet`
* `onError`

Performance has also been improved (see issue [#369](https://github.com/c15t/c15t/issues/369)), resulting in better INP scores when using callbacks or GTM.

### RTL Support

c15t now supports RTL languages in its prebuilt components, so you can use them in any language.

### README Updates

All package README files have been refreshed with:

* Improved formatting and structure
* Clearer examples and usage instructions
* More comprehensive installation guides

## 🐛 Bug Fixes & Improvements

### **@c15t/react**

* Fixed a bug where the dialog overlay was not showing by default.
* Improved the export of compound components, which can now be imported directly from the package.

### **c15t**

* Deprecated unused methods and properties to simplify the API.
* Improved fallback handling when the `showConsentBanner` API request fails.

### **@c15t/translations**

* Added Hebrew translations.

## 📦 Dependency Updates

### **@c15t/backend**

* Updated to Zod 4
* Updated ORPC to 1.8
* Updated OpenTelemetry to latest

<ContributorBlock usernames={["BurnedChris", "KayleeWilliams", "guy-borderless"]} title="Thank you to our contributors" />

# v1.6.1 - React Scroll Lock Fix
URL: https://c15t.com/changelog/1.6.1
Patch release fixing a bug where the scroll lock persisted after the dialog has been dismissed.

## 🐛 Bug Fixes & Improvements

### **@c15t/react**

Fixed the scroll lock persisting after the dialog has been dismissed.

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v1.7.0 - Script Loader & iFrame Blocking
URL: https://c15t.com/changelog/1.7.0
Minor release with a new approach to script loader and iFrame blocking.

## ✨ New Features

### Script Loader

We're deprecating the tracking blocker and replacing it with a new approach to managing script loading based on consent.

The [script loader](/docs/frameworks/javascript/script-loader) will handle the loading, unloading and life cycle of all scripts based on consent.

To make using the script loader easier, we've added a new `@c15t/scripts` package that contains prebuilt scripts for common analytics and marketing tools as well as introduced [integration guides](/docs/integrations) for integrating c15t with your tools such as Google Tag Manager (GTM) and PostHog.

```ts
import { ConsentManagerProvider } from '@c15t/react';
import { googleTagManager } from '@c15t/scripts/google-tag-manager';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <ConsentManagerProvider options={{
      scripts: [
        googleTagManager({
          id: 'GTM-XXXXXXX',
        }),
        {
          id: 'example',
          src: 'https://analytics.example.com/script.js',
          category: 'analytics',
        }
      ]
    }}>
      {children}
    </ConsentManagerProvider>
  );
}
```

⚠️ **Heads-up:** the current tracking blocker will be removed in c15t v2.0. It is automatically disabled when using the script loader in v1.7.0.

See the [Script Loader documentation](/docs/frameworks/react/script-loader) for full details.

### iFrame Blocking

Stopping iframes such as YouTube embeds from loading until consent is given is important for privacy and compliance. This update introduces two new ways to block iframes:

* Frame Component (React - Recommended): This is a React component that conditionally renders content and provides a pre-built/customizable placeholder providing great UX. [Learn more about the Frame component](/docs/frameworks/react/components/frame)
* Headless: This is a headless implementation that does not render any DOM elements. It only manages the src/data-src attributes of existing iframe elements.

```ts
import { Frame } from '@c15t/react';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <Frame category="marketing" className="aspect-video w-full">
      <iframe
        title="Cool Duck Video"
        src="https://www.youtube.com/embed/mQJ6q1ZCzsg"
        width="100%"
        height="100%"
      />
    </Frame>
  );
}
```

See the [iFrame Blocking documentation](/docs/frameworks/react/iframe-blocking) for full details.

## Dynamic Consent Categories

Consent categories are now dynamic and update based on the content of the page. For example, if you set the categories to `['necessary', 'marketing']` but there is an script (via the script loader) with the category `['experience']`, the consent banner will show the `experience` category as well.

This logic is applied to the iframe blocking as well via the `data-category` attribute and the Frame component in React.

## New Examples!

We've moved our examples to a new repository, [examples](https://github.com/c15t/examples). As well as added more detailed examples instead of barebones examples.

Currently the in-depth examples are only available for the React & Next.js frameworks but we'll be updating the JavaScript examples soon.

![New Examples](https://qawfa2yzgrix7k7v.public.blob.vercel-storage.com/changelogs/1.7.0-New-Examples.png)

## 🐛 Bug Fixes & Improvements

### **@c15t/nextjs**

* Fixed both headless exports for Next.js

### **@c15t/react**

* Fixed missing CSS variables for font-family & line-height for the cookie banner
* Improved button hover transitions when changing theme
* Fixed missing "use client" causing build errors in Next.js 14

### **@c15t/backend**

* Fixed handling of multiple subdomains e.g. `foo.bar.example.com`

### **@c15t/cli**

* Corrected spelling of "GitHub" in CLI commands
* Generated React & Next.js code now follows a new pattern for improved DX

### **@c15t/logger**

* Added a new logger package for logging errors and warnings for use in the CLI & backend to replace external logging package.

### **@c15t/translations**

* Added translations for the Frame component

<ContributorBlock usernames={["KayleeWilliams", "BurnedChris"]} title="Thank you to our contributors" />

# v1.7.1 - CLI Improvements & Bug Fixes
URL: https://c15t.com/changelog/1.7.1
Patch release with CLI improvements including bun support and bug fixes.

## 🐛 Bug Fixes & Improvements

### **@c15t/cli**

* Added support for bun package manager
* Added install @c15t/scripts prompt
* Fixed default log level
* Fixed Next.js Pages component creation in components directory
* Updated various dependencies

### **@c15t/nextjs**

* Fixed missing InitialDataPromise type export for pages
* Fixed certain headers missing on non-rewrite requests
* Fixed ClientSideOptionsProvider causing infinite re-renders in certain cases
* Updated dependencies

### **@c15t/react**

* Fixed FOUC & Hydration issue with Frame component

### **c15t**

* Updated dependencies

### **@c15t/node-sdk**

* Updated dependencies

### **@c15t/backend**

* Updated dependencies

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v1.8.0 - Cross-Subdomain Consent, Legal Links, User Identification & EU Languages
URL: https://c15t.com/changelog/1.8.0
Feature release adding cross-subdomain consent persistence via cookies, configurable legal links in components, user identification tracking, and comprehensive language support with all 24 EU official languages.

## ✨ New Features

### Hybrid Cookie/LocalStorage Approach for consent

This update changes how we store consent in the browser, from using local-storage only to a hybrid approach with both cookies & local storage.

Cookies will now allow you to check consent on the server side & persist consent across subdomains e.g. `dashboard.example.com` & `example.com`.

To enable this, you use the `storageConfig` option.

```tsx
<ConsentManagerProvider
  options={{
    storageConfig: {
      storageKey: 'my-consent', // Custom override for local storage + cookie key 
      crossSubdomain: true,
    },
  }}
>
```

Existing consent under the old `privacy-consent-storage` key will be automatically migrated to the new `c15t` key.

### Configurable Legal Links

You can now add various legal links to the consent manager. This can be used to display links in the consent banner, dialog, etc.

```tsx
<ConsentManagerProvider
  options={{
    legalLinks: {
      privacyPolicy: { href: '/privacy-policy' },
      termsOfService: { href: '/terms-of-service' },
      cookiePolicy: { href: '/cookie-policy' },
    },
  }}
>
```

You can filter what legal links you want to display (if any) on the pre-made components by passing the `legalLinks` prop.

```tsx
// Show no legal links (default)
<CookieBanner />

// Show both cookie policy and terms of service
<CookieBanner legalLinks={['cookiePolicy', 'termsOfService']} />

```

<div style={{ display: 'flex', gap: 16, maxHeight: 250, alignItems: 'flex-start', overflow: 'visible' }}>
<img src="https://qawfa2yzgrix7k7v.public.blob.vercel-storage.com/changelogs/1.8.0-Legal-Links-Banner.png" alt="Legal Links Banner" style={{ maxHeight: 250, objectFit: 'contain', borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }} />

<img src="https://qawfa2yzgrix7k7v.public.blob.vercel-storage.com/changelogs/1.8.0-Legal-Links-Dialog.png" alt="Legal Links Dialog" style={{ maxHeight: 250, objectFit: 'contain', borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }} />
</div>

### User Identification

We've enabled user identification in the consent manager. This allows you to link a user's ID to a consent record both before & after consent is given.

An external ID can be set in various ways:

```tsx
<ConsentManagerProvider
  options={{
    user: {
      id: 'usr_foobar',
      identityProvider: 'better-auth',
    }
  }}
>

// Or via the `identifyUser` method in the Store
const { identifyUser } = useConsentManager();

identifyUser({
  id: 'usr_foobar',
  identityProvider: 'better-auth',
});
```

This change also brings a new endpoint to the backend: `PATCH /consent/identify`. So you'll need to update your backend to support this new endpoint.

### All 24 Official Languages of the European Union

We've added support for all 24 official languages of the European Union as well as additional languages to the translations package bringing the total number of supported languages to 33.

Current languages include:

||||||||
|--|--|--|--|--|--|--|
|Bulgarian (bg)|Czech (cs)|Danish (da)|German (de)|Greek (el)|English (en)|Spanish (es)|
|Estonian (et)|Finnish (fi)|French (fr)|Irish (ga)|Hebrew (he)|Croatian (hr)|Hungarian (hu)|
|Indonesian (id)|Italian (it)|Lithuanian (lt)|Latvian (lv)|Maltese (mt)|Dutch (nl)|Polish (pl)|
|Portuguese (pt)|Romanian (ro)|Slovak (sk)|Slovenian (sl)|Swedish (sv)|Chinese (zh)|Welsh (cy)|
|Icelandic (is)|Luxembourgish (lb)|Norwegian Bokmål (nb)|Norwegian Nynorsk (nn)|Romansh (rm)|||

### Script Loader Target Location

The script loader now supports specifying the target location of the script in the DOM. This is useful for scripts that need to be loaded in the body of the document.

This can be done with the `target` option, which defaults to `head` if not specified.

```tsx
{
  id: 'example',
  src: 'https://analytics.example.com/script.js',
  category: 'analytics',
  target: 'body',
}
```

### Overriding Country, Region & Language

You can now override the country, region & language of the consent manager. This overrides the headers sent to the backend, allowing for better testing, this also works in offline mode.

```tsx
<ConsentManagerProvider
  options={{
    overrides: {
      country: "DE",
      region: "BE",
      language: "de",
    }
  }}
>
```

## 🐛 Bug Fixes & Improvements

### **@c15t/scripts**

* Added new [Databuddy](https://c15t.com/docs/integrations/databuddy) prebuilt script
* Updated dependencies

### **@c15t/nextjs**

* Ensure all exports from core are re-exported
* Updated dependencies

### **@c15t/react**

* Ensure all exports from core are re-exported
* Updated dependencies

### **c15t**

* Updated dependencies

### **@c15t/translations**

* Updated dependencies

### **@c15t/scripts**

* Updated dependencies

### **@c15t/cli**

* Updated dependencies

### **@c15t/backend**

* Updated dependencies

### **@c15t/node-sdk**

* Updated dependencies

### **@c15t/dev-tools**

* Updated dependencies

<ContributorBlock usernames={["KayleeWilliams", "BurnedChris", "izadoesdev", "djmisha", "davidturnbull"]} title="Thank you to our contributors" />

# v1.8.2 - React Bug Fixes
URL: https://c15t.com/changelog/1.8.2
Patch release with bug fixes and improvements.

## 🐛 Bug Fixes & Improvements

### **c15t**

* Added ability to disable c15t with the `enabled` prop. c15t will grant all consents by default when disabled as well as loading all scripts by default. Useful for when you want to disable consent handling but still allow the integration code to be in place.

### **@c15t/react**

* Fixed Frame component CSS overriding
* Fixed legal links using the asChild slot causing multi-child error

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v1.8.3 - Experimental Global Privacy Control Support & Bug Fixes
URL: https://c15t.com/changelog/1.8.3
Patch release with experimental Global Privacy Control support and bug fixes.

## 🐛 Bug Fixes & Improvements

### **c15t**

* Added `experimental_globalPrivacyControl` option. This will respect the Global Privacy Control signal in opt-out jurisdictions, like California (CCPA). This is set to `false` by default.
* Fixed auto-grant ignoring existing consents.
* Fixed offline mode ignoring overrides.
* Fixed auto-grant not updating selected consents.

### **@c15t/react**

* Fixed custom styling support for dialog and accordion.

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.0 - New Styling System, Policy Packs, Backend v2 & More
URL: https://c15t.com/changelog/2.0.0
Stable release notes for c15t 2.0, covering the token-based styling system, policy packs, GPC, IAB TCF 2.3, bundled docs, c15t/skills, dev tools, backend v2, migration tooling, and the prebuilt UI.

c15t 2.0 is a major release across all of our packages. It ships a new styling model, a policy-driven consent system, a rewritten backend, expanded framework integrations, and a streamlined migration and setup path.

## Highlights

* [New token-based styling system](#new-token-based-styling-system)
* [Policy packs and GPC support](#policy-packs-and-gpc-support)
* [IAB TCF 2.3 support](#iab-tcf-23-support)
* [Improved Next.js DX and optimizations](#improved-nextjs-dx--optimizations)
* [Script loading, network blocking, and integrations](#script-loading-network-blocking-and-integrations)
* [Backend v2](#backend-v2)
* [Migration and setup with c15t CLI](#migration-and-setup-with-c15t-cli)
* [Dev tools and diagnostics](#dev-tools-and-diagnostics)
* [Bundled docs and c15t skills](#bundled-docs-and-c15t-skills)
* [New hosted infrastructure for Inth.com](#new-hosted-infrastructure-for-inthcom)
* [Apache 2.0 licensing](#apache-20-licensing)
* [onConsentChanged callback](#onconsentchanged-callback)
* [Prebuilt branding](#prebuilt-branding)
* [Additional changes in 2.0](#additional-changes-in-20)

## New token-based styling system

2.0 uses a styling model built around semantic design tokens instead of deeply nested theme objects. Now style colors, typography, spacing, radius, motion, and surface-level component treatments from one token system. Slots are also available when you want to apply a classname or style to specific component such as the banner's footer.

We have also moved from the css-in-js approach of c15t 1.0 to CSS stylesheet imports e.g.`@c15t/react/styles.css` and `styles.tw3.css`, this improves performance on the main thread and ensures the styling is predictable. Build tools like Turbopack split up Javacript into different chunks causing ordering issues, however these tools consolidate CSS to avoid the CSS ordering issues.

→ [React Styling](/docs/frameworks/react/styling/overview) · [Next.js Styling](/docs/frameworks/next/styling/overview) · [ConsentBanner](/docs/frameworks/react/components/consent-banner) · [ConsentDialog](/docs/frameworks/react/components/consent-dialog) · [ConsentWidget](/docs/frameworks/react/components/consent-widget)

## Policy packs and GPC support

Every organization is different, we designed 1.0 to be a "one-size-fits-all" system but that is not the case. Some may want to only care about consent in the US, or others want to souley focus on the EU-market and want to show an opt-in banner everywhere.

Policy packs define regional consent behavior explicitly. c15t resolves the active policy at runtime from an ordered set of regional policies.

* Built-in presets cover Europe opt-in, Europe IAB, California opt-in, California opt-out, Quebec opt-in, and world-no-banner flows
* Resolution follows a fixed order: region, country, fallback, then default
* Per-policy GPC support means opt-out regions such as California can honor Global Privacy Control without forcing the same behavior onto unrelated policies
* Fallback policies protect strict regions even when geo headers are missing
* Policy fingerprints automatically re-prompt users when consent-affecting policy semantics change
* Snapshot tokens bind consent writes to the policy decision returned by `/init`
* `inspectPolicies()` helps catch misconfiguration before deployment

→ [React Policy Packs](/docs/frameworks/react/policy-packs) · [Next.js Policy Packs](/docs/frameworks/next/policy-packs) · [Policy Packs Concepts](/docs/frameworks/react/concepts/policy-packs) · [Self-Host Guide](/docs/self-host/guides/policy-packs)

## New hosted infrastructure for Inth.com

As part of 2.0's release we have upgraded the infrastructure used by customers on `inth.com`. This has many benefits such as being faster & improved bot detection, so your usage requests are more accurate to the human-visitors.

Currently this is under the new `inth.app` domain, you can see this in the dashboard for your project as the URL is slightly different than the layout of the previous one. Legacy `c15t.dev` will move over to the new infrastructure in the course of the coming weeks with 0 downtime

## IAB TCF 2.3 support

IAB TCF 2.3 is a consent framework used for programatic advertising, they are notably different than standard banners and have strict UI-requirements, including the "Us and our 1028 partners" text.

c15t now supports this framework and has pre-built UI for the `IABConsentBanner` and `IABConsentDialog` and is available via Policy Packs and a runtime ad-on `@c15t/iab` (so your client-bundle doesn't get bloated if you don't need it).

To run IAB TCF 2.3 you need to register as a CMP with [IAB Europe](https://iabeurope.eu/transparency-consent-framework/) which has a registration fee. For user's hosting with Inth you do not need to do this step and instead can use IAB via a project add-on.

→ [React IAB Overview](/docs/frameworks/react/iab) · [Next.js IAB Overview](/docs/frameworks/next/iab) · [Self-Host IAB Guide](/docs/self-host/guides/iab-tcf)

## Migration and setup with c15t cli

The c15t CLI has been overhauled internally and includes new features:

* Migration Codemods (v1 -> v2)
* Improved scaffolding with component generation selection, script setup & more.
* Setup c15t/skills

It's worth noting that there is a lot of breaking changes in this release so a fresh start might be ideal so you can follow our recommended practices particularly for `@c15t/nextjs`.

→ [React Quickstart](/docs/frameworks/react/quickstart) · [Next.js Quickstart](/docs/frameworks/next/quickstart) · [Self-Host Quickstart](/docs/self-host/quickstart) · [AI Agents](/docs/ai-agents)

## Bundled docs and c15t skills

Agents are prevalient in most of our day-to-day activities as a developer. To leverage this c15t now bundles version-matched docs directly with the published packages under `docs/**`.

* `node_modules/c15t/docs/`
* `node_modules/@c15t/react/docs/`
* `node_modules/@c15t/nextjs/docs/`
* `node_modules/@c15t/backend/docs/`

This allows agents can read the docs for the exact installed version. Giving the agent full-knowledge of c15t such as how to customize, set up Meta Pixel, and optimize it.

You can install c15t skills today with `npx skills add c15t/skills`.

→ [AI Agents](/docs/ai-agents)

## Apache 2.0 licensing

c15t 2.0 changes the project license from `GPL-3.0-only` to `Apache-2.0`.

This makes the project easier to evaluate and adopt in a wider range of commercial and internal environments, while keeping the standard Apache 2.0 attribution and patent terms.

→ [License](/docs/oss/license) · [Contributing](/docs/oss/contributing)

## Dev tools and diagnostics

2.0 ships `@c15t/dev-tools`, a floating development panel for inspecting consent behavior in real time.

* inspect consent state, geo context, language, and initialization data
* inspect policy resolution with full match traces
* simulate region and GPC overrides during development
* inspect policy actions and consent UI decisions
* script lifecycle activity and manifest telemetry

The panel gives teams a way to inspect policy behavior, consent state, and script gating without stitching together console logs and custom debug code.

## onConsentChanged callback

We have added a new callback: `onConsentChanged`. This runs explicitly on consent saves that actually change persisted preferences.

→ [React DevTools](/docs/frameworks/react/components/dev-tools) · [Next.js DevTools](/docs/frameworks/next/components/dev-tools) · [React Callbacks](/docs/frameworks/react/callbacks) · [Next.js Callbacks](/docs/frameworks/next/callbacks)

## Improved Next.js DX & Optimizations

`@c15t/nextjs` now has a simpler default architecture. The provider is client-side by default, so callbacks and consent UI can stay together instead of being split across separate wrapper components. When you do want server-preloaded data, the same provider can accept `ssrData` from `fetchInitialData()`.

Optimization is also clearer now:

* Use a same-origin `/api/c15t` rewrite as the baseline for browser requests. This reduces extra DNS/TLS setup, hides the backend origin, and makes blocking less likely.
* Use `C15tPrefetch` on static routes. It starts `/init` before hydration, and matching prefetched data is consumed automatically during first initialization.
* Use `fetchInitialData()` on dynamic routes. It starts `/init` in a Server Component and streams the result into the provider, but it opts the route into dynamic rendering via `next/headers`.

As a rule of thumb: rewrites for everyone, `C15tPrefetch` for static routes, `fetchInitialData()` for dynamic routes. In our production benchmarks, these strategies improved script and banner startup by roughly 30-90% compared with plain client-only init.

→ [Next.js Quickstart](/docs/frameworks/next/quickstart) · [Next.js Optimization](/docs/frameworks/next/optimization) · [Next.js Server-Side](/docs/frameworks/next/server-side)

## Script loading, Network Blocking and integrations

The integrations from `c15t/scripts` have been re-written in a manifest format which has a range of benefits including:

* More predictable lifecycle. 2.0 has explicit phases like bootstrap, install, afterLoad, onLoadGranted, and onConsentDenied instead of burying sequencing inside ad hoc callback code
* Safer and easier to validate. Manifests are schema-versioned and checked before execution, and the compiler enforces things like interpolation correctness and only one loadScript step in install.
* Less raw inline JS. The old Meta Pixel helper literally shipped the vendor bootstrap as a big textContent string; the new one expresses the same behavior as defineStubFunction, callGlobal, and loadScript steps. That is easier to read, test, and reason about.
* Better reuse and future server support.
* Better debugging. The runtime emits manifest phase and step telemetry, so DevTools can show phase-level activity instead of you reverse-engineering callback order from custom code.
* Cleaner vendor parity. Google Consent Mode is modeled directly as manifest metadata (consentMapping, consentSignal) rather than each helper manually doing the same mapping work in slightly different callback code.

Instead of handling an onDelete callback for every script to clean it up, the page is now reloaded to clear already-loaded third-party JavaScript when previously granted consent is revoked. This is the best way to handle 3rd party cookies due to the flimsy nature of trying to tear-down every script as the JavaScript is already on the page.

In 1.0 we shipped a massive list of domains & associated categories, this wasn't a smart idea as it increased bundle size but also made it more of a black-box when enabled. In 2.0 we've remade it as an actual network blocker, not a black box, removing the pre-determined list for your own rules to go in, by default no network requests are blocked. It is still prefered, when possible to use the script loader as controlling what Javascript runs on your site is better than blocking it.

→ [React Script Loader](/docs/frameworks/react/script-loader) · [Next.js Script Loader](/docs/frameworks/next/script-loader) · [Integrations Overview](/docs/integrations/overview) · [React Network Blocker](/docs/frameworks/react/network-blocker) · [Next.js Network Blocker](/docs/frameworks/next/network-blocker)

## Backend v2

We rewrote the backend seeing a 60% bundle-size reduction on a Cloudflare Worker, reducing start-up cost and keeping it suited for edge deployments. We did this by replacing ORPC & Zod with Valibot and Hono, as we did not need the majorty of features in the previous stack. It also comes with improved OpenTelemetry support.

It includes a new subject-centric API that makes more sense as the data-subject (user) is the core thing, not consents.

Other backend changes:

* a root `/` endpoint for simpler health checks
* `/status` health coverage improvements, including database checks
* flattened backend entrypoints for TypeScript DX

→ [Self-Host Quickstart](/docs/self-host/quickstart) · [API Endpoints](/docs/self-host/api/endpoints) · [Self-Host Policy Packs](/docs/self-host/guides/policy-packs)

## Prebuilt branding

We've updated the prebuilt UI's branding to be tags attahed to the banner, in the dialog footer like before. The "Secured by" text has also been localised into every language we support.

→ [ConsentBanner](/docs/frameworks/react/components/consent-banner) · [ConsentDialog](/docs/frameworks/react/components/consent-dialog) · [ConsentWidget](/docs/frameworks/react/components/consent-widget) · [ConsentDialogTrigger](/docs/frameworks/react/components/consent-dialog-trigger)

## Additional changes in 2.0

2.0 also includes a number of smaller but important product, UI, and packaging changes:

* shared UI primitives now power consent surfaces through `@c15t/ui/primitives`, with adapters for Solid, Vue, and Svelte. Allowing for future c15t packages for those frameworks.
* the new `PreferenceItem` primitive unifies several expandable-row patterns used across the consent UI
* fixed-position consent surfaces avoid horizontal overflow and clipped dialog content on mobile viewports
* `prefers-reduced-motion` is respected throughout the shipped UI
* package declaration output moved out of runtime bundles into `dist-types/` for publish artifacts and Vite compatibility
* translation-facing APIs were renamed from `translations` to `i18n`
* hosted/offline terminology uses `hosted` instead of `c15t` mode

Taken together, these changes make 2.0 a full update to the runtime model, policy system, backend architecture, integration ergonomics, and developer tooling.

## Breaking Changes

### Styling system v1 removed

The legacy nested theme keys and older per-component styling model are replaced by the new token-based styling system. Customizations should now flow through tokens, slots, CSS variables, class overrides, compound components, or fully headless usage.

### Provider options flattened

The old `react: { ... }` wrapper is gone. UI options such as `theme`, `colorScheme`, and `disableAnimation` now live at the provider level.

### Backend v1 removed

The old backend implementation and `/v1` routes are no longer part of 2.0. The current backend surface is the v2 architecture centered around `c15tInstance()` and Fetch-style handlers.

### New API: `/show-consent-banner` replaced with `/init`

Initialization now flows through `/init`, which returns the consent runtime payload, geo context, translations, and policy data, as well as a new subject-centric API

### Consent UI state normalized around `activeUI`

`showPopup`, `isPrivacyDialogOpen`, `setShowPopup()`, and `setIsPrivacyDialogOpen()` are replaced by the `activeUI` state and `setActiveUI()` API.

### Component names updated

The prebuilt component names are now clearer:

|v1|v2|
|--|--|
|`CookieBanner`|`ConsentBanner`|
|`ConsentManagerDialog`|`ConsentDialog`|
|`ConsentManagerWidget`|`ConsentWidget`|

### `gdprTypes` renamed to `consentCategories`

Consent categories are no longer framed as GDPR-only. The `initialGDPRTypes` and `gdprTypes` options are replaced by `consentCategories`.

### Tracking blocker replaced with network blocker

The legacy tracking blocker is replaced by the network blocker, which intercepts `fetch` and `XMLHttpRequest` calls using consent-aware domain rules.

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.0-rc.0 — New Styling System, IAB TCF, Dev Tools, Backend v2 & More
URL: https://c15t.com/changelog/2.0.0-rc.0
Release candidate introducing a token-based styling system, IAB TCF 2.3 support, dev tools, backend v2, network blocker, GPC support and a complete documentation overhaul.

It's been almost a year since we first started work on c15t, 2.0 is the implementation of the past year of lessons we've learned. It ships a new token-based styling system, full IAB TCF 2.3 support, a dedicated dev-tools panel, a rewritten backend. Every component has been renamed for clarity, and the entire documentation has been rewritten.

## Highlights

* [New token-based styling system](#new-styling-system) replacing the v1 nested theme keys
* [IAB TCF 2.3 CMP support](#iab-tcf-23-support) with TC String generation and `__tcfapi`
* [Dev Tools panel](#dev-tools) for inspecting consent state in development
* [Backend v2](#backend-api-v2) with `c15tInstance()`, valibot+hono, and `/docs` endpoint
* [Subject-centric API](#subject-centric-api-replaces-consent-identifyverify) replacing consent identify/verify
* [OpenTelemetry instrumentation](#opentelemetry-instrumentation) with automatic PII stripping
* [New CLI](#new-cli) with in-depth quickstarts for scripts and theming
* [Network blocker](#network-blocker) replacing the old tracking blocker
* [Backend cache adapters](#backend-cache-adapters) for Cloudflare KV, Upstash Redis, and in-memory
* [Improved script handling](#improved-script-handling) with automatic page reload on revocation
* [Consent Dialog Trigger](#consent-dialog-trigger) for resurfacing the consent UI
* [Improved Next.js DX](#improved-nextjs-dx) with cleaner App Directory support

## Breaking Changes

### Styling System v1 Removed

The legacy deeply-nested theme keys and per-component CSS variables have been removed. You must migrate to the new [token-based styling system](/docs/frameworks/react/styling/overview).

### Flattened Provider Options

The `react: { ... }` configuration object in `ConsentManagerProvider` has been removed. All UI options (`theme`, `colorScheme`, `disableAnimation`) are now top-level provider props.

### Backend v1 Removed

The deprecated v1 backend implementation and `/v1` routes have been removed. The former v2 contracts, handlers, and types are now the top-level backend entrypoints. See the [self-host quickstart](/docs/self-host/quickstart) for the current API surface.

### `/show-consent-banner` Replaced with `/init`

The endpoint has been renamed to better reflect its purpose — it returns geo data, consent info, and translations during initialization. Update any custom integrations to use [`/init`](/docs/self-host/api/endpoints).

### `showConsentBanner` Prop Removed

Banner visibility is now driven by jurisdiction and model detection with built-in opt-out support. Remove any custom logic that toggled `showConsentBanner` and use the jurisdiction-aware configuration instead.

### Tracking Blocker Replaced with Network Blocker

The legacy tracking blocker has been removed. The new [network blocker](/docs/frameworks/react/network-blocker) intercepts `fetch`/`XMLHttpRequest` and blocks requests based on consent and domain rules. The default list of blocked domains has been removed.

### Replaced showPopup & isPrivacyDialogOpen with activeUI

Replaced showPopup & isPrivacyDialogOpen with activeUI / setActiveUI for more deterministic component rendering: `none | 'banner' | 'dialog'`.

### Component Renames

Components have been renamed for clarity:

|v1|v2|
|--|--|
|`CookieBanner`|`ConsentBanner`|
|`ConsentManagerDialog`|`ConsentDialog`|
|`ConsentManagerWidget`|`ConsentWidget`|

### `gdprTypes` Renamed to `consentCategories`

The `initialGDPRTypes` and `gdprTypes` config options have been renamed to `consentCategories` to reflect that consent categories are not GDPR-specific. Update your store and provider configuration accordingly.

### `ignoreGeoLocation` Prop Removed

The `ignoreGeoLocation` prop has been removed. Use the overrides configuration instead to control banner visibility during development.

### Deprecated Store Options Removed

Several previously deprecated store options, deep imports, and helper libraries (`consent-utils`, GTM helper) have been removed. Switch to the documented `createConsentManagerStore` and `StoreOptions` types.

### Backend Architecture Changed (zod+oRPC → valibot+hono)

The backend contract and router system has been completely rewritten, replacing zod and oRPC with valibot and hono. If you were extending the backend with custom contracts or middleware, you will need to update to the new system.

### Subject-Centric API Replaces Consent Identify/Verify

The `/consent/identify` and `/consent/verify` endpoints have been removed. They are replaced by the new subject-centric API (`/subject/*` endpoints) and `/consent/check`. Update any direct API calls accordingly.

→ [API Endpoints](/docs/self-host/api/endpoints)

### Tailwind CSS Layers

c15t now uses CSS Layers for better Tailwind integration — you no longer need `!` prefixes for overrides. Tailwind CSS v3.x does not support CSS Layers, so check the [Tailwind docs](/docs/frameworks/react/styling/tailwind) if you're on v3.

## New Features

### New Styling System

A modern, token-based system replaces the v1 nested theme keys. Control colors, typography, spacing, and radius globally using semantic design tokens. Fine-tune individual elements with component slots, CSS variables, `className` overrides, or go fully unstyled with `noStyle`.

→ [Styling Overview](/docs/frameworks/react/styling/overview)

### Component Renames & Compound Components

All components have been renamed for clarity (`CookieBanner` → `ConsentBanner`, etc.).

→ [ConsentBanner](/docs/frameworks/react/components/consent-banner) · [ConsentDialog](/docs/frameworks/react/components/consent-dialog) · [ConsentWidget](/docs/frameworks/react/components/consent-widget)

### Dev Tools

New `@c15t/dev-tools` package with a floating inspector panel for viewing consent state, jurisdiction info, and consent history during development.

→ [Dev Tools](/docs/frameworks/react/components/dev-tools)

### @c15t/ui Package

Extracted shared UI primitives into a dedicated package — theme system, style primitives, animation sync, and utilities used across all c15t components.

### Backend API v2

New `c15tInstance()` API with a standard Fetch handler that works with any framework. The backend now auto-generates OpenAPI documentation at `/docs` and ships new endpoints for consent management.

→ [Self-Host Quickstart](/docs/self-host/quickstart) · [API Endpoints](/docs/self-host/api/endpoints) · [Configuration](/docs/self-host/api/configuration)

### New CLI

The c15t/cli has been re-built to allow for more in-depth quickstarts like customizng your scripts and theme.

→ [Next.js Quickstart](/docs/frameworks/next/quickstart)

### IAB TCF 2.3 Support

Full Consent Management Platform implementation including Global Vendor List integration, `IABConsentBanner`, `IABConsentDialog`, TC String generation, and the `__tcfapi` stub.

> ⚠️ **Warning:**
> IAB TCF support is functional but not yet certified by the IAB. Certification is in progress.

→ [IAB Overview](/docs/frameworks/react/iab)

### Improved Script Handling

Instead of manually implemnting logic to unload each script with a callback, the page will now reload when consent is revoked (assuming consent was granted prior), removing 100% of the JavaScript of the page.

→ [Script Loader](/docs/frameworks/react/script-loader) · [Integrations](/docs/integrations/overview)

### Network Blocker

Intercepts `fetch` and `XMLHttpRequest` calls, blocking requests to configured domains until the user has given consent for the relevant category.

→ [Network Blocker](/docs/frameworks/react/network-blocker)

### Global Privacy Control (GPC)

The consent manager now honors browser GPC signals. When a GPC signal is detected, stricter defaults are applied for tracking categories and the state is reflected in the consent UI and callbacks.

### Improved Next.js DX

Removed the `<ClientSideOptionsProvider />` for cleaner c15t implementations in App Directory. We removed our pages implementation as the performance wasn't what we wanted.

→ [Next.js Quickstart](/docs/frameworks/next/quickstart) · [React Quickstart](/docs/frameworks/react/quickstart)

### Consent Dialog Trigger

A new floating widget that re-opens the consent dialog when clicked. Some regulations want it so users can easily resurface the consent UI at any time, if you don't want this we recommend adding a link in your footer to open the dialog.

→ [Consent Dialog Trigger](docs/frameworks/next/components/consent-dialog-trigger)

### OpenTelemetry Instrumentation

The backend now ships with OpenTelemetry spans for DB, cache, external, and request operations. PII is automatically stripped from span attributes — error messages, stack traces, IPs, and query strings are all sanitized.

### Backend Cache Adapters

New pluggable cache adapter system with built-in support for Cloudflare KV, Upstash Redis, and in-memory caching. Used for GVL data and other cacheable responses.

→ [Configuration](/docs/self-host/api/configuration)

### @c15t/schema Package

All API schemas and domain types have been extracted into a dedicated `@c15t/schema` package, providing a single source of truth for the consent data model.

### `prefers-reduced-motion` Support

All c15t components now respect the `prefers-reduced-motion` OS setting, automatically disabling animations for users who prefer reduced motion.

## Improvements

* Canada jurisdiction now correctly distinguishes Quebec (Law 25, opt-in) from the rest of Canada (PIPEDA, opt-out), matching how CCPA is region-specific to California
* c15t/backend's bundle size in a Cloudflare Worker is now 60% smaller (1.92mb), reducing start times in serverless enviroments.
* Removed redundant columns and tables in c15t/backend
* Complete [documentation overhaul](/docs) covering every component, hook, and API
* New `selectLanguage` helper and cached language key in `@c15t/translations`
* Gated debug logger in core replacing bare `console.log` calls (disabled by default)
* `/status` endpoint now includes a database health check

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.0-rc.5 — Policy Packs, Per-Policy GPC, Fallback Policies & Dev-Tools Improvements
URL: https://c15t.com/changelog/2.0.0-rc.5
Release candidate introducing policy packs for regional consent resolution, per-policy GPC support, fallback policies, policy inspection, and developer-experience improvements.

This RC introduces **policy packs** as the main addition in `v2.0.0-rc.5`. Instead of relying on implicit jurisdiction behavior, you can now define regional consent policies explicitly and let c15t resolve the active policy at runtime based on visitor location. `rc.5` also adds per-policy GPC handling, safer geo-failure fallbacks, policy-aware validation, and better tooling for inspecting how a policy was chosen.

## Highlights

* [Policy packs](#policy-packs) for declarative regional consent configuration
* [Per-policy GPC support](#per-policy-gpc) via `consent.gpc`
* [Fallback policies](#fallback-policies) as a safety net when geo-location fails
* [Policy fingerprints & re-prompting](#policy-fingerprints--re-prompting) to automatically resurface consent when policies change
* [Built-in presets](#built-in-presets) for Europe, California, Quebec, and more
* [Policy validation](#policy-validation) with `inspectPolicies()` for catching misconfigurations
* [Dev-tools policy panel](#dev-tools-policy-panel) for inspecting match resolution in real time
* [Snapshot tokens](#snapshot-tokens) for binding consent writes to the original policy decision
* [Naming & DX improvements](#naming--dx-improvements) across hosted/offline modes, i18n, and legal links
* [Bundled package docs](#bundled-package-docs) for version-matched local reference in `node_modules`

## New Features

### Policy Packs

Policy packs are ordered arrays of policies that control the consent model, categories, UI, and proof settings for each region. The backend resolves the right policy for each `/init` request based on the visitor's geo-location.

```ts
import { c15tInstance, policyPackPresets } from '@c15t/backend';

const c15t = c15tInstance({
  adapter,
  trustedOrigins: ['https://app.example.com'],
  policyPacks: [
    policyPackPresets.europeOptIn(),
    policyPackPresets.californiaOptOut(),
    policyPackPresets.worldNoBanner(),
  ],
});
```

Resolution follows a fixed priority: **region → country → fallback → default**. Within the same matcher type, first match wins by array order.

Each policy controls:

* **Consent model** — `opt-in`, `opt-out`, `none`, or `iab`
* **Categories** — which consent categories are in scope
* **Scope mode** — `strict` (block out-of-scope) or `permissive` (allow out-of-scope)
* **UI** — banner, dialog, or none, with per-surface action customization
* **Proof** — what to record (IP, user agent, language)
* **I18n** — language and message profile overrides

The `/init` response now includes `policy` (the resolved runtime config) and `policyDecision` (explainability metadata with `matchedBy`, fingerprint, and geo context).

> [Policy Packs Concepts](/docs/frameworks/react/concepts/policy-packs) · [Self-Host Guide](/docs/self-host/guides/policy-packs)

### Per-Policy GPC

Each policy can now individually opt in to respecting the [Global Privacy Control](https://globalprivacycontrol.org/) signal via `consent.gpc`:

```ts
{
  id: 'california',
  match: { regions: [{ country: 'US', region: 'CA' }] },
  consent: { model: 'opt-out', gpc: true },
}
```

When `gpc: true` and the visitor's browser sends a GPC signal, `marketing` and `measurement` categories are automatically denied during auto-granting. This moves GPC handling from a global behavior to an explicit per-policy setting, which is especially useful for opt-out regions like California. Opt-in policies can leave it disabled when GPC does not change the effective behavior.

### Fallback Policies

A new `match.fallback` flag provides a safety net when geo-location fails (no Cloudflare, Vercel, or AWS geo-headers). This is semantically distinct from `isDefault`:

* **`isDefault`** — catch-all for known locations that don't match specific policies ("rest of world")
* **`fallback`** — safety net for unknown locations when geo fails ("assume strictest")

```ts
{
  id: 'strict_fallback',
  match: { fallback: true, countries: [...EEA_COUNTRY_CODES] },
  consent: { model: 'opt-in' },
  ui: { mode: 'banner' },
}
```

The `europeOptIn()` and `europeIab()` presets include `fallback: true` by default, so the recommended setup protects EU users automatically — even when `disableGeoLocation` is enabled or CDN headers are missing.

### Policy Fingerprints & Re-Prompting

Each resolved policy now includes a **material policy fingerprint** — a SHA-256 hash of consent-affecting fields (model, categories, scope, allowed actions, proof settings). When you change a policy in a way that affects consent semantics, c15t automatically detects the fingerprint mismatch and re-prompts returning users.

Presentation-only changes (copy, layout, scroll lock, i18n) do not trigger re-prompts.

### Built-In Presets

Six presets cover the most common regional configurations:

|Preset|Model|Matches|
|--|--|--|
|`europeOptIn()`|`opt-in`|EEA + UK + geo fallback|
|`europeIab()`|`iab`|EEA + UK + geo fallback (TCF 2.3)|
|`californiaOptIn()`|`opt-in`|US-CA region|
|`californiaOptOut()`|`opt-out`|US-CA region|
|`quebecOptIn()`|`opt-in`|CA-QC region|
|`worldNoBanner()`|`none`|default catch-all|

Matcher helpers (`policyMatchers.eu()`, `.eea()`, `.uk()`, `.iab()`, `.fallback()`, `.merge()`) make custom pack composition easy.

### Policy Validation

`inspectPolicies()` validates your policy pack before deployment, catching:

* Multiple default or fallback policies
* IAB policies without `iab.enabled: true` or with custom UI overrides
* Duplicate or missing policy IDs
* Policies with no matchers
* Missing default or fallback policies (warnings)
* Overlapping country/region matchers (warnings)

### Dev-Tools Policy Panel

The dev-tools panel now includes a full **match trace** showing the resolution path for every request: region → country → fallback → default, with MATCH/MISS indicators and the resolved policy ID. The location panel shows the active policy summary with `matchedBy` metadata.

### Snapshot Tokens

When `policySnapshot.signingKey` is configured, `/init` returns a signed JWT alongside the resolved policy. By default, invalid, expired, or missing snapshot tokens now cause `POST /subjects` to return `409 Conflict`. Deployments that prefer availability can opt into `policySnapshot.onValidationFailure = 'resolve_current'` to fall back to current write-time resolution instead.

### Bundled Package Docs

The four main c15t packages now ship version-matched Markdown docs inside the installed package itself:

* `node_modules/c15t/docs/`
* `node_modules/@c15t/react/docs/`
* `node_modules/@c15t/nextjs/docs/`
* `node_modules/@c15t/backend/docs/`

This includes generated reference material like prop and type tables, so local AI tools and developers can read the docs for the exact installed package version instead of relying on stale external docs or model knowledge.

## Improvements

* Renamed `c15t` mode to `hosted` and improved hosted vs offline documentation
* Renamed translation-facing APIs from `translations` to `i18n` across runtime types
* Improved legal links and overrides documentation
* Added v1→v2 codemods for renamed APIs and imports
* `@c15t/backend` API entrypoints flattened for better TypeScript DX
* Backend now exposes a base `/` root endpoint for health checks
* React compiler compatibility fixes
* Dark mode fix for `@c15t/ui`
* Dialog width customization and `disableAnimation` fixes
* `ConsentDialogLink` component added to `@c15t/react`
* Dev-tools UI improvements with persisted overrides and better diagnostics
* Updated Lithuanian translations
* CSS import path fixes (`.css` → `.js`)

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.0-rc.6 — Smaller Client Bundles, Modular IAB, UI Primitives, and Flexible Policy Actions
URL: https://c15t.com/changelog/2.0.0-rc.6
Release candidate focused on smaller client bundles, extracted IAB support, shared UI primitives with framework adapters, flexible policy action layouts, and cleaner package styling/toolchain boundaries.

This RC focuses on shipped-surface cleanup and developer ergonomics rather than brand-new UI components. Client bundles are smaller, IAB support is now modular for teams that need it, policy UI surfaces can express richer primary action layouts, and the packaging/toolchain work around stylesheets, docs, and build artifacts is much cleaner. Prebuilt UI styles also move onto explicit stylesheet entrypoints, which cuts down on JS-driven style loading and keeps more styling work on the CSS path.

## Highlights

* Smaller client bundles by tree-shaking translations and schema-heavy dependencies out of the main client path
* IAB support extracted into `@c15t/iab`, so non-IAB users no longer ship IAB runtime code by default
* Policies now support `primaryActions` arrays for more flexible banner and dialog layouts
* Prebuilt UI now ships explicit stylesheet entrypoints such as `@c15t/react/styles.css` and `@c15t/nextjs/styles.css`, reducing JS-side style loading overhead
* Shared UI primitives (`@c15t/ui/primitives`) power all interactive components with framework-agnostic state logic, keyboard navigation, and CSS variant generators
* Framework adapter packages (`@c15t/solid`, `@c15t/vue`, `@c15t/svelte`) provide shared primitives and styles for non-React frameworks
* Toolchain and release housekeeping landed alongside the feature work, including dependency refreshes, bundled docs, and cleaner publish artifacts

## Smaller Client Bundles

The biggest user-facing win in `rc.6` is bundle reduction in the standard client path.

|Metric|Before|After|Change|
|--|--|--|--|
|Client bundle (raw)|\~644 KB|\~464.5 KB|**-180 KB**|
|Client bundle (gzip)|\~180 KB|\~130.5 KB|**-50 KB**|

This came from three main changes:

* The offline client no longer pulls in all bundled locales by default when it only needs English as the base fallback
* Client-facing imports no longer drag Valibot and the full schema bundle into the main runtime path
* SHA-256 hashing was simplified so browser builds no longer need the old `node:crypto` fallback path

Together, those changes make the default install noticeably lighter without changing the public consent flow API.

## Modular IAB Support

IAB TCF support now lives in a dedicated addon package: `@c15t/iab`.

That means teams who do not enable IAB no longer pay for the IAB runtime in their default bundle, while teams that do need it get a cleaner integration model:

```tsx
import { iab } from '@c15t/iab';
import { IABConsentBanner } from '@c15t/react/iab';
```

For non-IAB users, this extraction also reduced shipped code further, cutting about `12.9 KB` gzip from the previous non-IAB path.

## More Flexible Policy Actions

Policies now normalize around `primaryActions` instead of a single `primaryAction` field. That makes it possible to express multi-primary layouts when a policy opts into them, while keeping shipped defaults predictable.

The important behavior change is mostly about flexibility rather than migration pressure:

* custom policies can emphasize more than one action where appropriate
* headless and prebuilt UI now consume the same normalized action shape
* shipped presets and offline defaults still keep `customize` as the default emphasized action

## Packaging and Toolchain Cleanup

This RC also tightens up the package surface around styles, docs, and release tooling.

* Prebuilt React and Next.js UI now ship explicit stylesheet entrypoints including `styles.css` and `iab/styles.css`
* `@c15t/ui` publishes stylesheet assets directly instead of relying on JS-driven style inclusion behavior, which reduces unnecessary client-side JS work for prebuilt UI consumers
* Tailwind guidance is now aligned around explicit host-app stylesheet imports for Tailwind 3 and Tailwind 4
* Package docs are bundled with published packages, and declaration output continues moving out of runtime bundle trees for cleaner consumption by tools and bundlers
* Dependency refreshes, benchmark workflows, and RC housekeeping landed as part of the same release stream

For teams using the prebuilt UI, this means styles are now loaded from actual stylesheet entrypoints instead of piggybacking on component JS modules. That keeps the styling contract more explicit, improves bundler predictability, and shifts more work off the runtime JavaScript path.

In our simulated mobile benchmark, this reduced main-thread impact by about `14ms`. That matters because there is less JavaScript competing during startup, styles can apply earlier through the normal CSS path, and the browser has a little more room to initialize consent UI and related scripts on slower devices.

## Shared UI Primitives and Framework Adapters

This RC introduces a shared primitive runtime at `@c15t/ui/primitives` that extracts framework-agnostic state management, keyboard navigation, and toggle logic from React components into pure TypeScript utilities. Seven primitives are available: accordion, button, collapsible, dialog, switch, tabs, and preference-item.

The new **PreferenceItem** primitive unifies three previously distinct expandable-row patterns (Radix Accordion in the consent widget, custom button + AnimatedCollapse in the IAB dialog, and manual state management for nested collapsibles) into a single composable compound component with semantic slots for trigger, header, meta, auxiliary, and control regions.

Framework adapter packages — `@c15t/solid`, `@c15t/vue`, and `@c15t/svelte` — re-export the shared primitives and CSS variant generators. Each framework has its own storybook with shared interaction tests that validate the same DOM contract (`data-state`, `data-slot`, ARIA attributes) across all frameworks.

**Bundle impact (consent surfaces vs 2.0.0 baseline):**

|Metric|2.0.0|Current|Change|
|--|--|--|--|
|JS (raw)|1,012 KB|946 KB|**-66 KB (-6.6%)**|
|JS (gzip)|288 KB|273 KB|**-15 KB (-5.3%)**|
|CSS (raw)|0 KB|17 KB|+17 KB|
|CSS (gzip)|0 KB|2.5 KB|+2.5 KB|
|**Total (gzip)**|**288 KB**|**276 KB**|**-13 KB (-4.4%)**|

The CSS increase reflects styles moving from runtime `createElement("style")` calls to static stylesheet entrypoints, which is a net win for main-thread performance.

**Runtime performance (react-browser-bench, full-ui scenario):**

|Metric|Before|After|Change|
|--|--|--|--|
|useTheme calls per load|35|23|**-35%**|
|useTheme total time|0.10 ms|0.02 ms|**-80%**|
|useTheme avg per call|3 μs|0.8 μs|**-73%**|

The `useTheme()` hook — called by every component in the tree — now memoizes its deep merge so it only recomputes when theme context actually changes. The focus trap utility (`@c15t/ui/utils/dom`) also replaced `offsetWidth`/`offsetHeight` visibility checks (which force synchronous layout recalculation on every Tab keypress) with the `checkVisibility()` API. Both optimizations live in the shared layer and benefit all frameworks equally.

## Learn more

For implementation details and follow-up discussion, see the linked pull requests.

* [#672](https://github.com/c15t/c15t/pull/672) — tree-shake translations and Valibot from the client bundle
* [#668](https://github.com/c15t/c15t/pull/668) — extract IAB support into `@c15t/iab`
* [#674](https://github.com/c15t/c15t/pull/674) — support `primaryActions` arrays in policies
* [#670](https://github.com/c15t/c15t/pull/670) — update Zustand, TypeScript 6, benchmarks, docs, and related RC/toolchain work

## Notes

* There are no headline breaking changes in this release candidate.
* The largest migration-sensitive change in this RC is the modular IAB packaging split for teams using IAB features.

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.0-rc.7 — Theming Fixes, Simpler Tailwind Setup, and Clearer Customization Guidance
URL: https://c15t.com/changelog/2.0.0-rc.7
Release candidate focused on fixing theming regressions in the prebuilt UI, simplifying the Tailwind setup contract, clarifying the recommended customization ladder, and adding better manual coverage for CSS behavior across Tailwind 3, Tailwind 4, and plain CSS.

`v2.0.0-rc.7` is a cleanup release aimed at styling correctness and clearer implementation guidance rather than new surface area. The main focus is fixing the theming regressions that showed up in `rc.6`, tightening the contract around how c15t styles interact with Tailwind, clarifying the customization ladder across the docs, and improving the manual review workflow for cross-environment CSS behavior before the final 2.0 release.

## Highlights

* Fixed slot theming regressions in the React prebuilt UI
* Simplified the Tailwind setup contract to match the actual shipped `@layer components` behavior
* Clarified the recommended customization ladder across the AI agent docs plus the React and Next.js component guides
* Added a manual CSS matrix harness to compare Tailwind 3, Tailwind 4, and plain CSS side by side
* Strengthened regression coverage for slot styling, switch tokens, and packaging/tooling edge cases

## Fixed Theming Regressions

The biggest user-facing fixes in `rc.7` are around per-slot theming.

### Slot `noStyle` no longer leaks to the DOM

Resolved slot metadata is now sanitized before it reaches rendered DOM elements, so internal flags such as `noStyle` are consumed by c15t instead of being forwarded as invalid HTML attributes.

### Slot `style` now applies on the documented surfaces

Inline styles provided through slot objects now apply correctly on the rendered elements, including the `consentWidgetAccordion` path that was previously documented but not fully wired.

### Switch track tokens now win correctly

`switchTrack` and `switchTrackActive` theme tokens now resolve from the rendered component subtree instead of losing to the shared module defaults. This makes provider-level and scoped theme overrides behave predictably without requiring `!important`.

### Shared adapter guardrail in `@c15t/ui`

`@c15t/ui` now exports a small DOM prop sanitizing helper so future framework adapters can safely bind resolved slot styles without reintroducing these same issues.

## Tailwind Setup Is Simpler

This RC also removes the stale idea that c15t needs its own dedicated Tailwind layer contract.

The shipped component CSS already lands in Tailwind's `components` layer, so the docs and templates now reflect that reality:

* **Tailwind 4**: import Tailwind normally, with no extra `c15t` layer declaration
* **Tailwind 3**: keep the wrapped `@tailwind base` pattern, but standardize on `@layer base, components, utilities;`

This cleanup affects the public setup guidance in the React and Next.js docs as well as the CLI Tailwind CSS template helper used during setup.

## Clearer Customization Guidance

`rc.7` also tightens the guidance around how teams should customize the shipped UI.

The docs, AI-agent guidance, and React compound-component examples now push the same escalation path:

* start with the stock component and provider options
* use theme tokens and slots for styling changes
* reach for compound components only when markup really needs to change
* use `noStyle` or headless mode only when the stock structure is no longer the right fit

This matters because the `rc.6` theming regressions showed that users were hitting advanced escape hatches too early. `rc.7` fixes the broken slot behavior and also makes the recommended path much harder to misread.

## Better CSS Review Before Release

To make styling regressions easier to catch, the repo now includes a manual CSS matrix harness under `benchmarks/`.

It renders the same consent scenarios across:

* Tailwind 3
* Tailwind 4
* plain CSS

The preview shell shows those environments side by side so complex styling cases can be checked visually before release work lands. This is intentionally a manual review tool for now, not a CI gate.

## Improvements

* The demo theme showcase now includes regression-focused previews for the fixed theming contract
* Added browser/render-path regression tests for slot props and switch token styling
* Added CLI coverage for the new Tailwind CSS template contract
* Refreshed the bundled guidance for agents and the React/Next.js docs so customization advice matches the shipped component model
* Fixed CI issues around preview workflow outputs, benchmark config typing, and CSS test path resolution

## Learn more

* [#697](https://github.com/c15t/c15t/pull/697) — fix RC theming regressions, clean up Tailwind setup guidance, and add the CSS matrix harness
* [#699](https://github.com/c15t/c15t/pull/699) — clarify the customization ladder across AI agent docs, React/Next.js guides, and component examples

## Notes

* There are no planned breaking changes in `v2.0.0-rc.7`
* This release is scheduled for **April 8, 2026**

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.0.1 - TanStack Devtools Support & Tailwind Import Ordering
URL: https://c15t.com/changelog/2.0.1
Patch release adding official TanStack Devtools support for @c15t/dev-tools and improving Tailwind v4 stylesheet import ordering in the c15t CLI.

## 🐛 Bug Fixes & Improvements

### **@c15t/dev-tools**

Added official TanStack Devtools support for `@c15t/dev-tools`.

This release stabilizes the existing integration and makes it ready to document publicly:

* Added the `c15tDevtools()` plugin factory for TanStack Devtools, while keeping `c15tDevtoolsPlugin()` as a backward-compatible alias
* Switched the integration to TanStack Devtools' React plugin API instead of the previous custom mount pattern
* Kept the embedded c15t panel connected across TanStack tab switches so it does not drop the store connection when the plugin view remounts
* Updated the embedded panel styling to better match TanStack Devtools
* Added demo coverage for repro and regression testing

#### Usage

```tsx
import { TanStackDevtools } from '@tanstack/react-devtools';
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
import { c15tDevtools } from '@c15t/dev-tools/tanstack';

export function AppDevtools() {
  return (
    <TanStackDevtools
      plugins={[
        {
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
        c15tDevtools({
          defaultOpen: true,
        }),
      ]}
    />
  );
}
```

### **@c15t/cli**

Improved Tailwind v4 stylesheet import ordering when the CLI adds c15t stylesheets to app-level CSS files.

This keeps c15t imports at the end of the top-level `@import` block so preset styles such as Fumadocs load first and do not override c15t theme tokens unexpectedly.

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.1.0 - Expanded Script Integrations and Provider Registry
URL: https://c15t.com/changelog/2.1.0
Minor release expanding the consent-aware script loader with a registry-backed provider system, more prebuilt integrations, stronger lifecycle utilities, CLI discovery updates, and German translation refinements.

c15t 2.1 expands the script loader into a broader consent-aware integration system. The release adds a registry-backed provider model, many more prebuilt script helpers, stronger shared lifecycle utilities, and clearer documentation for using third-party scripts safely across React and Next.js.

This is a minor release with no breaking changes.

## Highlights

* New registry-backed provider system for script integrations
* New prebuilt helpers for analytics, ads and pixels, functional tools, and tag managers
* Public integration registry for discovery and CLI generation
* Shared utilities for script URLs, attributes, Google Consent Mode, install steps, and lifecycle callback execution
* Runtime timestamp handling for Google Tag and Google Tag Manager
* PostHog region and load-mode controls
* Expanded script-loader and integration documentation
* German translation casing and tone refinements

## Registry-backed script providers

`@c15t/scripts` now has a central registry for built-in integrations. The registry gives each helper a stable identity, category, consent category, package subpath, and discovery metadata.

The registry is now the source of truth for built-in script helper discovery, which means integrations can be surfaced consistently across package exports, tests, docs, and CLI prompts.

This also makes the script-loader API easier to grow without each helper carrying its own slightly different setup conventions.

## New script integrations

2.1 adds and expands prebuilt helpers across the common third-party script categories:

### Analytics

* Ahrefs Analytics
* Cloudflare Web Analytics
* Fathom Analytics
* Hotjar
* Matomo Analytics
* Microsoft Clarity
* Mixpanel Analytics
* Plausible Analytics
* Rybbit Analytics
* Segment
* Umami Analytics
* Vercel Analytics

### Ads and pixels

* Reddit Pixel
* Snapchat Pixel

Existing ads and pixel helpers such as Meta Pixel, TikTok Pixel, LinkedIn Insights, Microsoft UET, and X Pixel also received stronger registry coverage and updated tests.

### Functional tools

* Crisp
* Intercom
* PromptWatch

Each helper is modeled as a manifest-backed integration so c15t can reason about when it loads, what it injects, and how it behaves when consent changes.

## Shared lifecycle foundations

Provider manifests now share common utilities for:

* resolving script URLs and host overrides
* building boolean and JSON data attributes
* constructing install steps
* mapping Google Consent Mode categories
* resolving lifecycle-time values
* creating consistent script callback payloads
* testing helper parity against registry metadata

This makes helper behavior more predictable and gives each provider stronger coverage for loader URLs, attributes, consent callbacks, queued vendor calls, and unload behavior.

## Google Tag and Google Tag Manager

Google Tag and Google Tag Manager now resolve boot timestamps during script lifecycle execution instead of when the helper is constructed.

That keeps documented setup patterns compatible with Next.js Cache Components and other prerendering flows where helpers may be created before the browser-side script lifecycle actually runs.

## PostHog controls

The PostHog helper now supports explicit regional and loading behavior:

* `region: 'eu' | 'us'` derives the matching API, UI, and bootstrap hosts
* explicit host overrides keep the bootstrap script aligned with the configured API host
* `loadMode: 'always'` preserves the existing cookieless consent-sync behavior
* `loadMode: 'after-consent'` waits for measurement consent before injecting PostHog
* `loadMode: 'disabled'` prevents the helper from issuing a PostHog network request

The PostHog docs now call out the privacy-first EU setup using `region: 'eu'` with `loadMode: 'after-consent'`.

## CLI and docs discovery

The CLI script picker now reads from the shared registry instead of maintaining its own hand-written option list.

The script-loader docs were also reorganized around a clearer lifecycle model:

* Pending
* Loaded
* Updated
* Unloaded

The React, Next.js, shared script-loader, and integration overview pages now use the same mental model and category structure. Integration pages include more direct guidance for how each provider loads, which consent category controls it, and what happens when consent is revoked.

## German translations

German translations now use more consistent casing and tone across consent banners, preference dialogs, and related UI text.

<ContributorBlock usernames={["BurnedChris", "mezotv", "KayleeWilliams"]} title="Thank you to our contributors" />

# v2.1.0 Draft - v3 API Preview and Faster React Runtime
URL: https://c15t.com/changelog/2.1.0-v3-api-preview
Draft release notes for the opt-in v3 API preview, covering the kernel contract, React render isolation, v3 hosted transport alignment, and benchmark results from the @c15t/react v3 examples.

> Draft note: this is currently written as `v2.1.0` because the release adds opt-in v3 entrypoints across core, React, Next.js, and IAB packages. If we classify it as a patch preview instead, update the frontmatter and package list before publishing.

This release introduces the first opt-in preview of the v3 API for c15t, `@c15t/react`, and `@c15t/nextjs`.

The goal of v3 is not to replace the stable v2 API in-place. The new API ships behind explicit `/v3` entrypoints so teams can try the new runtime model without changing existing v2 integrations.

## Highlights

* New framework-neutral kernel in `c15t/v3`
* Policy-first v3 surface aligned with the current policy-pack runtime
* v3 hosted consent writes are aligned back to the backend's subject endpoint, `POST /subjects`
* React v3 provider and hooks isolate renders to the selected consent slice
* Next.js v3 helpers prefetch rich init data into a serializable `KernelConfig`
* IAB v3 handle exposes the CMP API through an observable getter

## Policy-first v3 API

v3 moves the consent runtime around a small kernel:

```ts
import { createConsentKernel, createHostedTransport } from 'c15t/v3';

const kernel = createConsentKernel({
  transport: createHostedTransport({
    backendURL: '/api/c15t',
  }),
});

await kernel.commands.init();
await kernel.commands.save('all');
```

Adapters read from the same snapshot:

```ts
const snapshot = kernel.getSnapshot();

snapshot.consents;
snapshot.hasConsented;
snapshot.subjectId;
snapshot.policy;
snapshot.model;
snapshot.activeUI;
```

The important change is that the v3 preview no longer exposes legacy jurisdiction/banner fields as part of its public contract.

Instead, the resolved policy is the source of truth:

* `policy.model` determines whether the effective model is `opt-in`, `opt-out`, `iab`, or `null`
* `policy.ui.mode` determines whether the active UI is `banner`, `dialog`, or `none`
* geographic data remains an input to policy resolution, but not the main public runtime contract

This matches the direction already taken by the v2 policy-pack runtime, where jurisdiction-shaped fields are deprecated compatibility data rather than the behavior source of truth. v3 uses the preview period to make that contract explicit and avoid carrying deprecated fields into new framework adapters.

This also makes the React adapter smaller and easier to keep consistent with the framework-neutral kernel. React now subscribes to kernel state by selected slice instead of recreating consent semantics inside provider state.

## Hosted saves are aligned with `/subjects`

The v3 hosted transport now writes consent records through the same subject-centric API used by the current backend:

```txt
POST /subjects
```

This is a v3 preview alignment fix. v2 already uses the subject endpoint; the issue was that the new v3 transport had temporarily drifted to the wrong write URL while the preview API was being shaped.

The v3 save body maps the kernel snapshot into the backend schema with:

* `subjectId`
* `domain`
* `type: 'cookie_banner'`
* `preferences`
* `givenAt`
* `policySnapshotToken`
* `tcString`
* `jurisdictionModel`
* `uiSource`
* `consentAction`
* external subject identity fields

`subjectId` is generated lazily before the first save and reused for future writes. Persistence hydration restores that subject ID locally without making a backend save.

## Faster React runtime

The biggest user-visible improvement is in `@c15t/react/v3`.

The v2 React provider exposes a larger consent manager object through React state and context. That is ergonomic, but it means a consent mutation can fan out through components that do not care about the changed category.

The v3 React provider creates one kernel per mount and lets hooks subscribe to exactly the slice they need:

```tsx
import { ConsentProvider, useConsent } from '@c15t/react/v3';

function MarketingScripts() {
  const allowed = useConsent('marketing');
  return allowed ? <Scripts /> : null;
}
```

In the render-count benchmark, ten children read five different consent categories, then only `marketing` changes:

|Runtime|Mount commits|Mutation commits|
|--|--:|--:|
|v2 `ConsentManagerProvider` + `useConsentManager()`|20|20|
|v3 `ConsentProvider` + `useConsent(category)`|10|2|

That is a 50% lower mount count in the benchmark harness and a 90% reduction in mutation fanout. Only the two components reading `marketing` re-rendered.

The browser benchmarks also show faster visible UI and consent-triggered script loading in the local deterministic examples.
These numbers come from a 50-iteration local run after rebuilding the benchmark apps and removing script-count probe overhead from the measured path:

|Benchmark|v2 median|v3 median|Change|
|--|--:|--:|--:|
|Banner visible|73.2 ms|59.1 ms|-19.3%|
|Banner mount|39.3 ms|33.1 ms|-15.8%|
|Script loading, 5 scripts|12.9 ms|9.7 ms|-24.8%|
|Script loading, 10 scripts|14.0 ms|10.3 ms|-26.4%|
|Script loading, 25 scripts|20.3 ms|11.9 ms|-41.4%|
|Script loading, 50 scripts|26.7 ms|18.2 ms|-31.8%|

The deterministic routes preseed backend state and use local scripts, so the results should be read as runtime overhead comparisons, not third-party network latency measurements.

The bundle-size story is more nuanced. The v3 API is split by design, so common paths can import only the provider, hooks, UI, and modules they use. Synthetic routes that import every v3 feature can still be larger than a narrower v2 route. We will continue tracking common route shapes separately from full harness routes.

## Next.js v3 prefetch

`@c15t/nextjs/v3/server` now returns a plain `KernelConfig` that can be awaited in a Server Component and passed to the client boundary:

```tsx
import { prefetchInitialConsent } from '@c15t/nextjs/v3/server';
import { ConsentBoundary } from '@c15t/nextjs/v3';

export default async function RootLayout({ children }) {
  const config = await prefetchInitialConsent({
    backendURL: '/api/c15t',
  });

  return (
    <ConsentBoundary config={config} backendURL="/api/c15t">
      {children}
    </ConsentBoundary>
  );
}
```

The prefetch result preserves rich init fields through first render:

* location
* translations
* branding
* policy
* policy decision
* policy snapshot token
* GVL
* custom vendors
* CMP ID

This keeps first paint aligned with the backend's resolved policy while still letting the client refresh init after mount.

## Compatibility

This is an opt-in API preview. Existing v2 imports keep working:

```ts
import { ConsentManagerProvider } from '@c15t/react';
```

The v3 surface is available through explicit v3 entrypoints:

```ts
import { createConsentKernel } from 'c15t/v3';
import { ConsentProvider } from '@c15t/react/v3';
import { ConsentBoundary } from '@c15t/nextjs/v3';
```

Because v3 is still unstable, we are using the preview period to validate framework integration patterns, React Compiler behavior, and benchmark coverage before promoting this contract to stable.

## Notes

* This release is scheduled for **May 3, 2026**
* The v3 API is opt-in and does not require existing v2 applications to migrate
* The final version number may change before publish depending on whether we classify this as a minor preview or a patch-level opt-in feature

<ContributorBlock usernames={["KayleeWilliams"]} title="Thank you to our contributors" />

# v2.2.0 - Consent-Aware Embeds, Configurable Controls, and More Integrations
URL: https://c15t.com/changelog/2.2.0
Minor release adding consent-aware Google Maps and YouTube components, a configurable consent controls toolbar, eight script integrations, a reusable SDK hook, policy-aware action styling, CSP nonce support, reliability fixes, and new translations.

c15t 2.2 expands consent-aware integrations beyond background scripts and into the parts of your product that people interact with. The release adds ready-to-use Google Maps and YouTube components, a configurable consent controls toolbar, eight new script providers, a reusable hook for custom SDK integrations, and improvements across consent storage, IAB TCF, theming, translations, and the self-hosted backend.

This is a minor release with no breaking changes.

## Highlights

* New consent-aware `GoogleMap` and `YouTubeEmbed` components for React and Next.js
* New opt-in `ConsentDialogTriggerToolbar` for combining privacy preferences with app-owned controls
* New `useConsentScript` hook for custom SDK-backed integrations
* Eight new built-in providers: Adobe Analytics, Amplitude, Clearbit, Heap, Hightouch, LogRocket, Pirsch, and RudderStack
* RudderStack pre-consent buffering with category-to-consent-ID mapping
* Microsoft Clarity Consent V2 support and a corrected Mixpanel bootstrap
* PostHog initialization and pre-load event queue fixes
* Policy-aware primary action styling, including IAB consent surfaces
* New `nonce` option applying your CSP nonce to injected styles and scripts
* Reliable offline IAB GVL loading and language refreshes
* Stronger consent submission deduplication and timestamp handling
* Hindi and Gujarati translations for the full consent experience

## Consent-aware Google Maps and YouTube

The new renderable integrations handle both consent and the interface shown while third-party content is blocked or loading.

`GoogleMap` keeps the Google Maps JavaScript API off the page until the configured consent category is allowed. It shares one page-level loader across map instances, adopts an existing compatible Maps SDK, and provides accessible blocked, loading, and error states. Loader failures can be retried without creating duplicate Google Maps registrations.

`YouTubeEmbed` keeps the iframe unmounted until consent, so no YouTube request is made while the content is blocked. It defaults to the privacy-enhanced `youtube-nocookie.com` host, lazy loading, a responsive 16:9 frame, and type-safe options for video IDs, start times, and player parameters.

Both components are available from `@c15t/react` and `@c15t/nextjs`. Their loading and error messages use the active c15t translations and can be replaced with custom fallbacks.

→ [Google Maps](/docs/integrations/google-maps) · [YouTube](/docs/integrations/youtube)

## Build custom SDK integrations with `useConsentScript`

The new `useConsentScript` hook provides the lifecycle foundation used by `GoogleMap`. Use it when a third-party SDK needs more than a script element and your component must wait for a callback or global API before it can render.

The hook:

* registers the script through the consent manager
* shares compatible registrations within one provider
* exposes blocked, loading, ready, and error states
* resolves callback-based or global SDK readiness
* supports timeouts and explicit retries
* cleans up registrations according to the selected unmount behavior

This keeps custom widgets connected to the same consent and script lifecycle as c15t's built-in integrations.

→ [React Script Loader](/docs/frameworks/react/script-loader) · [Next.js Script Loader](/docs/frameworks/next/script-loader)

## Configurable consent controls toolbar

React and Next.js now include `ConsentDialogTriggerToolbar`, an opt-in alternative to the existing single-button `ConsentDialogTrigger`. It combines one built-in privacy preferences action with app-owned controls such as theme, accessibility, or support actions.

![Custom-styled consent controls toolbar with theme, support, and privacy actions](https://lgfiy5dnwualqura.public.blob.vercel-storage.com/changelogs/2.2.0-consent-dialog-trigger-toolbar-closeup-09yglfWBRtIoFjhSJ6qmxm21NRLoAK.png)

```tsx
<ConsentDialogTriggerToolbar
  ariaLabel="Site controls"
  actions={[
    {
      id: 'theme',
      label: 'Dark color scheme',
      icon: isDark ? <SunIcon /> : <MoonIcon />,
      pressed: isDark,
      onSelect: toggleColorScheme,
    },
    {
      id: 'support',
      label: 'Open support chat',
      icon: <ChatIcon />,
      onSelect: openSupportChat,
    },
  ]}
  preferences={{
    icon: 'fingerprint',
    label: 'Manage privacy settings',
  }}
/>
```

The toolbar supports horizontal and vertical layouts, drag-to-corner positioning, keyboard navigation, disabled and pressed action states, theme slots, direct style overrides, and fully custom styling with `noStyle`. Your application owns custom action state and behavior, while c15t always provides exactly one action that opens consent preferences.

The existing `ConsentDialogTrigger` API and single-button behavior are unchanged, so adopting the toolbar does not require a migration.

→ [React Consent Dialog Trigger](/docs/frameworks/react/components/consent-dialog-trigger) · [Next.js Consent Dialog Trigger](/docs/frameworks/next/components/consent-dialog-trigger)

## Eight new script integrations

`@c15t/scripts` adds eight built-in, registry-backed helpers, growing the provider registry from 28 to 36 integrations:

* **Adobe Analytics** — loads an Adobe Experience Platform Data Collection Tags embed behind measurement consent
* **Amplitude** — reproduces the Browser SDK 2 queue and synchronizes runtime opt-out state
* **Clearbit** — gates visitor and company enrichment on marketing consent
* **Heap** — implements the current heap.js callback queue contract
* **Hightouch** — queues the Events browser SDK with optional host and initial page tracking
* **LogRocket** — loads and initializes session replay after measurement consent
* **Pirsch** — preserves Pirsch's required script ID and identification-code attributes
* **RudderStack** — implements the v3 queue with validated write-key and data-plane configuration

Each provider includes registry metadata, framework examples, lifecycle guidance, and contract coverage against the vendor's current loader behavior.

→ [Integrations Overview](/docs/integrations/overview)

## RudderStack pre-consent mode

RudderStack still blocks its SDK until consent by default. 2.2 also adds an explicit pre-consent mode for teams that need to preserve event attribution before a decision is made.

With `consentManagement.mapping`, you can map c15t categories to RudderStack consent IDs. c15t then loads RudderStack in its inert pre-consent mode, disables storage, buffers delivery, and sends every consent decision through `rudderanalytics.consent()`.

The default remains the stricter load gate. Pre-consent mode is opt-in because it should only be used when the mapped behavior matches your privacy policy.

→ [RudderStack](/docs/integrations/rudderstack)

## Microsoft Clarity, Mixpanel, and PostHog fixes

The Microsoft Clarity helper now uses Consent V2. c15t maps `marketing` consent to `ad_Storage` and `measurement` consent to `analytics_Storage`, and `defaultConsent` accepts a Consent V2 payload.

The helper also no longer adds Clarity's `v` marker before the vendor runtime loads. Clarity treated that marker as a duplicate installation, raised `CL001`, and could silently collect no data.

The Mixpanel helper now implements the official snippet contract, including the `__SV` version marker and `_i` initialization registry. This prevents the SDK from reporting a version mismatch and dropping events queued before it finishes loading.

The PostHog helper now seeds the pending initialization tuple expected by current `array.js` releases. It also keeps `posthog.capture(...)` calls made before the SDK arrives in PostHog's root queue and applies the consent decision before those events replay. Existing installed SDK methods remain untouched if an `after-consent` integration loads again after consent is revoked and restored.

The core script loader also now preserves an explicit `async: false`, which is required by synchronous vendor embeds such as legacy Adobe Tags configurations.

→ [Microsoft Clarity](/docs/integrations/microsoft-clarity) · [Mixpanel](/docs/integrations/mixpanel-analytics) · [PostHog](/docs/integrations/posthog)

## Policy-aware primary action styling

Themes can now define `consentActions.primary` to style whichever action the active policy marks as primary. The policy continues to decide whether that action is accept, reject, or customize, while the theme controls how primary actions look.

Explicit component props and per-action theme keys still take precedence. The IAB consent banner now uses the same resolution rules instead of bypassing `consentActions` with hard-coded button variants.

## Content Security Policy support

c15t injects a `<style>` element for your theme tokens and a `<script>` element for each consented vendor. Neither carried a nonce, so a nonce-based Content Security Policy blocked both — and because a directive that specifies a nonce ignores `'unsafe-inline'`, the only escape was to abandon nonces for that directive.

The provider now accepts a `nonce` and applies it to everything c15t injects:

```tsx
<ConsentManagerProvider options={{ mode: 'offline', nonce }}>
  {children}
</ConsentManagerProvider>
```

A `nonce` set on an individual script definition still takes precedence, so you can override a single vendor without changing the provider.

This covers the elements c15t injects. Inline `style` attributes are governed by `style-src-attr`, a directive that ignores nonces entirely, so a policy that restricts it is unaffected by this option.

→ [React ConsentManagerProvider](/docs/frameworks/react/components/consent-provider) · [Next.js ConsentManagerProvider](/docs/frameworks/next/components/consent-root)

## IAB TCF reliability

IAB TCF now works correctly when c15t runs in offline mode or falls back from the hosted service. The IAB runtime receives the GVL fetcher directly, allowing the Global Vendor List to load so the banner can render.

GVL requests now use the resolved consent language, keeping vendor purposes and features aligned with the rest of the interface. Changing language or location overrides also carries the IAB configuration through re-initialization and refreshes the GVL instead of retaining stale content.

→ [React IAB](/docs/frameworks/react/iab) · [Next.js IAB](/docs/frameworks/next/iab) · [Self-Hosted IAB](/docs/self-host/guides/iab-tcf)

## More reliable consent submissions

Concurrent saves with the same consent decision are now coalesced in the client and resolve to the same deterministic record in the backend. This prevents duplicate consent rows when identical requests arrive together while preserving idempotent retries across every supported database.

The backend also handles incorrect client clocks more safely. Timestamps more than five minutes in the future are clamped to server time for consent validity, while the original client value is retained in metadata and used to keep retries idempotent. The client then synchronizes its local consent state to the timestamp accepted by the server.

Legacy duplicate lookups are now scoped to the current tenant, and timestamps outside JavaScript's representable `Date` range are rejected before an ID is derived.

## Backend, API, and compatibility improvements

* Browser, SSR, prefetch, and Node SDK requests now forward `x-c15t-version`, and the backend allows it through CORS preflight handling.
* Custom `headers` configured for hosted clients are no longer dropped. They are included in the runtime cache key so differently configured clients cannot share an instance.
* Explicit ports in `trustedOrigins` are now matched exactly, while host-only entries remain port-agnostic.
* Legal document types now accept suffixed variants such as `terms_and_conditions_b2b`, allowing multiple policies from the same family.
* Generated OpenAPI request schemas are more accurate for consent, subject, and legal-document endpoints.
* `@c15t/backend` now supports `drizzle-orm` 0.45.x, Prisma 7, and MongoDB 7 through updated optional peer ranges.
* A dependency and security audit updates core runtime dependencies, removes unused oRPC packages, and raises patched dependency floors. Published declaration types remain semantically unchanged after the move to TypeScript 7 and rslib 0.23.

## Hindi, Gujarati, and translation fixes

Hindi (`hi`) and Gujarati (`gu`) are now available across cookie banners, consent dialogs, preference centers, and IAB TCF consent UI, bringing the translation catalog to 35 languages.

The second sentence of the IAB consent-storage notice is now translated in all 32 non-English locales instead of falling back to English. This release also fixes a stray German word in the Latvian custom-vendors notice.

## Documentation and integration checks

Every new script and renderable integration has a dedicated guide with React and Next.js examples, lifecycle behavior, configuration, and verification steps. The docs also clarify consent subject identification and add 11 comparison guides for teams evaluating c15t alongside other consent tools.

Built-in script providers are now exercised by a daily live-vendor monitor, with additional checks that always-loaded providers do not send data while consent is denied. This helps catch upstream loader changes that static tests cannot see.

<ContributorBlock usernames={["devcool20", "IshaanXCoder", "d180", "lyricwulf", "sorodrigo", "BurnedChris", "kgarg2468", "KayleeWilliams"]} title="Thank you to our contributors" />

# v3.0.0 - The Open Standard for Cookie Banners
URL: https://c15t.com/changelog/3.0.0
Major release notes for c15t 3.0. One consent engine for Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit and plain HTML, banners in the server HTML, the consent manifest, policy rules, GPP, publisher restrictions, new integrations and a rewritten self-hosted backend.

c15t 3 is a rebuild. v2 was a React library with a Next.js adapter. v3 is one
consent engine with adapters for eight frameworks and a script tag, and every
adapter passes the same conformance suite, so a policy behaves the same in
Nuxt as it does in Next.js. Server-rendered apps can now decide consent on the
server and send the banner with the page.

Your visitors shouldn't notice the upgrade, because v3 reads the consent v2
stored. Your code will notice. Read [Upgrading](#upgrading) before you start.

## Highlights

* **Eight frameworks and a script tag.** TanStack Start, Nuxt, Vue, Astro,
  Svelte and SvelteKit join Next.js and React. `@c15t/browser` covers plain
  HTML, WordPress, Shopify and other CMS sites.
* **One package.** `npm install c15t`, then import from `c15t/next`,
  `c15t/react`, `c15t/vue`, `c15t/tanstack-start` or `c15t/astro`.
* **Banner in the first HTML.** Server-rendered frameworks can render the
  banner on the server. v2 always mounted it after hydration.
* **Consent manifest.** Your server caches one manifest per site and decides
  each visitor's policy itself. With 150 ms of backend latency, time to first
  byte in our Next.js benchmark fell from 157.6 ms to 7.4 ms.
* **Less work in the browser.** Smaller render-blocking CSS, themes built on
  the server, the dialog and optional modules loaded on demand, and React
  components that re-render only when the value they read changes.
* **Policy rules.** A simpler policy format, 34 presets instead of 6,
  notice-only prompts, and Global Privacy Control applied live instead of
  stored as a refusal.
* **Per-vendor consent.** Visitors can switch off one vendor inside a category
  they allowed, without IAB.
* **GPP and publisher restrictions.** GPP 1.1 with 16 US state sections, and
  IAB publisher restrictions encoded in the TC string.
* **New integrations.** Cloudflare Zaraz, Klaviyo and the OpenAI pixel for
  ChatGPT Ads. `@c15t/scripts` is now `@c15t/integrations`.
* **Rewritten self-hosted backend.** Built on Effect SQL, with PostgreSQL,
  MySQL and SQLite, and a migrator that adopts your v2 database.

## One engine, more frameworks

v2 kept consent in a Zustand store that set up blockers and wrote to `window`
as soon as you created it. v3's consent kernel does nothing until you call a
command, so it is safe to import on the server, and every adapter reads it
the same way. One conformance suite tests React, Vue and Svelte against the
same policy, storage, event and accessibility checks, including records
written by v2.

In v2, the `c15t` package was the headless engine. In v3 it installs the
engine and the adapters, and the root `c15t` import is still the engine. The
scoped packages, such as `@c15t/nextjs`, are still published. Svelte, the
script tag and the vendor helpers install separately as `@c15t/svelte`,
`@c15t/browser` and `@c15t/integrations`.

|Framework|What's new|Start here|
|--|--|--|
|Next.js|Server-side consent in both the App Router and, new in v3, the Pages Router. Static export, ISR and Cache Components are supported. Requires Next.js 15 or 16.|[Quickstart](/docs/frameworks/next/quickstart)|
|TanStack Start|New adapter. Consent resolves in the root route loader.|[Quickstart](/docs/frameworks/tanstack-start/quickstart)|
|React|Client-rendered apps such as Vite, React Router and Remix. Requires React 18 or 19.|[Quickstart](/docs/frameworks/react/quickstart)|
|Nuxt|New module, with server rendering and a Nuxt DevTools tab. Works with Nuxt 3 and 4, including Vue Vapor pages in Nuxt 4.6.|[Quickstart](/docs/frameworks/nuxt/quickstart)|
|Vue|New plugin for Vue 3 apps without Nuxt.|[Quickstart](/docs/frameworks/vue/quickstart)|
|Astro|New integration. The banner is plain `.astro` markup with no framework JavaScript, and the dialog is an island in Svelte, React or Vue.|[Quickstart](/docs/frameworks/astro/quickstart)|
|Svelte and SvelteKit|New package, `@c15t/svelte`, with SvelteKit helpers in `@c15t/svelte/kit`.|[Svelte](/docs/frameworks/svelte/quickstart), [SvelteKit](/docs/frameworks/sveltekit/quickstart)|
|HTML and CMS sites|New package, `@c15t/browser`, with setup steps for WordPress, Webflow, Shopify and seven other platforms.|[Quickstart](/docs/frameworks/html/quickstart)|
|JavaScript|`createConsentRuntime()` for your own UI, or `@c15t/browser` for the stock banner.|[Quickstart](/docs/frameworks/javascript/quickstart)|

The script tag needs no build step. Your Inth project serves it with your
backend URL and policy already inside:

```html
<script src="https://your-project.inth.app/c15t.js" defer></script>
```

A self-hosted backend serves the same file at its own `/c15t.js`, and jsDelivr
has it for sites without a backend.

## Faster pages

Most of the speed in v3 comes from deciding consent earlier, on the server
where possible, and from keeping CSS and optional code off the critical path.

### The banner in the first HTML

Next.js, TanStack Start, Nuxt, Astro and SvelteKit can resolve consent while
they render, so the banner arrives with the page and a returning visitor's
gated scripts start at hydration. A slow backend can't hold the page past a
500 ms budget by default. The Next.js App Router streams consent by default, which keeps
the banner out of the first HTML; awaiting it can delay the page's reveal by
about 300 ms. [Next.js rendering](/docs/frameworks/next/rendering) compares
the options.

### Consent manifest

The backend has a new `GET /manifest` endpoint. It returns one public document
per project with everything `/init` needs and no visitor data, so a CDN can
cache it. Your server keeps a copy and resolves each visitor from the
request's country, region, language and GPC headers. Page renders stop
waiting on the consent backend, and only cache misses reach it. If the
manifest can't be read, the server falls back to `/init`.

In a Next.js 16 production build with a local backend that adds 150 ms to
each request, medians of 10 runs:

|Server render|Time to first byte|Banner painted|
|--|--:|--:|
|Backend `/init` on every request|157.6 ms|180 ms|
|Manifest, warm cache|7.4 ms|28 ms|

Both rows are v3. v2 never put the banner in the server HTML, so it never paid
for that round trip. [Data fetching](/docs/concepts/data-fetching) compares
the modes, and each framework's rendering guide shows how to turn the
manifest on.

### Less work in the browser

* **CSS.** The main stylesheet holds only what a first paint can show, and
  dialog styles load with the dialog. In a Next.js 16 build, render-blocking
  CSS from c15t fell from 10.3 KB to 8.8 KB gzip.
* **Themes.** `ConsentTheme` and `generateThemeCSS()` render theme CSS on the
  server. v2 sent every visitor about 1.9 KB gzip of generator code.
* **React re-renders.** Components re-render only when the value they read
  changes. With 10 components reading 5 categories, changing one category
  caused 20 renders in v2 and 2 in v3.
* **On-demand code.** The script loader, network and iframe blockers, IAB, GPP
  and the preference dialog load only on pages that use them.
* **IAB pages.** Server integrations send a reference to the Global Vendor
  List instead of the list. With 1,211 vendors, the init JSON drops from 860 KB
  to 6.6 KB.

## Policies

Policy packs are now policy rules. A rule describes behavior only: who sees a
prompt, what kind, and which categories it covers. Layout moves to the
client's `presentation` option. Rules with unknown keys or categories now fail
validation.

* **Presets.** `policyPackPresets` is now `policyRulePresets`, and
  `worldNoBanner()` is now `worldOptOutNoPrompt()`. 28 presets are new, covering the US
  privacy states, Canada, Australia, Japan, Switzerland, the UK, Brazil,
  India and much of Asia and the Middle East. Each lists its sources in
  `review`. A preset is a starting point, not legal advice.
  `recommendedPolicyRules()` gives you a ready set. The
  `policy-packs-to-policy-rules` codemod renames both.
* **Notice prompts.** `prompt: 'notice'` asks for an acknowledgement instead
  of a choice, and leaves earlier refusals in place.
* **No jurisdiction label.** v2 picked `GDPR`, `CCPA` or `NONE` from a fixed
  country table. v3 decides from your rules alone.
* **Consent records.** A record stores only what the visitor did. c15t works
  out permissions against the current rule each time it reads it, so the same
  record can mean different things under opt-in and opt-out rules.
* **Asking again.** c15t asks again when a choice expires or when the rule it
  was made under changes in a way that affects it. Bump `copyRevision` to ask
  everyone after a wording change.
* **Global Privacy Control.** GPC is read live on every evaluation and never
  stored as a refusal, so the restriction ends when the browser stops sending
  it.

[Policies](/docs/concepts/policies) and
[how consent works](/docs/concepts/how-consent-works) cover the model.

## Consent controls

* **Per-vendor consent outside IAB.** Declare `vendors`, and the preference
  center lists each category's vendors with its own switch.
* **`ConsentGate`** replaces `Frame` in every framework and holds back any
  embed until its category or vendor is allowed.
* **Banner presentation.** `presentation` picks a `floating`, `bar`, `widget`
  or `wall` banner, its position and its actions.
* **Experiments.** A/B test presentation and theme, with a per-arm summary
  from the backend. See [banner experiments](/docs/guides/banner-experiments).
* **Clear on revocation.** `clearOnRevocation` deletes declared cookies and
  storage keys when a visitor revokes a category.
* **Follow another CMP.** `consentSource` mirrors an existing CMP's decisions.

## IAB TCF and GPP

* **Global Privacy Platform.** c15t can install the GPP 1.1 API at `__gpp`.
  IAB rules add the TC string, and US rules add the visitor's state section
  for 16 states, with the US National section for everyone else.
* **Publisher restrictions.** v2 never encoded them. v3 writes them into the
  TC string, applies them to gated scripts and shows each vendor under the
  legal basis they leave.
* **IAB in every framework.** v2 had IAB banners for React and Next.js only.
  v3 adds Nuxt, Vue, Astro, Svelte, SvelteKit and the script tag.

TCF 2.4 support arrived in v2.3.0 and carries over.

## Integrations

`@c15t/scripts` is now `@c15t/integrations`. Subpaths and helper names stay the
same, all 38 v2 helpers carry over, and `@c15t/scripts` stays published as a
deprecated re-export until v4.

|New integration|What it does|
|--|--|
|[Cloudflare Zaraz](/docs/integrations/cloudflare-zaraz)|Maps c15t categories to Zaraz purposes. Zaraz still runs the tools.|
|[Klaviyo](/docs/integrations/klaviyo)|Signup forms and onsite tracking, with a forms-only mode that keeps tracking off.|
|[OpenAI pixel](/docs/integrations/openai-pixel)|The ChatGPT Ads measurement pixel, with typed conversion events.|

`createEventDispatcher()` sends one event to every allowed integration that
has an event API. PostHog, Google Tag Manager, gtag and Segment take new
options. Helpers now re-run their consent steps only when their own vendor's
consent changes, and Matomo, Amplitude, Heap, Umami, Meta, X, TikTok and Crisp
have fixes. See the [integrations overview](/docs/integrations/overview).

## Self-hosted backend

`@c15t/backend` is rewritten on Effect 4 and Effect SQL, and
`c15tInstance(options).handler(request)` works as before. Queries use joins
and new indexes. In our benchmark, with PGlite and 1,000 subjects among 20,000
other rows, the subject read path went from 11.9 ms to 3.3 ms median.

* PostgreSQL, MySQL and SQLite replace the Drizzle, Prisma, TypeORM, Kysely
  and MongoDB adapters. MongoDB has no migration path.
* `c15t self-host migrate` adopts a v2 schema without dropping tables or
  columns.
* New routes serve the manifest, session reports for visitor counts,
  experiment summaries and the script-tag bundles.
* A save retried up to 7 days after a failure is accepted if the policy
  hasn't changed since the click.
* A v3 backend can share a database with a v2 backend while you roll out.

See the [backend quickstart](/docs/self-host/quickstart) and
[database setup](/docs/self-host/guides/database-setup).

`@c15t/node-sdk` has a new client, `createC15tClient()`. Methods return a
result instead of throwing, and transient failures retry. See the
[Node.js SDK reference](/docs/self-host/api/node-sdk).

## CLI and dev tools

* `c15t setup` scaffolds every supported framework, and `--plan` previews the
  changes first. See [setup](/docs/cli/commands/setup).
* [Codemods](/docs/cli/commands/codemods) migrate most v2 source: the
  provider and its transports, moved exports, `useConsentManager()`,
  callbacks, policy presets, CSS variables, the Tailwind CSS 3 plugin, dev
  tools, `@c15t/scripts` imports, the Node.js SDK and the backend config.
  Where a change needs a decision, they leave a `TODO(c15t v3)` comment that
  fails the build.
* Dev tools no longer depend on React. There is a panel for any framework,
  plus TanStack Devtools and Nuxt DevTools tabs.

## Upgrading

Each v2 package has a step-by-step guide that opens with a prompt you can
paste into a coding agent: [Next.js](/docs/frameworks/next/upgrade-v3),
[React](/docs/frameworks/react/upgrade-v3) and
[JavaScript](/docs/frameworks/javascript/upgrade-v3). If you run
your own c15t backend, [upgrade it](/docs/self-host/upgrade-v3) and the
Node.js SDK in the same release.

**Visitors keep their choices.** v3 reads the `c15t` cookie and storage key
v2 wrote. A v2 denial keeps blocking its category, and a v2 grant keeps
applying until it expires. When the rule comes from a preset and the v2 record
noted its policy, v3 also asks again if that policy changed.

**Upgrade clients and backend together.** A v3 client can't read a v2
backend's `/init`. It shows no banner and keeps optional categories denied.
Inth-hosted URLs work with v3 clients.

**Start with the codemods.**

```bash
npx @c15t/cli codemods consent-provider-options root-exports-to-subpaths use-consent-manager-to-hooks scripts-to-integrations dev-tools-to-c15t policy-packs-to-policy-rules callbacks-to-v3 theme-to-consent-theme iab-option-to-iab-provider css-variables-to-v3 postcss-tailwind3 --dry-run --json
```

Review the proposed files, then run the command again without `--dry-run`.
Self-hosted backends and Node.js servers add `backend-config-to-v3` and
`node-sdk-to-v3`.

## Breaking changes

The upgrade guides cover each of these with before and after code.

* **Every package.** ESM only. React 18 or later and Next.js 15 or later.
* **Provider.** `ConsentManagerProvider` is now `ConsentProvider`, and `mode`
  plus `backendURL` become one transport, such as `hosted({ url })`. Next.js
  server rendering moves from `fetchInitialData()` to `resolveConsent()` and
  `ConsentRoot`. Codemod: `consent-provider-options`.
* **Hooks.** `useConsentManager()` is gone, replaced by one hook per field.
  Codemod: `use-consent-manager-to-hooks`.
* **Exports.** Headless hooks, trigger atoms, token types and flat banner
  parts leave the `c15t/react` and `c15t/next` roots for subpaths. Codemod:
  `root-exports-to-subpaths`.
* **Callbacks.** `onConsentSet` and `onConsentChanged` become
  `onPermissionsChanged` and `onChoiceRecorded`, with new payloads. Codemod:
  `callbacks-to-v3`.
* **Themes and styles.** `theme` tokens no longer produce CSS on their own, so
  render `ConsentTheme`. Tailwind CSS 3 needs the `c15t/postcss-tailwind3`
  plugin, and several CSS variables are renamed. Codemods:
  `theme-to-consent-theme`, `postcss-tailwind3` and `css-variables-to-v3`.
* **IAB.** The `iab` provider option becomes `IABProvider`, and `@c15t/iab`
  drops `createIABManager`. Codemod: `iab-option-to-iab-provider`.
* **Removed.** `YouTubeEmbed`, `GoogleMap`, `useConsentScript()` and
  `ConsentButton`.
* **JavaScript.** The v2 store and `getOrCreateConsentRuntime()` are gone.
* **Self-hosted backend.** `adapter` becomes `database`, `policyPacks` moves
  to `manifest.policyRules`, and the schema needs a migration. Codemod:
  `backend-config-to-v3`.
* **Node SDK.** `c15tClient()` becomes `createC15tClient()`. Codemod:
  `node-sdk-to-v3`.
* **CLI and dev tools.** Run `c15t login` again. Dev tools move to
  `c15t/react/devtools` and `c15t/next/devtools`. Codemod:
  `dev-tools-to-c15t`.

<ContributorBlock usernames={["KayleeWilliams", "BurnedChris", "dan-hale", "bennajah", "prashantbhudwal"]} title="Thank you to our contributors" />

# @c15t/browser client options
URL: https://c15t.com/docs/shared/browser/client-options
Shared option tables for the @c15t/browser client, used by the HTML and JavaScript guides.

## Connection and policy

The `init()` and `createConsentClient()` of the `@c15t/browser` ES module,
`@c15t/browser/headless` and `@c15t/browser/iab` take `mode` as a factory
and none of the connection options below it. The script-tag builds and the
`@c15t/browser/hosted` and `@c15t/browser/offline` entries take the rest of
the table: `c15t.js` and `@c15t/browser/hosted` accept hosted mode only and
require a backend URL or hosted factory, and `c15t.offline.js` and
`@c15t/browser/offline` accept offline mode only.

|Option|Type|Default|What it does|
|--|--|--|--|
|`mode`|A transport factory. Script-tag builds also take `'hosted'`, `'offline'` or `'manifest'`.|Required in the ES modules. Script-tag builds pick it from the other options.|A factory from `manifest()`, `hosted()`, `offline()` or `custom()` is used as is; see [consent modes](/docs/concepts/modes). In the script-tag builds, `manifest` when `manifest` or `manifestURL` is set, `hosted` when `backendURL` is set, otherwise `offline`. Hosted mode without `backendURL` throws.|
|`backendURL`|`string`|none|Script-tag builds, `/hosted` and `/offline` entries. Your Inth or self-hosted backend URL, for hosted and manifest modes. In the ES modules, pass it to the factory, such as `hosted({ backendURL })`.|
|`manifest`|`ConsentManifest`|none|Script-tag builds. The backend's policy manifest, inlined in the page, for manifest mode. In the ES modules, `manifest({ snapshot })`.|
|`manifestURL`|`string`|none|Script-tag builds. Where manifest mode fetches the manifest. A URL that ends in `/manifest` also gives the backend URL; any other URL needs `backendURL` too. In the ES modules, `manifest({ manifestURL })`.|
|`policyRules`|array of policy rules or preset names|recommended rules|Script-tag builds and the `/hosted` and `/offline` entries. Offline mode only. A preset name such as `'europeOptIn'` stands for that preset in `policyRulePresets`. An unknown name throws. In the ES modules, `offline({ policyRules })` with rule objects.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|The visitor's location, language or GPC signal, when the page knows it. Policy matching uses these instead of detection.|
|`prefetch`|kernel configuration|none|A server-resolved init answer. When it carries a resolved policy, the client renders from it and does not call `/init`.|
|`enabled`|`boolean`|`true`|`false` grants every category, shows no UI and loads every configured script at once.|

## Scripts, blockers and data

|Option|Type|Default|What it does|
|--|--|--|--|
|`scripts`|`Script[]`|`[]`|Vendor scripts to load once their category is allowed. Each entry needs `id`, `category`, and `src` or `textContent`.|
|`consentCategories`|category names|categories your scripts, iframes and rules use|The categories the preference dialog offers, within the policy's scope. `necessary` is always included.|
|`networkBlocker`|`{ rules, enabled?, logBlockedRequests?, onRequestBlocked? }` or `false`|off|Hold `fetch` and `XMLHttpRequest` calls that match a rule until the rule's category is allowed.|
|`iframeBlocker`|`{ disableAutomaticBlocking? }` or `false`|on|Gate iframes that carry `data-category` or `data-vendor`. `false` turns it off. With `disableAutomaticBlocking: true`, c15t checks iframes only when you call `processIframes()`.|
|`nonce`|`string`|none|Content Security Policy nonce for the stock UI's `<style>` element and every `<script>` the `scripts` option loads. A script's own `nonce` wins. With a nonce set, c15t runs only the `<script type="text/plain" data-c15t-category>` tags that carry the same `nonce`.|
|`scriptLoader`|`{ onDebug? }`|none|`onDebug` receives every script loader lifecycle event.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. The preference dialog lists a switch for each. They merge with vendors from the backend, `vendor` fields on scripts and rules, and `data-c15t-vendor` on gated tags.|
|`clearOnRevocation`|cookies and storage keys per category|off|Delete named cookies and storage keys when their category is denied. Read once, at start.|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reload the page after an accept, reject or save turns off a category that was allowed, once the save request finishes.|
|`callbacks`|`{ onChoiceRecorded?, onPermissionsChanged?, onError?, onBeforeConsentRevocationReload? }`|none|Functions c15t calls on consent events.|
|`storageConfig`|`{ storageKey?, crossSubdomain?, defaultDomain?, defaultExpiryDays? }`|key `c15t`, current host, 365 days|The name, domain and lifetime of the consent cookie and localStorage key.|
|`persistence`|`boolean` or `{ storageConfig?, skipHydration?, sync? }`|`true`|Read and write choices in the cookie and localStorage, and follow other tabs. `false` keeps choices in memory only. `{ sync: false }` stops following other tabs.|
|`user`|`{ externalId, identityProvider?, identityToken?, externalIdType?, properties? }`|none|An identified visitor, sent with consent records. [`identityToken`](/docs/self-host/api/node-sdk#verify-a-link-made-in-the-browser) verifies the link. Links only a subject the next save creates; use `identify()` for an existing one.|
|`iab`|IAB options or `false`|none|CMP settings such as `cmpId` and `vendors`. Only the IAB build accepts it; the other builds throw when it is set.|

## Presentation and copy

|Option|Type|Default|What it does|
|--|--|--|--|
|`ui`|UI options or `false`|stock UI on|Theme tokens, CSS, surfaces and mounting. `false` starts the client with no UI. See [UI options](#ui-options).|
|`presentation`|`{ prompt?, preferences? }`|floating banner, bottom left|Banner shape, position, button layout and blocking, within what the policy allows.|
|`i18n`|`{ locale?, messages }`|English|The language to start in, and messages per language that override the bundled, backend or manifest copy key by key for that language.|
|`legalLinks`|`{ privacyPolicy?, cookiePolicy?, termsOfService? }`|none|Each link is `{ href, label?, target?, rel? }`. The banner and dialog show only the links their `legalLinks` option lists.|

## UI options

These go under `ui`. The headless builds ignore them.

|Option|Type|Default|What it does|
|--|--|--|--|
|`theme`|theme tokens|none|Colors, radius, typography, spacing and motion. The same token object every c15t package takes.|
|`css`|`string`|none|CSS added after the bundled stylesheet, in the same root as the UI.|
|`colorScheme`|`'light'`, `'dark'` or `'system'`|`'system'`|Which token set to use. `system` follows the visitor's setting and updates when it changes.|
|`shadow`|`boolean`|`true`|Render inside a shadow root. `false` renders into the page, where your stylesheet applies.|
|`styles`|`boolean`|`true`|Include the bundled stylesheet. Set `false` with `shadow: false` when the page loads the stylesheet itself.|
|`noStyle`|`boolean`|`false`|Render markup with no c15t classes and no bundled stylesheet, for fully custom CSS. `theme` and `css` still apply.|
|`disableAnimation`|`boolean`|the visitor's reduced motion setting|Show and hide surfaces without transitions.|
|`container`|element or CSS selector|`document.body`|Where the UI host element is appended. A selector that matches nothing throws.|
|`banner`|`boolean` or banner options|`true`|`false` renders no banner. An object sets copy and behavior; see the banner options.|
|`dialog`|`boolean` or dialog options|`true`|`false` renders no preference dialog.|
|`trigger`|`boolean` or trigger options|`false`|Render the floating button that reopens the dialog.|
|`iab`|`{ loadErrorText?, saveErrorText?, moreVendorsText? }`|translated copy|Copy for the IAB vendor list states. IAB build only.|

## Banner options

These go under `ui.banner`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`title`|`string`|translated title|Heading. A notice uses the notice title by default.|
|`description`|`string`|translated description|Body text. A notice uses the notice description by default.|
|`acceptButtonText`|`string`|"Accept All"|Label of the accept button.|
|`rejectButtonText`|`string`|"Reject All"|Label of the reject button.|
|`customizeButtonText`|`string`|"Customize"|Label of the button that opens the dialog.|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description. `null` or `[]` shows none.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag. The IAB banner always keeps it.|
|`scrollLock`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|
|`trapFocus`|`boolean`|from `presentation`|Deprecated. Use `presentation.prompt.blocking`.|

The dismiss button of a notice always uses the translated
`common.acknowledge` label. Change it through `i18n`.

## Dialog options

These go under `ui.dialog`.

|Option|Type|Default|What it does|
|--|--|--|--|
|`legalLinks`|list of `privacyPolicy`, `cookiePolicy`, `termsOfService`, or `null`|none|Which configured legal links to show after the description.|
|`hideBranding`|`boolean`|`false`|Hide the "Secured by" tag at the bottom of the dialog.|

The dialog's title, description, category names and button labels come
from translations. Change them through `i18n`.

## Trigger options

`ui.trigger: true` shows the trigger with its defaults. An object sets these:

|Option|Type|Default|What it does|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner the button starts in.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`showWhen`|`'always'` or `'after-consent'`|`'always'`|`after-consent` hides the button until the visitor has answered the prompt.|
|`ariaLabel`|`string`|"Open privacy settings"|The button's accessible name. It has no visible text.|
|`persistPosition`|`boolean`|`true`|Remember the corner a visitor dragged the button to, in localStorage. A remembered corner wins over `position`.|

|Value|What a click does|
|--|--|
|`accept`|Like the banner's accept button, allows every category the dialog offers without IAB. Under an IAB policy it confirms the vendors' declared processing through the CMP. Optional categories without declared consent purposes remain denied. See [categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).|
|`reject`|Rejects every optional category the dialog offers.|
|`customize`|Opens the preference dialog. Records nothing.|
|`dismiss`|Dismisses a notice. This records an acknowledgement, not consent, and does nothing unless the policy shows a notice.|
|`banner`|Shows the banner again. Records nothing.|
|`close`|Closes the banner or dialog. Records nothing.|

|Event|Payload|When it fires|
|--|--|--|
|`ready`|the snapshot|The policy has resolved and the UI can render. For a returning visitor, `hasConsented()` is reliable from here.|
|`consent`|the snapshot|Permissions, the recorded choice or the vendor switches changed. This includes a stored choice restored at start, a save, an expiry and a GPC change.|
|`ui`|`'banner'`, `'dialog'` or `'none'`|The surface c15t wants shown changed.|
|`error`|the error|A backend call failed, or an IAB step failed.|

A `ready` listener added after the policy resolved runs at once with the
snapshot from that moment. A `ui` listener added after that runs at once
with the current surface. `consent` and `error` listeners only hear later
changes.

# Astro
URL: https://c15t.com/docs/shared/build-manifests/astro
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

`manifest()`, the default mode, bundles the manifest. The integration fetches
it when `astro build` or `astro dev` starts, then embeds it in its generated
server options. The middleware and the consent route use that same snapshot.
The browser options omit it; only `manifest({ resolve: 'browser' })` serves
it to the browser, as the prerendered `/api/c15t/manifest`. No
generated file or extra import is needed. `astro check` and `astro sync` do
not fetch, so type checks work without the backend. `astro preview` serves the
completed build and never fetches a new snapshot.

The build fetches only from an absolute upstream backend URL or
`manifestURL`, because it cannot fetch a route in the app it is still
compiling. `c15t()` without a `backendURL` reads `PUBLIC_C15T_BACKEND_URL`, then
`PUBLIC_INTH_PROJECT_URL`.
With a relative URL, `manifest({ source: 'runtime' })`,
`manifest({ snapshot })`, `hosted()` or `offline()`, the integration skips
the fetch. If the fetch fails, or no backend URL is set, `astro build` stops.
`astro dev` logs a warning instead, and the server fetches and caches the
policy at runtime. The config is read once at build time, so the built server
keeps the backend URL and the snapshot it was built with.

To let a build continue when the snapshot can't be fetched, set
`onBuildError: 'runtime'`, or build with `C15T_ON_BUILD_ERROR=runtime`:

```js title="astro.config.mjs"
c15t({ onBuildError: 'runtime' });
```

`onBuildError: 'fail'` stops `astro dev` too, and stops the build on a
relative URL.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

For policy updates without a rebuild, set `mode: manifest({ source: 'runtime' })`.
The server then fetches and caches the policy at runtime.

# Javascript
URL: https://c15t.com/docs/shared/build-manifests/javascript
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Install `c15t@alpha` alongside `@c15t/browser` for the build plugin. Add it to
your existing Vite plugins:

```ts title="vite.config.ts (plugins option)"
import { consentManifest } from 'c15t/build';

export default {
	plugins: [
		// Keep your existing framework plugins here.
		consentManifest({ backendURL: 'https://your-project.inth.app' }),
	],
};
```

Without `backendURL`, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`. The plugin
fetches the policy during `vite build`, or in `vite dev` when the app first
loads it, and serves it as `snapshot` from `c15t/generated`. A build fetches
only when the app uses `manifest()`. In your browser entry point, pass
`manifest()` as the mode of the existing `init()` call. It reads the snapshot
and the backend URL from `c15t/generated`:

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';

init({ mode: manifest() });
```

Keep your scripts and UI options. The browser resolves the snapshot without
a manifest request when the policy does not need geography, or the required
country and region are known through `overrides`. When required
geography is missing, it calls backend `/init` and uses the backend's resolved
policy and translations. Those visitors still wait for a backend round trip
and can receive newer policy than the build snapshot.

When the build has no snapshot, as in `vite dev` after a failed fetch,
`snapshot` is `undefined`, and the browser fetches
`${backendURL}/manifest` instead.

A script-tag site without a build step cannot run this hook.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy updates without a rebuild, use `hosted()`, which asks the backend's
`/init` on each page load, or `manifest({ source: 'runtime' })`, which fetches
the manifest at runtime. Both keep reading the backend URL from the plugin.

# Next
URL: https://c15t.com/docs/shared/build-manifests/next
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

# Next Config
URL: https://c15t.com/docs/shared/build-manifests/next-config
Wrap your Next.js config in `withConsentManifest`. An existing config object or function goes in as the first argument, unchanged:

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

# Next Pages
URL: https://c15t.com/docs/shared/build-manifests/next-pages
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Wrap your Next.js config in `withConsentManifest`. An existing config object
or function goes in as the first argument, unchanged:

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

`next build`, `next dev` and `next typegen` fetch `${backendURL}/manifest` and
write the policy to `node_modules/.cache/c15t/`, outside your source tree, so
there is nothing to keep out of Git. `next start` serves the built snapshot and
fetches no policy. Without a `backendURL` option, the build reads the
`backendURL` in `c15t.config.ts`, which defaults to
`NEXT_PUBLIC_C15T_BACKEND_URL`, then `NEXT_PUBLIC_INTH_PROJECT_URL`, so saves
and the snapshot point at the same
project.

The wrapper reads `c15t.config.ts` the way Next.js reads `next.config.ts`, and
skips the fetch for `mode: hosted()`, `mode: offline()`,
`manifest({ snapshot })` and `manifest({ source: 'runtime' })`, which read no
build-time manifest. Those builds never contact the backend. If the file can't
be read at build time, for example because it imports something Node can't
load, the build warns and fetches as for `manifest()`.

The wrapper also finds `c15t.config.ts` (or `.mts`, `.js`, `.mjs`) at the
project root, next to `next.config.ts`, and points `c15t/generated` at the
cache, in Turbopack and webpack. `ConsentRoot`, `resolveConsent` and the
consent route read both without an import. Server code that needs the
snapshot itself imports `snapshot` from `c15t/generated`. Only server
bundles get the snapshot: in a browser bundle,
`c15t/generated` imports `server-only`, so importing it from a client
component fails the build. The wrapper also adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages`, so Pages Router server bundles see the
aliases. A package you list in `serverExternalPackages` stays external: it
reads no `c15t.config.ts` and fetches the policy at runtime.

If the fetch fails, `next build` stops. `next dev` logs a warning instead, and
`snapshot` is `undefined`, so the server fetches and caches the policy at
runtime, as with
[runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
To let a build continue the same way, set `onBuildError: 'runtime'`, or run it
with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="next.config.ts"
export default withConsentManifest(nextConfig, { onBuildError: 'runtime' });
```

A missing backend URL counts as a failed fetch. The build skips the fetch and
leaves `snapshot` `undefined` when the backend URL is relative, or when the
config sets `output: 'export'`, which has no server to use the snapshot. With
`onBuildError: 'fail'`, a relative URL stops the build. A static export always
skips the fetch.

`withConsentProps()` and `createPagesConsentRoute()` read the snapshot
through the same alias. The wrapper adds `c15t`, `@c15t/core` and
`@c15t/nextjs` to `transpilePackages` for this: the Pages Router leaves
dependencies external on the server otherwise, and an external package does
not see the alias.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

To apply policy edits without a rebuild, set
`mode: manifest({ source: 'runtime' })` in `c15t.config.ts`. The server then
uses [runtime manifest caching](/docs/frameworks/next/optimization#reuse-cached-policy-data).
Keep `withConsentManifest`, which also finds `c15t.config.ts`.

# Nuxt
URL: https://c15t.com/docs/shared/build-manifests/nuxt
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

The default mode, `manifest()`, bundles the manifest. The module reads
`NUXT_PUBLIC_C15T_BACKEND_URL`, then `NUXT_PUBLIC_INTH_PROJECT_URL`, when the
`c15t` key sets no `backendURL`, so
`nuxt.config.ts` needs only the module:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
});
```

The module fetches the snapshot during `nuxt build` and when `nuxt dev`
starts, and embeds it in the server bundle. `nuxt prepare` does not fetch, so
dependency installation and type generation do not need the backend. The
consent route and the server render read the snapshot; it stays out of
runtime config and out of the browser bundle. Only
`manifest({ resolve: 'browser' })` adds it to the browser bundle, because the
browser then resolves the policy itself. Production server startup does not
fetch another manifest.

The module skips the fetch for `manifest({ source: 'runtime' })`, a
`manifest({ snapshot })` you supply, and the `hosted()` and `offline()`
modes. A relative backend URL is also skipped, unless `onBuildError` is
`'fail'`.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

Set `onBuildError` under the `c15t` key in `nuxt.config.ts`. In dev, and in a
build with `onBuildError: 'runtime'`, a failed fetch leaves the server without
a snapshot, and the server fetches and caches the policy at runtime.

For policy updates without a rebuild, set `mode: manifest({ source: 'runtime' })`.
The server then fetches and caches the policy at runtime, and refreshes it
in the background.

# React
URL: https://c15t.com/docs/shared/build-manifests/react
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Add `consentManifest` to your existing Vite plugin list:

```ts title="vite.config.ts (plugins option)"
import { consentManifest } from 'c15t/build';

export default {
	plugins: [
		// Keep your existing framework plugins here.
		consentManifest({ backendURL: 'https://your-project.inth.app' }),
	],
};
```

Without `backendURL`, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`. The plugin
fetches the policy during `vite build`, or in `vite dev` when the app first
loads it, and serves it as `snapshot` from `c15t/generated`. A build fetches
only when the app uses `manifest()`. In `src/consent.tsx`, create the
provider's mode with `manifest()` from `c15t/react` instead of `hosted()`. It
reads the snapshot and the backend URL from `c15t/generated`:

```tsx title="src/consent.tsx"
import { manifest } from 'c15t/react';

const mode = manifest();
```

Keep passing `mode` to `ConsentProvider`. The browser resolves the snapshot
without `/manifest` when it has the geography the policy needs, or the policy
does not depend on geography. Supply known country and region through `inputs`
or overrides to keep regional resolution on the snapshot.

When the build has no snapshot, as in `vite dev` after a failed fetch,
`snapshot` is `undefined`, and the browser fetches
`${backendURL}/manifest` instead.

When the required country or region is missing, the transport calls backend
`/init` and uses its resolved policy and translations. `consentManifest` warns
during the build when it downloads such a policy, and suggests `hosted()`. That response can use
newer backend policy than the build snapshot. This is a full consent resolution,
so these visitors still wait for a backend round trip. `ConsentProvider` sends
that request while it first renders, before the page mounts, unless the visitor
has a stored choice.

The browser cannot guess the banner from the snapshot alone when locations
differ. With a European opt-in rule and no banner elsewhere, a banner shown
before `/init` answers would vanish for most of the world. The exception is a
policy whose country and region rules all show the same banner, with a default
rule that covers everywhere else: the browser resolves it at once. To skip the
round trip for location-specific rules, pass the country your CDN or edge
already knows through `inputs`.

Policy and resolver code are part of the browser bundle.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy updates without a rebuild, use `hosted({ backendURL })` from `c15t/react`
as the mode and omit the build plugin. That setup resolves policy through the
backend `/init` on each page load.

# Sveltekit
URL: https://c15t.com/docs/shared/build-manifests/sveltekit
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

The [quickstart](/docs/frameworks/sveltekit/quickstart) sets this up across
these files:

|File|Role|
|--|--|
|`vite.config.ts`|`consentManifest` from `@c15t/svelte/vite` fetches the policy.|
|`src/hooks.server.ts`|`c15tHandle()`, whose default mode, `manifest()`, resolves from the fetched policy.|
|`src/routes/+layout.server.ts`|`export { loadConsent as load }` resolves each visitor.|
|`src/routes/+layout.svelte`|`ConsentRoot state={data.consent}` renders the result.|

The plugin's position in `plugins` does not matter. It fetches the policy
once Vite has resolved its config, before anything compiles. Without a
`backendURL` option, it reads `PUBLIC_C15T_BACKEND_URL`, then
`PUBLIC_INTH_PROJECT_URL`, from the environment or `.env`.

The plugin detects the `sveltekit()` plugin and keeps the snapshot on the
server. `loadConsent` and `createConsentRoute()` read it without an import.
The browser bundle never holds it: `ConsentRoot` gets the resolved policy
from `loadConsent` instead.

Static hosts follow [build a static site](/docs/frameworks/sveltekit/rendering#build-a-static-site)
instead.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

On SvelteKit 3, `svelte-kit sync` resolves the Vite config, so it runs the
plugin and fetches the policy too, following the same rules when the fetch
fails. SvelteKit 2.68 also runs the plugin during `svelte-kit sync`, but logs
a failed fetch and continues.

To apply policy edits without a rebuild, set
`c15tHandle({ mode: manifest({ source: 'runtime' }) })` and follow
[fetch the manifest at runtime](/docs/frameworks/sveltekit/rendering#fetch-the-manifest-at-runtime).
To have the backend resolve every visit instead, set
`c15tHandle({ mode: hosted() })`. The layout load then calls the backend's
`/init`, and so does the browser on pages the server did not resolve.

# Tanstack Start
URL: https://c15t.com/docs/shared/build-manifests/tanstack-start
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

Add the plugin before `tanstackStart()`:

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/tanstack-start/build';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), tanstackStart(), viteReact()],
});
```

The plugin reads the backend URL from `backendURL`, or from
`VITE_C15T_BACKEND_URL`, then `VITE_INTH_PROJECT_URL`, when you leave
`backendURL` out. If `VITE_C15T_BACKEND_URL` is unset, the plugin sets it to the URL it used, so app code can read
`import.meta.env.VITE_C15T_BACKEND_URL` instead of repeating the URL.

The plugin fetches the policy during `vite build`, or in `vite dev` when the
server first loads it, and serves it to server code as `snapshot` from `c15t/generated`. In the browser
bundle, `snapshot` is `undefined`, so the policy never ships to the browser.
`createConsentStateHandler()` reads the snapshot and the backend URL from
there, as the
[quickstart root route](/docs/frameworks/tanstack-start/quickstart#resolve-consent-in-the-root-route)
shows:

```ts title="src/routes/__root.tsx"
import { createServerFn } from '@tanstack/react-start';
import { createConsentStateHandler } from 'c15t/tanstack-start/server';

// Reads the backend URL and the policy consentManifest() downloaded.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);
```

`createConsentRoute()` reads them the same way.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

If the fetch fails, `vite build` stops. `vite dev` logs a warning instead,
and `snapshot` is `undefined`, so the server fetches and caches the policy at
runtime. To let a build continue the same way, set `onBuildError: 'runtime'`,
or run it with `C15T_ON_BUILD_ERROR=runtime`:

```ts title="vite.config.ts"
consentManifest({ onBuildError: 'runtime' }),
```

For policy updates without a rebuild, pass
`mode: manifest({ source: 'runtime' })` to `createConsentStateHandler` and
keep the plugin, which still supplies the backend URL. See
[runtime fetching](/docs/frameworks/tanstack-start/rendering#await-consent-in-the-loader).

# Vue
URL: https://c15t.com/docs/shared/build-manifests/vue
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

`consentManifest()` from `c15t/vue/vite` downloads the policy during
`vite build`, when the app uses `manifest()`, and in `vite dev` when the app
first loads it:

```ts title="vite.config.ts"
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [vue(), consentManifest()] });
```

Without a `backendURL` option, the plugin reads `VITE_C15T_BACKEND_URL`, then
`VITE_INTH_PROJECT_URL`, from the environment or `.env`. `manifest()` from `c15t/vue/vue-plugin`, with no
options, reads the downloaded policy and the same backend URL, so `src/main.ts`
needs no import from `c15t/generated`:

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

The browser resolves the visitor's policy from the bundled snapshot, with no
`/manifest` request. When the policy depends on the visitor's country or
region and neither `inputs` nor `geoURL` supplies one, the browser asks the
backend's `/init` instead. The app bundles the policy and English copy, and
loads the resolver as its own chunk when it needs it.

When the build has no snapshot, as in `vite dev` after a failed download,
`manifest()` fetches `${backendURL}/manifest` when the app starts.

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

For policy edits without a rebuild, use
[`manifest({ source: 'runtime' })`](/docs/frameworks/vue/rendering#fetch-the-manifest-at-runtime),
or [`hosted()`](/docs/frameworks/vue/rendering#ask-the-backend-for-each-visitors-policy)
when you need the backend's geolocation.

# Build Time Manifest
URL: https://c15t.com/docs/shared/build-time-manifest
The build fetches your public policy once and bundles it, so the server never fetches it at runtime.

The build fetches your public policy once and bundles it, so the server never
fetches it at runtime.

# Build Time Manifest Notes
URL: https://c15t.com/docs/shared/build-time-manifest-notes
The snapshot is fixed at build time:

The snapshot is fixed at build time:

* Rebuild after changing policies, translations or vendors. If your CI caches
  build output, force a fresh build.
* Consent choices still go to the backend.

The build reads the backend URL from your public backend URL variable when
the config doesn't pass one: `NEXT_PUBLIC_C15T_BACKEND_URL` in Next.js,
`NUXT_PUBLIC_C15T_BACKEND_URL` in Nuxt, `PUBLIC_C15T_BACKEND_URL` in Astro,
Svelte and SvelteKit, and `VITE_C15T_BACKEND_URL` in TanStack Start and other
Vite apps. Each also reads the matching Inth variable, such as
`NEXT_PUBLIC_INTH_PROJECT_URL`, when the c15t one is unset. See
[set the backend URL](/docs/concepts/modes#set-the-backend-url).

The fetch waits at most 10 seconds. When it fails, or no backend URL is set,
every framework does the same thing:

|Command|Default when the fetch fails|
|--|--|
|Production build: `next build`, `vite build`, `nuxt build`, `astro build`|The build stops with an error.|
|Dev: `next dev`, `vite dev`, `nuxt dev`, `astro dev`|A warning, and the server fetches the policy at runtime.|

Set `onBuildError` to use one behaviour for both. `'fail'` stops dev too.
`'runtime'` lets a production build finish, and the server fetches the policy
at runtime. The `C15T_ON_BUILD_ERROR` environment variable overrides the
option, so you can deploy during a backend outage without a code change:

```sh
C15T_ON_BUILD_ERROR=runtime npm run build
```

Turborepo's strict environment mode hides undeclared variables from tasks, so
list `C15T_ON_BUILD_ERROR` in the build task's `passThroughEnv` there.

The build skips the fetch, without an error, when it can't use a snapshot,
for example when the backend URL is relative. With `onBuildError: 'fail'`, a
relative URL stops the build. [Consent modes](/docs/concepts/modes#what-happens-when-the-download-fails)
lists every case.

# Inth Hosting
URL: https://c15t.com/docs/shared/comparisons/inth-hosting
You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

## Let Inth run your consent backend

You need a backend to store consent records outside the visitor's browser. [Inth](https://inth.com) builds c15t and hosts that backend and its database for c15t's framework integrations, browser package and headless API. Your consent interface and vendor controls stay in your application.

Connect your application to an Inth project with the [framework setup guide](/docs/frameworks). Inth also serves your consent policy, so static sites can use it without their own application server.

Offline mode keeps choices on the visitor's device and creates no remote consent records. Use it for development and tests, not production.

You can [self-host the c15t backend](/docs/self-host/overview) when your team needs to operate the service. Your team then owns the database, backups, updates and availability.

# Static Config
URL: https://c15t.com/docs/shared/examples/astro-static/static-config

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t, { hosted } from 'c15t/astro';

export default defineConfig({
	integrations: [svelte(), c15t({ mode: hosted() })],
});
```

# Analytics Events
URL: https://c15t.com/docs/shared/examples/astro/analytics-events

```ts title="src/analytics-events.ts"
import { createEventDispatcher } from '@c15t/integrations/events';
import { getConsentClient } from 'c15t/astro/client';

import consentClient from './c15t.client';

export const trackSearch = function trackSearch(resultCount: number) {
	const client = getConsentClient();
	if (!client) {
		return;
	}
	const events = createEventDispatcher({
		getSnapshot: client.getConsent,
		scripts: consentClient.scripts ?? [],
	});
	events.track('search', { resultCount });
};
```

# Cached Layout
URL: https://c15t.com/docs/shared/examples/astro/cached-layout

```astro title="src/layouts/cached.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';
import ConsentBannerDeferred from 'c15t/astro/components/consent-banner-deferred.astro';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBannerDeferred />
		<ConsentDialog />
	</body>
</html>
```

# Client Entrypoint
URL: https://c15t.com/docs/shared/examples/astro/client-entrypoint

```ts title="src/c15t.client.ts"
import { posthog } from '@c15t/integrations/posthog';
import type { C15tClientOptionsExtension } from 'c15t/astro';

export default {
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
} satisfies C15tClientOptionsExtension;
```

# Consent Video
URL: https://c15t.com/docs/shared/examples/astro/consent-video

```astro title="src/components/consent-video.astro"
---
import { ConsentDialogLink } from 'c15t/astro/components';
---

<consent-video>
	<div data-video>
		<p>Allow measurement to load this YouTube video.</p>
	</div>
	<ConsentDialogLink>Open privacy settings</ConsentDialogLink>
</consent-video>

<script>
	import { getConsentClient } from 'c15t/astro/client';

	class ConsentVideo extends HTMLElement {
		dispose?: () => void;

		connect = () => {
			const client = getConsentClient();
			const container = this.querySelector('[data-video]');
			if (this.dispose || !client || !container) {
				return;
			}
			const render = () => {
				// Measurement is allowed and the visitor has not switched YouTube
				// off. An undeclared vendor is never allowed, so declare youtube.
				if (!client.isVendorAllowed('youtube')) {
					container.textContent =
						'Allow measurement to load this YouTube video. No video request is sent before permission.';
					return;
				}
				if (container.querySelector('iframe')) {
					return;
				}
				const frame = document.createElement('iframe');
				frame.src = 'https://www.youtube-nocookie.com/embed/czTksCF6X8Y';
				frame.title = 'YouTube video';
				frame.allowFullscreen = true;
				container.replaceChildren(frame);
			};
			render();
			this.dispose = client.subscribe(render);
		};

		connectedCallback() {
			// c15t boots from a module script, which can run after this one.
			document.addEventListener('DOMContentLoaded', this.connect, {
				once: true,
			});
			this.connect();
		}

		disconnectedCallback() {
			document.removeEventListener('DOMContentLoaded', this.connect);
			this.dispose?.();
			this.dispose = undefined;
		}
	}

	if (!customElements.get('consent-video')) {
		customElements.define('consent-video', ConsentVideo);
	}
</script>
```

# Gated Inline Script
URL: https://c15t.com/docs/shared/examples/astro/gated-inline-script

```astro title="src/pages/index.astro (partial)"
<script data-c15t-category="measurement" is:inline type="text/plain">
	document.getElementById('inline-script-status').textContent =
		'Measurement script ran';
</script>
```

# Iab Layout
URL: https://c15t.com/docs/shared/examples/astro/iab-layout

```astro title="src/layouts/iab.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentDialogLink,
	ConsentScript,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink kind="iab">Privacy settings</ConsentDialogLink>
		</footer>
		<IABConsentBanner />
		<IABConsentDialog />
	</body>
</html>
```

# Layout
URL: https://c15t.com/docs/shared/examples/astro/layout

```astro title="src/layouts/base.astro"
---
import { ClientRouter } from 'astro:transitions';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentScript,
} from 'c15t/astro/components';

interface Props {
	title: string;
}

const { title } = Astro.props;
---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta content="width=device-width, initial-scale=1" name="viewport" />
		<title>{title}</title>
		<ConsentScript />
		<ClientRouter />
	</head>
	<body>
		<slot />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
		<ConsentBanner />
		<ConsentDialog />
	</body>
</html>
```

# Server Config
URL: https://c15t.com/docs/shared/examples/astro/server-config

```js title="astro.config.mjs"
import node from '@astrojs/node';
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t from 'c15t/astro';

export default defineConfig({
	adapter: node({ mode: 'standalone' }),
	integrations: [svelte(), c15t()],
	output: 'server',
});
```

# Vendors Option
URL: https://c15t.com/docs/shared/examples/astro/vendors-option

```ts title="astro.config.mjs (partial)"
vendors: [
	{
		category: 'measurement',
		description: 'Product analytics and session insights.',
		id: 'posthog',
		name: 'PostHog',
		privacyPolicyUrl: 'https://posthog.com/privacy',
	},
	{
		category: 'measurement',
		description: 'Embedded videos.',
		id: 'youtube',
		name: 'YouTube',
		privacyPolicyUrl: 'https://policies.google.com/privacy',
	},
	{
		category: 'marketing',
		description: 'Ad conversion tracking.',
		id: 'x-pixel',
		name: 'X Pixel',
		privacyPolicyUrl: 'https://x.com/en/privacy',
	},
],
```

# Embed
URL: https://c15t.com/docs/shared/examples/html/embed

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

# Gated Scripts
URL: https://c15t.com/docs/shared/examples/html/gated-scripts

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	src="/posthog.js"
></script>
<!-- X Pixel's base code, pasted inline -->
<script
	type="text/plain"
	data-c15t-category="marketing"
>
	!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);
	},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',
	a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');
	twq('config','YOUR_X_PIXEL_ID');
</script>
```

# Headless Bar
URL: https://c15t.com/docs/shared/examples/html/headless-bar

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.headless.js"
	defer
></script>

<style>
	.cookie-bar {
		position: fixed;
		inset: auto 0 0;
		z-index: 50;
		display: flex;
		flex-wrap: wrap;
		align-items: center;
		gap: 0.75rem 1.5rem;
		padding: 0.875rem 1.5rem;
		background: #14213d;
		color: #f8f9fb;
		font:
			0.9375rem/1.5 system-ui,
			sans-serif;
		box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
	}

	.cookie-bar__text {
		flex: 1 1 20rem;
		margin: 0;
	}

	.cookie-bar__actions {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem;
	}

	.cookie-bar button {
		padding: 0.5rem 1rem;
		border: 1px solid #f8f9fb;
		border-radius: 999px;
		background: transparent;
		color: inherit;
		font: inherit;
		cursor: pointer;
	}

	.cookie-bar .cookie-bar__button {
		background: #f8f9fb;
		color: #14213d;
		font-weight: 600;
	}

	.cookie-bar .cookie-bar__link {
		border-color: transparent;
		text-decoration: underline;
		text-underline-offset: 3px;
	}

	.cookie-bar button:focus-visible {
		outline: 2px solid #fca311;
		outline-offset: 2px;
	}
	/* On narrow screens, Reject and Accept share a row at equal width. */
	@media (max-width: 30rem) {
		.cookie-bar__actions {
			width: 100%;
		}

		.cookie-bar__actions button {
			flex: 1 1 40%;
		}

		.cookie-bar__actions .cookie-bar__link {
			flex-basis: 100%;
		}
	}

	/* The headless build has no dialog, so preferences open inside the bar. */
	.cookie-bar[hidden],
	.cookie-bar__prefs[hidden] {
		display: none;
	}

	.cookie-bar__prefs {
		display: flex;
		flex-wrap: wrap;
		gap: 0.5rem 1.25rem;
		flex-basis: 100%;
		margin: 0;
		padding: 0;
		border: 0;
	}

	.cookie-bar__prefs label {
		display: flex;
		align-items: center;
		gap: 0.375rem;
	}
</style>

<section
	id="cookie-bar"
	class="cookie-bar"
	aria-label="Cookie consent"
	hidden
>
	<p class="cookie-bar__text">
		We use cookies to measure traffic and improve this site. Choose which
		ones can run.
	</p>
	<fieldset
		class="cookie-bar__prefs"
		hidden
	>
		<legend class="cookie-bar__text">Allow these cookies:</legend>
		<label
			><input
				type="checkbox"
				name="functionality"
			/>
			Functionality</label
		>
		<label
			><input
				type="checkbox"
				name="measurement"
			/>
			Measurement</label
		>
		<label
			><input
				type="checkbox"
				name="experience"
			/>
			Experience</label
		>
		<label
			><input
				type="checkbox"
				name="marketing"
			/>
			Marketing</label
		>
	</fieldset>
	<div class="cookie-bar__actions">
		<!-- c15t wires data-c15t-action buttons itself; they need no code. -->
		<button
			type="button"
			class="cookie-bar__link"
			data-c15t-action="customize"
		>
			Preferences
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="dismiss"
			data-notice-only
			hidden
		>
			Got it
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="reject"
			data-choice-only
		>
			Reject all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-c15t-action="accept"
			data-choice-only
		>
			Accept all
		</button>
		<button
			type="button"
			class="cookie-bar__button"
			data-save
			hidden
		>
			Save
		</button>
	</div>
</section>

<script>
	const bar = document.getElementById('cookie-bar');
	const prefs = bar.querySelector('.cookie-bar__prefs');
	const saveButton = bar.querySelector('[data-save]');
	const switches = prefs.querySelectorAll('input');
	const choiceButtons = bar.querySelectorAll('[data-choice-only]');
	const noticeButtons = bar.querySelectorAll('[data-notice-only]');

	// The tag is deferred, so queue calls until window.c15t is the real API.
	window.c15t = window.c15t || [];
	const queue = (call) => {
		if (Array.isArray(window.c15t)) {
			window.c15t.push(call);
		} else {
			window.c15t[call[0]](...call.slice(1));
		}
	};

	// c15t says which surface is due; the page decides what it looks like.
	// 'banner' shows the bar, 'dialog' opens the switches, 'none' hides it.
	queue([
		'on',
		'ui',
		(surface) => {
			const { kind } = c15t.getSnapshot().promptRequirement;
			const editing = surface === 'dialog';
			// A notice gets one acknowledgement button instead of Accept and Reject.
			for (const button of choiceButtons) {
				button.hidden = kind === 'notice' && !editing;
			}
			for (const button of noticeButtons) {
				button.hidden = kind !== 'notice' || editing;
			}
			for (const input of switches) {
				input.checked = c15t.has(input.name);
			}
			prefs.hidden = !editing;
			saveButton.hidden = !editing;
			bar.hidden =
				surface === 'none' || (surface === 'banner' && kind === 'none');
		},
	]);

	// Save records exactly what the switches show.
	saveButton.addEventListener('click', () => {
		const choice = {};
		for (const input of switches) {
			choice[input.name] = input.checked;
		}
		c15t.save(choice);
	});
</script>
```

# Preferences Link
URL: https://c15t.com/docs/shared/examples/html/preferences-link

```html title="index.html"
<a href="#c15t-preferences">Privacy settings</a>
```

# Script Tag
URL: https://c15t.com/docs/shared/examples/html/script-tag

```html title="index.html"
<script
	src="https://your-project.inth.app/c15t.js"
	defer
></script>
```

# Tailwind Classes
URL: https://c15t.com/docs/shared/examples/html/tailwind-classes

```html title="index.html"
<link
	rel="stylesheet"
	href="/tailwind.css"
/>
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			ui: {
				// The banner renders in a shadow root, where the page's
				// stylesheets do not reach. Link your Tailwind build into it
				// too, and keep the page's own link: Tailwind 4 registers
				// variables with @property, which only works in the page.
				stylesheetURLs: ['/tailwind.css'],
				theme: {
					slots: {
						consentBannerCard: 'rounded-none border-4 border-sky-600',
						consentBannerTitle: 'uppercase tracking-wide',
					},
				},
			},
		},
	]);
</script>
```

# Theme
URL: https://c15t.com/docs/shared/examples/html/theme

```html title="index.html"
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			ui: {
				theme: {
					colors: {
						primary: '#6943a3',
						primaryHover: '#533285',
						textOnPrimary: '#ffffff',
					},
					radius: { lg: '18px' },
				},
			},
		},
	]);
</script>
```

# Vendor Gated Embed
URL: https://c15t.com/docs/shared/examples/html/vendor-gated-embed

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	data-vendor="youtube"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

# Vendor Gated Scripts
URL: https://c15t.com/docs/shared/examples/html/vendor-gated-scripts

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	data-c15t-vendor="posthog"
	src="/vendor/posthog.js"
></script>
<!-- X Pixel's base code, pasted inline -->
<script
	type="text/plain"
	data-c15t-category="marketing"
	data-c15t-vendor="x-pixel"
>
	!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);
	},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',
	a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');
	twq('config','YOUR_X_PIXEL_ID');
</script>
```

# Vendor Scripts
URL: https://c15t.com/docs/shared/examples/html/vendor-scripts

```html title="index.html"
<!-- PostHog's snippet, saved as a file on your site -->
<script
	type="text/plain"
	data-c15t-category="measurement"
	src="/posthog.js"
></script>
```

# Vendors
URL: https://c15t.com/docs/shared/examples/html/vendors

```html title="index.html"
<!-- Runs before the deferred c15t.js tag, so init() picks it up -->
<script>
	window.c15t = window.c15t || [];
	c15t.push([
		'config',
		{
			vendors: [
				{
					id: 'posthog',
					name: 'PostHog',
					category: 'measurement',
					description: 'Product analytics and session insights.',
					privacyPolicyUrl: 'https://posthog.com/privacy',
				},
				{
					id: 'youtube',
					name: 'YouTube',
					category: 'measurement',
					description: 'Embedded videos.',
					privacyPolicyUrl: 'https://policies.google.com/privacy',
				},
				{
					id: 'x-pixel',
					name: 'X Pixel',
					category: 'marketing',
					description: 'Ad conversion tracking.',
					privacyPolicyUrl: 'https://x.com/en/privacy',
				},
			],
		},
	]);
</script>
```

# Actions
URL: https://c15t.com/docs/shared/examples/javascript/actions

```ts title="src/consent-ui.ts"
const label: Record<PresentationAction, string> = {
	accept: 'Accept all',
	customize: 'Choose cookies',
	dismiss: 'OK',
	reject: 'Reject optional',
	save: 'Save preferences',
};

// Each button is a visitor action. Only these calls record a choice.
const perform = async function perform(action: PresentationAction) {
	if (action === 'customize') {
		kernel.set.activeUI('dialog');
		return;
	}
	if (action === 'dismiss') {
		await kernel.commands.dismissNotice();
		return;
	}
	let choice: Partial<ConsentState> | 'all' | 'none' =
		action === 'accept' ? 'all' : 'none';
	if (action === 'save') {
		choice = {};
		for (const input of fields.querySelectorAll<HTMLInputElement>('input')) {
			const category = latest.policyRule.scope.find(
				(name) => name === input.name
			);
			if (category) {
				choice[category] = input.checked;
			}
		}
	}
	kernel.set.activeUI('none');
	const result = await kernel.commands.save(choice);
	status.textContent = result.ok
		? 'Your preferences are saved.'
		: 'Saved in this browser. Backend delivery will retry.';
};

// The policy decides which actions each surface offers, and in what order.
const renderActions = function renderActions(
	container: HTMLElement,
	surface: 'prompt' | 'preferences',
	snapshot: ConsentSnapshot
) {
	const presentation = resolveConsentPresentation({
		policy: snapshot.policyRule,
		surface,
	});
	const buttons = presentation.orderedActions.map((action) => {
		const button = document.createElement('button');
		button.type = 'button';
		button.textContent = label[action];
		button.addEventListener('click', () => {
			void perform(action);
		});
		return button;
	});
	if (surface === 'prompt') {
		for (const right of presentation.rights) {
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent =
				right === 'opt-out'
					? 'Do not sell or share my data'
					: 'Privacy settings';
			button.addEventListener('click', () => kernel.set.activeUI('dialog'));
			buttons.push(button);
		}
	}
	container.replaceChildren(...buttons);
};
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/javascript/callbacks

```ts title="src/main.ts"
import { hosted, init } from '@c15t/browser';

import { scripts } from './scripts';

export const consent = init({
	callbacks: {
		// Only a visitor's own accept, reject or save.
		onChoiceRecorded: ({ confirmed, snapshot }) => {
			console.info('Visitor confirmed', confirmed, snapshot.explicitChoice);
		},
		onError: ({ error }) => {
			console.warn('Consent request failed:', error);
		},
		// Any change to what may run, including a restored choice.
		onPermissionsChanged: ({ previous, snapshot }) => {
			console.info('Permissions', previous, snapshot.effectivePermissions);
		},
	},
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});

// The surface c15t wants shown: 'banner', 'dialog' or 'none'.
consent.on('ui', (surface) => {
	document.documentElement.dataset.consentSurface = surface ?? 'none';
});
```

# Clear On Revocation
URL: https://c15t.com/docs/shared/examples/javascript/clear-on-revocation

```ts title="src/clear-on-revocation.ts"
import type { ConsentKernel } from 'c15t';
import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';

export const clearTrackingData = function clearTrackingData(
	kernel: ConsentKernel
) {
	return createClearOnRevocation({
		config: {
			marketing: { cookies: ['_fbp', '_gcl_au'] },
			measurement: { cookies: ['_ga', '_ga_*'], localStorage: ['analytics:*'] },
		},
		kernel,
	});
};
```

# Devtools
URL: https://c15t.com/docs/shared/examples/javascript/devtools

```ts title="src/main.ts"
if (import.meta.env.DEV) {
	const { mountDevTools } = await import('@c15t/browser/devtools');
	mountDevTools(consent, { defaultTab: 'scripts' });
}
```

# Embed
URL: https://c15t.com/docs/shared/examples/javascript/embed

```html title="index.html"
<iframe
	data-src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
	data-category="measurement"
	title="YouTube video"
	allow="encrypted-media; picture-in-picture"
	allowfullscreen
></iframe>
```

# Gpp
URL: https://c15t.com/docs/shared/examples/javascript/gpp

```ts title="src/main.ts"
import { hosted, init } from '@c15t/browser';
import { mountGPP } from '@c15t/browser/gpp';

const consent = init({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
});

// Installs `window.__gpp` and keeps it in step with the visitor's choices.
const gpp = mountGPP(consent);

window.__gpp?.('addEventListener', (event) => {
	const { eventName, data } = event as { eventName: string; data: unknown };
	if (eventName === 'signalStatus' && data === 'ready') {
		console.log('GPP string', gpp.getGPPString());
	}
});
```

# Iframe Blocker
URL: https://c15t.com/docs/shared/examples/javascript/iframe-blocker

```ts title="src/iframe-blocker.ts"
import type { ConsentKernel } from 'c15t';
import { createIframeBlocker } from 'c15t/modules/iframe-blocker';

// Watches the page for <iframe data-src data-category> and sets `src` while
// the category is allowed.
export const gateIframes = function gateIframes(kernel: ConsentKernel) {
	return createIframeBlocker({ kernel });
};
```

# Init
URL: https://c15t.com/docs/shared/examples/javascript/init

```ts title="src/main.ts"
import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

# Kernel
URL: https://c15t.com/docs/shared/examples/javascript/kernel

```ts title="src/consent.ts"
import { createConsentKernel, createHostedTransport } from 'c15t';
import { createPersistence } from 'c15t/modules/persistence';
import { createScriptLoader } from 'c15t/modules/script-loader';

import { scripts } from './scripts';

export const startConsentKernel = async function startConsentKernel(
	backendURL: string
) {
	const kernel = createConsentKernel({
		transport: createHostedTransport({ backendURL }),
	});
	// Each module is yours to create and dispose. This kernel has no iframe
	// blocker, network blocker, data clearing or reload after revocation.
	const persistence = createPersistence({ kernel });
	const loader = createScriptLoader({ kernel, scripts });
	await kernel.commands.init();
	return {
		dispose() {
			loader.dispose();
			persistence.dispose();
			kernel.dispose();
		},
		kernel,
	};
};
```

# Lifecycle
URL: https://c15t.com/docs/shared/examples/javascript/lifecycle

```ts title="src/consent-ui.ts"
const unsubscribe = kernel.subscribe(render);
const stopErrors = kernel.events.on('command:error', ({ command }) => {
	if (command === 'init') {
		status.textContent =
			'Consent could not load. Check the backend endpoint and allowed origin.';
	}
});
render(kernel.getSnapshot());
// Reads stored choices, resolves the policy and starts script loading.
runtime.start();

window.addEventListener('pagehide', (event) => {
	// Back and Forward restore a cached page with the same runtime.
	if (event.persisted) {
		return;
	}
	unsubscribe();
	stopErrors();
	runtime.dispose();
});
```

# Network Blocker
URL: https://c15t.com/docs/shared/examples/javascript/network-blocker

```ts title="src/network-blocker.ts"
import type { ConsentKernel } from 'c15t';
import { createNetworkBlocker } from 'c15t/modules/network-blocker';

export const blockTracking = function blockTracking(kernel: ConsentKernel) {
	return createNetworkBlocker({
		kernel,
		onRequestBlocked: ({ method, url, rule }) => {
			console.info('Held back', method, url, rule?.id);
		},
		rules: [
			{
				category: 'measurement',
				domain: 'collect.example.com',
				id: 'collector',
			},
			{
				category: 'measurement',
				domain: 'example.com',
				id: 'events',
				methods: ['POST'],
				pathIncludes: '/api/track',
			},
		],
	});
};
```

# Preference Draft
URL: https://c15t.com/docs/shared/examples/javascript/preference-draft

```ts title="src/preference-form.ts"
import type { AllConsentNames } from 'c15t';
import { createPreferenceDraft } from 'c15t/preference-draft';
import type { ConsentRuntime } from 'c15t/runtime';

// Render a form of category switches that records nothing until Save.
export const mountPreferenceForm = function mountPreferenceForm(
	runtime: ConsentRuntime,
	form: HTMLFormElement
): () => void {
	const draft = createPreferenceDraft(runtime.kernel);

	const render = () => {
		const { displayedCategories, isStale, values } = draft.getState();
		form.replaceChildren(
			...displayedCategories.map((category: AllConsentNames) => {
				const label = document.createElement('label');
				const input = document.createElement('input');
				input.type = 'checkbox';
				input.checked = values[category];
				input.disabled = category === 'necessary';
				input.addEventListener('change', () => {
					draft.set(category, input.checked);
				});
				label.append(input, ` ${category}`);
				return label;
			})
		);
		if (isStale) {
			// The policy changed under an unsaved edit: Save records nothing
			// until the visitor reviews the current choices.
			const review = document.createElement('button');
			review.type = 'button';
			review.textContent = 'Review choices';
			review.addEventListener('click', draft.reset);
			form.append(review);
		}
		const save = document.createElement('button');
		save.textContent = 'Save';
		form.append(save);
	};

	form.addEventListener('submit', (event) => {
		event.preventDefault();
		void draft.save();
	});
	render();
	// The draft follows the record and the policy while subscribed.
	return draft.subscribe(render);
};
```

# Preferences Link
URL: https://c15t.com/docs/shared/examples/javascript/preferences-link

```html title="index.html"
<a href="#c15t-preferences">Privacy settings</a>
```

# Runtime
URL: https://c15t.com/docs/shared/examples/javascript/runtime

```ts title="src/consent-runtime.ts"
import { hosted } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

import { scripts } from './scripts';

// One runtime for the page: policy, stored choices, script loading,
// iframe blocking and the reload after a revocation.
export const runtime = createConsentRuntime({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
});
```

# Runtime Devtools
URL: https://c15t.com/docs/shared/examples/javascript/runtime-devtools

```ts title="src/consent-ui.ts"
if (import.meta.env.DEV) {
	const { createDevTools } = await import('@c15t/dev-tools');
	const tools = createDevTools({ kernel });
	import.meta.hot?.dispose(() => tools.destroy());
}
```

# Sentry Scripts
URL: https://c15t.com/docs/shared/examples/javascript/sentry-scripts

```ts title="src/consent-scripts.ts"
import { sentry } from '@c15t/integrations/sentry';

export const scripts = [
	sentry({
		dsn: 'https://your-key@o0.ingest.sentry.io/0',
		initOptions: {
			release: 'my-app@1.0.0',
			replaysOnErrorSampleRate: 1,
			replaysSessionSampleRate: 0.1,
			tracesSampleRate: 0.1,
		},
	}),
];
```

# Theme
URL: https://c15t.com/docs/shared/examples/javascript/theme

```ts title="src/main.ts"
const consent = init({
	mode: hosted({ backendURL: 'https://your-project.inth.app' }),
	scripts,
	ui: {
		theme: {
			colors: {
				primary: '#6943a3',
				primaryHover: '#533285',
				textOnPrimary: '#ffffff',
			},
			radius: { lg: '18px' },
		},
	},
});
```

# Translations
URL: https://c15t.com/docs/shared/examples/javascript/translations

```ts title="src/main.ts"
import { init, offline } from '@c15t/browser';
import { policyRulePresets } from 'c15t';

import { scripts } from './scripts';

// Offline mode shows the copy in `i18n`. With a backend, the backend's copy
// for the visitor's language replaces these messages.
export const consent = init({
	i18n: {
		locale: 'de',
		messages: {
			de: {
				common: {
					acceptAll: 'Alle akzeptieren',
					acknowledge: 'OK',
					customize: 'Anpassen',
					rejectAll: 'Alle ablehnen',
					save: 'Einstellungen speichern',
				},
				cookieBanner: {
					description:
						'Wir verwenden Cookies, um die Nutzung dieser Website zu messen.',
					title: 'Wir respektieren Ihre Privatsphäre',
				},
			},
		},
	},
	mode: offline({ policyRules: [policyRulePresets.europeOptIn()] }),
	scripts,
});
```

# Transport Custom
URL: https://c15t.com/docs/shared/examples/javascript/transport-custom

```ts title="src/consent-runtime.ts"
import { createOfflineTransport, custom, policyRulePresets } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

// Resolve the policy in the browser and record choices with your own API.
const local = createOfflineTransport({
	policyRules: [policyRulePresets.europeOptIn()],
});

export const runtime = createConsentRuntime({
	mode: custom({
		init: local.init,
		async save(payload) {
			const response = await fetch('/api/consent', {
				body: JSON.stringify({
					choice: payload.choice,
					consents: payload.consents,
					subjectId: payload.subjectId,
				}),
				headers: { 'content-type': 'application/json' },
				method: 'POST',
			});
			return { ok: response.ok, subjectId: payload.subjectId };
		},
	}),
});
```

# Transport Manifest
URL: https://c15t.com/docs/shared/examples/javascript/transport-manifest

```ts title="src/consent-runtime.ts"
import { manifest } from '@c15t/browser';
import { createConsentRuntime } from 'c15t/runtime';

// Fetch the backend's public manifest and resolve the policy in the browser.
// Saves still go to the backend.
export const runtime = createConsentRuntime({
	mode: manifest({ manifestURL: 'https://your-project.inth.app/manifest' }),
});
```

# Transport Offline
URL: https://c15t.com/docs/shared/examples/javascript/transport-offline

```ts title="src/consent-runtime.ts"
import { offline } from '@c15t/browser';
import { policyRulePresets } from 'c15t';
import { createConsentRuntime } from 'c15t/runtime';

// No backend: rules resolve in the browser and choices stay there. The
// browser does not know the visitor's country, so the page supplies it.
export const runtime = createConsentRuntime({
	mode: offline({
		policyRules: [
			policyRulePresets.europeOptIn(),
			policyRulePresets.worldNone(),
		],
	}),
	overrides: { country: document.documentElement.dataset.country },
});
```

# Vendor Consent
URL: https://c15t.com/docs/shared/examples/javascript/vendor-consent

```ts title="src/vendor-consent.ts"
import { isVendorAllowed } from 'c15t';
import type { SaveResult, Vendor } from 'c15t';
import type { ConsentRuntime } from 'c15t/runtime';

export const vendors: Vendor[] = [
	{
		category: 'marketing',
		id: 'x-pixel',
		name: 'X Pixel',
		privacyPolicyUrl: 'https://x.com/privacy',
	},
];

// Whether the vendor may run now: it is declared, its category is allowed
// and the visitor has not switched it off. An undeclared id returns false.
export const canVendorRun = function canVendorRun(
	runtime: ConsentRuntime,
	vendorId: string
): boolean {
	return isVendorAllowed(runtime.kernel.getSnapshot(), vendorId);
};

// Record one vendor switch. The empty category input confirms no category;
// `save()` with no input would also confirm every displayed category.
export const saveVendorSwitch = function saveVendorSwitch(
	runtime: ConsentRuntime,
	vendorId: string,
	granted: boolean
): Promise<SaveResult> {
	return runtime.kernel.commands.save({}, { vendors: { [vendorId]: granted } });
};
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/javascript/vite-config

```ts title="vite.config.ts"
import { consentManifest } from 'c15t/build';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [consentManifest()] });
```

# Pages App
URL: https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-app

```tsx title="pages/_app.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ConsentPageProps } from 'c15t/next/pages';
import type { AppProps } from 'next/app';

import '@/styles/globals.css';

const App = ({ Component, pageProps }: AppProps<ConsentPageProps>) => (
	// Pages without getServerSideProps resolve consent in the browser.
	<ConsentRoot state={pageProps.consent}>
		<Component {...pageProps} />
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentRoot>
);

export default App;
```

# Pages Config
URL: https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-config

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	routePrefix: '/api/c15t',
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

# Pages Consent Route
URL: https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-consent-route

```ts title="pages/api/c15t/[...c15t].ts"
import { createPagesConsentRoute } from 'c15t/next/pages';

export default createPagesConsentRoute();
```

# Pages Ssr
URL: https://c15t.com/docs/shared/examples/nextjs-pages-router/pages-ssr

```tsx title="pages/index.tsx (partial)"
import { withConsentProps } from 'c15t/next/pages';

export const getServerSideProps = withConsentProps();
```

# App Router Awaited Layout
URL: https://c15t.com/docs/shared/examples/nextjs/app-router-awaited-layout

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import { Suspense } from 'react';
import type { ReactNode } from 'react';

import './globals.css';

const ResolvedConsent = async ({ children }: { children: ReactNode }) => {
	const state = await resolveConsent();

	return (
		<ConsentRoot state={state}>
			{children}
			<ConsentBanner />
			<ConsentDialog />
			<footer>
				<ConsentDialogLink>Privacy settings</ConsentDialogLink>
			</footer>
		</ConsentRoot>
	);
};

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<Suspense fallback={null}>
				<ResolvedConsent>{children}</ResolvedConsent>
			</Suspense>
		</body>
	</html>
);

export default RootLayout;
```

# Branded Layout
URL: https://c15t.com/docs/shared/examples/nextjs/branded-layout

```tsx title="app/branded/layout.tsx"
import { ConsentTheme } from 'c15t/next';
import type { ReactNode } from 'react';

import { brandTheme } from '@/lib/theme';

const BrandedLayout = ({ children }: { children: ReactNode }) => (
	<>
		<ConsentTheme theme={brandTheme} />
		{children}
	</>
);

export default BrandedLayout;
```

# Browser Layout
URL: https://c15t.com/docs/shared/examples/nextjs/browser-layout

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import type { ReactNode } from 'react';

import './globals.css';

// No resolveConsent: the browser resolves consent, so pages can be static.
const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<ConsentRoot>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/nextjs/callbacks

```ts title="lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/next';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

# Client Side Config
URL: https://c15t.com/docs/shared/examples/nextjs/client-side-config

```ts title="c15t.config.ts"
import { defineConsentConfig, hosted } from 'c15t/next';

// The browser asks the backend's /init. The backend URL comes from
// NEXT_PUBLIC_C15T_BACKEND_URL.
export default defineConsentConfig({ mode: hosted() });
```

# Compose Banner
URL: https://c15t.com/docs/shared/examples/nextjs/compose-banner

```tsx title="components/cookie-banner.tsx"
'use client';

import { ConsentBanner, useTranslations } from 'c15t/next';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

# Compose Button
URL: https://c15t.com/docs/shared/examples/nextjs/compose-button

```tsx title="components/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

# Config
URL: https://c15t.com/docs/shared/examples/nextjs/config

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';

// The backend URL comes from NEXT_PUBLIC_C15T_BACKEND_URL.
export default defineConsentConfig({ routePrefix: '/api/c15t' });
```

# Consent Route
URL: https://c15t.com/docs/shared/examples/nextjs/consent-route

```ts title="app/api/c15t/[...c15t]/route.ts"
import { createConsentRoute } from 'c15t/next/api';

export const { GET } = createConsentRoute();
```

# Experiment Layout
URL: https://c15t.com/docs/shared/examples/nextjs/experiment-layout

```tsx title="app/layout.tsx"
import { resolveConsent } from 'c15t/next/server';
import { Suspense } from 'react';
import type { ReactNode } from 'react';

import { ExperimentConsent } from '@/components/experiment-consent';
import { bannerExperiment } from '@/lib/experiment';
import { bannerExperimentFlag } from '@/lib/flags';

import '@/styles/globals.css';

const ResolvedConsent = async ({ children }: { children: ReactNode }) => {
	const arm = await bannerExperimentFlag();
	const state = await resolveConsent({
		// `off` keeps this visitor out of the experiment.
		experiment: arm === 'off' ? undefined : { ...bannerExperiment, arm },
	});

	return <ExperimentConsent state={state}>{children}</ExperimentConsent>;
};

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			<Suspense fallback={null}>
				<ResolvedConsent>{children}</ResolvedConsent>
			</Suspense>
		</body>
	</html>
);

export default RootLayout;
```

# I18n
URL: https://c15t.com/docs/shared/examples/nextjs/i18n

```ts title="lib/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/next';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

# Iab Consent
URL: https://c15t.com/docs/shared/examples/nextjs/iab-consent

```tsx title="components/iab-consent.tsx"
'use client';

import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

# Iab Publisher Restrictions
URL: https://c15t.com/docs/shared/examples/nextjs/iab-publisher-restrictions

```tsx title="components/iab-consent.tsx"
'use client';

import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

const publisherRestrictions = [
	// Vendors 10 and 755 may not use purpose 4.
	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
	// Vendor 755 must use legitimate interest for purpose 7.
	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
];

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

# Language Switcher
URL: https://c15t.com/docs/shared/examples/nextjs/language-switcher

```tsx title="components/language-switcher.tsx"
'use client';

import { useInit, useSetLanguage, useSnapshot } from 'c15t/next';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

# Next Config
URL: https://c15t.com/docs/shared/examples/nextjs/next-config

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

// Reads NEXT_PUBLIC_C15T_BACKEND_URL, like defineConsentConfig.
export default withConsentManifest(nextConfig);
```

# Quickstart Config
URL: https://c15t.com/docs/shared/examples/nextjs/quickstart-config

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

# Quickstart Layout
URL: https://c15t.com/docs/shared/examples/nextjs/quickstart-layout

```tsx title="app/layout.tsx"
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/next';
import { resolveConsent } from 'c15t/next/server';
import type { ReactNode } from 'react';

import './globals.css';

const RootLayout = ({ children }: { children: ReactNode }) => (
	<html lang="en">
		<body>
			{/* Not awaited: the page renders while consent resolves. */}
			<ConsentRoot state={resolveConsent()}>
				{children}
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
		</body>
	</html>
);

export default RootLayout;
```

# Quickstart Next Config
URL: https://c15t.com/docs/shared/examples/nextjs/quickstart-next-config

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = {} satisfies NextConfig;

export default withConsentManifest(nextConfig);
```

# Static Export Next Config
URL: https://c15t.com/docs/shared/examples/nextjs/static-export-next-config

```ts title="next.config.ts"
import { withConsentManifest } from 'c15t/next/build';
import type { NextConfig } from 'next';

const nextConfig = { output: 'export' } satisfies NextConfig;

// Finds c15t.config.ts. A static export skips the manifest download.
export default withConsentManifest(nextConfig);
```

# Theme
URL: https://c15t.com/docs/shared/examples/nextjs/theme

```ts title="lib/theme.ts"
import { defineTheme } from 'c15t/next';

export const brandTheme = defineTheme({
	colors: { primary: '#315c47', primaryHover: '#24473a' },
	radius: { lg: '16px' },
});
```

# Third Parties Scripts
URL: https://c15t.com/docs/shared/examples/nextjs/third-parties-scripts

```ts title="lib/scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import type { Script } from 'c15t';

export const scripts: Script[] = [
	// Replaces <GoogleAnalytics gaId="G-XXXXXXXXXX" />
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
	// Replaces <GoogleTagManager gtmId="GTM-XXXXXXX" />
	googleTagManager({ id: 'GTM-XXXXXXX' }),
];
```

# Video Embed
URL: https://c15t.com/docs/shared/examples/nextjs/video-embed

```tsx title="components/video-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';

export const VideoEmbed = () => (
	<ConsentGate category="measurement">
		<iframe
			className="video-frame"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
			allowFullScreen
		/>
	</ConsentGate>
);
```

# Static Config
URL: https://c15t.com/docs/shared/examples/nuxt-static/static-config

```ts title="nuxt.config.ts"
import { manifest } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: {
		// A static host has no server: the browser resolves the policy the
		// build bundled, and the module adds no consent route.
		mode: manifest({ resolve: 'browser' }),
		routePrefix: false,
	},
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
	ssr: false,
});
```

# App Config
URL: https://c15t.com/docs/shared/examples/nuxt/app-config

```ts title="app/app.config.ts"
import { posthog } from '@c15t/integrations/posthog';

export default defineAppConfig({
	c15t: {
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	},
});
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/nuxt/callbacks

```ts title="app/consent-callbacks.ts"
import type { C15tNuxtConfig } from 'c15t/vue';

export const callbacks = {
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ snapshot }) => {
		console.info('Choice recorded', snapshot.explicitChoice);
	},
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies NonNullable<C15tNuxtConfig['callbacks']>;
```

# Color Scheme
URL: https://c15t.com/docs/shared/examples/nuxt/color-scheme

```ts title="nuxt.config.ts (c15t options)"
// Follow the visitor's system setting, with a dark primary of our own.
colorScheme: 'system',
theme: { dark: { primary: '#7fd1a8' } },
```

# Consent Status
URL: https://c15t.com/docs/shared/examples/nuxt/consent-status

```vue title="app/components/ConsentStatus.vue"
<script setup lang="ts">
// May measurement code run right now?
const permissions = useConsent();
// What did the visitor decide? `null` until they accept, reject or save.
const choice = useExplicitChoice();
const activeUI = useConsentActiveUI();
</script>

<template>
	<section aria-label="Your privacy choices">
		<p v-if="choice">You saved your privacy choices.</p>
		<p v-else>You have not made a privacy choice yet.</p>
		<p>
			Measurement is
			{{ permissions.measurement ? 'allowed' : 'not allowed' }} right now.
		</p>
		<button type="button" @click="activeUI = 'manager'">
			Change your choices
		</button>
	</section>
</template>
```

# Consent Surfaces
URL: https://c15t.com/docs/shared/examples/nuxt/consent-surfaces

```vue title="app/components/ConsentSurfaces.vue"
<script setup lang="ts">
// The module registers ConsentDialogTrigger globally. It does not register
// the banner or the dialog, so import them.
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
import ConsentManager from 'c15t/vue/runtime/components/consent-manager.vue';
</script>

<template>
	<!-- Render these in app.vue in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

# Devtools
URL: https://c15t.com/docs/shared/examples/nuxt/devtools

```vue title="app/components/ConsentDebugTools.vue"
<script setup lang="ts">
import { defineAsyncComponent } from 'vue';

// Development builds only: the dynamic import keeps DevTools out of
// production bundles.
const ConsentDevTools = import.meta.dev
	? defineAsyncComponent(() => import('c15t/vue/devtools'))
	: null;
</script>

<template>
	<ConsentDevTools v-if="ConsentDevTools" position="bottom-right" />
</template>
```

# Embed
URL: https://c15t.com/docs/shared/examples/nuxt/embed

```vue title="app/components/VideoEmbed.vue"
<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

# Headless Prompt
URL: https://c15t.com/docs/shared/examples/nuxt/headless-prompt

```vue title="app/components/ConsentPrompt.vue"
<script setup lang="ts">
const activeUI = useConsentActiveUI();
const saveConsent = useConsentSave();
const { displayedCategories, save: saveDraft, values } = useConsentDraft();

// Recording a choice satisfies the prompt, so c15t closes the banner itself.
const choose = (choice: 'all' | 'none') => {
	void saveConsent(choice);
};

// Preferences stay open until you close them. c15t records the draft
// locally before the network request, so closing right away is safe.
const savePreferences = () => {
	void saveDraft();
	activeUI.value = null;
};
</script>

<template>
	<section
		v-if="activeUI === 'banner'"
		class="consent-prompt"
		aria-label="Cookie consent"
	>
		<p>We use cookies for measurement and marketing.</p>
		<button type="button" @click="choose('none')">Reject all</button>
		<button type="button" @click="choose('all')">Accept all</button>
		<button type="button" @click="activeUI = 'manager'">Customize</button>
	</section>
	<section
		v-else-if="activeUI === 'manager'"
		class="consent-prompt"
		aria-label="Privacy settings"
	>
		<label v-for="category in displayedCategories" :key="category">
			<input
				v-model="values[category]"
				type="checkbox"
				:disabled="category === 'necessary'"
			/>
			{{ category }}
		</label>
		<button type="button" @click="savePreferences">Save</button>
	</section>
</template>
```

# Iab Opt In
URL: https://c15t.com/docs/shared/examples/nuxt/iab-opt-in

```ts title="nuxt.config.ts (c15t options)"
// Turns IAB TCF on. The CMP ID and vendor list come from `/init`.
iab: {},
```

# Iab Surfaces
URL: https://c15t.com/docs/shared/examples/nuxt/iab-surfaces

```vue title="app/components/IabSurfaces.vue"
<script setup lang="ts">
import IABConsentBanner from 'c15t/vue/runtime/components/iab-consent-banner.vue';
import IABConsentDialog from 'c15t/vue/runtime/components/iab-consent-dialog.vue';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

# Language Switcher
URL: https://c15t.com/docs/shared/examples/nuxt/language-switcher

```vue title="app/components/LanguageSwitcher.vue"
<script setup lang="ts">
const language = useConsentLanguage();
const kernel = useConsentKernel();

// Resolving again with `init()` loads the banner and dialog text in the
// new language.
const switchTo = (code: string) => {
	language.value = code;
	void kernel.commands.init();
};
</script>

<template>
	<button type="button" @click="switchTo('en')">English</button>
	<button type="button" @click="switchTo('de')">Deutsch</button>
</template>
```

# Nuxt Config
URL: https://c15t.com/docs/shared/examples/nuxt/nuxt-config

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	compatibilityDate: '2026-07-04',
	modules: ['c15t/vue'],
});
```

# Nuxt Gtag Scripts
URL: https://c15t.com/docs/shared/examples/nuxt/nuxt-gtag-scripts

```ts title="app/consent-scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';

export const scripts = [
	// Was gtag: { id: 'G-XXXXXXXXXX' } in nuxt.config.ts. Move a `gtag.config`
	// object to the `config` option unchanged.
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
];
```

# Nuxt Scripts Events
URL: https://c15t.com/docs/shared/examples/nuxt/nuxt-scripts-events

```vue title="app/components/PurchaseButton.vue"
<script setup lang="ts">
import { metaPixelEvent } from '@c15t/integrations/meta-pixel';

const props = defineProps<{ value: number }>();
const consent = useConsent();

const onPurchase = () => {
	// Was proxy.gtag('event', 'purchase', ...) from useScriptGoogleAnalytics()
	window.gtag?.('event', 'purchase', { currency: 'USD', value: props.value });

	// Was proxy.fbq('track', 'Purchase', ...) from useScriptMetaPixel().
	// fbq stays defined after a revocation until the page reloads, so check
	// the permission, not the global.
	if (consent.value.marketing) {
		metaPixelEvent('Purchase', { currency: 'USD', value: props.value });
	}
};
</script>

<template>
	<button type="button" @click="onPurchase">Buy now</button>
</template>
```

# Nuxt Scripts Registry
URL: https://c15t.com/docs/shared/examples/nuxt/nuxt-scripts-registry

```ts title="app/consent-scripts.ts"
import { gtag } from '@c15t/integrations/google-tag';
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { metaPixel } from '@c15t/integrations/meta-pixel';

export const scripts = [
	// Was useScriptGoogleAnalytics({ id: 'G-XXXXXXXXXX' })
	gtag({ category: 'measurement', id: 'G-XXXXXXXXXX' }),
	// Was useScriptGoogleTagManager({ id: 'GTM-XXXXXXX' })
	googleTagManager({ id: 'GTM-XXXXXXX' }),
	// Was useScriptMetaPixel({ id: '123456789012345' })
	metaPixel({ pixelId: '123456789012345' }),
];
```

# Privacy Page
URL: https://c15t.com/docs/shared/examples/nuxt/privacy-page

```vue title="app/pages/privacy.vue"
<template>
	<main>
		<h1>Privacy settings</h1>
		<p>Choose which optional cookies this site may use.</p>
		<ConsentWidget />
	</main>
</template>
```

# Root
URL: https://c15t.com/docs/shared/examples/nuxt/root

```vue title="app/app.vue"
<template>
	<ConsentRoot />
	<NuxtPage />
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

# Self Host Route
URL: https://c15t.com/docs/shared/examples/nuxt/self-host-route

```ts title="server/api/self-host/[...all].ts"
export default defineEventHandler(async (event) => {
	const instance = await getInstance();
	return instance.handler(toWebRequest(event));
});
```

# Vapor Embed
URL: https://c15t.com/docs/shared/examples/nuxt/vapor-embed

```vue title="app/components/VideoEmbed.vue"
<!-- A Vapor component passing both slots to ConsentGate. -->
<script setup vapor lang="ts"></script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

# Vapor Nuxt Config
URL: https://c15t.com/docs/shared/examples/nuxt/vapor-nuxt-config

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
	c15t: { backendURL: 'https://your-project.inth.app' },
	modules: ['c15t/vue'],
	// Vapor needs Vue 3.6. Opt components in with `<script setup vapor>`.
	vue: { vapor: true },
});
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/react/callbacks

```ts title="src/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/react';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

# Consent
URL: https://c15t.com/docs/shared/examples/react/consent

```tsx title="src/consent.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	manifest,
} from 'c15t/react';
import type { ReactNode } from 'react';

const options = {
	// The policy the build downloaded from VITE_C15T_BACKEND_URL.
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
};

export const Consent = ({ children }: { children: ReactNode }) => (
	<ConsentProvider options={options}>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

# Experiment Consent
URL: https://c15t.com/docs/shared/examples/react/experiment-consent

```tsx title="src/consent.tsx"
import { defineExperiment } from 'c15t';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentProvider,
	hosted,
} from 'c15t/react';
import type { ConsentProviderCallbacks } from 'c15t/react';
import type { ReactNode } from 'react';

import { scripts } from './scripts';

const mode = hosted({ backendURL: 'https://your-project.inth.app' });

// `control` is the stock banner. `wall` blocks the page until the visitor
// chooses.
const bannerExperiment = defineExperiment({
	arms: { wall: { prompt: { variant: 'wall' } } },
	id: 'banner-shape',
});

const pushToDataLayer = (event: Record<string, unknown>) => {
	const page = window as Window & { dataLayer?: unknown[] };
	page.dataLayer ??= [];
	page.dataLayer.push(event);
};

// Forward each impression and choice made under an arm to your analytics.
const callbacks = {
	onChoiceRecorded: ({ consentAction, experiment }) => {
		if (experiment) {
			pushToDataLayer({
				arm: experiment.arm,
				consent_action: consentAction,
				event: 'c15t_choice_recorded',
				experiment_id: experiment.id,
			});
		}
	},
	onSurfaceShown: ({ experiment, surface }) => {
		if (experiment) {
			pushToDataLayer({
				arm: experiment.arm,
				event: 'c15t_surface_shown',
				experiment_id: experiment.id,
				surface,
			});
		}
	},
} satisfies ConsentProviderCallbacks;

export const Consent = ({
	arm,
	children,
}: {
	/**
	 * The arm your flag provider resolved. Omit it to let c15t pick, or pass
	 * `off` to leave this visitor out of the experiment.
	 */
	arm?: 'control' | 'wall' | 'off';
	children: ReactNode;
}) => (
	<ConsentProvider
		options={{
			callbacks,
			experiment: arm === 'off' ? undefined : { ...bannerExperiment, arm },
			mode,
			scripts,
		}}
	>
		{children}
		<ConsentBanner />
		<ConsentDialog />
		<footer>
			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
		</footer>
	</ConsentProvider>
);
```

# Headless Banner
URL: https://c15t.com/docs/shared/examples/react/headless-banner

```tsx title="src/consent-banner.tsx"
import { useHeadlessConsentUI, useTranslations } from 'c15t/react/headless';

const ACTION_LABELS = {
	accept: 'acceptAll',
	customize: 'customize',
	dismiss: 'acknowledge',
	reject: 'rejectAll',
	save: 'save',
} as const;

export const Banner = () => {
	const { banner, performAction, openDialog } = useHeadlessConsentUI();
	const { common, rights } = useTranslations();

	if (!banner.isVisible) {
		return null;
	}

	return (
		<section aria-label="Privacy">
			{banner.preferenceControls.map((right) => (
				<button key={right} type="button" onClick={openDialog}>
					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
				</button>
			))}
			{banner.actionGroups.map((group) => (
				<div key={group.join('-')}>
					{group.map((action) => (
						<button
							key={action}
							type="button"
							data-primary={banner.primaryActions.includes(action) || undefined}
							onClick={() => performAction(action)}
						>
							{common[ACTION_LABELS[action]]}
						</button>
					))}
				</div>
			))}
		</section>
	);
};
```

# I18n
URL: https://c15t.com/docs/shared/examples/react/i18n

```ts title="src/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/react';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

# Iab Consent
URL: https://c15t.com/docs/shared/examples/react/iab-consent

```tsx title="src/iab-consent.tsx"
import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

# Iab Publisher Restrictions
URL: https://c15t.com/docs/shared/examples/react/iab-publisher-restrictions

```tsx title="src/iab-consent.tsx"
import {
	IABProvider,
	IABConsentBanner,
	IABConsentDialog,
} from 'c15t/react/iab';

const publisherRestrictions = [
	// Vendors 10 and 755 may not use purpose 4.
	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
	// Vendor 755 must use legitimate interest for purpose 7.
	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
];

export const IABConsent = ({ cmpId }: { cmpId: number }) => (
	<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
		<IABConsentBanner />
		<IABConsentDialog />
	</IABProvider>
);
```

# Language Switcher
URL: https://c15t.com/docs/shared/examples/react/language-switcher

```tsx title="src/language-switcher.tsx"
import { useInit, useSetLanguage, useSnapshot } from 'c15t/react';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

# Main
URL: https://c15t.com/docs/shared/examples/react/main

```tsx title="src/main.tsx"
import { createRoot } from 'react-dom/client';

import { App } from './app';
import { Consent } from './consent';

const root = document.getElementById('root');
if (!root) {
	throw new Error('Missing #root element');
}
createRoot(root).render(
	<Consent>
		<App />
	</Consent>
);
```

# Optional Feature
URL: https://c15t.com/docs/shared/examples/react/optional-feature

```tsx title="src/optional-feature.tsx"
import { useConsent } from 'c15t/react';

export const OptionalFeature = () => {
	const allowed = useConsent('marketing');
	return allowed ? <div>Optional marketing content</div> : null;
};
```

# Reject Button
URL: https://c15t.com/docs/shared/examples/react/reject-button

```tsx title="src/reject-button.tsx"
import { useSaveConsents } from 'c15t/react';

export const RejectButton = () => {
	const save = useSaveConsents();
	return (
		<button
			type="button"
			onClick={() => {
				void save('none');
			}}
		>
			Reject optional
		</button>
	);
};
```

# Video Embed
URL: https://c15t.com/docs/shared/examples/react/video-embed

```tsx title="src/video-embed.tsx"
import { ConsentDialogLink, ConsentGate } from 'c15t/react';

export const VideoEmbed = () => (
	<ConsentGate
		category="measurement"
		placeholder={
			<div className="placeholder">
				<p>Allow measurement to load this YouTube video.</p>
				<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
			</div>
		}
	>
		<iframe
			title="YouTube video"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
			allow="encrypted-media; picture-in-picture"
			allowFullScreen
		/>
	</ConsentGate>
);
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/react/vite-config

```ts title="vite.config.ts"
import react from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/build';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [react(), consentManifest()] });
```

# Nextjs Route
URL: https://c15t.com/docs/shared/examples/self-host/nextjs-route

```ts title="app/api/c15t/[[...path]]/route.ts"
import { c15tInstance } from '@c15t/backend';

import config from '../../../../c15t-backend.config';

export const runtime = 'nodejs';
const backend = c15tInstance({ ...config, basePath: '/api/c15t' });

export const GET = (request: Request) => backend.handler(request);
export const POST = GET;
export const PUT = GET;
export const PATCH = GET;
export const OPTIONS = GET;
```

# Bottom Bar
URL: https://c15t.com/docs/shared/examples/storybook-astro/bottom-bar

```ts title="astro.config.mjs (partial)"
presentation: {
	prompt: { position: 'bottom', variant: 'bar' },
},
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/storybook-astro/callbacks

```ts title="src/consent-callbacks.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';

export const callbacks: C15tClientOptionsExtension['callbacks'] = {
	// Runs when the visitor selects accept, reject or save.
	onChoiceRecorded: ({ snapshot }) => {
		document.dispatchEvent(
			new CustomEvent('consent:choice', { detail: snapshot.explicitChoice })
		);
	},
	// Runs whenever a permission changes, whatever the cause.
	onPermissionsChanged: ({ previous, snapshot }) => {
		document.dispatchEvent(
			new CustomEvent('consent:permissions', {
				detail: { current: snapshot.effectivePermissions, previous },
			})
		);
	},
};
```

# React Island
URL: https://c15t.com/docs/shared/examples/storybook-astro/react-island

```tsx title="src/components/consent-status.tsx"
import { getConsentClient, openDialog } from 'c15t/astro/client';
import { ConsentProvider, useConsent } from 'c15t/react';

const MeasurementStatus = () => {
	const allowed = useConsent('measurement');
	return (
		<p>
			<span data-testid="measurement-status">
				Measurement is {allowed ? 'allowed' : 'not allowed'}.
			</span>{' '}
			<button
				onClick={() => {
					void openDialog();
				}}
				type="button"
			>
				Change cookie settings
			</button>
		</p>
	);
};

const ConsentStatus = () => {
	// The page's consent runtime, which the c15t integration started.
	const runtime = getConsentClient()?.runtime;
	if (!runtime) {
		return null;
	}
	return (
		// `colorScheme: null` leaves dark mode to the integration.
		<ConsentProvider options={{ colorScheme: null }} runtime={runtime}>
			<MeasurementStatus />
		</ConsentProvider>
	);
};

export default ConsentStatus;
```

# Bottom Bar
URL: https://c15t.com/docs/shared/examples/storybook-react/bottom-bar

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

/** The stock banner, drawn as a full-width bar along the bottom edge. */
export const CookieBanner = () => (
	<ConsentBanner variant="bar" position="bottom" />
);
```

# Brand Card
URL: https://c15t.com/docs/shared/examples/storybook-react/brand-card

```tsx title="src/consent-ui.tsx"
import { ConsentBanner, ConsentDialog, ConsentTheme } from 'c15t/react';

import { brandTheme } from './consent-theme';

/**
 * Render inside your ConsentProvider, and pass `theme: brandTheme` in the
 * provider options so the action styles apply too.
 */
export const ConsentUI = () => (
	<>
		<ConsentTheme theme={brandTheme} />
		<ConsentBanner />
		<ConsentDialog />
	</>
);
```

# Brand Theme
URL: https://c15t.com/docs/shared/examples/storybook-react/brand-theme

```ts title="src/consent-theme.ts"
import { defineTheme } from 'c15t/react';

export const brandTheme = defineTheme({
	colors: {
		border: '#e4dccf',
		primary: '#2f6f4e',
		primaryHover: '#24563c',
		surface: '#fbf8f3',
		textOnPrimary: '#ffffff',
	},
	consentActions: { primary: { mode: 'filled', variant: 'primary' } },
	radius: { lg: '4px', md: '4px' },
	typography: { fontFamily: 'Georgia, "Times New Roman", serif' },
});
```

# Choice Wall
URL: https://c15t.com/docs/shared/examples/storybook-react/choice-wall

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

/** A centered prompt with a backdrop. The page waits for a choice. */
export const CookieBanner = () => <ConsentBanner variant="wall" />;
```

# Class Names Css Modules
URL: https://c15t.com/docs/shared/examples/storybook-react/class-names-css-modules

```ts title="src/consent-components.ts"
import type { ConsentProviderOptions } from 'c15t/react';

import styles from './banner.module.css';

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: styles.card } },
};
```

# Class Names Css Modules Css
URL: https://c15t.com/docs/shared/examples/storybook-react/class-names-css-modules-css

```css title="src/banner.module.css"
.card {
	border: 3px solid rgb(219 39 119);
	border-radius: 4px;
}
```

# Class Names Emotion
URL: https://c15t.com/docs/shared/examples/storybook-react/class-names-emotion

```ts title="src/consent-components.ts"
import { css } from '@emotion/css';
import type { ConsentProviderOptions } from 'c15t/react';

const card = css({ border: '3px solid rgb(234 88 12)', borderRadius: 4 });

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: card } },
};
```

# Class Names Stylex
URL: https://c15t.com/docs/shared/examples/storybook-react/class-names-stylex

```ts title="src/consent-components.ts"
import * as stylex from '@stylexjs/stylex';
import type { ConsentProviderOptions } from 'c15t/react';

const styles = stylex.create({
	card: {
		borderColor: 'rgb(22 163 74)',
		borderRadius: 4,
		borderStyle: 'solid',
		borderWidth: 3,
	},
});

/**
 * Pass as `components` in your ConsentProvider options. `stylex.props()`
 * returns `className` and, for dynamic styles, `style`; the slot takes both.
 */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: stylex.props(styles.card) },
};
```

# Class Names Vanilla Extract
URL: https://c15t.com/docs/shared/examples/storybook-react/class-names-vanilla-extract

```ts title="src/consent-components.css.ts"
import { style } from '@vanilla-extract/css';
import type { ConsentProviderOptions } from 'c15t/react';

const card = style({ border: '3px solid rgb(37 99 235)', borderRadius: 4 });

/** Pass as `components` in your ConsentProvider options. */
export const components: ConsentProviderOptions['components'] = {
	banner: { card: { className: card } },
};
```

# Compose Banner
URL: https://c15t.com/docs/shared/examples/storybook-react/compose-banner

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner, useTranslations } from 'c15t/react';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

# Compose Button
URL: https://c15t.com/docs/shared/examples/storybook-react/compose-button

```tsx title="src/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

# Headless Bar
URL: https://c15t.com/docs/shared/examples/storybook-react/headless-bar

```tsx title="src/cookie-bar.tsx"
import { useHeadlessConsentUI } from 'c15t/react/headless';
import type { HeadlessConsentBannerAction } from 'c15t/react/headless';

import './cookie-bar.css';

const labels: Record<HeadlessConsentBannerAction, string> = {
	accept: 'Accept all',
	customize: 'Preferences',
	dismiss: 'Got it',
	reject: 'Reject all',
	save: 'Save',
};

export const CookieBar = () => {
	const { banner, openDialog, performAction } = useHeadlessConsentUI();

	if (!banner.isVisible) {
		return null;
	}

	// The policy decides which actions this visitor gets, and in what order.
	// Preferences has its own button, so it is always there.
	const actions = banner.orderedActions.filter(
		(action) => action !== 'customize'
	);

	return (
		<section className="cookie-bar" aria-label="Cookie consent">
			<p className="cookie-bar__text">
				We use cookies to measure traffic and improve this site. Choose which
				ones can run.
			</p>
			<div className="cookie-bar__actions">
				<button type="button" className="cookie-bar__link" onClick={openDialog}>
					Preferences
				</button>
				{actions.map((action) => (
					<button
						key={action}
						type="button"
						className="cookie-bar__button"
						onClick={() => performAction(action)}
					>
						{labels[action]}
					</button>
				))}
			</div>
		</section>
	);
};
```

# Headless Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-react/headless-bar-css

```css title="src/cookie-bar.css"
.cookie-bar {
	position: fixed;
	inset: auto 0 0;
	z-index: 50;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.75rem 1.5rem;
	padding: 0.875rem 1.5rem;
	background: #14213d;
	color: #f8f9fb;
	font:
		0.9375rem/1.5 system-ui,
		sans-serif;
	box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
}

.cookie-bar__text {
	flex: 1 1 20rem;
	margin: 0;
}

.cookie-bar__actions {
	display: flex;
	flex-wrap: wrap;
	gap: 0.5rem;
}

.cookie-bar button {
	padding: 0.5rem 1rem;
	border: 1px solid #f8f9fb;
	border-radius: 999px;
	background: transparent;
	color: inherit;
	font: inherit;
	cursor: pointer;
}

.cookie-bar .cookie-bar__button {
	background: #f8f9fb;
	color: #14213d;
	font-weight: 600;
}

.cookie-bar .cookie-bar__link {
	border-color: transparent;
	text-decoration: underline;
	text-underline-offset: 3px;
}

.cookie-bar button:focus-visible {
	outline: 2px solid #fca311;
	outline-offset: 2px;
}
/* On narrow screens, Reject and Accept share a row at equal width. */
@media (max-width: 30rem) {
	.cookie-bar__actions {
		width: 100%;
	}

	.cookie-bar__actions button {
		flex: 1 1 40%;
	}

	.cookie-bar__actions .cookie-bar__link {
		flex-basis: 100%;
	}
}
```

# Slim Bar
URL: https://c15t.com/docs/shared/examples/storybook-react/slim-bar

```tsx title="src/cookie-banner.tsx"
import { ConsentBanner } from 'c15t/react';

import './slim-bar.css';

/**
 * The title, copy and the policy's buttons in a single row. The compound
 * parts keep the policy's actions, so a required Reject button stays.
 */
export const CookieBanner = () => (
	<ConsentBanner.Root variant="bar">
		<ConsentBanner.Card className="slim-bar">
			<ConsentBanner.Header className="slim-bar__text">
				<ConsentBanner.Title />
				<ConsentBanner.Description />
			</ConsentBanner.Header>
			<ConsentBanner.PolicyActions />
		</ConsentBanner.Card>
	</ConsentBanner.Root>
);
```

# Slim Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-react/slim-bar-css

```css title="src/slim-bar.css"
.slim-bar {
	box-sizing: border-box;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.5rem 1.5rem;
	padding: 0.5rem 1.5rem;
}

/* Title and description share one line. */
.slim-bar__text {
	display: flex;
	flex: 1 1 20rem;
	flex-direction: row;
	flex-wrap: wrap;
	align-items: baseline;
	gap: 0 0.5rem;
	padding: 0;
}

/* The actions share the text's row, so drop the footer's own box. */
.slim-bar > [data-testid='consent-banner-footer'] {
	padding: 0;
	border: 0;
	background: none;
}
```

# Bottom Bar
URL: https://c15t.com/docs/shared/examples/storybook-svelte/bottom-bar

```svelte title="src/lib/cookie-banner.svelte"
<script lang="ts">
	import { ConsentBanner } from '@c15t/svelte';
</script>

<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
<ConsentBanner variant="bar" position="bottom" />
```

# Consent Actions
URL: https://c15t.com/docs/shared/examples/storybook-svelte/consent-actions

```svelte title="src/lib/cookie-choices.svelte"
<script lang="ts">
	import { ConsentButton, ConsentDialog } from '@c15t/svelte';
</script>

<section aria-labelledby="cookie-choices">
	<h2 id="cookie-choices">Cookie choices</h2>
	<ConsentButton action="accept-consent" variant="primary" mode="filled">
		Accept all
	</ConsentButton>
	<ConsentButton action="reject-consent">Reject optional</ConsentButton>
	<ConsentButton action="open-consent-dialog" mode="ghost">
		Choose cookies
	</ConsentButton>
</section>
<ConsentDialog />
```

# Consent Callbacks
URL: https://c15t.com/docs/shared/examples/storybook-svelte/consent-callbacks

```ts title="src/lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from '@c15t/svelte';

// Pass as `callbacks={callbacks}` on ConsentProvider.
export const callbacks: ConsentProviderCallbacks = {
	// Runs just before c15t reloads the page after a withdrawal.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// An explicit accept, reject or save. Never runs for defaults, expiry,
	// policy changes or privacy signals.
	onChoiceRecorded: ({ snapshot, confirmed }) => {
		console.info('Visitor chose', snapshot.explicitChoice, confirmed);
	},
	// A failed command, such as an /init request that could not reach the
	// backend.
	onError: ({ error }) => {
		console.warn('c15t error', error);
	},
	// Any change to what may run, whatever caused it.
	onPermissionsChanged: ({ snapshot, previous }) => {
		console.info('Permissions', previous, '->', snapshot.effectivePermissions);
	},
};
```

# Consent Events
URL: https://c15t.com/docs/shared/examples/storybook-svelte/consent-events

```svelte title="src/lib/consent-events.svelte"
<script lang="ts">
	import { getConsentKernel } from '@c15t/svelte';

	// Read the kernel at the top level; subscribe in an effect so the
	// listener is removed when the component unmounts.
	const kernel = getConsentKernel();
	let lastRecorded = $state<string | null>(null);

	$effect(() =>
		kernel.events.on('choice:recorded', ({ snapshot }) => {
			const { measurement } = snapshot.effectivePermissions;
			lastRecorded = measurement ? 'measurement allowed' : 'measurement denied';
		})
	);
</script>

<p data-testid="last-recorded">
	{lastRecorded ?? 'No choice recorded on this page yet'}
</p>
```

# Consent I18n
URL: https://c15t.com/docs/shared/examples/storybook-svelte/consent-i18n

```ts title="src/lib/consent-i18n.ts"
import type { I18nConfig } from '@c15t/svelte';

// Pass as `i18n={i18n}` on ConsentProvider. Messages merge over the
// bundled English copy, so list only the keys you change.
export const i18n: Partial<I18nConfig> = {
	locale: 'en',
	messages: {
		en: {
			common: { customize: 'Choose cookies', rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Your privacy on this site' },
		},
	},
};
```

# Consent Status
URL: https://c15t.com/docs/shared/examples/storybook-svelte/consent-status

```svelte title="src/lib/consent-status.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	// Call getters at the top level of the component, inside the provider.
	const consent = getConsentManager();

	// A permission: may measurement code run now?
	const measurementAllowed = $derived(consent.has('measurement'));
	// A recorded choice: what did the visitor decide? `null` until they choose.
	const measurementChoice = $derived(
		consent.explicitChoice?.categories.measurement?.value
	);
</script>

<dl>
	<dt>Measurement may run</dt>
	<dd data-testid="measurement-permission">
		{measurementAllowed ? 'Yes' : 'No'}
	</dd>
	<dt>Visitor's measurement choice</dt>
	<dd data-testid="measurement-choice">
		{measurementChoice === undefined
			? 'Not chosen'
			: measurementChoice
				? 'Allowed'
				: 'Denied'}
	</dd>
</dl>
```

# Floating Trigger
URL: https://c15t.com/docs/shared/examples/storybook-svelte/floating-trigger

```svelte title="src/lib/privacy-trigger.svelte"
<script lang="ts">
	import { ConsentDialog, ConsentDialogTrigger } from '@c15t/svelte';
</script>

<!-- A floating button in the bottom-left corner that opens preferences.
     Visitors can drag it to another corner; c15t remembers where. -->
<ConsentDialogTrigger defaultPosition="bottom-left" size="sm" />
<ConsentDialog />
```

# Headless Bar
URL: https://c15t.com/docs/shared/examples/storybook-svelte/headless-bar

```svelte title="src/lib/cookie-bar.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	import './cookie-bar.css';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Preferences',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};

	// The policy decides which actions this visitor gets, and in what order.
	// Preferences has its own button, so it is always there.
	const actions = $derived(
		consent.banner.orderedActions.filter((action) => action !== 'customize')
	);
</script>

{#if consent.banner.isVisible}
	<section class="cookie-bar" aria-label="Cookie consent">
		<p class="cookie-bar__text">
			We use cookies to measure traffic and improve this site. Choose which ones
			can run.
		</p>
		<div class="cookie-bar__actions">
			<button
				type="button"
				class="cookie-bar__link"
				onclick={() => consent.openDialog()}
			>
				Preferences
			</button>
			{#each actions as action (action)}
				<button
					type="button"
					class="cookie-bar__button"
					onclick={() => consent.performAction(action)}
				>
					{labels[action]}
				</button>
			{/each}
		</div>
	</section>
{/if}
```

# Headless Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-svelte/headless-bar-css

```css title="src/cookie-bar.css"
.cookie-bar {
	position: fixed;
	inset: auto 0 0;
	z-index: 50;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.75rem 1.5rem;
	padding: 0.875rem 1.5rem;
	background: #14213d;
	color: #f8f9fb;
	font:
		0.9375rem/1.5 system-ui,
		sans-serif;
	box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
}

.cookie-bar__text {
	flex: 1 1 20rem;
	margin: 0;
}

.cookie-bar__actions {
	display: flex;
	flex-wrap: wrap;
	gap: 0.5rem;
}

.cookie-bar button {
	padding: 0.5rem 1rem;
	border: 1px solid #f8f9fb;
	border-radius: 999px;
	background: transparent;
	color: inherit;
	font: inherit;
	cursor: pointer;
}

.cookie-bar .cookie-bar__button {
	background: #f8f9fb;
	color: #14213d;
	font-weight: 600;
}

.cookie-bar .cookie-bar__link {
	border-color: transparent;
	text-decoration: underline;
	text-underline-offset: 3px;
}

.cookie-bar button:focus-visible {
	outline: 2px solid #fca311;
	outline-offset: 2px;
}
/* On narrow screens, Reject and Accept share a row at equal width. */
@media (max-width: 30rem) {
	.cookie-bar__actions {
		width: 100%;
	}

	.cookie-bar__actions button {
		flex: 1 1 40%;
	}

	.cookie-bar__actions .cookie-bar__link {
		flex-basis: 100%;
	}
}
```

# Iab Surfaces
URL: https://c15t.com/docs/shared/examples/storybook-svelte/iab-surfaces

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

# Network Blocker
URL: https://c15t.com/docs/shared/examples/storybook-svelte/network-blocker

```ts title="src/lib/network-blocker.ts"
import type { UseNetworkBlockerOptions } from '@c15t/svelte';

// Pass as `networkBlocker={networkBlocker}` on ConsentProvider.
export const networkBlocker: UseNetworkBlockerOptions = {
	onRequestBlocked: ({ method, url }) => {
		console.info('Blocked until consent', method, url);
	},
	rules: [
		{
			category: 'measurement',
			domain: 'google-analytics.com',
			id: 'google-analytics',
		},
		{
			category: 'marketing',
			domain: 'connect.facebook.net',
			id: 'meta-pixel',
			pathIncludes: '/signals',
		},
	],
};
```

# Own Preferences
URL: https://c15t.com/docs/shared/examples/storybook-svelte/own-preferences

```svelte title="src/lib/cookie-preferences.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
	const config = $derived(consent.translationConfig);
	const copy = $derived(config.translations[config.defaultLanguage ?? 'en']);
</script>

{#if consent.draft.isStale}
	<p role="alert">The cookie policy changed. Review your choices.</p>
{/if}
<fieldset>
	<legend>Cookie preferences</legend>
	{#each consent.getDisplayedConsents() as category (category.name)}
		<label>
			<input
				type="checkbox"
				checked={consent.selectedConsents[category.name] ?? false}
				disabled={category.name === 'necessary'}
				onchange={(event) =>
					consent.setConsent(category.name, event.currentTarget.checked)}
			/>
			{copy?.consentTypes?.[category.name]?.title ?? category.name}
		</label>
	{/each}
</fieldset>
<button
	type="button"
	disabled={consent.draft.isStale}
	onclick={() => consent.saveConsents('custom')}
>
	Save preferences
</button>
```

# Privacy Controls
URL: https://c15t.com/docs/shared/examples/storybook-svelte/privacy-controls

```svelte title="src/lib/privacy-controls.svelte"
<script lang="ts">
	import { ConsentDialog, getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();

	// Record one category from your own button. setConsent changes the draft;
	// saveConsents('custom') records it.
	const allowAnalytics = async () => {
		consent.setConsent('measurement', true);
		await consent.saveConsents('custom');
	};
</script>

<button type="button" onclick={() => consent.setActiveUI('dialog')}>
	Privacy settings
</button>
<button type="button" onclick={allowAnalytics}> Allow analytics </button>
<ConsentDialog />
```

# Privacy Settings Page
URL: https://c15t.com/docs/shared/examples/storybook-svelte/privacy-settings-page

```svelte title="src/routes/privacy/+page.svelte"
<script lang="ts">
	import { ConsentWidget } from '@c15t/svelte';
</script>

<h1>Privacy settings</h1>
<p>Choose which optional cookies this site may use.</p>
<!-- The category switches and save buttons, inline on the page. -->
<ConsentWidget />
```

# Slim Bar
URL: https://c15t.com/docs/shared/examples/storybook-svelte/slim-bar

```ts title="src/lib/consent-options.ts"
import type { ConsentManagerOptions } from '@c15t/svelte';

import './slim-bar.css';

/**
 * Spread into the options you pass to `ConsentProvider`. The bar
 * keeps the stock markup and actions; the slot classes put it on one row.
 */
export const slimBar = {
	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
	theme: {
		slots: {
			consentBannerCard: 'slim-bar',
			consentBannerHeader: 'slim-bar__text',
		},
	},
} satisfies Partial<ConsentManagerOptions>;
```

# Slim Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-svelte/slim-bar-css

```css title="src/slim-bar.css"
.slim-bar {
	box-sizing: border-box;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.5rem 1.5rem;
	padding: 0.5rem 1.5rem;
}

/* Title and description share one line. */
.slim-bar__text {
	display: flex;
	flex: 1 1 20rem;
	flex-direction: row;
	flex-wrap: wrap;
	align-items: baseline;
	gap: 0 0.5rem;
	padding: 0;
}

/* The actions share the text's row, so drop the footer's own box. */
.slim-bar > [data-testid='consent-banner-footer'] {
	padding: 0;
	border: 0;
	background: none;
}
```

# Bottom Bar
URL: https://c15t.com/docs/shared/examples/storybook-vue/bottom-bar

```vue title="src/CookieBanner.vue"
<script setup lang="ts">
import ConsentBanner from 'c15t/vue/runtime/components/consent-banner.vue';
</script>

<template>
	<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
	<ConsentBanner variant="bar" position="bottom" />
</template>
```

# Headless Bar
URL: https://c15t.com/docs/shared/examples/storybook-vue/headless-bar

```vue title="src/CookieBar.vue"
<script setup lang="ts">
import {
	useConsentActiveUI,
	useConsentPolicyActions,
	useConsentSave,
	useDismissNotice,
	usePromptRequirement,
} from 'c15t/vue/vue-plugin';
import { computed } from 'vue';

import './cookie-bar.css';

const labels: Record<string, string> = {
	accept: 'Accept all',
	dismiss: 'Got it',
	reject: 'Reject all',
};

const activeUI = useConsentActiveUI();
const prompt = usePromptRequirement();
const { actionGroups } = useConsentPolicyActions('prompt');
const saveConsent = useConsentSave();
const dismissNotice = useDismissNotice();

const isVisible = computed(
	() => activeUI.value === 'banner' && prompt.value.kind !== 'none'
);

// The policy decides which actions this visitor gets, and in what order.
// Preferences has its own button, so it is always there.
const actions = computed(() =>
	actionGroups.value.flat().filter((action) => action in labels)
);

const run = (action: string) => {
	if (action === 'accept') {
		void saveConsent('all');
	} else if (action === 'reject') {
		void saveConsent('none');
	} else if (action === 'dismiss') {
		void dismissNotice();
	}
};
</script>

<template>
	<section v-if="isVisible" class="cookie-bar" aria-label="Cookie consent">
		<p class="cookie-bar__text">
			We use cookies to measure traffic and improve this site. Choose which ones
			can run.
		</p>
		<div class="cookie-bar__actions">
			<button
				type="button"
				class="cookie-bar__link"
				@click="activeUI = 'manager'"
			>
				Preferences
			</button>
			<button
				v-for="action in actions"
				:key="action"
				type="button"
				class="cookie-bar__button"
				@click="run(action)"
			>
				{{ labels[action] }}
			</button>
		</div>
	</section>
</template>
```

# Headless Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-vue/headless-bar-css

```css title="src/cookie-bar.css"
.cookie-bar {
	position: fixed;
	inset: auto 0 0;
	z-index: 50;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.75rem 1.5rem;
	padding: 0.875rem 1.5rem;
	background: #14213d;
	color: #f8f9fb;
	font:
		0.9375rem/1.5 system-ui,
		sans-serif;
	box-shadow: 0 -4px 16px rgb(0 0 0 / 0.15);
}

.cookie-bar__text {
	flex: 1 1 20rem;
	margin: 0;
}

.cookie-bar__actions {
	display: flex;
	flex-wrap: wrap;
	gap: 0.5rem;
}

.cookie-bar button {
	padding: 0.5rem 1rem;
	border: 1px solid #f8f9fb;
	border-radius: 999px;
	background: transparent;
	color: inherit;
	font: inherit;
	cursor: pointer;
}

.cookie-bar .cookie-bar__button {
	background: #f8f9fb;
	color: #14213d;
	font-weight: 600;
}

.cookie-bar .cookie-bar__link {
	border-color: transparent;
	text-decoration: underline;
	text-underline-offset: 3px;
}

.cookie-bar button:focus-visible {
	outline: 2px solid #fca311;
	outline-offset: 2px;
}
/* On narrow screens, Reject and Accept share a row at equal width. */
@media (max-width: 30rem) {
	.cookie-bar__actions {
		width: 100%;
	}

	.cookie-bar__actions button {
		flex: 1 1 40%;
	}

	.cookie-bar__actions .cookie-bar__link {
		flex-basis: 100%;
	}
}
```

# Slim Bar
URL: https://c15t.com/docs/shared/examples/storybook-vue/slim-bar

```ts title="src/consent-options.ts"
import type { C15tVuePluginOptions } from 'c15t/vue/vue-plugin';

import './slim-bar.css';

/**
 * Spread into the options you pass to `app.use(c15tVue, ...)`. The bar keeps
 * the stock markup and actions; the slot classes put it on one row.
 */
export const slimBar = {
	components: {
		banner: {
			card: { class: 'slim-bar' },
			header: { class: 'slim-bar__text' },
		},
	},
	presentation: { prompt: { position: 'bottom', variant: 'bar' } },
} satisfies C15tVuePluginOptions;
```

# Slim Bar Css
URL: https://c15t.com/docs/shared/examples/storybook-vue/slim-bar-css

```css title="src/slim-bar.css"
.slim-bar {
	box-sizing: border-box;
	display: flex;
	flex-wrap: wrap;
	align-items: center;
	gap: 0.5rem 1.5rem;
	padding: 0.5rem 1.5rem;
}

/* Title and description share one line. */
.slim-bar__text {
	display: flex;
	flex: 1 1 20rem;
	flex-direction: row;
	flex-wrap: wrap;
	align-items: baseline;
	gap: 0 0.5rem;
	padding: 0;
}

/* The actions share the text's row, so drop the footer's own box. */
.slim-bar > [data-testid='consent-banner-footer'] {
	padding: 0;
	border: 0;
	background: none;
}
```

# App
URL: https://c15t.com/docs/shared/examples/svelte/app

```svelte title="src/App.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		manifest,
	} from '@c15t/svelte';

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentProvider mode={manifest()} {scripts}>
	<main>
		<h1>c15t + Svelte</h1>
		<p>Your app goes here.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

# Scripts
URL: https://c15t.com/docs/shared/examples/svelte/scripts

```ts title="src/scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	// Loads PostHog only after the visitor allows measurement.
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

# Theme Css
URL: https://c15t.com/docs/shared/examples/svelte/theme-css

```css title="src/consent-theme.css"
/* Load after @c15t/svelte/styles.css so these values win. */
:root {
	--c15t-primary: #6943a3;
	--c15t-primary-hover: #533285;
	--c15t-text-on-primary: #ffffff;
	--c15t-radius-lg: 18px;
}
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/svelte/vite-config

```ts title="vite.config.ts"
import { consentManifest } from '@c15t/svelte/vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [consentManifest(), svelte()] });
```

# Youtube Embed
URL: https://c15t.com/docs/shared/examples/svelte/youtube-embed

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

# App Locals
URL: https://c15t.com/docs/shared/examples/sveltekit/app-locals

```ts title="src/app.d.ts"
/// <reference types="@c15t/svelte/kit/locals" />
```

# Custom Banner
URL: https://c15t.com/docs/shared/examples/sveltekit/custom-banner

```svelte title="src/lib/custom-consent-banner.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Customize',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};
</script>

{#if consent.banner.isVisible}
	<section class="custom-consent-banner" aria-label="Cookie consent">
		<p>
			We use cookies to measure traffic and show ads. Choose which ones can run.
		</p>
		<!-- The policy decides which actions this visitor gets, and in what order. -->
		{#each consent.banner.actionGroups as group, index (index)}
			<div>
				{#each group as action (action)}
					<button type="button" onclick={() => consent.performAction(action)}>
						{labels[action]}
					</button>
				{/each}
			</div>
		{/each}
	</section>
{/if}

<style>
	.custom-consent-banner {
		position: fixed;
		inset: auto 1rem 1rem;
		max-width: 32rem;
		padding: 1rem;
		border: 1px solid currentColor;
		border-radius: 0.5rem;
		background: white;
	}
	.custom-consent-banner div {
		display: flex;
		gap: 0.5rem;
		margin-top: 0.5rem;
	}
</style>
```

# Dev Tools
URL: https://c15t.com/docs/shared/examples/sveltekit/dev-tools

```svelte title="src/lib/consent-dev-tools.svelte"
<script lang="ts">
	import { dev } from '$app/env';

	// Import the panel only in development, so production bundles never
	// download it.
	const devTools = dev ? import('@c15t/svelte/devtools') : null;
</script>

{#if devTools}
	{#await devTools then { ConsentDevTools }}
		<ConsentDevTools />
	{/await}
{/if}
```

# Headless Layout
URL: https://c15t.com/docs/shared/examples/sveltekit/headless-layout

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import {
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		hosted,
	} from '@c15t/svelte';

	import CustomConsentBanner from '#lib/custom-consent-banner.svelte';
	import { scripts } from '#lib/scripts.js';

	let { children } = $props();

	const mode = hosted({ backendURL: 'https://your-project.inth.app' });
</script>

<ConsentProvider {mode} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<CustomConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

# Hooks
URL: https://c15t.com/docs/shared/examples/sveltekit/hooks

```ts title="src/hooks.server.ts"
import { c15tHandle } from '@c15t/svelte/kit';

export const handle = c15tHandle();
```

# Layout
URL: https://c15t.com/docs/shared/examples/sveltekit/layout

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import { posthog } from '@c15t/integrations/posthog';
	import {
		ConsentBanner,
		ConsentDialog,
		ConsentDialogLink,
		ConsentRoot,
	} from '@c15t/svelte';

	let { children, data } = $props();

	const scripts = [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	];
</script>

<ConsentRoot state={data.consent} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<ConsentBanner />
	<ConsentDialog />
</ConsentRoot>
```

# Layout Server
URL: https://c15t.com/docs/shared/examples/sveltekit/layout-server

```ts title="src/routes/+layout.server.ts"
export { loadConsent as load } from '@c15t/svelte/kit';
```

# Manifest Layout Server
URL: https://c15t.com/docs/shared/examples/sveltekit/manifest-layout-server

```ts title="src/routes/+layout.server.ts"
// Resolves with the mode, route prefix and snapshot `c15tHandle()` holds.
export { loadConsent as load } from '@c15t/svelte/kit';
```

# Node Sdk Client
URL: https://c15t.com/docs/shared/examples/sveltekit/node-sdk-client

```ts title="src/lib/c15t-client.ts"
import { createC15tClient } from '@c15t/node-sdk';

export const c15t = createC15tClient({
	baseUrl: process.env.C15T_API_URL || 'http://localhost:5173/api/self-host',
});
```

# Prerender
URL: https://c15t.com/docs/shared/examples/sveltekit/prerender

```ts title="src/routes/about/+page.ts"
// Build this page once as static HTML. While SvelteKit prerenders,
// `loadConsent` returns no visitor's consent, so the browser resolves it
// here.
export const prerender = true;
```

# Route Handlers
URL: https://c15t.com/docs/shared/examples/sveltekit/route-handlers

```ts title="src/routes/api/c15t/[...path]/+server.ts"
import { createConsentRoute } from '@c15t/svelte/kit';

// GET /api/c15t/init resolves the visitor from the bundled policy, and
// GET /api/c15t/manifest serves it. Other methods are not handled: the
// browser saves consent to the backend URL directly. Pair it with
// `c15tHandle({ routePrefix: '/api/c15t' })`.
export const { GET } = createConsentRoute();
```

# Scripts
URL: https://c15t.com/docs/shared/examples/sveltekit/scripts

```ts title="src/lib/scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	// Loads PostHog only after the visitor allows measurement.
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

# Self Host Route
URL: https://c15t.com/docs/shared/examples/sveltekit/self-host-route

```ts title="src/routes/api/self-host/[...all]/+server.ts"
import type { RequestHandler } from './$types';

// Load the backend on first request, in its own chunk. SvelteKit 3 builds
// with Rolldown, which can otherwise move modules the backend shares with
// lazily loaded chunks into this route's chunk and export them from it, and
// SvelteKit rejects a route that exports anything besides its handlers.
const loadBackend = () => import('#lib/server/c15t-backend.js');

const handleRequest: RequestHandler = async ({ request }) => {
	const { backend } = await loadBackend();
	return backend.handler(request);
};

export const GET = handleRequest;
export const POST = handleRequest;
export const PUT = handleRequest;
export const PATCH = handleRequest;
export const OPTIONS = handleRequest;
```

# Theme
URL: https://c15t.com/docs/shared/examples/sveltekit/theme

```ts title="src/lib/server/consent-theme.ts"
import { generateThemeCSS } from '@c15t/ui/theme';

// Modules in a `server` directory never reach the browser, so the theme
// generator stays on the server. The CSS is generated once, when the server
// starts.
export const themeCSS = generateThemeCSS({
	colors: {
		primary: '#6943a3',
		primaryHover: '#533285',
		textOnPrimary: '#ffffff',
	},
	radius: { lg: '18px' },
});
```

# Theme Load
URL: https://c15t.com/docs/shared/examples/sveltekit/theme-load

```ts title="src/routes/+layout.server.ts"
import { themeCSS } from '#lib/server/consent-theme.js';

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = () => ({ themeCSS });
```

# Theme Style
URL: https://c15t.com/docs/shared/examples/sveltekit/theme-style

```svelte title="src/routes/+layout.svelte"
<svelte:head>
	<!-- generateThemeCSS escapes `<`, so its output is safe in a style element. -->
	{@html `<style id="c15t-theme">${data.themeCSS}</style>`}
</svelte:head>
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/sveltekit/vite-config

```ts title="vite.config.ts"
import { consentManifest } from '@c15t/svelte/vite';
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), sveltekit({ adapter: adapter() })],
});
```

# Astro Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/astro/astro-config

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import { defineConfig } from 'astro/config';
import c15t, { offline } from 'c15t/astro';

export default defineConfig({
	integrations: [
		svelte(),
		c15t({
			mode: offline({
				policyRules: [
					{
						id: 'tailwind-matrix',
						match: { isDefault: true },
						model: 'opt-in',
						prompt: 'choice',
					},
				],
			}),
		}),
	],
});
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/astro/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/astro/slot

```astro title="src/pages/index.astro"
<ConsentBanner class="!p-[7px] dark:!p-[11px]" />
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/astro/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{astro,html,ts}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/astro/tailwind-css

```css title="src/styles/global.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/browser/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

# Script Tag
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/script-tag

```html title="index.html"
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	defer
></script>
```

# Script Tag Light Dom
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/script-tag-light-dom

```html title="light-dom.html"
<script>
	window.c15t = [['config', { ui: { shadow: false, styles: false } }]];
</script>
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	defer
></script>
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default { content: ['./*.html'], darkMode: 'class' } satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-css

```css title="style.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Tailwind Css Light Dom
URL: https://c15t.com/docs/shared/examples/tailwind-v3/html/tailwind-css-light-dom

```css title="style.css"
/*
 * With `shadow: false`, c15t's injected stylesheet is layered and Tailwind
 * 3's preflight is not, so preflight wins. Turn the injected sheet off and
 * build c15t's rules into your Tailwind CSS instead.
 */
@import '@c15t/browser/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode,
	// Tailwind 3 builds c15t's stylesheet from globals.css.
	styles: false,
}}
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15-turbopack/tailwind-css

```css title="app/globals.css"
/* Turbopack rejects an @import below other rules, so it goes first. */
@import 'c15t/next/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode,
	// Tailwind 3 builds c15t's stylesheet from globals.css.
	styles: false,
}}
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-15/tailwind-css

```css title="app/globals.css"
/* Turbopack rejects an @import below other rules, so it goes first. */
@import 'c15t/next/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode,
	// Tailwind 3 builds c15t's stylesheet from globals.css.
	styles: false,
}}
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-turbopack/tailwind-css

```css title="app/globals.css"
/* Turbopack rejects an @import below other rules, so it goes first. */
@import 'c15t/next/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode,
	// Tailwind 3 builds c15t's stylesheet from globals.css.
	styles: false,
}}
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/next-16-webpack/tailwind-css

```css title="app/globals.css"
/* Turbopack rejects an @import below other rules, so it goes first. */
@import 'c15t/next/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Nuxt Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/nuxt-config

```ts title="nuxt.config.ts"
import { hosted } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { backendURL: '/api/c15t', mode: hosted() },
	compatibilityDate: '2026-07-04',
	css: ['~/assets/css/main.css'],
	modules: ['c15t/vue'],
	postcss: {
		plugins: {
			'c15t/postcss-tailwind3': {},
			tailwindcss: {},
			autoprefixer: {},
		},
	},
	ssr: false,
});
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/slot

```ts title="app/app.config.ts"
// Tailwind scans `app/`, so keep slot classes here rather than in
// nuxt.config.ts.
export default defineAppConfig({
	c15t: {
		components: { banner: { root: { class: '!p-[7px] dark:!p-[11px]' } } },
	},
});
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./app/**/*.{vue,ts}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/nuxt/tailwind-css

```css title="app/assets/css/main.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/react/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/react/slot

```tsx title="src/main.tsx"
const options = {
	components: { banner: { root: { className: '!p-[7px] dark:!p-[11px]' } } },
	mode,
	// Tailwind 3 builds c15t's stylesheet from app.css.
	styles: false,
};
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/react/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/react/tailwind-css

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import 'c15t/react/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/react/vite-config

```ts title="vite.config.ts"
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [react()] });
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/svelte/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/svelte/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/svelte/slot

```svelte title="src/App.svelte"
<ConsentBanner class="!p-[7px] dark:!p-[11px]" />
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/svelte/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{svelte,ts}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/svelte/tailwind-css

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import '@c15t/svelte/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/svelte/vite-config

```ts title="vite.config.ts"
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [svelte()] });
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: {
		'@c15t/svelte/postcss-tailwind3': {},
		tailwindcss: {},
		autoprefixer: {},
	},
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/slot

```svelte title="src/routes/+layout.svelte"
<ConsentBanner class="!p-[7px] dark:!p-[11px]" />
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{html,svelte,ts}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/tailwind-css

```css title="src/app.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import '@c15t/svelte/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/sveltekit/vite-config

```ts title="vite.config.ts"
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [sveltekit()] });
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/slot

```tsx title="src/routes/__root.tsx"
options={{
	components: {
		banner: {
			root: { className: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode,
	// Tailwind 3 builds c15t's stylesheet from styles.css.
	styles: false,
}}
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./src/**/*.{ts,tsx}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/tailwind-css

```css title="src/styles.css"
/* Vite ignores an @import below other rules, so it goes first. */
@import 'c15t/tanstack-start/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/tanstack-start/vite-config

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [tanstackStart({ prerender: { enabled: true } }), react()],
});
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/vue/postcss-config

```js title="postcss.config.mjs"
export default {
	plugins: { 'c15t/postcss-tailwind3': {}, tailwindcss: {}, autoprefixer: {} },
};
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v3/vue/slot

```ts title="src/main.ts"
.use(c15tVue, {
	components: {
		banner: {
			root: { class: '!p-[7px] dark:!p-[11px]' },
		},
	},
	mode: hosted(),
})
```

# Tailwind Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/vue/tailwind-config

```ts title="tailwind.config.ts"
import type { Config } from 'tailwindcss';

export default {
	content: ['./index.html', './src/**/*.{vue,ts}'],
	darkMode: 'class',
} satisfies Config;
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v3/vue/tailwind-css

```css title="src/style.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v3/vue/vite-config

```ts title="vite.config.ts"
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [vue(), consentManifest({ backendURL: '/api/c15t' })],
});
```

# Astro Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/astro/astro-config

```js title="astro.config.mjs"
import svelte from '@astrojs/svelte';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'astro/config';
import c15t, { offline } from 'c15t/astro';

export default defineConfig({
	integrations: [
		svelte(),
		c15t({
			mode: offline({
				policyRules: [
					{
						id: 'tailwind-matrix',
						match: { isDefault: true },
						model: 'opt-in',
						prompt: 'choice',
					},
				],
			}),
		}),
	],
	vite: { plugins: [tailwindcss()] },
});
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/astro/slot

```astro title="src/pages/index.astro"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/astro/tailwind-css

```css title="src/styles/global.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Script Tag
URL: https://c15t.com/docs/shared/examples/tailwind-v4/html/script-tag

```html title="index.html"
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	defer
></script>
```

# Script Tag Light Dom
URL: https://c15t.com/docs/shared/examples/tailwind-v4/html/script-tag-light-dom

```html title="light-dom.html"
<script
	src="/c15t.offline.js"
	data-mode="offline"
	data-country="DE"
	data-shadow="false"
	defer
></script>
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/html/tailwind-css

```css title="style.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/postcss-config

```js title="postcss.config.mjs"
export default { plugins: { '@tailwindcss/postcss': {} } };
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15-turbopack/tailwind-css

```css title="app/globals.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15/postcss-config

```js title="postcss.config.mjs"
export default { plugins: { '@tailwindcss/postcss': {} } };
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-15/tailwind-css

```css title="app/globals.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/postcss-config

```js title="postcss.config.mjs"
export default { plugins: { '@tailwindcss/postcss': {} } };
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-turbopack/tailwind-css

```css title="app/globals.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Postcss Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/postcss-config

```js title="postcss.config.mjs"
export default { plugins: { '@tailwindcss/postcss': {} } };
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/slot

```tsx title="app/consent.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/next-16-webpack/tailwind-css

```css title="app/globals.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Nuxt Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/nuxt-config

```ts title="nuxt.config.ts"
import tailwindcss from '@tailwindcss/vite';
import { hosted } from 'c15t/vue';

export default defineNuxtConfig({
	c15t: { backendURL: '/api/c15t', mode: hosted() },
	compatibilityDate: '2026-07-04',
	css: ['~/assets/css/main.css'],
	modules: ['c15t/vue'],
	ssr: false,
	vite: { plugins: [tailwindcss()] },
});
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/slot

```ts title="app/app.config.ts"
// Tailwind scans `app/`, so keep slot classes here rather than in
// nuxt.config.ts.
export default defineAppConfig({
	c15t: {
		components: { banner: { root: { class: 'p-[7px] dark:p-[11px]' } } },
	},
});
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/nuxt/tailwind-css

```css title="app/assets/css/main.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/react/slot

```tsx title="src/main.tsx"
const options = {
	components: { banner: { root: { className: 'p-[7px] dark:p-[11px]' } } },
	mode,
};
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/react/tailwind-css

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/react/vite-config

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [react(), tailwindcss()] });
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/svelte/slot

```svelte title="src/App.svelte"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/svelte/tailwind-css

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/svelte/vite-config

```ts title="vite.config.ts"
import { svelte } from '@sveltejs/vite-plugin-svelte';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [svelte(), tailwindcss()] });
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/slot

```svelte title="src/routes/+layout.svelte"
<ConsentBanner class="p-[7px] dark:p-[11px]" />
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/tailwind-css

```css title="src/app.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/sveltekit/vite-config

```ts title="vite.config.ts"
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [tailwindcss(), sveltekit()] });
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/slot

```tsx title="src/routes/__root.tsx"
options={{
	components: {
		banner: {
			root: { className: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode,
}}
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/tailwind-css

```css title="src/styles.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/tanstack-start/vite-config

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		tailwindcss(),
		tanstackStart({ prerender: { enabled: true } }),
		react(),
	],
});
```

# Slot
URL: https://c15t.com/docs/shared/examples/tailwind-v4/vue/slot

```ts title="src/main.ts"
.use(c15tVue, {
	components: {
		banner: {
			root: { class: 'p-[7px] dark:p-[11px]' },
		},
	},
	mode: hosted(),
})
```

# Tailwind Css
URL: https://c15t.com/docs/shared/examples/tailwind-v4/vue/tailwind-css

```css title="src/style.css"
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tailwind-v4/vue/vite-config

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite';
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [vue(), consentManifest({ backendURL: '/api/c15t' }), tailwindcss()],
});
```

# Build Manifest Server Fn
URL: https://c15t.com/docs/shared/examples/tanstack-start/build-manifest-server-fn

```ts title="src/routes/__root.tsx"
import { createServerFn } from '@tanstack/react-start';
import { createConsentStateHandler } from 'c15t/tanstack-start/server';

// Reads the backend URL and the policy consentManifest() downloaded.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/tanstack-start/callbacks

```ts title="src/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from 'c15t/tanstack-start';

export const callbacks = {
	// Right before the page reloads because a save withdrew a permission.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ confirmed, snapshot }) => {
		console.info('Choice recorded', confirmed, snapshot.explicitChoice);
	},
	// A consent command failed, such as a save the backend rejected.
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies ConsentProviderCallbacks;
```

# Compose Banner
URL: https://c15t.com/docs/shared/examples/tanstack-start/compose-banner

```tsx title="src/components/cookie-banner.tsx"
import { ConsentBanner, useTranslations } from 'c15t/tanstack-start';

import { BrandButton } from './brand-button';

const actionParts = {
	accept: ConsentBanner.AcceptButton,
	customize: ConsentBanner.CustomizeButton,
	dismiss: ConsentBanner.DismissButton,
	reject: ConsentBanner.RejectButton,
} as const;

/**
 * The stock card, title and copy, with each action the policy asks for
 * rendered as your own button. `PolicyActions` decides which actions appear
 * and in what order, so a notice still gets its acknowledgement.
 */
export const CookieBanner = () => {
	const { common } = useTranslations();
	const labels = {
		accept: common.acceptAll,
		customize: common.customize,
		dismiss: common.acknowledge,
		reject: common.rejectAll,
	};

	return (
		<ConsentBanner.Root>
			<ConsentBanner.Card>
				<ConsentBanner.Header>
					<ConsentBanner.Title />
					<ConsentBanner.Description />
				</ConsentBanner.Header>
				<ConsentBanner.PolicyActions
					renderAction={(action, { key, isPrimary, ...props }) => {
						if (action === 'save') {
							return null;
						}
						const Action = actionParts[action];
						return (
							<Action key={key} {...props} asChild noStyle>
								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
									{labels[action]}
								</BrandButton>
							</Action>
						);
					}}
				/>
			</ConsentBanner.Card>
		</ConsentBanner.Root>
	);
};
```

# Compose Button
URL: https://c15t.com/docs/shared/examples/tanstack-start/compose-button

```tsx title="src/components/brand-button.tsx"
import { forwardRef } from 'react';
import type { ButtonHTMLAttributes, ForwardedRef } from 'react';

interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
	tone?: 'solid' | 'outline';
}

const renderBrandButton = function renderBrandButton(
	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
	ref: ForwardedRef<HTMLButtonElement>
) {
	return (
		<button
			ref={ref}
			{...props}
			className={['brand-button', className].filter(Boolean).join(' ')}
			data-tone={tone}
			// Under `asChild`, c15t passes no type. Default to `button` so an
			// action never submits a surrounding form.
			type={type === 'submit' ? 'submit' : 'button'}
		/>
	);
};

/**
 * Your design system's button. To work under `asChild`, it forwards its ref
 * and passes every other prop to the `button` element, so c15t's click
 * handler, `data-action` and class names reach the DOM.
 */
export const BrandButton = forwardRef(renderBrandButton);

BrandButton.displayName = 'BrandButton';
```

# Consent Route
URL: https://c15t.com/docs/shared/examples/tanstack-start/consent-route

```ts title="src/routes/api/c15t/$.ts"
import { createFileRoute } from '@tanstack/react-router';
import { createConsentRoute } from 'c15t/tanstack-start/api';

export const Route = createFileRoute('/api/c15t/$')({
	server: { handlers: createConsentRoute({ proxy: true }) },
});
```

# I18n
URL: https://c15t.com/docs/shared/examples/tanstack-start/i18n

```ts title="src/consent-i18n.ts"
import type { ConsentProviderOptions } from 'c15t/tanstack-start';

// Keys you leave out keep the copy from your Inth project.
export const i18n = {
	messages: {
		de: {
			common: { rejectAll: 'Optionale ablehnen' },
			cookieBanner: { title: 'Cookies auf dieser Website' },
		},
		en: {
			common: { rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Cookies on this site' },
		},
	},
} satisfies ConsentProviderOptions['i18n'];
```

# Iab Consent
URL: https://c15t.com/docs/shared/examples/tanstack-start/iab-consent

```tsx title="src/components/iab-consent.tsx"
import {
	IABConsentBanner,
	IABConsentDialog,
	IABProvider,
} from 'c15t/react/iab';
import { useModel } from 'c15t/tanstack-start';

export const IABConsent = ({ cmpId }: { cmpId: number }) => {
	const model = useModel();
	if (model !== 'iab') {
		return null;
	}
	return (
		<IABProvider cmpId={cmpId}>
			<IABConsentBanner />
			<IABConsentDialog />
		</IABProvider>
	);
};
```

# Language Switcher
URL: https://c15t.com/docs/shared/examples/tanstack-start/language-switcher

```tsx title="src/components/language-switcher.tsx"
import { useInit, useSetLanguage, useSnapshot } from 'c15t/tanstack-start';

const languages = [
	{ code: 'en', label: 'English' },
	{ code: 'de', label: 'Deutsch' },
];

export const LanguageSwitcher = () => {
	const setLanguage = useSetLanguage();
	const init = useInit();
	const language = useSnapshot().translations?.language ?? 'en';

	return (
		<select
			aria-label="Consent language"
			value={language}
			onChange={(event) => {
				setLanguage(event.target.value);
				// Setting the language alone keeps the current copy. Init fetches
				// the policy and copy for the new language.
				void init();
			}}
		>
			{languages.map(({ code, label }) => (
				<option key={code} value={code}>
					{label}
				</option>
			))}
		</select>
	);
};
```

# Root
URL: https://c15t.com/docs/shared/examples/tanstack-start/root

```tsx title="src/routes/__root.tsx"
import { posthog } from '@c15t/integrations/posthog';
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

// Start's compiler keeps the handler and the bundled policy on the server.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);

const scripts = [
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	loader: async () => ({ consent: await getConsentState() }),
});
```

# Same Origin Root
URL: https://c15t.com/docs/shared/examples/tanstack-start/same-origin-root

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

import { scripts } from '../scripts';

// Declare the server function in your own module. Start's compiler splits
// the server code out of the browser bundle at this call site. The browser
// sends init and saves to the consent route in src/routes/api/c15t/$.ts.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler({ proxy: true, routePrefix: '/api/c15t' })
);

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	loader: async () => ({ consent: await getConsentState() }),
});
```

# Scripts
URL: https://c15t.com/docs/shared/examples/tanstack-start/scripts

```tsx title="src/routes/__root.tsx"
const scripts = [
	posthog({
		id: 'phc_your_project_key',
		initOptions: { cookieless_mode: 'never' },
		loadMode: 'after-consent',
	}),
];
```

# Self Host Route
URL: https://c15t.com/docs/shared/examples/tanstack-start/self-host-route

```ts title="src/routes/api/self-host/$.ts"
const handle = async function handle({ request }: { request: Request }) {
	const instance = await getInstance();
	return instance.handler(request);
};

export const Route = createFileRoute('/api/self-host/$')({
	server: {
		handlers: {
			DELETE: handle,
			GET: handle,
			OPTIONS: handle,
			PATCH: handle,
			POST: handle,
			PUT: handle,
		},
	},
});
```

# Start
URL: https://c15t.com/docs/shared/examples/tanstack-start/start

```ts title="src/start.ts"
import { createStart } from '@tanstack/react-start';
import { consentRequestMiddleware } from 'c15t/tanstack-start/middleware';

export const startInstance = createStart(() => ({
	requestMiddleware: [consentRequestMiddleware()],
}));
```

# Static Root
URL: https://c15t.com/docs/shared/examples/tanstack-start/static-root

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
	consentPrefetchHead,
} from 'c15t/tanstack-start';

import { scripts } from '../scripts';

const backendURL =
	import.meta.env.VITE_C15T_BACKEND_URL ?? 'https://your-project.inth.app';

// No loader: the HTML is built ahead of time, so the browser resolves
// consent after it loads, from the backend URL consentManifest() read.
const RootComponent = () => (
	<html lang="en">
		<head>
			<HeadContent />
		</head>
		<body>
			<ConsentRoot state={{}} scripts={scripts}>
				<Outlet />
				<ConsentBanner />
				<ConsentDialog />
				<footer>
					<ConsentDialogLink>Privacy settings</ConsentDialogLink>
				</footer>
			</ConsentRoot>
			<Scripts />
		</body>
	</html>
);

export const Route = createRootRoute({
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
		// Optional: start the /init request while the browser parses <head>.
		...consentPrefetchHead({ backendURL }),
	}),
});
```

# Streamed Root
URL: https://c15t.com/docs/shared/examples/tanstack-start/streamed-root

```tsx title="src/routes/__root.tsx"
import {
	createRootRoute,
	HeadContent,
	Outlet,
	Scripts,
} from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import {
	ConsentBanner,
	ConsentDialog,
	ConsentDialogLink,
	ConsentRoot,
} from 'c15t/tanstack-start';
import {
	consentLoaderOptions,
	createConsentStateHandler,
} from 'c15t/tanstack-start/server';

import { scripts } from '../scripts';

// Declare the server function in your own module. Start's compiler splits
// the server code out of the browser bundle at this call site.
const getConsentState = createServerFn({ method: 'GET' }).handler(
	createConsentStateHandler()
);

const RootComponent = () => {
	const { consent } = Route.useLoaderData();
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<ConsentRoot state={consent} scripts={scripts}>
					<Outlet />
					<ConsentBanner />
					<ConsentDialog />
					<footer>
						<ConsentDialogLink>Privacy settings</ConsentDialogLink>
					</footer>
				</ConsentRoot>
				<Scripts />
			</body>
		</html>
	);
};

export const Route = createRootRoute({
	...consentLoaderOptions,
	component: RootComponent,
	head: () => ({
		meta: [
			{ charSet: 'utf-8' },
			{ content: 'width=device-width, initial-scale=1', name: 'viewport' },
		],
	}),
	// Not awaited: the page streams without waiting for consent, and
	// ConsentRoot accepts the pending promise.
	loader: () => ({ consent: getConsentState() }),
});
```

# Video Embed
URL: https://c15t.com/docs/shared/examples/tanstack-start/video-embed

```tsx title="src/components/video-embed.tsx"
import { ConsentDialogLink, ConsentGate } from 'c15t/tanstack-start';

export const VideoEmbed = () => (
	<ConsentGate
		category="measurement"
		placeholder={
			<div>
				<p>
					Allow measurement to load this YouTube video. No video request is sent
					before permission.
				</p>
				<ConsentDialogLink>Open privacy settings</ConsentDialogLink>
			</div>
		}
	>
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			sandbox="allow-scripts allow-same-origin allow-presentation"
			allowFullScreen
		/>
	</ConsentGate>
);
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/tanstack-start/vite-config

```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import viteReact from '@vitejs/plugin-react';
import { consentManifest } from 'c15t/tanstack-start/build';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [consentManifest(), tanstackStart(), viteReact()],
});
```

# App
URL: https://c15t.com/docs/shared/examples/vue/app

```vue title="src/App.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentRoot } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentRoot />
	<main>
		<h1>c15t with Vue</h1>
		<p>PostHog loads after you allow measurement.</p>
	</main>
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
</template>
```

# Callbacks
URL: https://c15t.com/docs/shared/examples/vue/callbacks

```ts title="src/consent-callbacks.ts"
import type { C15tVuePluginOptions } from 'c15t/vue/vue-plugin';

export const callbacks = {
	// The visitor clicked Accept all, Reject all or Save.
	onChoiceRecorded: ({ snapshot }) => {
		console.info('Choice recorded', snapshot.explicitChoice);
	},
	onError: ({ error }) => {
		console.error('c15t', error);
	},
	// Permissions changed for any reason: a choice, an expired choice, a new
	// policy or a privacy signal.
	onPermissionsChanged: ({ previous, snapshot }) => {
		console.info('Permissions', previous, snapshot.effectivePermissions);
	},
} satisfies NonNullable<C15tVuePluginOptions['callbacks']>;
```

# Consent Status
URL: https://c15t.com/docs/shared/examples/vue/consent-status

```vue title="src/ConsentStatus.vue"
<script setup lang="ts">
import {
	useConsent,
	useConsentActiveUI,
	useExplicitChoice,
} from 'c15t/vue/vue-plugin';

// May measurement code run right now?
const permissions = useConsent();
// What did the visitor decide? `null` until they accept, reject or save.
const choice = useExplicitChoice();
const activeUI = useConsentActiveUI();
</script>

<template>
	<section aria-label="Your privacy choices">
		<p v-if="choice">You saved your privacy choices.</p>
		<p v-else>You have not made a privacy choice yet.</p>
		<p>
			Measurement is
			{{ permissions.measurement ? 'allowed' : 'not allowed' }} right now.
		</p>
		<button type="button" @click="activeUI = 'manager'">
			Change your choices
		</button>
	</section>
</template>
```

# Consent Surfaces
URL: https://c15t.com/docs/shared/examples/vue/consent-surfaces

```vue title="src/ConsentSurfaces.vue"
<script setup lang="ts">
import {
	ConsentBanner,
	ConsentDialogTrigger,
	ConsentManager,
} from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Render these in place of ConsentRoot, not next to it. -->
	<ConsentBanner variant="bar" position="bottom" />
	<ConsentManager />
	<ConsentDialogTrigger />
</template>
```

# Customize
URL: https://c15t.com/docs/shared/examples/vue/customize

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';
import { scripts } from './scripts';

createApp(App)
	.use(c15tVue, {
		components: { banner: { card: { class: 'brand-consent-card' } } },
		mode: manifest(),
		presentation: { prompt: { position: 'bottom', variant: 'bar' } },
		scripts,
		tokens: {
			'c15t-primary': '#6943a3',
			'c15t-primary-hover': '#533285',
			'c15t-radius-lg': '18px',
			'c15t-text-on-primary': '#ffffff',
		},
	})
	.mount('#app');
```

# Devtools
URL: https://c15t.com/docs/shared/examples/vue/devtools

```vue title="src/ConsentDevTools.vue"
<script setup lang="ts">
import { defineAsyncComponent } from 'vue';

// Development builds only: the dynamic import keeps DevTools out of
// production bundles.
const DevTools = import.meta.env.DEV
	? defineAsyncComponent(() => import('c15t/vue/devtools'))
	: null;
</script>

<template>
	<DevTools v-if="DevTools" position="bottom-right" />
</template>
```

# Embed
URL: https://c15t.com/docs/shared/examples/vue/embed

```vue title="src/VideoEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
</script>

<template>
	<ConsentGate category="measurement">
		<iframe
			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y"
			title="YouTube video"
			loading="lazy"
			allowfullscreen
		/>
		<template #placeholder>
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</template>
	</ConsentGate>
</template>
```

# Headless App
URL: https://c15t.com/docs/shared/examples/vue/headless-app

```vue title="src/App.vue"
<script setup lang="ts">
import { useConsentActiveUI } from 'c15t/vue/vue-plugin';

import ConsentPrompt from './ConsentPrompt.vue';
import HomePage from './HomePage.vue';

const activeUI = useConsentActiveUI();
</script>

<template>
	<ConsentPrompt />
	<HomePage />
	<footer>
		<button type="button" @click="activeUI = 'manager'">
			Privacy settings
		</button>
	</footer>
</template>
```

# Headless Main
URL: https://c15t.com/docs/shared/examples/vue/headless-main

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';
import { scripts } from './scripts';

createApp(App).use(c15tVue, { mode: manifest(), scripts }).mount('#app');
```

# Headless Prompt
URL: https://c15t.com/docs/shared/examples/vue/headless-prompt

```vue title="src/ConsentPrompt.vue"
<script setup lang="ts">
import {
	useConsentActiveUI,
	useConsentDraft,
	useConsentSave,
} from 'c15t/vue/vue-plugin';

const activeUI = useConsentActiveUI();
const saveConsent = useConsentSave();
const { displayedCategories, save: saveDraft, values } = useConsentDraft();

// Recording a choice satisfies the prompt, so c15t closes the banner itself.
const choose = (choice: 'all' | 'none') => {
	void saveConsent(choice);
};

// Preferences stay open until you close them. c15t records the draft
// locally before the network request, so closing right away is safe.
const savePreferences = () => {
	void saveDraft();
	activeUI.value = null;
};
</script>

<template>
	<section
		v-if="activeUI === 'banner'"
		class="consent-prompt"
		aria-label="Cookie consent"
	>
		<p>We use cookies for measurement and marketing.</p>
		<button type="button" @click="choose('none')">Reject all</button>
		<button type="button" @click="choose('all')">Accept all</button>
		<button type="button" @click="activeUI = 'manager'">Customize</button>
	</section>
	<section
		v-else-if="activeUI === 'manager'"
		class="consent-prompt"
		aria-label="Privacy settings"
	>
		<label v-for="category in displayedCategories" :key="category">
			<input
				v-model="values[category]"
				type="checkbox"
				:disabled="category === 'necessary'"
			/>
			{{ category }}
		</label>
		<button type="button" @click="savePreferences">Save</button>
	</section>
</template>
```

# Iab Opt In
URL: https://c15t.com/docs/shared/examples/vue/iab-opt-in

```ts title="src/main.ts"
import { c15tVue, hosted } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		// Turns IAB TCF on. The CMP ID and vendor list come from `/init`.
		iab: {},
		mode: hosted(),
	})
	.mount('#app');
```

# Iab Surfaces
URL: https://c15t.com/docs/shared/examples/vue/iab-surfaces

```vue title="src/IabSurfaces.vue"
<script setup lang="ts">
import { IABConsentBanner, IABConsentDialog } from 'c15t/vue/vue-plugin';
</script>

<template>
	<!-- Only for sites where every policy uses IAB TCF. ConsentRoot
	     switches between the IAB and standard surfaces for you. -->
	<IABConsentBanner />
	<IABConsentDialog initial-tab="purposes" />
</template>
```

# Language Switcher
URL: https://c15t.com/docs/shared/examples/vue/language-switcher

```vue title="src/LanguageSwitcher.vue"
<script setup lang="ts">
import { useConsentKernel, useConsentLanguage } from 'c15t/vue/vue-plugin';

const language = useConsentLanguage();
const kernel = useConsentKernel();

// Resolving again with `init()` loads the banner and dialog text in the
// new language.
const switchTo = (code: string) => {
	language.value = code;
	void kernel.commands.init();
};
</script>

<template>
	<button type="button" @click="switchTo('en')">English</button>
	<button type="button" @click="switchTo('de')">Deutsch</button>
</template>
```

# Main
URL: https://c15t.com/docs/shared/examples/vue/main

```ts title="src/main.ts"
import { posthog } from '@c15t/integrations/posthog';
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { createApp } from 'vue';

import App from './App.vue';

createApp(App)
	.use(c15tVue, {
		mode: manifest(),
		scripts: [
			posthog({
				id: 'phc_your_project_key',
				initOptions: { cookieless_mode: 'never' },
				loadMode: 'after-consent',
			}),
		],
	})
	.mount('#app');
```

# Network Blocker
URL: https://c15t.com/docs/shared/examples/vue/network-blocker

```ts title="src/network-blocker.ts"
import type { UseNetworkBlockerOptions } from 'c15t/vue/vue-plugin';

export const networkBlocker = {
	onRequestBlocked: (info) => {
		console.info('Blocked until consent', info.method, info.url);
	},
	rules: [
		{ category: 'measurement', domain: 'google-analytics.com' },
		{
			category: 'marketing',
			domain: 'facebook.com',
			methods: ['POST'],
			pathIncludes: '/tr',
		},
	],
} satisfies UseNetworkBlockerOptions;
```

# Privacy Settings
URL: https://c15t.com/docs/shared/examples/vue/privacy-settings

```vue title="src/PrivacySettings.vue"
<script setup lang="ts">
import { ConsentWidget } from 'c15t/vue/vue-plugin';
</script>

<template>
	<section aria-labelledby="privacy-settings-title">
		<h1 id="privacy-settings-title">Privacy settings</h1>
		<p>Choose which optional cookies this site may use.</p>
		<ConsentWidget />
	</section>
</template>
```

# Vite Config
URL: https://c15t.com/docs/shared/examples/vue/vite-config

```ts title="vite.config.ts"
import vue from '@vitejs/plugin-vue';
import { consentManifest } from 'c15t/vue/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [vue(), consentManifest()] });
```

# Iab Gpp
URL: https://c15t.com/docs/shared/iab-gpp
The policy rule c15t matched for the visitor decides whether a section applies. The visitor's location only picks which US section carries it.

## How the policy decides the section

The policy rule c15t matched for the visitor decides whether a section
applies. The visitor's location only picks which US section carries it.

|Matched rule and visitor|Section in the GPP string|
|--|--|
|`iab` rule, with IAB TCF set up|`tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged|
|`iab` rule, any visitor, with `tcf: false`|None; `applicableSections` is `[-1]`|
|Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section|That state's section, such as `usca` (ID 8)|
|The same rule, US visitor whose region is unknown or whose state has no section|`usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'`|
|The same rule, `usApproach: 'national'`|`usnat` for every US visitor|
|A rule without those rights, such as `none`|None|
|A visitor outside the US under any rule other than `iab`|None|

Every `opt-in` and `opt-out` rule has the `preferences` right, and every
`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
them. A rule that gives the visitor no way to opt out produces no US
section, even when the visitor sends a GPC signal.

State sections exist for California, Colorado, Connecticut, Delaware, Florida,
Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
Island are not encoded yet: their published specifications start the section
with a header that the IAB reference implementation does not encode. Visitors
there get the fallback, `usnat` by default. So does a US visitor whose region
the geo headers did not supply.

The MSPA US National specification describes `usnat` for MSPA signatories
that chose the national approach. Without `mspaMode`, c15t reports the
fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction: 2`), which still carries the opt-outs to vendors such as Prebid.js. If you
reserve `usnat` for the national approach, set `usFallback: 'none'`; those
visitors then get no section until their state resolves.

## What the US sections report

* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
  out) when the `marketing` category is not permitted, otherwise `2`. A
  refusal, a GPC signal the rule maps to `marketing` through
  `privacySignals.gpc`, and an opt-in rule without a grant all count.
* The opt-out notices: `1` (given), since the rule offers an opt-out.
* The sharing or processing notice: `1` when the rule has the `disclosure`
  right, otherwise `2`.
* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
  GPC subsection. It is reported even when the rule does not map GPC to a
  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
  should follow it too.
* Sensitive data and known-child consents: `0` (not applicable). c15t has no
  category for them, so the string states that you do not process sensitive
  data or knowingly process children's data. If you do, GPP from c15t does
  not describe your processing; collect and signal that consent separately.
* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.

The notice fields are your attestation, made through the rule's rights:
c15t cannot see whether your privacy notice is on the page. Show the notices
the rule promises, including a persistent opt-out control.

## GPP options

Every field is optional. Pass them in the `gpp` option, where `gpp: true`
uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
`@c15t/browser`.

|Option|Default|Effect|
|--|--|--|
|`cmpId`|the IAB CMP ID c15t holds, else `1`|CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.|
|`usApproach`|`'state'`|`'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.|
|`usFallback`|`'usnat'`|Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.|
|`mspaMode`|unset|`'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable.|
|`optOutCategories`|`['marketing']`|Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.|
|`tcf`|`true`|Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.|

## Check the signal

Open the browser console on a page with GPP on and call:

```js
__gpp('ping', (data) => console.log(data));
```

For a California visitor who has not opted out, the result includes
`applicableSections: [8]`, `signalStatus: 'ready'` and
`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
returns the same value. Scripts in iframes reach the API through the
`__gppLocator` frame and `postMessage`.

Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
as the IAB reference implementation does: TCF vendors read consent from
events, not on demand.

`signalStatus` stays `'not ready'` while the policy is pending, while the
banner or dialog is open, while an `iab` rule has no confirmed TC String,
and while a new TC String is decoded. Listeners added with
`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
and `sectionChange` events, then `signalStatus: 'ready'`.

## Ad tags that load before c15t

c15t installs `__gpp` in the browser once consent starts, after it loads the
GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
the calls and listeners a stub queued, whether the stub keeps listeners on
`__gpp.events`, as the GPP specification's sample does, or returns them from
`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
When another stub already answers iframes, c15t leaves that to it, so each
iframe call gets one reply.

If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
The `gpp` option reports the conflict to the `onError` callback,
`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
CMP per page.

GPP signals what the visitor chose; it does not block scripts. Gate vendor
scripts with c15t's script loading as well.

# Iab Publisher Restrictions
URL: https://c15t.com/docs/shared/iab-publisher-restrictions
Each restriction type has a requirement that depends on the vendor list:

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

# Iab Tcf 2 4
URL: https://c15t.com/docs/shared/iab-tcf-2-4
The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their locked section with a lock icon, because the visitor cannot object to them.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

# Embed content by framework
URL: https://c15t.com/docs/shared/integrations/consent-embed
Mount remote iframe content only while the configured category is allowed.

## Add the embed to your framework

Create `src/embed-config.ts` using the configuration on this page, then select
your framework. Keep the existing [consent setup](/docs/frameworks), its policy
and preferences UI. These examples do not create a second consent provider.

**Next.js**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
'use client';

import { ConsentGate } from 'c15t/next';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**TanStack Start**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/tanstack-start';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**React**

Render this component inside your existing consent boundary or provider.

```tsx title="src/consent-embed.tsx"
import { ConsentGate } from 'c15t/react';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';

export function ConsentEmbed() {
  return (
    <ConsentGate category={embedCategory}>
      <iframe
        src={embedURL}
        title={embedTitle}
        loading="lazy"
        allowFullScreen
        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
      />
    </ConsentGate>
  );
}
```

`ConsentGate` keeps the iframe absent while permission is denied and removes it
on revocation. Keep your existing consent styles and preferences dialog.

**Nuxt**

The Nuxt module registers `ConsentGate` and `ConsentDialogLink`, so
this component imports only the embed configuration.

```vue title="app/components/ConsentEmbed.vue"
<script setup lang="ts">
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the server HTML and the DOM while
permission is denied, and removes it on revocation. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Render this component inside the app that installed the c15t Vue plugin.

```vue title="src/ConsentEmbed.vue"
<script setup lang="ts">
import { ConsentDialogLink, ConsentGate } from 'c15t/vue/vue-plugin';
import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<template>
  <ConsentGate :category="embedCategory">
    <iframe
      :src="embedURL"
      :title="embedTitle"
      loading="lazy"
      allowfullscreen
      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
    />
    <template #placeholder>
      <p>Allow {{ embedCategory }} to load this content.</p>
      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
    </template>
  </ConsentGate>
</template>
```

`ConsentGate` keeps the iframe out of the DOM while permission is denied,
and removes it on revocation. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Use the shared browser helper below with Astro's existing page runtime.
Add this component to pages using your consent-enabled base layout:

```astro title="src/components/ConsentEmbed.astro"
<c15t-consent-embed style="display: block"></c15t-consent-embed>

<script>
  import { getConsentClient } from 'c15t/astro/client';
  import { mountConsentEmbed } from '../consent-embed';

  class ConsentEmbed extends HTMLElement {
    dispose?: () => void;

    connect = () => {
      if (this.dispose) return;
      const client = getConsentClient();
      if (!client) return;
      this.dispose = mountConsentEmbed(
        this,
        client.runtime.kernel,
        () => { void client.openDialog(); },
      );
    };

    connectedCallback() {
      document.addEventListener('DOMContentLoaded', this.connect, { once: true });
      this.connect();
    }

    disconnectedCallback() {
      document.removeEventListener('DOMContentLoaded', this.connect);
      this.dispose?.();
      this.dispose = undefined;
    }
  }

  if (!customElements.get('c15t-consent-embed')) {
    customElements.define('c15t-consent-embed', ConsentEmbed);
  }
</script>
```

The first mount waits for the page's module scripts, including c15t's boot
script. Later `ClientRouter` mounts reuse the existing runtime. Removing the
component unsubscribes and removes the iframe. Do not create another consent
runtime for this embed.

**Svelte**

Render this component inside the existing `ConsentProvider`.
The provider from your quickstart supplies its consent state.

```svelte title="src/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**SvelteKit**

Render this component inside the existing `ConsentRoot`.
Keep the SvelteKit root and its server-resolved state unchanged.

```svelte title="src/lib/ConsentEmbed.svelte"
<script lang="ts">
  import { ConsentGate } from '@c15t/svelte';
  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
</script>

<ConsentGate category={embedCategory}>
  <iframe
    src={embedURL}
    title={embedTitle}
    loading="lazy"
    allowfullscreen
    style:width="100%"
    style:aspect-ratio={embedAspectRatio}
    style:min-height="200px"
    style:border="0"
  ></iframe>
</ConsentGate>
```

The Svelte `ConsentGate` waits until the browser is mounted and the category is
allowed. Its default placeholder opens preferences. Revocation removes the
iframe.

**HTML**

The c15t script tag gates iframes that name a category. Put the embed's URL
in `data-src` instead of `src`, using the values from the configuration on
this page:

```html
<iframe
  data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1"
  data-category="measurement"
  title="Product video"
  loading="lazy"
  allowfullscreen
></iframe>
```

c15t sets `src` once the category is allowed and removes it on revocation.
Without `src` the iframe loads nothing, so hide it with CSS and show a link
to `#c15t-preferences` in its place. See
[HTML embeds](/docs/frameworks/html/embeds).

**JavaScript**

Use the shared browser helper below with your existing client. Put an
empty container where the embed should appear:

```html
<div id="consent-embed"></div>
```

In your browser entry point, after `init()`:

```ts
import { mountConsentEmbed } from './consent-embed';

const container = document.querySelector<HTMLElement>('#consent-embed');
if (!container) throw new Error('Missing consent embed container');

const disposeEmbed = mountConsentEmbed(container, consent.kernel, () =>
  consent.openDialog(),
);
```

`consent` is the client from `init()` in your quickstart. With
`createConsentRuntime`, pass `runtime.kernel` and your own function that
opens preferences. Call `disposeEmbed()` when the page or component is
destroyed. Iframe markup with `data-src` and `data-category` also works
without the helper, because both setups gate iframes by default.

## Browser helper for Astro and JavaScript

Only the Astro and JavaScript examples need this helper. It creates the iframe
when permission allows it, keeps an existing player mounted across unrelated
snapshot updates, and removes it on revocation.

```ts title="src/consent-embed.ts"
import {
	embedCategory,
	embedURL,
	embedTitle,
	embedAspectRatio,
} from './embed-config';

type EmbedKernel = {
	getSnapshot: () => {
		effectivePermissions: Record<typeof embedCategory, boolean>;
	};
	subscribe: (listener: () => void) => () => void;
};

export function mountConsentEmbed(
	container: HTMLElement,
	kernel: EmbedKernel,
	openPreferences: () => void
) {
	const render = () => {
		if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
			if (container.querySelector('iframe')) return;
			const frame = document.createElement('iframe');
			frame.src = embedURL;
			frame.title = embedTitle;
			frame.loading = 'lazy';
			frame.allowFullscreen = true;
			Object.assign(frame.style, {
				width: '100%',
				aspectRatio: embedAspectRatio,
				minHeight: '200px',
				border: '0',
			});
			container.replaceChildren(frame);
		} else {
			if (container.querySelector('button')) return;
			const button = document.createElement('button');
			button.type = 'button';
			button.textContent = 'Open privacy settings to view this content';
			button.onclick = openPreferences;
			container.replaceChildren(button);
		}
	};

	render();
	const unsubscribe = kernel.subscribe(render);
	return () => {
		unsubscribe();
		container.replaceChildren();
	};
}
```

Keep a transcript, address or other useful alternative outside the embed.
`loading="lazy"` is a performance hint; the consent condition controls whether
the iframe exists at all. A denied category may be fixed by policy, so opening
preferences does not guarantee that the visitor can grant it.

## Gate existing iframe markup

For markup that uses `data-category` and `data-src`, the
`createIframeBlocker` module from `c15t/modules/iframe-blocker` promotes
`data-src` only when the category has consent and the URL resolves to HTTP or
HTTPS. Relative URLs resolve against the iframe document's base URL.
Malformed URLs and other schemes, including `javascript:`, `data:` and `blob:`,
remain in `data-src` without loading. Correct the URL and call
`processAllIframes()` to retry.

Keep the initial URL in `data-src`, without `src`, so the browser cannot load
it before the blocker runs. The module does not sanitize arbitrary HTML or
modify iframes without `data-category`.

# Google Consent Mode in c15t helpers
URL: https://c15t.com/docs/shared/integrations/google-consent-mode
When the Google helpers load, what they send before a choice, and how c15t categories map to Google consent types.

## Google loads before a choice by default

With the default `loadMode: 'always'`, the `googleTagManager` and `gtag`
helpers set `alwaysLoad: true`. Before the visitor chooses, the helper creates
the `dataLayer` queue, sends `gtag('consent', 'default', ...)` with the current
permissions and loads Google's script. After each permission change it sends
`gtag('consent', 'update', ...)`. Google's tags then adjust what they store and
send; see Google's
[Consent Mode overview](https://developers.google.com/tag-platform/security/concepts/consent-mode).

So the browser contacts Google before consent. If your policy requires no
Google request until the visitor allows it, set `loadMode: 'after-consent'`.
The helper then creates nothing and requests nothing until its category is
allowed. When it loads, it sends the `default` command first, with the
permissions at that moment, and `update` commands after later changes. Under
an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

## How categories map to Google consent types

|c15t category|Google consent types|
|--|--|
|`necessary`|`security_storage`|
|`functionality`|`functionality_storage`|
|`measurement`|`analytics_storage`|
|`marketing`|`ad_storage`, `ad_user_data`, `ad_personalization`|
|`experience`|`personalization_storage`|

Each Google type is `granted` when its category is allowed and `denied`
otherwise. If a visitor turns off the helper's vendor, every optional type is
sent as `denied`. The `consentMapping` option replaces the whole table, so
include every category you still want signalled.

Under an opt-out policy, the default command can grant types before the
visitor has chosen anything. That is a permission, not a recorded choice.

# Register vendor scripts
URL: https://c15t.com/docs/shared/integrations/register-scripts
Add a vendor script configuration to the c15t provider you already have, in each framework.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

# Check a consent-gated vendor helper
URL: https://c15t.com/docs/shared/integrations/vendor-revocation-and-verify
The shared browser test and revocation behavior for vendor helpers that wait for consent.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.

# Next.js consent and scripts
URL: https://c15t.com/docs/shared/next-consent-wrapper
Register scripts in the Next.js c15t.config.ts used by the router guides.

## Register scripts in c15t.config.ts

The [runnable Next.js example](/docs/examples) loads PostHog under the
measurement category. Replace the placeholder `phc_your_project_key` with your
project key, or replace the helper with the
[integration](/docs/integrations/overview) your application uses. Include the
measurement category in your policy.

Put the scripts in `c15t.config.ts`, next to `next.config.ts`:

```ts title="c15t.config.ts"
import { posthog } from '@c15t/integrations/posthog';
import { defineConsentConfig } from 'c15t/next';

export default defineConsentConfig({
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});
```

PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
cookieless capture after rejection. Remove any existing PostHog loader,
including `next/script` and tag-manager entries, so the integration loads once.

`withConsentManifest` in `next.config.ts` finds the file, and `ConsentRoot`
reads its `scripts` in the browser, so a Server Component layout renders
`ConsentRoot` without passing them. The file is bundled into the browser as
well as the server, so it must hold no secrets.

`scripts`, `vendors`, `clearOnRevocation`, `networkBlocker`, `persistence`,
`scriptLoader` and `options` can also be passed to `ConsentRoot` as props,
which win over the config. Functions can't cross from a Server Component to a
Client Component, so pass them as props only from a `'use client'` file.

# ConsentBanner
URL: https://c15t.com/docs/shared/react/components/consent-banner
Shared ConsentBanner reference tables for the React and Next.js adapters.

|Prop|Type|Default|Description|
|--|--|--|--|
|`title`|`ReactNode`|translation|Overrides the title. Under a notice the default is `cookieBanner.noticeTitle`.|
|`description`|`ReactNode`|translation|Overrides the description. Under a notice the default is `cookieBanner.noticeDescription`.|
|`acceptButtonText`|`ReactNode`|`common.acceptAll`|Accept label.|
|`rejectButtonText`|`ReactNode`|`common.rejectAll`|Reject label.|
|`customizeButtonText`|`ReactNode`|`common.customize`|Customize label.|
|`dismissButtonText`|`ReactNode`|`common.acknowledge`|Label of the notice acknowledgement.|
|`variant`|`PromptVariant`|`floating`|Shape of the prompt. See [Variants](#variants).|
|`position`|`PromptPosition`|per variant|Where the prompt sits. Must be valid for the variant.|
|`blocking`|`boolean`|`true` on `wall`|Backdrop, scroll lock, focus trap, and no outside dismissal, as one value.|
|`layout`|`ConsentBannerLayout`|policy default|Orders and groups actions. Required actions the layout omits are restored.|
|`primaryButton`|`ConsentBannerButton \|ConsentBannerButton[]`|`'customize'`|Which actions get the primary treatment. On a notice, dismiss is primary when it is the only action.|
|`direction`|`'row' \|'column'`|`'row'`|How action groups flow.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which configured legal links render inline.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`scrollLock`|`boolean`|unset|Deprecated. Use `blocking` to control scrolling, focus and backdrop together.|
|`trapFocus`|`boolean`|unset|Deprecated. Use `blocking`.|
|`disableAnimation`|`boolean`|`false`|Skips enter and exit animations.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

# ConsentDialog
URL: https://c15t.com/docs/shared/react/components/consent-dialog
Shared ConsentDialog reference for the React and Next.js adapters.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`open`|`boolean`|follows the active surface|Controls the open state. When set, Escape and the dialog's own Save Settings, Accept All and Reject All buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed.|
|`showTrigger`|`boolean \|ConsentDialogTriggerProps`|`false`|Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'none']`|Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.|
|`legalLinks`|`(keyof LegalLinks)[] \|null`|none|Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag in the card.|
|`uiSource`|`string`|`'dialog'`|Source identifier recorded with saves made from this dialog.|
|`scrollLock`, `trapFocus`|`boolean`|from `blocking`|Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.|
|`disableAnimation`|`boolean`|`false`|Skips the enter and exit animation of the backdrop and the card.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The dialog is a modal wrapper around the preference center. Its card has a
header with the title `consentManagerDialog.title` and the description
`consentManagerDialog.description` followed by the legal links, then the
same category accordion and Reject All, Accept All and Save Settings actions that
`ConsentWidget` renders, then the branding tag. It mounts through a portal
into `document.body` after hydration, so it is never part of the server
HTML.

Without an `open` prop, the dialog follows the active surface and opens while
it is `dialog`. These set that surface:

* The Customize button on a `ConsentBanner`, and the "Manage preferences"
  or "Do not sell or share my data" button a notice renders.
* `ConsentDialogLink` and `ConsentDialogTrigger`.
* The button in a `ConsentGate` placeholder.
* `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
  from `useHeadlessConsentUI()` on the headless subpath.

The component code is split into its own chunk, so it is not part of the
first page load. It renders nothing until that chunk is ready, and the
chunk downloads at the first of these:

* The browser's first idle period after the page's `load` event, while the
  banner is shown or a `ConsentDialogLink`, `ConsentDialogTrigger`,
  `ConsentGate` button or other button that opens the dialog is mounted.
  This covers a visitor who taps or presses Enter with no hover or focus
  first. Browsers without `requestIdleCallback`, such as Safari, wait
  200 ms after `load` instead.
* Hover or focus on a button that opens the dialog.
* The dialog opening.

Passing `open={true}` or `showTrigger` loads it on mount. A visit with
saved consent and nothing on the page that opens the dialog never
downloads it.

Idle loading is skipped when the visitor has Save-Data on
(`navigator.connection.saveData`), on a `2g` or `slow-2g` connection, and
while offline; hover and focus still load it. To load the chunk only on
hover, focus or open, set `preloadDialog: 'intent'` in the provider
options. The default is `'idle'`. With Next.js, pass it through
`ConsentRoot`'s `options` prop.

If a preload fails, for example because the visitor is offline, nothing is
cached: the next hover, focus or open tries the download again.

The dialog's CSS travels in the same chunk and is applied before the dialog
renders, so the first page load carries only the banner's rules.

Without an `open` prop, Escape closes the dialog without saving. If the
policy still owes a choice, the banner comes back. Save Settings, Accept All and
Reject All close it as soon as the choice is recorded in the browser, in
the same task as the click; the exit animation still plays. The request to
the backend runs afterwards and never reopens the dialog: a failed request
keeps the choice, reports through `onError` and is retried later. See
[when a choice is saved](/docs/concepts/consent-state#when-a-choice-is-saved)
for the order of events. A draft that went stale because the policy changed keeps the dialog open
for review. With `open={true}`, these actions leave the dialog visible; the
parent must set `open={false}` to close it. Clicking the backdrop does not
close it. Closing discards toggles that were not saved: the next open starts
from the recorded choice again. After a save from an uncontrolled dialog,
every consent surface hides unless the policy still owes a prompt, in which
case the banner returns.

The preference center is blocking by default: a backdrop, body scroll lock
and focus trap, all as one value. Set `presentation.preferences.blocking`
to `false` in the provider options to remove all three; the deprecated
`scrollLock` and `trapFocus` props do the same for one dialog. `variant`
and `position` are prompt options. Setting them under
`presentation.preferences` logs an `invalid-variant` diagnostic in
development and changes nothing; the dialog is always centered.

The dialog never opens without a resolved policy rule, even when the
active surface is already `dialog`; it appears as soon as a rule resolves,
without a remount. A rule with `model: 'none'` and no rights owes no consent
UI, so the dialog stays closed under it. When such a rule lists any right,
for example `rights: ['disclosure']` or `rights: ['preferences']`, the dialog
can open as a settings route and Save completes without writing a consent
record.

Copy comes from these translation keys: `consentManagerDialog.title`,
`consentManagerDialog.description`, `common.acceptAll`, `common.rejectAll`,
`common.save`, and `consentTypes.<category>.title` and `.description` for
each row.

## Accessibility

The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
while it is blocking. Its `dir` attribute follows the active language.

While blocking, focus moves on open to the first tabbable control in the
panel, so a keyboard user sees the focus ring on a control rather than
around the whole panel; the `aria-labelledby` and `aria-describedby`
wiring means a screen reader still announces the title and description as
focus enters. Tab and Shift+Tab wrap inside the panel, and on close focus
returns to the element that opened the dialog. A non-blocking dialog manages no focus: nothing moves focus into the
panel or back to the opener. The backdrop is `aria-hidden` and is not
focusable.

Each category switch has the category title as its accessible name. The
`necessary` switch is disabled and always on. A saved grant that the current
policy or a privacy signal overrides gets a note under its row, linked to
the switch through `aria-describedby`.

## Composition

Every part is available as `ConsentDialog.<Part>`: `Root`, `Overlay`,
`Card`, `Header`, `HeaderTitle`, `HeaderDescription`, `Content`, `Footer`
and `ConsentCustomizationCard`, the stock card. `Root` provides the portal,
open state, focus trap, scroll lock and backdrop, and accepts `open`,
`models`, `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`,
`uiSource` and `overlay`. Pass `overlay={false}` to render no backdrop, or a
node to replace the built-in one.

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription legalLinks={['privacyPolicy']} />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Keep `ConsentWidget` inside `Content`: it owns the draft, the switches and
the policy actions, and inherits the dialog's `uiSource`. `Footer` renders
the branding tag unless you pass children or `hideBranding`.

The positioner carries `data-slot="dialog-positioner"`, and both it and the
panel carry `data-blocking="true"` while blocking. Provider component slots
for the stock structure are `dialog.root`, `dialog.container`,
`dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
`dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.

`ConsentDialog` from the package root and from the
`c15t/react/consent-dialog` subpath is the deferred component described
under Behavior, and each `ConsentDialog.<Part>` loads with the same chunk.
`c15t/react/components/consent-dialog` exports the dialog without the
deferral, plus each part as a named export (`Card`, `Header`, `Overlay`,
`Root` and the rest). Importing from that path puts the dialog's code in
the bundle of every page that imports it, so the first open needs no
download but every visitor downloads the dialog.

## Verify

Use the default blocking, uncontrolled dialog and an optional in-scope
category that is not restricted by policy or privacy signals such as GPC.
Open the dialog from the banner's Customize button or a preferences link.
A centered card appears over a dimmed backdrop, the page behind it stops
scrolling, and Tab stays inside the card. Press Escape: the card closes and
focus returns to the button you used. Open it again, turn a category on and
choose Save. The dialog closes and `useConsent('<category>')` reports
`true` in your components; under a choice prompt the banner does not return,
while a `notice` prompt keeps its banner until it is acknowledged. Reload the
page and reopen the dialog: the switch reflects the saved choice.

# ConsentDialogLink
URL: https://c15t.com/docs/shared/react/components/consent-dialog-link
Shared ConsentDialogLink reference for the React and Next.js adapters.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`children`|`ReactNode`|required|The visible label, such as "Privacy settings" or "Manage preferences". It is also the accessible name.|
|`asChild`|`boolean`|`false`|Renders your own element, such as an anchor, instead of a `button`, and attaches the click handler to it.|
|`noStyle`|`boolean`|`true`|Omits c15t button classes. Native browser styles remain unless your CSS resets them. Pass `false` to render it as a consent button with `variant` and `mode`.|
|`onClick`|`(event) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to keep it closed.|

Other `button` attributes such as `className`, `style`, `id` and `aria-*`
pass through to the rendered element.

## Behavior

`ConsentDialogLink` renders a `button` with `type="button"` and no c15t
styling by default. Clicking it makes `dialog` the active surface, which opens a
mounted `ConsentDialog`. It performs no save and does not change any
permission.

The element carries `data-c15t-rights` listing the rights of the active
policy rule, for example `disclosure opt-out preferences` under a US
opt-out rule and `disclosure preferences` under an opt-in rule, so a
stylesheet or a `::after` label can adapt the wording by region.

Without a resolved policy rule the link renders nothing and appears as soon
as a rule resolves, without a remount. A rule with `model: 'none'` and an
empty `rights` list owes no consent UI, so the link hides under it; a `none`
rule that lists any right, such as `['disclosure']`, shows the link and the
dialog opens as a settings route.

Mount exactly one `ConsentDialog` inside the same provider. If none is
mounted, the click still switches the active surface: nothing opens, and a
banner that was showing closes because the surface is no longer `banner`.

With `asChild`, the child's own `onClick` runs first; if it calls
`event.preventDefault()` the dialog stays closed. c15t does not prevent the
child's native behavior, so an anchor still follows its `href`. Use a
fragment or the current page as the destination, or render a `button`.

### ConsentDialogLink or ConsentDialogTrigger

Both open the same dialog and carry `data-c15t-rights`. Use
`ConsentDialogLink` where the control belongs in your own layout: a footer,
a privacy page, a settings menu. It has no position, icon or visibility
rule of its own. Use `ConsentDialogTrigger` when you want a floating,
draggable button that positions itself in a corner and can wait until the
prompt is answered.

## Accessibility

The rendered `button` is keyboard-focusable and activates with Enter and
Space; its accessible name is the text you pass as `children`, so give it
words that describe the destination rather than "click here". Because the
dialog it opens is labelled by its own title and, while blocking, returns
focus to the link on close, no additional `aria-haspopup` or
`aria-controls` is added; a non-blocking dialog manages no focus, so the
link does not regain it. With `asChild`,
focusability comes from your element: use a `button` or an anchor with an
`href`.

## Verify

Scroll to the footer. With the footer button reset applied, the link uses
your footer's text styles and has no button chrome. Activate it with a click or with Enter: the preference
center opens as a centered dialog. Close it with Escape: with the default
blocking dialog, focus returns to the link. In your browser's element
inspector the link has
`data-c15t-rights`; change the visitor's region to a US opt-out rule and
the value includes `opt-out`. Under a rule with `model: 'none'` and no
rights, the link is absent.

# ConsentDialogTrigger
URL: https://c15t.com/docs/shared/react/components/consent-dialog-trigger
Shared ConsentDialogTrigger reference tables for the React and Next.js adapters.

|Prop|Type|Default|Description|
|--|--|--|--|
|`icon`|`'branding' \|'fingerprint' \|'settings' \|ReactNode`|`'branding'`|Icon rendered inside the button.|
|`defaultPosition`|`'bottom-left' \|'bottom-right' \|'top-left' \|'top-right'`|`'bottom-right'`|Corner the button starts in.|
|`persistPosition`|`boolean`|`true`|Remember the corner the visitor dragged it to.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the button is visible. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

|Prop|Type|Default|Description|
|--|--|--|--|
|`actions`|`ConsentDialogTriggerToolbarAction[]`|`[]`|App-owned actions rendered beside the preferences action.|
|`preferences`|`ConsentDialogTriggerToolbarPreferences`|`{}`|Overrides for the built-in action: `icon`, `label`, `onSelect`, `className`, `style`. The label defaults to the opt-out or preferences right on the active rule.|
|`orientation`|`'horizontal' \|'vertical'`|`'horizontal'`|Layout direction.|
|`defaultPosition`|`CornerPosition`|`'bottom-right'`|Corner the toolbar starts in.|
|`persistPosition`|`boolean`|`true`|Remember the dragged corner.|
|`showWhen`|`'always' \|'after-prompt' \|'never'`|`'always'`|When the built-in preferences action is visible. App-owned actions always render. `after-prompt` waits until no choice or notice is owed.|
|`size`|`'sm' \|'md' \|'lg'`|`'md'`|Size of each action.|
|`ariaLabel`|`string`|`'Privacy controls'`|Accessible name for the toolbar group.|
|`noStyle`|`boolean`|`false`|Remove the default styling.|

While `<ConsentDevTools>` is mounted, the toolbar adds a DevTools button at
the end farthest from its corner and opens the DevTools panel beside itself.
The ready-made `ConsentDialogTrigger` switches to this toolbar layout for as
long as DevTools is mounted.

# ConsentGate
URL: https://c15t.com/docs/shared/react/components/consent-gate
Shared ConsentGate reference for the React and Next.js adapters.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The consent category whose effective permission gates the children, for example `'marketing'` or `'functionality'`.|
|`children`|`ReactNode`|required|The embed. It is not mounted until the category is allowed, so it makes no requests before permission.|
|`placeholder`|`ReactNode`|built-in placeholder|Replaces the built-in title and button while the category is not allowed. Falsy values such as `null`, `false`, `0` and an empty string use the built-in placeholder. Pass an empty fragment, `<></>`, to render no placeholder content.|

Other `div` attributes such as `className`, `style` and `ref` apply to the
wrapper element that stays in the page in both states. `ConsentGateProps` also
declares `noStyle` and `theme`, but the component does not apply them yet;
style the wrapper with `className`, and style the built-in placeholder
through its parts in the provider options.

## Behavior

`ConsentGate` renders a `div` wrapper. Inside it, when the effective permission for
`category` is granted, it renders the children; otherwise it renders the
placeholder. Permission is the same value `useConsent(category)` returns,
so it can be granted under an opt-out rule before the visitor records a
choice, and a recorded grant can be overridden by a privacy signal.

While effective permission is denied, the children are absent from the DOM,
so an iframe or a third-party widget inside `ConsentGate` sends no requests. When the visitor later revokes it, the
children unmount and the embed disappears. `ConsentGate` does not depend on the
network blocker or the iframe blocker modules; use those for markup you
cannot wrap in a component.

The built-in placeholder shows the title `consentGate.title`,
`Accept {category} consent to view this content.`, with `{category}`
replaced by `consentTypes.<category>.title`, and a button labelled
`consentGate.actionButton`, `Enable {category} consent`. The button opens the
preference center; it
does not grant the category by itself, because the visitor still has to
save. Mount a `ConsentDialog` in the same provider so the button has
something to open.

Under a policy with `scopeMode: 'strict'`, a category outside the rule's
scope cannot be granted. The built-in placeholder then shows `consentGate.policyBlocked`,
"This content is unavailable under your region's consent policy.", without
the button, and a stored grant for that category stays blocked.

When the provider starts from a snapshot prefetched on the server, the
server renders the placeholder for a denied category. For a granted
category it renders the empty wrapper, and the children mount once
hydration completes, so an iframe loads once even when the page streams
inside a `Suspense` boundary. A grant in the request cookie allows the
embed only when policy and privacy signals permit it. Browser privacy signals detected during hydration can
withdraw that permission. In a browser-only setup the
provider has no permission until it resolves policy on the client, so
`ConsentGate` shows the placeholder first and swaps in the embed after resolution
when the category is already granted.

`ConsentGate` is one component on this page; the per-vendor embed guides for
[YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) show a complete embed
configuration with sizing, titles and the same `ConsentGate` usage across
frameworks.

## Composition

The placeholder parts are available as `ConsentGate.Root`, `ConsentGate.Title` and
`ConsentGate.Button` for a custom placeholder that keeps the built-in copy and
behavior. `ConsentGate.Title` and `ConsentGate.Button` accept `category` and fill in the
translated text; pass children to either to replace it.

```tsx
<ConsentGate
  category="marketing"
  placeholder={
    <ConsentGate.Root>
      <ConsentGate.Title category="marketing" />
      <p>The video is also available on our channel.</p>
      <ConsentGate.Button category="marketing">Choose cookies</ConsentGate.Button>
    </ConsentGate.Root>
  }
>
  <iframe src="https://www.youtube-nocookie.com/embed/..." title="Product tour" />
</ConsentGate>
```

To restyle the built-in placeholder without replacing it, set its parts
under `components['consent-gate']` in the provider options. `root` is the
card, and `title` and `button` are its text and button. The `consentGate`, `consentGateTitle` and
`consentGateButton` theme slots reach the same parts. The button part
applies on top of `button.primary`.

```tsx
components: {
  'consent-gate': {
    root: { className: 'rounded-none' },
    button: { className: 'font-semibold' },
  },
},
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

## Accessibility

The placeholder is plain text and a `button`, so it is readable and
operable without the embed. Give the iframe a descriptive `title`, and keep a
transcript, address or link outside the `ConsentGate` for visitors who decline
the category. A denied category may be fixed by policy, so opening the
preference center does not guarantee that the visitor can grant it.

## Verify

Use an optional in-scope category that is available in the preference
center and is not restricted by policy or privacy signals such as GPC.
Load the page with the category denied. The placeholder text names the
category and the network panel shows no request to the embed's host. With a
prefetched snapshot, the server HTML contains the placeholder for a denied
category and neither placeholder nor embed for a granted category; the
embed appears after hydration and the network panel shows one request for
its document. Browser-only initialization
shows the placeholder before policy resolves, then replaces it with the
embed if the category is granted. After policy resolves, activate the
placeholder button: the preference center opens. Turn the category on and
Save: the placeholder is replaced by the embed and its requests start. Reject the
category again from the preference center: the embed disappears.

# ConsentWidget
URL: https://c15t.com/docs/shared/react/components/consent-widget
Shared ConsentWidget reference for the React and Next.js adapters.

## Props

|Prop|Type|Default|Description|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|A standalone widget hides the "Secured by" tag. Pass `false` to show it.|
|`uiSource`|`string`|`'widget'`|Source identifier recorded with saves made from this widget. Inside `ConsentDialog` it inherits `'dialog'`.|
|`disableAnimation`|`boolean`|`false`|Skips animations in the widget's parts.|
|`noStyle`|`boolean`|`false`|Removes the built-in styling from every part.|

## Behavior

The widget is the preference center without the modal around it: an
accordion with one row per category, each with a switch, followed by the
Reject All, Accept All and Save Settings actions. `ConsentDialog` renders this same
widget inside its card. Standalone, the widget renders in place, takes part
in server rendering, and does not touch the active surface, so it suits a
privacy page or an account settings screen.

The rows are `necessary` plus the categories in the active policy's scope,
narrowed to the categories the provider declares: `options.consentCategories`
and the categories of its scripts, network rules, vendors and discovered
frames. When nothing is declared, a permissive policy shows only `necessary`
and a strict one its whole scope.
The `necessary` switch is on and disabled. Row titles and descriptions come
from `consentTypes.<category>.title` and `.description`; the action labels
from `common.rejectAll`, `common.acceptAll` and `common.save`. One row is
expanded at a time.

### Draft and save

Switches edit a draft, not the visitor's permissions. Nothing is recorded
until Save. The draft seeds each category from the recorded choice; without
one it uses `presentation.preferences.defaults` from the provider options,
and without that it is on under an opt-out rule and on only for the rule's
preselected categories under an opt-in rule. Save records the displayed
categories, then reseeds the draft from the new record. Accept All and
Reject All record immediately without a separate Save. A save answers a
choice prompt, so an open choice banner closes; it does not dismiss a
`notice` prompt, which keeps its own acknowledgement record. Unsaved toggles
are lost when the widget unmounts.

When the policy changes in a way that affects the choice while the draft has
unsaved toggles, the widget shows an alert, "The privacy policy changed.
Review the current choices before saving.", with a Review choices button
that resets the draft. Save is refused until then. A draft without unsaved
toggles reseeds silently.

A saved grant that the current policy or a privacy signal such as Global
Privacy Control overrides shows a note under its row: "Your saved choice is
restricted by the current privacy settings." The switch still reflects the
saved value; the effective permission is off.

### Vendors

When the provider declares `vendors`, each category's expanded description
ends with one card per vendor whose category condition names that category,
styled like a category row: the vendor's name and a switch on the header,
and its description and privacy policy link behind the card's own expand
control. Cards start collapsed, so a long list stays one line per vendor,
and the category list scrolls inside the dialog rather than growing it.
A collapsed category or card renders its content element empty and mounts
the content the first time it opens, then keeps it mounted, so a long
vendor list costs nothing until a visitor expands its category.
Vendor switches edit the same draft as the category
switches and record on Save. Saving with one vendor off denies that vendor
only; the category stays granted and its other vendors keep loading. While
the category is off in the draft the vendor switches are disabled, with the
hint "Turn on this category to choose vendors." A vendor declared
`disabled`, or one that only falls under `necessary`, is listed without a
switch. Accept All and Reject All clear every vendor denial, including one
staged but not yet saved. Under an `iab` policy no vendor rows render.
Vendors that are only referenced by a script slug, without a name and
privacy policy URL, still gate loading but are not listed, and so does a
vendor whose condition negates a category, since no category row can
host it. See
[vendor consent](../vendor-consent).

### Actions

The preference center always renders Reject All, Accept All and Save Settings, with
Save Settings as the primary action. `presentation.preferences.layout`,
`primaryActions`, `direction` and `uiProfile` in the provider options
reorder and restyle them; a layout that omits one of the three has it
restored. Customize and dismiss actions never render here.

### When consent is not owed

Without a resolved policy rule the widget renders nothing and appears as
soon as a rule resolves, without a remount. A rule with `model: 'none'` and
an empty `rights` list renders nothing; a `none` rule that lists any right,
such as `['disclosure']`, renders the widget and Save completes without
writing a consent record.

For a fully custom preference center, `useConsentDraft()` returns the same
draft: `values`, `displayedCategories`, `vendors`, `isDirty`, `isStale`,
`set`, `update`, `setVendor`, `acceptAll`, `rejectAll`, `save` and `reset`.
A custom vendor control alone takes `useVendorDraft()`, the vendor slice of
that draft: `vendors`, `setVendor`, `isDirty`, `isStale`, `save` and `reset`.
`useDeclaredVendors()`, `useVendorChoice()` and `useVendorAllowed(id)` read
the declared list, the recorded denials and one vendor's effective result.

## Accessibility

Each row is a disclosure: a button that expands the category description
and a switch beside it, so a visitor can read the description without
changing the choice. Each switch has the category title as its accessible
name. A category's vendor cards sit in a `region` named "Vendors" with the
count; each card's expand button carries `aria-expanded`, each vendor
switch is named "Allow" followed by the vendor name, and is described by
the vendor's name element. The policy-change alert uses `role="alert"`, and a restriction note is
an `output` element linked to its switch through `aria-describedby`. The
root's `dir` attribute follows the active language.

## Composition

Every part is available as `ConsentWidget.<Part>`. `Root` provides the
draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
and `AccordionItems` render the stock rows; `AccordionItem`,
`AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
`AccordionArrow` and `Switch` build your own; `VendorList` renders one
category's vendor rows and takes a `category` prop. `PolicyActions` renders the
resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
`CustomizeButton` are the individual buttons.

`Accordion` is controlled: pass `value` and `onValueChange`, or no
category description ever opens. The stock `ConsentWidget` holds that state
for you. In this component, `ConsentWidget` comes from the same import as
the example at the top of the page:

```tsx
import { useState } from 'react';

export function PreferenceCenter() {
  const [open, setOpen] = useState<string[]>([]);

  return (
    <ConsentWidget.Root>
      <ConsentWidget.Accordion
        value={open}
        onValueChange={(next) => setOpen(Array.isArray(next) ? next : [next])}
      >
        <ConsentWidget.AccordionItems />
      </ConsentWidget.Accordion>
      <ConsentWidget.PolicyActions />
    </ConsentWidget.Root>
  );
}
```

Provider component slots for the stock structure are `manager.root`,
`manager.footer`, `manager.actionGroup`, `accordion.root`,
`accordion.triggerRow`, `accordion.title`, `accordion.control`,
`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`,
`vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`,
`vendor-list.item`, `vendor-list.header`,
`vendor-list.name`, `vendor-list.description`, `vendor-list.link`,
`vendor-list.control` and `tag.manager`.

`ConsentWidget` from the package root and from the
`c15t/react/consent-widget` subpath loads its code in a separate chunk the
first time it renders, so a page that never renders it does not download
it. `c15t/react/components/consent-widget` exports the widget without that
deferral, plus each part as a named export.

## Verify

Visit the page with the widget. Use a displayed optional category whose permission is
not restricted by policy or privacy signals such as GPC. One row per displayed
category appears, with `necessary` on and disabled. Turn that category on:
`useConsent('<category>')`
elsewhere on the page still reports the old value. Choose Save: it now
reports `true`. An open choice banner closes when the save answers its
prompt; a notice banner stays open until acknowledged. Reload the page: the
switch keeps the saved value. Without a saved choice or configured draft
defaults, optional switches start on under an opt-out rule.

# Dev Tools
URL: https://c15t.com/docs/shared/react/components/dev-tools
Shared DevTools reference for the React and Next.js adapters.

`DevTools` is a floating panel for the c15t v3 kernel. Use it during development to inspect consent values, scripts, location, the resolved policy, IAB state, events, and consent actions. The framework adapter reads the kernel from the nearest v3 provider. It never discovers a store through a window global.

> ⚠️ **Warning:**
> Load DevTools only in development. A conditional JSX expression stops it from mounting in production, but a static import can still add DevTools to the production bundle. Use a development-only dynamic import as shown below. The component renders nothing into the React tree and mounts its panel in document.body.

## Installation

No extra package is required. The React adapter and its engine are included
with the `c15t` package. Install `@c15t/dev-tools` directly only when you
need the imperative `createDevTools({ kernel })` API.

## Configuration

```tsx
<DevTools
  position="bottom-right"
  defaultOpen={false}
  defaultTab="consents"
  maxEvents={100}
  disabled={false}
/>
```

`position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
`bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
to choose that panel. `maxEvents` limits captured kernel and script events.
Set `disabled` to prevent mounting without removing the component. The
panel renders inside a shadow root by default, so page CSS does not reach
it. `shadow={false}` mounts it in the light DOM with its stylesheet in
`<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTriggerToolbar` or the ready-made `ConsentDialogTrigger`
is visible, the trigger shows a DevTools button and DevTools hides its own
floating launcher, so one control occupies the corner. The button sits at the
end of the toolbar farthest from its corner. The panel opens just past the
toolbar, aligned with its outer edge, and follows it when a visitor drags the
toolbar to another corner. `position` applies again once no trigger is
visible.

`ConsentDialogTrigger` becomes a two-button toolbar while DevTools is
mounted. A trigger composed from `ConsentDialogTrigger.Root` keeps its own
markup, and DevTools keeps its floating launcher beside it.

DevTools brings its launcher back whenever no trigger is visible, for example
while `showWhen="after-prompt"` waits for a choice. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

With the imperative engine, call `devTools.dock({ position, inline, block })`
to hide the launcher and anchor the panel `inline` and `block` pixels from the
viewport edges of `position`'s corner. Call `devTools.dock(null)` to restore
the launcher.

## Panels

Accept and reject apply only to categories displayed by the provider, leaving
hidden consent values unchanged. `necessary` always remains enabled. The
React adapter uses the current policy categories by default.

For an imperative integration with a narrower UI, pass
`getConsentCategories: () => ['necessary', 'measurement']` to
`createDevTools`. The getter is read again when an action runs. Headless UI
actions can use `kernel.commands.save('all', { categories: displayed })` or
`kernel.commands.save('none', { categories: displayed })`. These scoped bulk
saves use a `custom` transport action when they cover only part of the policy.
Actions covering the whole policy retain `all` or `necessary`. Without an
explicit scope or policy categories, bulk saves cover all known categories.

|Panel|What it shows|
|--|--|
|**Consents**|Inspect and save categories, accept all, or reject optional categories|
|**Scripts**|Configured scripts, loading status, search, and external page resources|
|**Location**|Resolved country and region, and location overrides|
|**Policy**|Resolved policy and UI configuration|
|**IAB**|Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings|
|**Events**|Timeline of consent changes, kernel events, and script lifecycle events|
|**Actions**|Show the banner, open preferences, hide consent UI, or refresh consent data|

### Script inspection

Set `defaultTab="scripts"` to open script inspection first. It reads all script
loaders attached to the current provider's kernel, including loaders created
before DevTools mounts. Search by script ID, category, URL, or status, then
expand a script to inspect its configuration and latest lifecycle event.

`loading` means an external script was inserted; `loaded` means its browser
load event fired, or an inline script or callback-only integration mounted.
`error` reports a loader error. `blocked` means consent requirements were not
met, and `pending` means an eligible script has not mounted. `present` means
the loader reused an element without a confirmed load result. `retained`
means consent was revoked but `persistAfterConsentRevoked` kept the element.
Retained scripts still receive `onConsentChange` with `hasConsent: false`, so
their integrations can send the vendor's consent-revocation command.
`alwaysLoad` bypasses the loading gate, not consent: callbacks receive the
actual consent state and updates across categories for integrations such as
Google Consent Mode.

Script details distinguish `allowedToLoad` from `consentGranted`. An
`alwaysLoad` integration can be allowed to load while its consent is denied.
Diagnostics expose these as `eligible` and `hasConsent`, respectively.

Lifecycle diagnostics work even when legacy debug forwarding is disabled.
The page scan lists external scripts and iframes present in the
DOM; it does not prove that they loaded successfully or were consent-gated.

For custom inspection tools, import `getScriptDiagnostics(kernel)` and
`subscribeScriptDiagnostics(kernel, listener)` from
`c15t/modules/script-loader`. The subscription reports loader
registration, updates, disposal, and lifecycle events. Read a fresh snapshot
after changes and call the returned unsubscribe function during cleanup.

### IAB editing

Under an IAB policy, the Consents tab is read-only. Edit and save vendors
and purposes in the IAB tab so the derived categories and TC string stay
consistent.

The IAB panel connects to the existing `@c15t/iab` module attached to the
provider's kernel. It does not create a second CMP or replace `__tcfapi`.
Controls become available after initialization, when the current policy uses
IAB and the vendor list is loaded.

Choose Vendors, Purposes, or Special features, then search by name or ID.
Vendors include the provider's custom vendors. Long lists show 20 entries per
page. Legitimate-interest controls appear for declared legitimate interests.
Search only filters the view; Accept all IAB and Reject all IAB apply to the
configured choices, including custom vendors.

Toggles update live IAB state and script gating immediately. Use Save IAB
consent to generate a fresh TC string and run the configured save transport.
The panel displays the last generated string; unsaved edits are not represented
in it. Copy TC string confirms success or reports clipboard failures. Raw IAB
data remains available in an expandable section.

IAB saves normally write the TC string to its standard cookie and localStorage.
For an in-memory playground, set `persistence: false` in the IAB module options
as well as disabling the provider's core persistence. The IAB option prevents
TC-string storage writes; it does not disable the configured save transport
or remove previously stored values.

Save and refresh actions show pending, success, and failure feedback. Controls
are disabled while a request is pending. A failed save does not roll back the
live choices; retry to record them.

For custom inspection tools, `getIABControls(kernel)` and
`subscribeIABControls(kernel, listener)` are exported from `c15t`.
The getter returns undefined before module initialization and after disposal.
A snapshot without an attached IAB module is read-only in DevTools.

## TanStack Devtools

Each embedded panel owns its event history and subscriptions. Unmounting it
destroys the instance; remounting starts a new history. If you need to capture
events while switching plugins, keep the c15t panel mounted. This differs from
the old globally shared DevTools store.

The React v3 DevTools adapter exports a panel component and plugin factory that match TanStack Devtools' plugin API:

```tsx
import * as React from 'react';
import { useRouter } from '@tanstack/react-router';
import { TanStackDevtools } from '@tanstack/react-devtools';
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
import { c15tDevtools } from 'c15t/react/devtools';

export function AppDevtools() {
  const router = useRouter();

  return (
    <TanStackDevtools
      plugins={[
        {
          name: 'TanStack Query',
          render: <ReactQueryDevtoolsPanel />,
        },
        {
          name: 'TanStack Router',
          render: <TanStackRouterDevtoolsPanel router={router} />,
        },
        c15tDevtools(),
      ]}
    />
  );
}
```

In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.

The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:

```tsx
import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';

const c15tPlugin = {
  name: 'Consent',
  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
    <C15tTanStackDevtoolsPanel theme={theme} />
  ),
};
```

## Props

|Property|Value|
|:--|:--|
|Type Name|\`ConsentDevToolsProps\`|
|Source Path|\`./packages/react/src/devtools.tsx\`|

\*ExtractedTypeTable: Could not extract "ConsentDevToolsProps" from "./packages/react/src/devtools.tsx" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.\*

# Compose your own banner
URL: https://c15t.com/docs/shared/react/compose
Shared compound-component content for the React, Next.js and TanStack Start compose pages.

Compose the banner from its parts when you need its elements in a different
order, an element it does not have, or your design system's button in place
of c15t's. The parts keep the stock
behavior. They read the same policy, record the same choices and render the
same class names, so theme tokens and slots still apply.

Try the lighter tools first:

|Change|Use|
|--|--|
|Colors, type, radius, spacing|[Theme tokens](/docs/customization/tokens)|
|Classes or attributes on one part|[Component parts](/docs/customization/slots)|
|Labels and languages|[Copy and translations](/docs/customization/translations)|
|Shape, position, button order|`ConsentBanner` props such as `variant`, `position`, `layout` and `primaryButton`|
|Different markup or order|Compound parts, on this page|
|Entirely custom UI and behavior|Headless hooks|

`ConsentBanner.Root` renders only while the banner is the active surface,
the same condition the stock `ConsentBanner` uses, so `CookieBanner` needs
no visibility logic. It renders nothing before a policy resolves and closes
once the visitor chooses.

`ConsentBanner.PolicyActions` renders the actions the policy asks for, in
the policy's order and groups, with any rights links, such as "Do not sell
or share my data", before them. For each action it calls `renderAction`
with the action name and the props c15t would give the stock button:
`key`, `consentAction`, `isPrimary`, and a `style` that stretches the
buttons when the layout fills the row. Return an element to replace that
button, or `null` to keep the stock one. The banner never renders `save`,
so the example skips it.

Each action part gets those props plus `asChild` and `noStyle`. `asChild`
renders `BrandButton` in place of c15t's `button`, and `noStyle` drops
c15t's button classes so they do not compete with yours. The part keeps its
behavior. Accept saves every category and Reject saves only necessary, and
both close the banner. Customize opens the preference dialog. Dismiss
records that the visitor saw a notice, without recording a choice.

With `asChild`, the part's default label does not render, because your
element keeps its own children. `useTranslations()` returns the labels the
stock buttons use, in the visitor's language.

Under a notice, the policy asks only for an acknowledgement, so
`PolicyActions` passes `dismiss` and `CookieBanner` renders one button. If
you place `ConsentBanner.AcceptButton` and `ConsentBanner.RejectButton`
yourself instead, they render under every policy, including one that owes
only a notice.

## Banner parts

Every part is a property of `ConsentBanner`. All parts except `Root` and
`PolicyActions` forward their ref, and they accept the attributes of the
element they render plus `noStyle`.

|Part|Renders|Props|
|--|--|--|
|`Root`|The `div` that positions the banner, only while the banner shows. Renders the backdrop itself when blocking.|`variant`, `position`, `blocking`, `models` (default `['opt-in', 'opt-out']`), `uiSource` (default `'banner'`), `noStyle`, `disableAnimation`|
|`Card`|The visible `div`, labelled with the title. `role="region"`, or `role="dialog"` with `aria-modal="true"` and a focus trap when blocking.|`asChild`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`Title`|An `h2` with the translated title, or the notice title under a notice.|children replace the text|
|`Description`|A `div` with the translated copy and the configured legal links.|`legalLinks`, `asChild`|
|`PolicyActions`|`Footer`, the rights links and the policy's action groups.|`renderAction`, children replace the rights links|
|`Footer`|A `div` for the actions.|`asChild`|
|`FooterSubGroup`|A `div` for one group of actions. `Actions` is an alias.|`asChild`|
|`AcceptButton`|A `button` that saves every category and closes the banner.|action button props|
|`RejectButton`|A `button` that saves only necessary and closes the banner.|action button props|
|`CustomizeButton`|A `button` that opens the preference dialog.|action button props|
|`DismissButton`|A `button` that acknowledges a notice.|action button props|
|`Rights`|A `div` with one `RightLink` per right the policy recommends, or nothing.|`rights`, `asChild`|
|`RightLink`|A `button` styled as underlined text that opens the preference dialog.|`right` (`'opt-out'` or `'preferences'`), `asChild`|
|`Overlay`|The backdrop of a blocking banner. `Root` already renders it, so do not add it.|none|

`Content` is an alias of `Card`.

The action buttons take `asChild`, `noStyle`, `consentAction`, `isPrimary`,
`variant` (`'primary'` or `'neutral'`), `mode` (`'filled'`, `'stroke'`,
`'lighter'` or `'ghost'`), `onClick` and any `button` attribute. Your
`onClick` runs before the action, and calling `event.preventDefault()` in
it skips the action. `consentAction` sets `data-action` and selects the
`theme.consentActions` entry. `PolicyActions` passes it for you, and
`DismissButton` sets it itself. A button you place yourself has no
`data-action` and no per-action theme until you pass `consentAction`.

`useConsentBannerSurface()` returns the `variant`, `position`,
`positionSource` and `blocking` that `Root` resolved, for your own elements
that depend on the banner's shape.

## Render a part as your own element

`asChild` swaps the part's element for the one element you pass as its
child. `Card`, `Header`, `Description`, `Footer`, `FooterSubGroup`,
`Rights`, `RightLink` and the action buttons support it. `Root` and
`Overlay` ignore it, and `Title` always renders an `h2`, so a child you pass
to `Title` ends up inside that `h2`. `Description` with `asChild` drops the
inline legal links.

The part merges its props onto your element:

* The part's props apply first, and props you set on the child win.
* `className` keeps both, the part's classes first.
* `style` merges, and your values win per property.
* Event handlers both run, yours first. On an action button, calling
  `event.preventDefault()` in yours skips c15t's action.
* The part's ref and your child's ref both receive the DOM node.
* Your child keeps its own children. The part's default content, such as a
  button label, does not render.

Your component has to pass its ref and every prop it does not use to its
DOM element. Otherwise c15t's click handler, `data-action` and focus
handling never reach the page. The `BrandButton` in the example does both.
Pass exactly one element. Text, a fragment or several children render
nothing.

Action buttons pass no `type` under `asChild`, so give your button a
default of `type="button"`. Without it, the button submits a surrounding
form.

## Compose the preference dialog

`ConsentDialog` has parts too. Compose it when the dialog needs a different
header or footer, and keep `ConsentWidget` inside `Content`. The widget
owns the category switches, the draft and the policy's Save, Accept and
Reject buttons.

|Part|Renders|Props|
|--|--|--|
|`Root`|The dialog in a portal on `document.body`, with its open state, backdrop, focus trap, scroll lock and Escape to close.|`open`, `models` (default `['opt-in', 'opt-out', 'none']`), `overlay` (a node, or `false` for none), `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`, `uiSource` (default `'dialog'`)|
|`Card`|The panel `div`.|`className`, `style`, `noStyle`|
|`Header`|A `div` for the title and copy.|`asChild`|
|`HeaderTitle`|An `h2` with `id="consent-dialog-title"`.|children replace the text|
|`HeaderDescription`|A `div` with `id="consent-dialog-description"` and the legal links.|`legalLinks`, `asChild`|
|`Content`|A `div` for `ConsentWidget`.|`asChild`|
|`Footer`|A `div` with the branding tag, unless you pass children or `hideBranding`.|`hideBranding`, `asChild`|
|`ConsentCustomizationCard`|The stock card with all of the above.|`legalLinks`, `hideBranding`, `noStyle`|
|`Overlay`|The backdrop. `Root` already renders it.|none|

```tsx
<ConsentDialog.Root>
  <ConsentDialog.Card>
    <ConsentDialog.Header>
      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
      <ConsentDialog.HeaderDescription />
    </ConsentDialog.Header>
    <ConsentDialog.Content>
      <ConsentWidget />
    </ConsentDialog.Content>
    <ConsentDialog.Footer hideBranding />
  </ConsentDialog.Card>
</ConsentDialog.Root>
```

Render the composed dialog in place of `ConsentDialog`, next to your
banner. The stock `ConsentDialog` downloads its code when the dialog first
opens. The parts load that same code when they first render, and a
composed `ConsentDialog.Root` renders on every page, so the code downloads
with the page. `c15t/react/components/consent-dialog` exports the same
parts without the deferral.

`ConsentWidget` has parts as well, such as `ConsentWidget.Root`,
`ConsentWidget.Accordion`, `ConsentWidget.AccordionItems` and
`ConsentWidget.PolicyActions`, for a preference list with your own layout.

## Keep the banner accessible

The stock parts carry the roles, labels and focus handling. A composed
banner keeps them as long as you keep the parts that own them:

* `Card` owns the banner's role, label and focus trap. With `asChild`, your
  element receives them, so do not set `role` or `aria-modal` on it.
* `Card` takes its `aria-label` from the translated title, not from text you
  pass to `Title`. If you change the title text, pass the same text as
  `aria-label` on `Card`.
* To attach your own ref to `Card`, pass a ref object from `useRef`. A
  callback ref turns off the focus trap on a blocking banner.
* Render each action as a real `button`. Its text is the accessible name,
  so keep the label inside your button.
* Keep a way to reopen preferences after the banner closes, such as the
  `ConsentDialogLink` in your footer.
* The dialog's `Root` names the panel with the ids on `HeaderTitle` and
  `HeaderDescription`. Keep both parts, or put `id="consent-dialog-title"`
  and `id="consent-dialog-description"` on your own heading and copy.

## Keep theme tokens and slots working

The parts render the stock class names, and the banner's `Root` renders
c15t's rules, so c15t's styles and `--c15t-*` tokens style a composed
banner the way they style the stock one.

Slots in the provider's `options.components` reach each part by key:
`banner.root`, `banner.card`, `banner.header`, `banner.title`,
`description.banner`, `banner.footer` and `banner.actions`,
`banner.actionGroup`, `banner.rights` and `banner.rightLink`. A class you
pass to a part joins its stock and slot classes. The stock `ConsentBanner`
also renders the `banner.cardShell` wrapper and the "Secured by" tag, and a
composed banner renders neither.

Action buttons read the `button.primary` or `button.secondary` slot and the
`theme.consentActions` entry for their `consentAction`. `noStyle` on a
button drops c15t's button classes and keeps slot classes. `noStyle` on
`Root` removes the built-in styling from every part inside it.

## Check the result

1. Clear site data and reload. The composed banner appears with your
   buttons. In DevTools Elements, each action is your element with a
   `data-action` attribute. In DevTools Network, no optional vendor request
   has fired.
2. Tab through the banner. Every action is reachable in the policy's order
   and shows a focus ring. Press Enter on Customize, and the preference
   dialog opens.
3. Click Reject all. The banner closes. Reload, and it stays closed with
   the vendors still blocked.
4. Reopen preferences from your footer link. The optional categories are
   off. Allow one, save, and only that category's vendors load.
5. If your policies include a notice region, test it too. The banner shows
   your acknowledgement button and no Accept or Reject.

[Verify consent](/docs/guides/verify-consent) has the full checklist.

# Headless
URL: https://c15t.com/docs/shared/react/headless
Shared headless consent UI content for the React and Next.js adapters.

The pre-built banner and dialog cover most designs through props, slots, and
the stylesheet. Go headless when your markup has to be something else
entirely: a design system component, a native sheet, or a layout the compound
parts cannot express.

Headless code owns the rendered controls, so it also owns the compliance
outcome. The hooks hand you the actions a policy requires, the rights it must
keep reachable, and diagnostics when your presentation drops one. Render from
those lists rather than from a fixed set of buttons, and a site that later adds
a notice region keeps working without a code change.

`banner.actionGroups` is the resolved layout: reject and accept share a group
at equal prominence, and the rest follow. `banner.orderedActions` is the same
list flattened. Under a notice the only action is `dismiss`, and
`banner.preferenceControls` recommends additional buttons for opening
preferences. Under a notice it contains `opt-out`, which selects the
"Do not sell or share my data" label. The example renders that button and
an "OK" button. Both controls keep their own command: opening
preferences and dismissing the notice.

The list is a rendering helper. It does not establish that your UI implements
all policy rights. Provide disclosure and persistent preferences access.

`performAction` saves all categories for `accept`, none for `reject`, the
current draft for `save`, records a dismissal for `dismiss`, and opens the
preference center for `customize`. `banner.diagnostics` reports when a host
layout drops a required action or gives equivalent actions different
prominence. Review each diagnostic when configuring custom presentation.

`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
shape from `presentation.prompt`, so a headless surface can follow the same
bar, widget, or wall choice the pre-built banner would make, and can trap
focus and lock scroll exactly when `blocking` is true.

# Hooks
URL: https://c15t.com/docs/shared/react/hooks/overview
Shared consent hook guidance for the React and Next.js adapters.

Call hooks inside the consent provider. `useConsent` reads effective permission,
which can be true under an opt-out policy without a recorded grant.

|Need|Hook|
|--|--|
|One category's current permission|`useConsent(category)`|
|All current permissions|`useConsents()`|
|Recorded per-category choices|`useExplicitChoice()`|
|Whether one declared vendor may run|`useVendorAllowed(id)`|
|Whether a prompt is required|`usePromptRequirement()`|
|Active policy and resolution|`usePolicyRule()`, `usePolicyResolution()`|
|Save an explicit choice|`useSaveConsents()`|
|Open or close a consent surface|`useSetActiveUI()`|
|Acknowledge a notice|`useDismissNotice()`|

This is an isolated action example, not a complete policy-aware banner. Use the
stock UI or headless surface actions for a complete prompt. Do not call save on
mount to persist a state derived from permissions.

Use focused hooks for feature gates. For a complete custom prompt or preference
center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
for staged choices, inside one `ConsentDraftProvider` so the save commits the
same draft. v3 has no `useConsentManager()`; the
[`use-consent-manager-to-hooks` codemod](/docs/cli/commands/codemods#migrate-useconsentmanager-to-v3-hooks)
rewrites most of its calls to hooks. Read [how consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice) before
treating a callback as evidence of a choice.

# IAB TCF
URL: https://c15t.com/docs/shared/react/iab/overview
Shared IAB TCF setup guidance for the React and Next.js adapters.

Use the IAB integration when your application needs the Transparency and Consent
Framework. Configure an IAB policy, the correct CMP identity and vendor data for
your deployment. A demo CMP ID is not a production configuration.

A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your users' consent records to someone else. Omitting it leaves the add-on
unmounted: no `__tcfapi`, and no TC String written.

Install `@c15t/iab` alongside your framework adapter, then mount the IAB
components inside an existing consent provider connected to Inth.

Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
preferences entry point through the surrounding consent provider.

## Resolve the policy before rendering

IAB components remain hidden until an applicable policy resolves. Forcing a
dialog open does not create a policy or vendor list. Inspect resolution and the
Global Vendor List response before changing rendering conditions.

IAB presentation follows `presentation.prompt.blocking` and
`presentation.preferences.blocking`. A blocking dialog needs focus management,
scroll locking and a backdrop together.

## Mount IABProvider for every IAB policy

IAB is opt-in. The standard `ConsentBanner` and `ConsentDialog` do not
handle the IAB model, so when a visitor's policy uses it, the backend
sends its vendor list and the app has no `IABProvider`, they throw an
`IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`):
`c15t: this visitor's policy uses IAB TCF, but no <IABProvider> is mounted`.
The error happens during render, on the server and in the browser, so
your error boundary or the framework's error overlay shows it. Render `IABProvider` from
`c15t/react/iab` for those visitors, or remove the `iab` model from the
policy.

## Verify vendor and purpose choices

Test category choices alongside vendor, purpose, legitimate-interest and special
feature controls used by your integration. Confirm the TC String and `__tcfapi`
reflect the saved state, and verify the vendor's actual requests. A category-only
banner test does not establish that the IAB flow works.

The visitor's policy uses the `iab` model and the backend sent its vendor
list, but no `IABProvider` is mounted. The standard banner and dialog do
not handle the IAB model, so they throw rather than leave the visitor
with no consent UI. Server and browser render the same error.

Fix it one of two ways:

* If the site uses IAB TCF, render `IABProvider` with `IABConsentBanner`
  and `IABConsentDialog` from `c15t/react/iab` inside your consent
  provider. They can sit next to the standard banner.
* If it does not, remove the `iab` model from the policy for that region
  in your Inth project or policy pack.

A backend that answers `gvl: null` turns IAB off for that request. The
policy then runs as opt-in and nothing throws.

The check passes once `c15t/react/iab` has loaded. If you import the IAB
components with a dynamic `import()`, a render of the standard banner
that happens before the import finishes still throws.

# Network blocker
URL: https://c15t.com/docs/shared/react/network-blocker
Shared network blocker reference for the React and Next.js adapters.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
resolves to a `451` response with the status text
`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
and fires an `error` event. Requests that match no rule are not delayed.

## When blocking starts

The provider holds matching requests from its first render in the browser,
before any of its children render or run effects. That covers requests from
child components, including their mount effects, and from effects in
components rendered next to the provider. The blocker module itself loads
after mount and decides each held request. Apps without `networkBlocker` do
not download it.

The standalone `useNetworkBlocker` hook works the same way from the first
render of the component that calls it. That render patches `fetch` and
`XMLHttpRequest`. If React throws the render away and never commits it, the
hold ends after 10 seconds. Nothing checked consent for the requests it held,
so they fail the way the blocker fails a blocked request: a 451 response for
`fetch`, a failed XHR. The same happens when the component unmounts before
the blocker loads.

While consent is unknown, a matching request that would be blocked waits
instead of failing. Consent is unknown until the policy has loaded, which is
also when a returning visitor's stored choice takes effect. The request is
then sent if the choice allows it and blocked otherwise. If the policy fails
to load, optional categories stay denied and waiting requests are blocked.
If the policy request never finishes, they keep waiting and are never sent.

A synchronous XHR cannot wait. Before the blocker module has loaded, a
matching one throws a `NetworkError` from `send()`. After that, one that
consent does not allow yet is blocked.

## What the network blocker cannot stop

The blocker only sees requests made after the provider starts rendering in
the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:

* Code that runs before the provider renders: inline scripts in the HTML,
  third-party tags in `<head>`, scripts loaded before hydration (such as
  `next/script` with `beforeInteractive`), and client modules that evaluate
  earlier. Webpack builds evaluate a route's client component modules when
  its chunk loads, so their top-level code runs first. Turbopack evaluates a
  client component module when its first element renders, which inside the
  provider is after blocking starts.
* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
  provider rendered.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` or `<iframe>` elements, web workers and service
  workers.
* With the standalone `useNetworkBlocker` hook instead of the provider
  option, requests sent before the component that calls it renders.
  Blocking starts in that component's first render, not the provider's.

Keep tracking calls out of that window:

* Send them from an effect or an event handler, never at module top level.
* Load vendor SDKs through `scripts` instead of a `<script>` tag or
  `next/script`, so they wait for consent before they run at all.
* Check `useConsent('measurement')` (or the category you need) before you
  call a vendor from your own code, and treat the blocker as a backstop.

## Verify

Open the browser's network panel, clear site data and reload. Requests
matching a rule should not appear until you grant their category; with
logging on, the console lists each blocked request. Reject, reload, and
check that they still do not appear. The
[verification guide](/docs/guides/verify-consent) covers automated checks.

# Styling
URL: https://c15t.com/docs/shared/react/styling/overview
Shared token, slot and class-name styling guidance for the React and Next.js adapters.

c15t's rules live in the cascade layer `components`, and each `<style>`
element the components render opens with Tailwind CSS 4's layer order,
`@layer properties, theme, base, components, utilities;`. Unlayered CSS,
Tailwind 4 utilities and StyleX's atomic classes override c15t's rules
without specificity tricks, whichever stylesheet loads first.
[Stylesheets and CSS layers](/docs/customization/stylesheets) explains the
order and which file holds the dialog's rules.

Tailwind CSS 3 has no cascade layers, and its unlayered preflight beats
c15t's layered rules. Set `styles: false` in the provider options, import
`styles.css` above the `@tailwind` directives, and add the
`c15t/postcss-tailwind3` PostCSS plugin before `tailwindcss`. Utilities
you pass to c15t parts then need the important modifier, such as
`!bg-red-500`. [Tailwind CSS](/docs/customization/tailwind#set-up-tailwind-css-3)
shows the tested setup for each framework.

Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
properties. The rules the components render set the default values, as
does `styles.css` when you import it with `styles: false`. To change them,
render `ConsentTheme` with your theme where your app renders on the server,
or override the variables directly in your CSS.

`ConsentTheme` renders a `<style id="c15t-theme">` element with the
variables for `theme`. It is not a client component: rendered from a Server
Component or another server-only file, the theme generator stays out of the
browser bundle. Rendered from a client component it still works, but the
browser downloads the generator (about 1.7 KB gzip). The provider no longer
turns `theme` tokens into CSS. It still reads `consentActions` and slot
styles from its `theme` option, and warns in development when `theme` holds
tokens but the page has no `c15t-theme` stylesheet.

|`ConsentTheme` prop|Purpose|
|--|--|
|`theme`|Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.|
|`colorScheme`|`'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`.|
|`nonce`|Content Security Policy nonce for the `<style>` element.|

Pass the same `colorScheme` to `ConsentTheme` and to the provider. If your
app manages dark mode through a root class, such as next-themes' `dark`
class, omit `colorScheme` and include that class in the server HTML.
[Dark mode](/docs/customization/dark-mode) covers `theme.dark`, `null` and
a dark first paint.

To switch between different token sets at runtime, render `ConsentTheme`
from a client component and change its props, which ships the generator.

Outside a component, call `generateThemeCSS(theme, colorScheme)` from
`c15t/react/utils`, or `@c15t/react/utils` with the scoped package. It
writes the same CSS as `ConsentTheme`. Outside React, import it from
`@c15t/ui/theme`. Call it on the server or at build time and put the result in a
`<style>` element or your stylesheet. It escapes `<`, so the result is safe
inside `<style>`.

Earlier v3 alphas generated theme CSS in the browser from the provider's
`theme` option. To migrate:

1. Move the theme into a module without `'use client'`, so server and
   client files can both import it.
2. Render `<ConsentTheme theme={theme} />` next to the consent root, from a
   Server Component or another server-rendered file. Pass `colorScheme` and
   `nonce` if you set them on the provider.
3. Keep passing `theme` to the provider only for `consentActions` and slot
   styles. A theme with tokens only can be removed from the provider.
4. The default tokens the provider used to inject now come with the rules
   the components render. If you import `styles.css` with `styles: false`,
   keep that import.

`consentActions` decides how each action role looks: `default` applies to
every button, `primary` to whichever actions the policy or your props mark
primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
Per-action keys win over `primary`, which wins over `default`.

Banner sizing has its own variables. Override them in CSS when a variant
needs a different footprint:

|Variable|Default|Applies to|
|--|--|--|
|`--consent-banner-max-width`|`440px`|`floating` cards|
|`--consent-banner-widget-max-width`|`20rem`|`widget` chips|
|`--consent-banner-wall-max-width`|`30rem`|`wall` cards|

The footer lays out its actions by the card's width, not the viewport's.
With the default `compact` profile, a card narrower than 22rem puts Reject
and Accept on one row and Customize on a full-width row below them.

## Colors by consent model

The primary action can change while the brand color stays the same. Set
`consentActions.primary` once, then select `primaryButton` per policy as
shown in [ConsentBanner](../components/consent-banner#per-policy-buttons).

To give opt-in and opt-out banners different colors, scope the tokens to
the root's attributes. Include hover and foreground colors when overriding
CSS tokens directly:

```css
[data-prompt][data-model='opt-in'] {
	--c15t-primary: #2f6f4e;
	--c15t-primary-hover: #24563c;
	--c15t-text-on-primary: #fff;
}

[data-prompt][data-model='opt-out'] {
	--c15t-primary: #6b3fa0;
	--c15t-primary-hover: #55327f;
	--c15t-text-on-primary: #fff;
}
```

These colors apply to the action marked primary. Button layout and color
changes do not change the policy or expire a saved choice.

## Slots

Each component part is a slot. A slot accepts any attributes the element
takes, so the contract is the same whether you write class strings or pass an
object with `className` and `style`. Set slots on the provider under
`components`, keyed by component and part.

The root also carries `data-variant`, so you can restyle one shape without
touching the others. Tailwind, giving a `bar` a brand-colored top edge and
tighter text:

```tsx
<ConsentProvider
	options={{
		mode,
		presentation: { prompt: { variant: 'bar' } },
		components: {
			banner: {
				root: { className: 'group' },
				card: {
					className:
						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
				},
			},
			description: {
				banner: { className: 'group-data-[variant=bar]:text-xs' },
			},
		},
	}}
/>
```

`data-variant` sits on the root, so child slots use Tailwind's `group`
prefix to read it.

[Class names and CSS-in-JS](/docs/customization/class-names) shows CSS
Modules, vanilla-extract, StyleX and Emotion classes on a part.

Set `noStyle` on a component to drop the built-in classes from every part and
keep only what your slots pass. Set `noStyle` in the provider options to do it
for every component.

[Component parts](/docs/customization/slots) lists every part key under
`components` and the `data-*` attributes each part carries. Action buttons
carry `data-action`, so a single rule such as `[data-action='dismiss']`
styles one role across every surface. Right links are underlined text by
default, so the only button on a notice is the primary action.

# Theme Tokens
URL: https://c15t.com/docs/shared/reference/theme-tokens

|CSS variable|Theme key|Default|
|--|--|--|
|`--c15t-primary`|`colors.primary`|`hsl(228, 100%, 60%)`|
|`--c15t-primary-hover`|`colors.primaryHover`|`hsl(228, 100%, 55%)`|
|`--c15t-surface`|`colors.surface`|`hsl(0, 0%, 100%)`|
|`--c15t-surface-hover`|`colors.surfaceHover`|`hsl(0, 0%, 98%)`|
|`--c15t-border`|`colors.border`|`hsl(0, 0%, 90%)`|
|`--c15t-border-hover`|`colors.borderHover`|`hsl(0, 0%, 85%)`|
|`--c15t-text`|`colors.text`|`hsl(0, 0%, 10%)`|
|`--c15t-text-muted`|`colors.textMuted`|`hsl(0, 0%, 40%)`|
|`--c15t-text-on-primary`|`colors.textOnPrimary`|auto-derived from `colors.primary` when omitted|
|`--c15t-overlay`|`colors.overlay`|`hsla(0, 0%, 0%, 0.5)`|
|`--c15t-switch-track`|`colors.switchTrack`|`hsl(0, 0%, 85%)`|
|`--c15t-switch-track-active`|`colors.switchTrackActive`|`colors.primary`|
|`--c15t-switch-thumb`|`colors.switchThumb`|`hsl(0, 0%, 100%)`|
|`--c15t-font-family`|`typography.fontFamily`|`system-ui, -apple-system, sans-serif`|
|`--c15t-font-size-sm`|`typography.fontSize.sm`|`0.875rem`|
|`--c15t-font-size-base`|`typography.fontSize.base`|`1rem`|
|`--c15t-font-size-lg`|`typography.fontSize.lg`|`1.125rem`|
|`--c15t-font-weight-normal`|`typography.fontWeight.normal`|`400`|
|`--c15t-font-weight-medium`|`typography.fontWeight.medium`|`500`|
|`--c15t-font-weight-semibold`|`typography.fontWeight.semibold`|`600`|
|`--c15t-line-height-tight`|`typography.lineHeight.tight`|`1.25`|
|`--c15t-line-height-normal`|`typography.lineHeight.normal`|`1.5`|
|`--c15t-line-height-relaxed`|`typography.lineHeight.relaxed`|`1.75`|
|`--c15t-space-xs`|`spacing.xs`|`0.25rem`|
|`--c15t-space-sm`|`spacing.sm`|`0.5rem`|
|`--c15t-space-md`|`spacing.md`|`1rem`|
|`--c15t-space-lg`|`spacing.lg`|`1.5rem`|
|`--c15t-space-xl`|`spacing.xl`|`2rem`|
|`--c15t-radius-sm`|`radius.sm`|`0.25rem`|
|`--c15t-radius-md`|`radius.md`|`0.5rem`|
|`--c15t-radius-lg`|`radius.lg`|`0.75rem`|
|`--c15t-radius-full`|`radius.full`|`9999px`|
|`--c15t-shadow-sm`|`shadows.sm`|`0 1px 2px hsla(0, 0%, 0%, 0.05)`|
|`--c15t-shadow-md`|`shadows.md`|`0 4px 12px hsla(0, 0%, 0%, 0.08)`|
|`--c15t-shadow-lg`|`shadows.lg`|`0 8px 24px hsla(0, 0%, 0%, 0.12)`|
|`--c15t-duration-fast`|`motion.duration.fast`|`80ms`|
|`--c15t-duration-normal`|`motion.duration.normal`|`150ms`|
|`--c15t-duration-slow`|`motion.duration.slow`|`200ms`|
|`--c15t-easing`|`motion.easing`|`cubic-bezier(0.4, 0, 0.2, 1)`|
|`--c15t-easing-out`|`motion.easingOut`|`cubic-bezier(0.215, 0.61, 0.355, 1)`|
|`--c15t-easing-in`|`motion.easingIn`|`cubic-bezier(0.55, 0.055, 0.675, 0.19)`|
|`--c15t-easing-in-out`|`motion.easingInOut`|`cubic-bezier(0.645, 0.045, 0.355, 1)`|
|`--c15t-easing-spring`|`motion.easingSpring`|`cubic-bezier(0.34, 1.56, 0.64, 1)`|

# Clear on revocation
URL: https://c15t.com/docs/shared/scripts/clear-on-revocation
Shared clearOnRevocation explanation for the framework clear on revocation pages.

## Name cookies and keys

Each optional category takes three lists. Without `clearOnRevocation`, c15t
deletes nothing, and `necessary` cannot be configured.

|Field|Takes|
|--|--|
|`cookies`|Cookie names, prefixes ending in `*` such as `'_ga_*'`, or `{ name, domain?, path?, partitioned? }` objects.|
|`localStorage`|Keys, or prefixes ending in `*`.|
|`sessionStorage`|Keys, or prefixes ending in `*`.|

Use an exact name, or a prefix followed by `*`. `_ga_*` matches `_ga_ABC123`
but not `_ga`, so list both. Regular expressions, a `*` anywhere but the end,
and a bare `*` are not supported. Cookie names are matched as written,
without URL decoding.

By default c15t tries the current host and its parent domains, and the
current path and its parents. For a cookie set on a specific scope, use an
object:

```ts
const cookies = [
  { name: 'analytics-id', domain: 'example.com', path: '/' },
  { name: 'checkout-metrics', domain: '', path: '/checkout' },
  { name: 'partitioned-metrics', partitioned: true },
];
```

An empty `domain` means a host-only cookie. A `domain` or `path` you set
replaces the automatic attempts for that field. Partitioned cookies need
`partitioned: true`. A prefix only finds cookies the current page can read,
so use an exact name for a cookie on another path.

c15t never deletes its own consent records, even when a pattern matches
them.

## When cleanup runs

* On the first page load after the policy resolves, for every denied
  category. This covers a new opt-in visitor and a returning visitor whose
  choice expired.
* Whenever a category changes from allowed to denied, after a saved refusal,
  expiry, a policy change or a Global Privacy Control signal.

Cleanup does not run during server rendering, while the policy is still
loading, on draft switch changes in the dialog, or when the provider
unmounts. It runs once per change and does not poll. Under an opt-out
policy, an expired choice that stays allowed deletes nothing. If a resolved
policy later falls back to denial after a failed request, cleanup deletes
the data, and a successful retry cannot restore it.

Switching off one vendor inside an allowed category deletes nothing, because
the category stays allowed.

## Browser limits

c15t can delete first-party cookies that JavaScript can read, and keys in
the current origin's `localStorage` and `sessionStorage`. It cannot delete
`HttpOnly` cookies or another origin's data; expire those from your server.
A vendor SDK still running on the page can write its cookies again, which is
one reason c15t reloads the page after a revocation. Deletion failures do
not block the consent update. See
[MDN on cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).

## Verify cleanup

1. Allow measurement and let Google Analytics run. In DevTools Application,
   Cookies shows `_ga` and a `_ga_<id>` cookie.
2. Open Privacy settings, turn measurement off and save. c15t reloads the
   page. Both cookies are gone, and `analytics:*` keys are gone from Local
   storage.
3. Reload. The cookies do not come back, because Google Analytics no longer
   loads.
4. If you listed a cookie with an explicit `domain` or `path`, repeat step 2
   and check that the cookie is gone from that scope too.

# Google load mode
URL: https://c15t.com/docs/shared/scripts/google-load-mode
Shared explanation of the loadMode option on the gtag and googleTagManager helpers, for the framework migration sections.

### Choose when Google loads

The `gtag` and `googleTagManager` helpers take a `loadMode` option. It
decides whether the page contacts Google before the helper's category is
allowed:

|`loadMode`|Until the category is allowed|Use it when|
|--|--|--|
|`'always'` (default)|c15t loads Google's script, sends Consent Mode `default` with the current permissions, then sends `update` as they change. Google receives requests with the optional consent types denied.|You want Consent Mode signals from visitors who have not allowed the category.|
|`'after-consent'`|c15t sends no request to Google.|Your site must make no request to Google before opt-in. You give up Consent Mode's cookieless pings and conversion modeling for visitors who haven't allowed the category.|

With `'after-consent'`, `gtag` waits for its `category`, and
`googleTagManager` waits for `measurement` or `marketing` because a container
usually holds both kinds of tag. Pass `category` to `googleTagManager` to
change that, for example `category: 'measurement'` for an analytics-only
container. Until the helper loads, `window.gtag` doesn't exist, and neither
does `window.dataLayer` unless you seeded it, so event calls written as
`window.gtag?.(...)` do nothing.

`'after-consent'` waits for the category to be allowed, not for a recorded
choice. Under an `opt-in` policy, that happens when the visitor allows it.
Under an `opt-out` or `none` policy, optional categories are allowed before a
choice, so the helper loads on the first page.

In either mode, the container runs every tag in it once it starts. Google
tags inside follow Consent Mode, but Custom HTML tags and third-party pixels
fire on their own triggers. With the default `category`, a visitor who
allowed only measurement starts the container, and a marketing pixel in it
loads too. With `'always'`, both load before any choice. Add a
consent check to each of those tags in GTM, or move the vendor out of the
container to its own c15t helper. See
[configure consent inside the container](/docs/integrations/google-tag-manager#configure-consent-inside-the-container).

Set it on each Google helper in your `scripts` array:

```ts
gtag({
	id: 'G-XXXXXXXXXX',
	category: 'measurement',
	loadMode: 'after-consent',
}),
googleTagManager({ id: 'GTM-XXXXXXX', loadMode: 'after-consent' }),
```

The [Google Tag](/docs/integrations/google-tag) and
[Google Tag Manager](/docs/integrations/google-tag-manager) guides list what
each mode sends and how to check it in DevTools.

# Vendor consent
URL: https://c15t.com/docs/shared/scripts/vendor-consent
Shared vendor consent explanation for the framework vendor consent pages.

## How vendor consent works

A visitor allows marketing, then switches off X Pixel. Other marketing
scripts load; X Pixel does not. c15t loads a script, network request or
iframe that names a vendor only when both are true:

* Its category is allowed.
* The visitor has not switched its vendor off.

A vendor switch never grants a category. With marketing denied, X Pixel stays
blocked whatever its own switch says. You do not need IAB TCF for this. Under
an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
TC string instead; see [IAB TCF](./iab).

## Vendor fields

|Field|Required|Behavior|
|--|--|--|
|`id`|Yes|Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.|
|`name`|Yes|Name shown in the preference dialog.|
|`category`|Yes|A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.|
|`privacyPolicyUrl`|Yes|Link shown next to the vendor.|
|`description`, `legalName`, `homepageUrl`|No|Extra detail shown on the vendor card.|
|`disabled`|No|List the vendor without a switch. A stored denial for it no longer applies.|

The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
[vendor guide](/docs/integrations/overview) names its slug.

You don't need to declare a helper's vendor. Each helper also sets
`vendorDetails` on its script: the vendor's name, privacy policy, homepage
and legal entity. The dialog lists the vendor with its own switch from
those. Declare the vendor in `vendors` to replace them, for example to link
your own data processing notice, or when you self-host a tool such as
Matomo, Umami, Plausible or PostHog and the vendor's privacy policy doesn't
cover your install. A declaration replaces `vendorDetails` as a whole and
doesn't merge with it.

Your own scripts can set `vendorDetails` too. A script with a `vendor` slug
and no `name` and `privacyPolicyUrl` from any source still loads with its
category, but the dialog has no switch for it. In development, c15t logs a
console warning that names the slug. Production builds skip the warning.

A self-hosted backend can declare vendors too. `/init` returns them and c15t
merges them with the vendors in code. When both declare the same `id`, the
code declaration wins.

## Gate scripts, requests and iframes by vendor

Put the vendor slug on each target:

|Target|Field|
|--|--|
|Script configuration|`vendor: 'x-pixel'`|
|Network blocker rule|`vendor: 'x-pixel'`|
|Iframe blocker|`data-vendor="x-pixel"` on the `<iframe>`|

An iframe with `data-vendor` and no `data-category` is gated on the vendor
alone. A script with `alwaysLoad` still loads when its vendor is off. Its
callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
you. While their vendor is off, they send every optional category as denied.

A vendor reads as allowed only when it is declared, its category is allowed
and the visitor has not switched it off. An id that nothing declares, in
`vendors`, on a script or iframe, or from the backend, reads as not allowed.
A typo such as `x-pixle` or a vendor you forgot to declare never looks like
consent. In development, c15t logs a console warning that names the id.

The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
A vendor's switch is disabled while its category is off. Save records the
vendors the visitor changed. Accept All and Reject All clear every vendor
denial, so each vendor follows its category again. The labels come from
`consentManagerDialog.vendors` in the translations: `title`,
`privacyPolicy`, `disabledByCategory` and `switchLabel`.

## What c15t stores

c15t stores only the vendors a visitor switched off, and sends the full
vendor map to the backend with the consent record. Under an opt-out policy,
every vendor starts on. Turning a vendor off that was on reloads the page,
the same as withdrawing a category, so code the vendor already ran stops.

## What switching a vendor off does not do

* It does not delete cookies the vendor already set.
  [Clear on revocation](./clear-on-revocation) does not run, because the
  category stays allowed. Delete the vendor's cookies from the script's
  `onConsentChange` when `info.vendor.granted` is `false`.
* It does not expire. The switch stays off until the visitor changes it or
  uses Accept All or Reject All, even across a policy change.
* Adding a vendor does not ask returning visitors again. A new vendor starts
  on inside an allowed category. Change the policy's `copyRevision` if a new
  vendor should prompt again.

## Verify vendor consent

Test the production build in a private window with DevTools Network open and
filtered to `ads-twitter.com`:

1. Register `xPixel()`. Open Privacy settings. The marketing row lists X
   Pixel with a switch.
2. Allow marketing and save. `uwt.js` loads.
3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
   page. After the reload there is no `uwt.js` request, and other marketing
   scripts still load.
4. Reload again. The X Pixel switch is still off.
5. Turn marketing off. The X Pixel switch is disabled.
6. Open Privacy settings and click Accept All. `uwt.js` loads again.

# Callbacks
URL: https://c15t.com/docs/shared/svelte/callbacks
Run your own code when consent changes through the provider's `callbacks` prop, a script's own callbacks, or a kernel event in one component:

## Pick the right callback

Run your own code when consent changes through the provider's `callbacks`
prop, a script's own callbacks, or a kernel event in one component:

|You want to|Use|
|--|--|
|Send a choice to your analytics or CRM when the visitor makes one|`callbacks.onChoiceRecorded`|
|Start or stop your own code when what may run changes|`callbacks.onPermissionsChanged`|
|Report failed backend requests|`callbacks.onError`|
|Show a message or flush data before a withdrawal reloads the page|`callbacks.onBeforeConsentRevocationReload`|
|Call a vendor's own consent API after its script loads|The script's `onConsentChange`|
|React to consent inside one component|`getConsentKernel().events.on()` or the manager's properties|

## onChoiceRecorded or onPermissionsChanged

`onChoiceRecorded` runs only when the visitor accepts, rejects or saves.
`onPermissionsChanged` runs whenever effective permissions change, whatever
the cause:

|Event|`onChoiceRecorded`|`onPermissionsChanged`|
|--|--|--|
|Visitor accepts, rejects or saves|Yes|Yes, if a permission changed|
|Policy resolves under opt-out and allows categories before a choice|No|Yes|
|Global Privacy Control overrides a grant|No|Yes|
|A recorded choice expires|No|Yes|
|Visitor dismisses a notice|No|No|

Use `onChoiceRecorded` for consent records and audit trails, because it fires
only for a visitor's action. Use `onPermissionsChanged` to start or stop code,
because it covers every way a permission changes. Never treat
`onPermissionsChanged` as proof that the visitor agreed to something.

## Pass callbacks to the provider

```ts title="src/lib/consent-callbacks.ts"
import type { ConsentProviderCallbacks } from '@c15t/svelte';

// Pass as `callbacks={callbacks}` on ConsentProvider.
export const callbacks: ConsentProviderCallbacks = {
	// Runs just before c15t reloads the page after a withdrawal.
	onBeforeConsentRevocationReload: ({ preferences }) => {
		console.info('Reloading with', preferences);
	},
	// An explicit accept, reject or save. Never runs for defaults, expiry,
	// policy changes or privacy signals.
	onChoiceRecorded: ({ snapshot, confirmed }) => {
		console.info('Visitor chose', snapshot.explicitChoice, confirmed);
	},
	// A failed command, such as an /init request that could not reach the
	// backend.
	onError: ({ error }) => {
		console.warn('c15t error', error);
	},
	// Any change to what may run, whatever caused it.
	onPermissionsChanged: ({ snapshot, previous }) => {
		console.info('Permissions', previous, '->', snapshot.effectivePermissions);
	},
};
```

Pass the object as `callbacks={callbacks}` on `ConsentProvider`. The
provider reads it once, when it is created. Keep the functions in a module or
in the component that renders the provider; on SvelteKit, not in a server
load, because a load cannot send functions to the browser.

|Callback|Payload|
|--|--|
|`onChoiceRecorded`|`snapshot`, the state after the choice; `confirmed`, the categories this action recorded; `actionAt`, the time.|
|`onPermissionsChanged`|`snapshot`, the state after the change; `previous`, the permissions before it.|
|`onError`|`error`, a message string.|
|`onBeforeConsentRevocationReload`|`preferences`, the permissions after the withdrawal.|

Callbacks run after c15t updates its own state, so `snapshot` and
`getConsentManager()` already hold the new values. Visitor actions happen in
the browser, so in practice that is where the callbacks run.

`onBeforeConsentRevocationReload` runs synchronously right before the reload.
Keep it short; the page is about to unload. It does not run when you set
`reloadOnConsentRevoked={false}`.

## Script callbacks

Each entry in `scripts` takes its own callbacks:

|Callback|Runs|
|--|--|
|`onBeforeLoad`|Before the loader adds the script.|
|`onLoad`|When the script loaded.|
|`onError`|When the script failed to load.|
|`onConsentChange`|When consent changes after the script loaded. Use it to call the vendor's own consent API.|
|`onDispose`|When the configuration is removed or the provider unmounts.|

Helpers from `@c15t/integrations` already set these for their vendor.
[Building integrations](/docs/integrations/building-integrations) shows how to
write them.

## Listen inside one component

For a component that shows or reacts to consent, subscribe to a kernel event
in `$effect`, so the listener goes away with the component. The
[context getters](./getters#listen-to-consent-events) page has the example.
For values you render, read the manager's properties instead; they update the
component without a listener.

## Verify the callbacks

Open the console, clear site data and reload:

1. Accept in the banner. `onChoiceRecorded` and `onPermissionsChanged` both
   log.
2. Dismiss a notice, if your policy shows one. Neither logs.
3. Withdraw a category you allowed. `onBeforeConsentRevocationReload` logs,
   then the page reloads.

# Components
URL: https://c15t.com/docs/shared/svelte/components
Import every component from `@c15t/svelte`, except the dev tools panel, which comes from `@c15t/svelte/devtools`. Render them inside the provider: `ConsentProvider` in a Svelte app, or `ConsentRoot`, which renders `ConsentProvider`, in a SvelteKit root layout. A component outside it throws `c15t: no v3 consent context`.

## Every component

Import every component from `@c15t/svelte`, except the dev tools panel,
which comes from `@c15t/svelte/devtools`. Render them inside the provider:
`ConsentProvider` in a Svelte app, or `ConsentRoot`, which renders
`ConsentProvider`, in a SvelteKit root layout. A component outside it throws
`c15t: no v3 consent context`.

|Component|Renders|Page|
|--|--|--|
|`ConsentBanner`|The first-layer banner when the policy asks for one.|[ConsentBanner](./components/consent-banner)|
|`ConsentDialog`|The preference dialog, loaded on first use.|[ConsentDialog](./components/consent-dialog)|
|`ConsentWidget`|The preference controls inline, for a settings page.|[ConsentWidget](./components/consent-widget)|
|`ConsentDialogLink`|An unstyled button that opens preferences, for your footer.|[ConsentDialogLink](./components/consent-dialog-link)|
|`ConsentDialogTrigger`|A floating, draggable button that opens preferences.|[ConsentDialogTrigger](./components/consent-dialog-trigger)|
|`ConsentGate`|Its children only while a category is allowed.|[ConsentGate](./components/consent-gate)|
|`ConsentButton`|A button that accepts, rejects, saves or opens preferences.|[ConsentButton](./components/consent-button)|
|`IABConsentBanner`|The IAB TCF banner, for visitors under an IAB policy.|[IABConsentBanner](./components/iab-consent-banner)|
|`IABConsentDialog`|The IAB TCF preference center.|[IABConsentDialog](./components/iab-consent-dialog)|
|`ConsentDevTools`|A development panel for the consent state.|[Dev tools](./components/dev-tools)|
|`Dialog`, `Switch`, `Tabs` and others|Unstyled building blocks for your own UI.|[Primitives](./components/primitives)|

`DevTools` and `C15TDevTools` are aliases for `ConsentDevTools`.

## Styles

There is no stylesheet to import. Each stock component adds the rules it
uses to `<head>` as a `<style>` element, once per page, before its own
elements render. On a server-rendered SvelteKit page, `c15tHandle` writes the
banner's rules into the HTML, so the banner is styled before hydration. The
dialog's rules, including the primitives', load with the dialog's code.

The IAB TCF banner and dialog also add their own rules. The IAB dialog adds
its rules when it opens, and includes the base rules it needs when rendered
without a banner. Pages without IAB components do not load the IAB sheets.

To run the stylesheet through Tailwind CSS 3 or put it in a named cascade
layer, set `styles={false}` on the provider and import
`@c15t/svelte/styles.css`. With IAB TCF, also import
`@c15t/svelte/iab/styles.css` after the base stylesheet;
[stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when.

## When components render nothing

Every consent surface stays hidden until a policy resolves for the visitor,
and again when the resolved policy asks for no prompt and grants no way to
change preferences. A missing banner or link is usually a policy result, not
a rendering bug. See
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

## Shared props

Several props mean the same thing on every component:

|Prop|Behavior|
|--|--|
|`noStyle`|Renders the same markup and behavior without c15t's classes. Set it on the provider for every component, or on one component.|
|`class`|Adds your class to the component's root element.|
|`hideBranding`|Hides the "Secured by" tag on the banner, dialog and widget.|
|`models`|The policy models a surface renders for: `opt-in`, `opt-out`, `iab` and `none`.|
|`legalLinks`|Which of the provider's legal links a banner or dialog shows, or `null` for none.|

Theme slots style one part of one component; [customize](./customize) lists
them.

# Consent Banner
URL: https://c15t.com/docs/shared/svelte/components/consent-banner
`variant` and `position` set the shape for one banner. The provider's `presentation` prop sets them for every surface; a prop on `ConsentBanner` wins. This banner is a full-width bar along the bottom edge:

## Change the shape

`variant` and `position` set the shape for one banner. The provider's
`presentation` prop sets them for every surface; a prop on `ConsentBanner`
wins. This banner is a full-width bar along the bottom edge:

```svelte title="src/lib/cookie-banner.svelte"
<script lang="ts">
	import { ConsentBanner } from '@c15t/svelte';
</script>

<!-- The stock banner, drawn as a full-width bar along the bottom edge. -->
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

A notice defaults to `bar` and a choice prompt to `floating`. A position that
does not fit the variant falls back to the variant's default and logs a
warning in development. When the page's text direction is right to left and
you set no position, a corner position flips to the other side.

The [design gallery](/docs/customization/recipes) has more banner designs
with tested Svelte code.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating'`, `'bar'`, `'widget'` or `'wall'`|from the policy|Shape of the banner.|
|`position`|see the table above|the variant's default|Where the banner sits.|
|`blocking`|`boolean`|`false`|Adds a backdrop, locks scrolling, traps focus and ignores outside clicks. `wall` is always blocking; a notice never is.|
|`layout`|array of `'accept'`, `'reject'`, `'customize'`, `'dismiss'` or nested groups|from the policy|Button order and grouping, such as `[['reject', 'accept'], 'customize']`.|
|`primaryButton`|one action or an array|from the policy|Which buttons get the primary style.|
|`title`, `description`|`string`|translated copy|Replace the heading and body for this banner.|
|`acceptButtonText`, `rejectButtonText`, `customizeButtonText`, `dismissButtonText`|`string`|translated copy|Replace one button label for this banner.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description. `null` shows none.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab']`|Policy models this banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes, keeping markup and behavior.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The policy wins where it conflicts with `layout` or `primaryButton`. A policy
that requires a reject button next to accept keeps it, whatever the layout
says. For copy used across the site, use the provider's `i18n` or your
backend's translations; see [translations](../translations).

## When the banner shows

`ConsentBanner` renders when all of these are true:

* A policy has resolved for the visitor and it asks for a prompt.
* The visitor has not chosen yet, or the policy asks them to choose again.
* The active surface is the banner, not the dialog or nothing.
* The policy's model is in `models`.

A visitor in a region without a consent law, or one who already chose, gets
no banner. That is a policy result; see
[why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).

A choice prompt shows Accept, Reject and Customize, in the order the policy
asks for. A notice, such as an opt-out policy that only informs, shows a
dismiss button and its own title and description from the `noticeTitle` and
`noticeDescription` translations. Dismissing a notice records the dismissal,
not a grant.

When the policy grants visitor rights, such as opting out of sale, the banner
shows each one as a text button that opens the preference dialog.

Accept and Reject record the choice and close the banner in the same task.
The backend request runs after; a failed request is retried and does not
reopen the banner. Customize opens `ConsentDialog`, so render the dialog too.

## Accessibility

* The banner card is a `region` labelled by the banner title. With `blocking`,
  it becomes a `dialog` with `aria-modal="true"`, and focus stays inside it
  until the visitor chooses.
* The title is an `h2`. Buttons are `<button type="button">` with their
  visible text as the accessible name.
* The banner does not move focus when it appears, unless focus trapping is on.
  Visitors reach it with Tab.
* With `prefers-reduced-motion`, the banner appears and leaves without a
  transition.
* The root sets `dir` from the active language, so right-to-left copy lays out
  correctly.

## Style the banner

`ConsentBanner` reads these theme slots from the provider's `theme` prop:
`consentBanner`, `consentBannerCard`, `consentBannerHeader`,
`consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`,
`consentBannerFooterSubGroup`, `consentBannerRights` and
`consentBannerRightLink`. [Customize](../customize) shows how to pass them.

The root element carries `data-testid="consent-banner-root"` and these
attributes for CSS and tests:

|Attribute|Value|
|--|--|
|`data-prompt`|`choice` or `notice`|
|`data-model`|`opt-in`, `opt-out` or `iab`|
|`data-variant`|the resolved variant|
|`data-position`|the resolved position|
|`data-blocking`|`true` when blocking|

Each button carries `data-action` with `accept`, `reject`, `customize` or
`dismiss`.

# Consent Button
URL: https://c15t.com/docs/shared/svelte/components/consent-button
`ConsentButton` is a button that performs one consent action, styled like the banner's buttons. Use it on a cookie policy page, an onboarding step or anywhere visitors should accept, reject or open preferences outside the banner:

## Put consent actions on your own pages

`ConsentButton` is a button that performs one consent action, styled like the
banner's buttons. Use it on a cookie policy page, an onboarding step or
anywhere visitors should accept, reject or open preferences outside the
banner:

```svelte title="src/lib/cookie-choices.svelte"
<script lang="ts">
	import { ConsentButton, ConsentDialog } from '@c15t/svelte';
</script>

<section aria-labelledby="cookie-choices">
	<h2 id="cookie-choices">Cookie choices</h2>
	<ConsentButton action="accept-consent" variant="primary" mode="filled">
		Accept all
	</ConsentButton>
	<ConsentButton action="reject-consent">Reject optional</ConsentButton>
	<ConsentButton action="open-consent-dialog" mode="ghost">
		Choose cookies
	</ConsentButton>
</section>
<ConsentDialog />
```

Render it inside `ConsentProvider`. A button with
`action="open-consent-dialog"` needs a mounted `ConsentDialog`.

## Props

`ConsentButton` also passes any `<button>` attribute through, such as `id`,
`disabled` or `aria-describedby`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`action`|see below|required|What the click does.|
|`category`|`AllConsentNames`|none|The category `set-consent` switches on.|
|`variant`|`'primary'` or `'neutral'`|`'neutral'`|Color emphasis.|
|`mode`|`'filled'`, `'stroke'`, `'lighter'` or `'ghost'`|`'stroke'`|Fill style.|
|`size`|`'medium'`, `'small'`, `'xsmall'` or `'xxsmall'`|`'small'`|Button size.|
|`closeConsentBanner`, `closeConsentDialog`|`boolean`|`false`|Close both surfaces after `dismiss-notice`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs first. Call `event.preventDefault()` to skip the action.|
|`children`|`Snippet`|none|The label.|

|`action`|Effect|
|--|--|
|`accept-consent`|Records every category in scope as allowed.|
|`reject-consent`|Records only `necessary`, rejecting the rest.|
|`custom-consent`|Records the current draft, as the dialog's save button does.|
|`dismiss-notice`|Records that the visitor dismissed a notice. Not a grant.|
|`open-consent-dialog`|Opens the preference dialog.|
|`set-consent`|Switches `category` on in the unsaved draft. Nothing is recorded until a save.|

## Behavior

Accept, reject and save record the choice in the same task as the click, and
the banner or dialog that showed closes. The backend request runs after. A
failed request is reported through the provider's `onError` callback and
retried; the click handler does not throw. A save refused because the policy
changed keeps the dialog open for review.

A button with `open-consent-dialog` starts loading the dialog chunk in idle
time while mounted, and on hover or focus.

## Accessibility

`ConsentButton` renders `<button type="button">` with its children as the
accessible name. Write labels that say what happens: "Accept all" records a
choice, "Choose cookies" opens preferences. Do not label a notice dismissal
"Accept". [Copy and translations](/docs/customization/translations#write-labels-that-describe-the-action)
has more guidance.

## Style the button

The button uses c15t's button classes and the `buttonPrimary` or
`buttonSecondary` theme slot, by `variant`. It carries `data-variant`,
`data-mode` and `data-size` for CSS. With `noStyle`, it renders with only
your `class` and none of those attributes.

# Consent Dialog
URL: https://c15t.com/docs/shared/svelte/components/consent-dialog
`ConsentDialog` is not part of the first page load. The component you render is a small loader; the dialog itself is a separate chunk that it imports:

## How the dialog loads

`ConsentDialog` is not part of the first page load. The component you render
is a small loader; the dialog itself is a separate chunk that it imports:

* In browser idle time after the page's `load` event, while a button that
  opens the dialog is mounted. Those buttons are the banner's Customize button,
  `ConsentDialogLink`, `ConsentDialogTrigger`, the `ConsentGate` placeholder
  and `ConsentButton` with `action="open-consent-dialog"`.
* When such a button is hovered or focused.
* At the latest, when the dialog opens.

Set the provider's `preloadDialog` to `'intent'` to skip the idle load and
load only on hover, focus or open. Idle loading is also skipped when the
browser asks to save data, on 2G connections and offline. Every
`ConsentDialog` on the page shares one import. If the import fails, the
surface the dialog replaced comes back, and the next hover, focus or open
retries. The dialog's CSS travels with that chunk and goes into `<head>`
before the dialog renders. With `styles={false}`, it comes from your imported
`@c15t/svelte/styles.css`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself. While `open` is `true`, the dialog stays open, even after Escape.|
|`showTrigger`|`boolean` or trigger props|`false`|Renders a floating `ConsentDialogTrigger` with the dialog. Pass an object for `defaultPosition`, `persistPosition`, `showWhen`, `size`, `ariaLabel`, `noStyle` and `class`.|
|`legalLinks`|array of `LegalLinks` keys, or `null`|every configured link|Which of the provider's `legalLinks` to show after the description.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['opt-in', 'opt-out', 'iab', 'none']`|Policy models the dialog opens for. `none` is included so a policy with no prompt but a right to change preferences still opens it.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the dialog content.|

`ConsentDialog` has no text props. Its title and description come from the
`consentManagerDialog` translations; see [translations](../translations).

With `showTrigger`, the dialog loads when it mounts, because the trigger needs
it at once. The trigger appears right after hydration. To keep a trigger in
server HTML, render `ConsentDialogTrigger` next to the dialog instead.

## What the dialog contains

The dialog renders the heading, the description with legal links, and a
[`ConsentWidget`](./consent-widget) with one switch per category and the save
buttons the policy allows. Categories come from the provider's
`consentCategories`, limited to the policy's scope. `necessary` is always on
and cannot be switched off.

Switches change an unsaved draft. The save button records the draft; the
accept and reject buttons record every category at once. The dialog closes in the same task
the choice is recorded. If the policy changes while the dialog is open, the
widget shows an alert and asks the visitor to review before saving.

## Open and close the dialog

Anything that sets the active surface to `'dialog'` opens it: the banner's
Customize button, `ConsentDialogLink`, `ConsentDialogTrigger`,
`getConsentManager().setActiveUI('dialog')` or
`getHeadlessConsent().openDialog()`.

Escape closes the dialog. Clicks outside it do not, so a visitor cannot lose
unsaved switches by accident. Closing without saving records nothing. If the
policy still owes a choice, the banner comes back.

With the `open` prop set, your component owns visibility. Escape then moves
the active surface off `'dialog'`, to `'banner'` while a choice is still owed
or `'none'` otherwise, and the dialog stays mounted until you set `open` to
`false`. Watch `getConsentManager().activeUI` to close it.

## Accessibility

* The dialog content is labelled by its title (`aria-labelledby`) and
  described by its description (`aria-describedby`).
* While the dialog is blocking, which is the default, focus is trapped inside
  it and the page behind does not scroll. The provider's `presentation` can
  turn blocking off for the dialog.
* Each category switch is a `switch` role labelled with the category title.
* The root sets `dir` from the active language.

## Style the dialog

`ConsentDialog` reads these theme slots: `consentDialog`, `consentDialogCard`,
`consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`,
`consentDialogContent` and `consentDialogTag`. The widget inside it reads the
`ConsentWidget` slots. The content element carries
`data-testid="consent-dialog-root"` and `data-blocking="true"` while
blocking.

# Consent Dialog Link
URL: https://c15t.com/docs/shared/svelte/components/consent-dialog-link
`ConsentDialogLink` takes its label as children and passes every other attribute, such as `class`, `id` or `aria-describedby`, to the `<button>` it renders.

## Props

`ConsentDialogLink` takes its label as children and passes every other
attribute, such as `class`, `id` or `aria-describedby`, to the `<button>` it
renders.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`children`|`Snippet`|required|The visible label, such as "Privacy settings".|
|`noStyle`|`boolean`|`true`|Unstyled by default so it matches your footer links. Set `false` for c15t's button style.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it opening.|
|any button attribute|||Passed to the `<button>`.|

There is no `asChild`. To style it like your links, give it the same class,
and reset the button's border, background and padding in that class.

## Behavior

* The link renders only when the policy offers a way to change preferences:
  a prompt or a visitor right. Visitors in a
  region with no consent law and no rights see no link.
* A click sets the active surface to `'dialog'`. It needs a mounted
  `ConsentDialog` in the same provider to show anything.
* It starts loading the dialog chunk in browser idle time while mounted, and
  on hover or focus. See [ConsentDialog](./consent-dialog#how-the-dialog-loads).

## Accessibility

The link is a `<button type="button">`, so keyboard users reach it with Tab
and activate it with Enter or Space. Its accessible name is its text. Keep the
text specific, such as "Privacy settings" or "Cookie preferences", rather
than "Click here".

## Style the link

The button carries `data-testid="consent-dialog-link"` and
`data-c15t-rights` with the rights the policy grants, separated by spaces.
Style it with your own class; with `noStyle` on, c15t adds no classes.

# Consent Dialog Trigger
URL: https://c15t.com/docs/shared/svelte/components/consent-dialog-trigger
`ConsentDialogTrigger` is a small round button, fixed to a corner of the viewport, that opens the preference dialog. It keeps preferences one click away on every page without a footer link. Render it next to `ConsentDialog`:

## Add a floating privacy button

`ConsentDialogTrigger` is a small round button, fixed to a corner of the
viewport, that opens the preference dialog. It keeps preferences one click
away on every page without a footer link. Render it next to `ConsentDialog`:

```svelte title="src/lib/privacy-trigger.svelte"
<script lang="ts">
	import { ConsentDialog, ConsentDialogTrigger } from '@c15t/svelte';
</script>

<!-- A floating button in the bottom-left corner that opens preferences.
     Visitors can drag it to another corner; c15t remembers where. -->
<ConsentDialogTrigger defaultPosition="bottom-left" size="sm" />
<ConsentDialog />
```

Render the component inside `ConsentProvider`. `ConsentDialog`'s
`showTrigger` prop renders the same button for you, but only after the dialog
chunk loads; a separate `ConsentDialogTrigger` is part of the page from the
first render.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`defaultPosition`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|The corner it starts in.|
|`persistPosition`|`boolean`|`true`|Remembers the corner a visitor drags it to, in local storage.|
|`showWhen`|`'always'` or `'never'`|`'always'`|`'never'` hides it.|
|`size`|`'sm'`, `'md'` or `'lg'`|`'md'`|Button size.|
|`ariaLabel`|`string`|`'Open privacy settings'`|Accessible name. Translate it yourself; it does not come from `i18n`.|
|`noStyle`|`boolean`|`false`|Drops c15t's classes, including the fixed positioning.|
|`class`|`string`|none|Extra class on the button.|
|`onclick`|`(event: MouseEvent) => void`|none|Runs before the dialog opens. Call `event.preventDefault()` to stop it.|
|`onPositionChange`|`(corner) => void`|none|Runs after a drag moves it to another corner.|

## Behavior

* The button renders only when the policy offers a way to change preferences,
  and hides while the dialog is open.
* Visitors can drag it. On release it snaps to the nearest corner in the
  direction of the drag. A drag does not open the dialog; a click does.
* The icon follows the project's branding.
* It is rendered into `document.body`, so a parent's `overflow` or
  `transform` does not clip it.
* It starts loading the dialog chunk in idle time and on hover or focus, like
  the other buttons that open the dialog.
* While `ConsentDevTools` is mounted, it becomes a two-button toolbar: the
  preferences button stays in the corner and a DevTools button sits beside it.
  The DevTools panel opens next to the toolbar instead of from its own
  launcher. See [DevTools](./dev-tools).

## Accessibility

The trigger is a `<button type="button">` with `aria-label`, since it shows
only an icon. Keep the label in the page's language by passing `ariaLabel`.
Dragging needs a pointer; keyboard users activate it with Enter or Space and
cannot move it, so pick a `defaultPosition` that does not cover your own
controls.

## Style the trigger

The button carries `data-testid="consent-dialog-trigger"`,
`data-c15t-trigger="true"` and `data-c15t-rights`. Its colors come from the
`--c15t-*` tokens; [theme tokens](/docs/customization/tokens) lists them.

# Consent Gate
URL: https://c15t.com/docs/shared/svelte/components/consent-gate
`ConsentGate` renders a `<div>` wrapper. Inside it, it renders the children while the visitor's effective permission for `category` is granted, and the placeholder otherwise. The permission is the same value as `getConsentManager().has(category)`. It can be granted before the visitor chooses, under an opt-out policy, and a recorded grant can be overridden by a privacy signal such as Global Privacy Control.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`category`|`AllConsentNames`|required|The category whose permission the content needs, such as `'measurement'` or `'marketing'`.|
|`children`|`Snippet`|none|The gated content. It is not in the DOM until the category is allowed.|
|`placeholder`|`Snippet`|built-in placeholder|Shown while the category is denied.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes from the built-in placeholder.|
|`class`|`string`|none|Class on the wrapper `<div>` that stays in the page in every state.|

## Behavior

`ConsentGate` renders a `<div>` wrapper. Inside it, it renders the children
while the visitor's effective permission for `category` is granted, and the
placeholder otherwise. The permission is the same value as
`getConsentManager().has(category)`. It can be granted before the visitor
chooses, under an opt-out policy, and a recorded grant can be overridden by a
privacy signal such as Global Privacy Control.

* While the category is denied, the children are absent from the DOM, so an
  iframe inside sends no request.
* When the visitor allows the category, the children mount. No reload.
* When the visitor withdraws it, the children unmount and the embed stops.
* Until the component has mounted in the browser, the wrapper is empty. The
  server HTML never contains the children or the placeholder, and the browser
  fills the wrapper one frame after mount.

The built-in placeholder shows `Accept {category} consent to view this content.`
and a button labelled `Enable {category} consent`, with the category's
translated title in place of `{category}`. The copy comes from the
`consentGate.title` and `consentGate.actionButton` translations. The button opens the
preference dialog; it does not grant the category, so mount `ConsentDialog`
in the same provider.

`ConsentGate` does not add its category to the preference dialog. Keep the
category in your policy's scope, and in `consentCategories` if you set that
prop.

## Accessibility

The built-in placeholder is plain text and a `<button>`, so it works without
the embed. Give the iframe a descriptive `title`, and give visitors who
decline another way to the content, such as a link to the video's page or a
store address next to the map. A category the policy blocks cannot be allowed
from preferences.

## Style the placeholder

Set `class` on `ConsentGate` to size the wrapper to the embed, for example an
`aspect-ratio` for a video, so the page does not shift when the embed
replaces the placeholder.

To restyle the built-in placeholder, set the `consentGate` slot for the card,
`consentGateTitle` and `consentGateButton` in the provider's `theme.slots`.
`consentGateButton` applies on top of `buttonPrimary`:

```ts
const theme = {
	slots: {
		consentGate: 'brand-gate',
		consentGateButton: { className: 'brand-gate-button' },
	},
};
```

The built-in placeholder carries `data-testid="consent-gate-placeholder"`,
its title `data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`. For a different design, pass your own
`placeholder` snippet.

# Consent Provider
URL: https://c15t.com/docs/shared/svelte/components/consent-provider
Pass each option as a top-level prop, or group them in `options`. When both set the same option, the top-level prop wins. The `ConsentManagerOptions` type from `@c15t/svelte` lists every option. SvelteKit's `ConsentRoot` takes the same props, except that `state` replaces `mode` and `prefetch`.

## Props

Pass each option as a top-level prop, or group them in `options`. When both
set the same option, the top-level prop wins. The `ConsentManagerOptions` type
from `@c15t/svelte` lists every option. SvelteKit's `ConsentRoot` takes the
same props, except that `state` replaces `mode` and `prefetch`.

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`mode`|`manifest()`, `hosted()`, `offline()` or `custom()` result, all from `@c15t/svelte`|required|Where policies come from and where choices are saved. Read once; remount the provider to change it. `ConsentRoot` builds it from `state`, or takes a `custom()` transport as `mode`.|
|`prefetch`|`ConsentState`|none|Server-resolved state, such as the result of `resolveConsent`. With a resolved policy in it, the first render already knows whether to show the banner, and the browser skips its own policy request. `ConsentRoot` passes it from `state`. Read once.|
|`scripts`|`Script[]`|none|Vendor scripts that load when their category is allowed. Updates after mount: new scripts go to the loader. See [scripts](../scripts).|
|`consentCategories`|`AllConsentNames[]`|the policy's categories|Categories the preference UI offers, within the policy's scope. Updates after mount.|
|`theme`|`Theme`|none|Slot classes and `consentActions` button styles. Design tokens in it are not applied in the browser. Updates after mount.|
|`presentation`|`ConsentPresentation`|the policy's defaults|Banner and dialog shape, position, button layout and blocking for every component. Updates after mount.|
|`legalLinks`|`LegalLinks`|none|Privacy policy, cookie policy and terms links shown in the banner and dialog. Updates after mount.|
|`i18n`|`Partial<I18nConfig>`|bundled English|Copy overrides per language. They win key by key over the backend's copy for the same language; see [translations](../translations). Read once.|
|`colorScheme`|`'light'`, `'dark'`, `'system'` or `null`|none|Toggles the `c15t-dark` class on `<html>`. `null` or unset leaves `<html>` alone. Updates after mount.|
|`noStyle`|`boolean`|`false`|Renders every component without c15t's classes. A component's own `noStyle` wins.|
|`disableAnimation`|`boolean`|follows `prefers-reduced-motion`|Turns off enter and exit transitions.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Defaults for the banner and dialog. `blocking` on a component sets both.|
|`preloadDialog`|`'idle'` or `'intent'`|`'idle'`|When `ConsentDialog` starts loading before its first open. See [ConsentDialog](./consent-dialog).|
|`networkBlocker`|options or `false`|off|Holds `fetch` and XHR requests to listed domains until their category is allowed. Updates after mount: new rules and `enabled` apply, and `false` removes the blocker. The blocker loads on demand. See [network blocker](../network-blocker).|
|`iframeBlocker`|`{ disableAutomaticBlocking?: boolean }` or `false`|on|Gates iframes that carry `data-category`. Updates after mount: `false` removes the blocker and a new `disableAutomaticBlocking` rebuilds it. See [embeds](../embeds).|
|`iab`|`ProviderIABOptions` or `false`|off|IAB TCF settings. Read once. See [IAB TCF](../iab).|
|`callbacks`|`ConsentProviderCallbacks`|none|`onChoiceRecorded`, `onPermissionsChanged`, `onError` and `onBeforeConsentRevocationReload`. The latest functions are called. See [callbacks](../callbacks).|
|`reloadOnConsentRevoked`|`boolean`|`true`|Reloads the page after a save withdraws a category or vendor that was granted.|
|`overrides`|`{ country?, region?, language?, gpc? }`|none|Forces the location, language or Global Privacy Control signal the policy resolves for. A change after mount resolves the policy again.|
|`user`|`User`|none|Identity sent with the policy request and every saved choice, so the choice is linked to your user ID. A different user after mount is identified with the backend; the user you mount with is not identified separately.|
|`storageConfig`|`StorageConfig`|cookie and key `c15t`|Names and lifetime of the stored choice. Read once. On SvelteKit, pass the same name as `cookieName` to the server helpers.|
|`persistence`|`boolean` or options|`true`|`false` keeps choices in memory only. Read once.|
|`clearOnRevocation`|`ClearOnRevocationConfig`|off|Deletes first-party cookies and storage entries when their category is withdrawn. Loads on demand. See [clearing data on revocation](../clear-on-revocation). Read once.|
|`vendors`|`Vendor[]`|none|Vendors offered for vendor-level consent outside IAB. See [vendor consent](../vendor-consent). Updates after mount: a new list replaces the declared vendors.|
|`nonce`|`string`|none|Content Security Policy nonce for the `<script>` elements the script loader adds. See [Content Security Policy](../content-security-policy). Read when the loader starts.|
|`enabled`|`boolean`|`true`|`false` grants every category, hides all consent UI and skips `/init`. Updates after mount: turning it off renders a separate permissive state and keeps the visitor's stored choice for when it is turned back on.|
|`runtime`|`ConsentRuntime`|none|A runtime you created with `createConsentRuntime()`. See [share one runtime](#share-one-runtime).|
|`options`|`ConsentManagerOptions`|none|The same options as one object.|
|`children`|`Snippet`|none|Your app. The provider renders no markup of its own.|

"Read once" options are read when the provider is created. Changing them later
has no effect until the provider remounts, and outside production a change to
`mode`, `i18n` or `experiment` logs a warning. Options that update after mount
are compared with their previous values, so a new `options` object that only
changes `theme` sends no request. The provider has no `policyRules`
option. For local policy rules, pass `offline({ policyRules })` as `mode`.

## What the provider does when it mounts

The provider creates the consent runtime while the component initializes, on
the server and in the browser. Creating it has no side effects, so the server
can render the banner from `prefetch`. In the browser, `onMount` starts the
runtime:

1. It reads the stored choice from the cookie and local storage.
2. It starts the script loader, the iframe blocker and, if configured, the
   network blocker and the IAB TCF add-on.
3. It resolves the policy with its `mode`, unless `prefetch` already holds
   one.

When the provider unmounts, it stops all of them. Keep one provider at the root of the app, so it stays mounted across
navigation and every component can reach it.

With `networkBlocker`, matching requests are held from the moment the provider
is created in the browser, before its children run their own code, until the
blocker decides them.

## Share one runtime

Pass `runtime` when two component trees that cannot share Svelte context need
the same consent state. Create it with `createConsentRuntime()` from
`@c15t/svelte`, pass it to each provider, and call `runtime.start()` and
`runtime.dispose()` yourself. A provider never starts or disposes a runtime it
did not create. Options that build the runtime, such as `mode`, `scripts` and
`callbacks`, come from your `createConsentRuntime()` call; display options such
as `theme` and `noStyle` still apply per provider.

## Verify the provider

Open the page in a private window with DevTools open:

1. The banner appears once the policy resolves. `window.c15t` in the console
   shows `pkg: '@c15t/svelte'`.
2. The Network panel shows the request your mode makes: none for
   `manifest()` with a bundled snapshot, one `/init` for `hosted()`, and
   none when the page came with a server-resolved state.
3. A component that calls `getConsentManager()` renders without the
   `c15t: no v3 consent context` error.

# Consent Widget
URL: https://c15t.com/docs/shared/svelte/components/consent-widget
`ConsentWidget` renders the preference controls inline: one switch per category, an expandable description for each, and the save buttons the policy allows. It is the same widget `ConsentDialog` shows, without the dialog around it. Use it for a privacy settings page:

## Put preferences on a page

`ConsentWidget` renders the preference controls inline: one switch per
category, an expandable description for each, and the save buttons the policy
allows. It is the same widget `ConsentDialog` shows, without the dialog
around it. Use it for a privacy settings page:

```svelte title="src/routes/privacy/+page.svelte"
<script lang="ts">
	import { ConsentWidget } from '@c15t/svelte';
</script>

<h1>Privacy settings</h1>
<p>Choose which optional cookies this site may use.</p>
<!-- The category switches and save buttons, inline on the page. -->
<ConsentWidget />
```

Render the page inside `ConsentProvider`. The widget works without
`ConsentDialog`, but keep the dialog mounted elsewhere if the banner's
Customize button should also work.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Shows the "Secured by" tag when `false`.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

`ConsentWidget` renders nothing until a policy resolves and asks for consent
UI. Then it lists the provider's `consentCategories`, limited to the policy's
scope, with `necessary` always on and disabled.

Each switch starts from the visitor's recorded choice. Before a choice, a
switch is on under an opt-out policy or for a category the policy preselects,
and off otherwise. Moving a switch changes an unsaved draft
that every consent component on the page shares. The save button records the
draft; the accept and reject buttons record every category at once.

A category with declared vendors lists them under its description, each with
its own switch, so a visitor can allow a category and still turn one vendor
off. Under an IAB policy, vendor rows are not shown.

If the policy changes while the visitor has unsaved changes, the widget shows
an alert with a **Review preferences** button. Saving the stale draft fails
until the visitor reviews it, so a choice made under the old policy is never
recorded under the new one.

## Accessibility

* Each category switch has the `switch` role and the category title as its
  accessible name.
* Each category heading is a button with `aria-expanded` that opens its
  description. Opening one closes the others.
* The stale-policy message uses `role="alert"`, so screen readers announce it.

## Style the widget

`ConsentWidget` reads the `consentWidget` and `consentWidgetFooter` theme
slots. The root carries `data-testid="consent-widget-root"`, and each
category row carries `data-testid="consent-widget-accordion-item-<category>"`.

# Dev Tools
URL: https://c15t.com/docs/shared/svelte/components/dev-tools
The panel is a floating inspector for the provider's consent runtime. Its tabs:

## What the panel shows

The panel is a floating inspector for the provider's consent runtime. Its
tabs:

|Tab|Shows|
|--|--|
|`consents`|Effective permissions and the recorded choice per category, with switches to stage and save a test choice.|
|`scripts`|Each registered script and its loading state.|
|`location`|The country, region and language the policy resolved for, with overrides to test another location.|
|`policy`|The resolved policy rule, its model, prompt, scope and rights.|
|`iab`|The TCF state, when IAB is on.|
|`events`|The consent runtime's events and script lifecycle events.|
|`actions`|Buttons to open the banner or dialog, reset the draft, clear stored records and resolve the policy again.|

Clearing records from the panel deletes the stored choice through the
provider's storage settings, so a custom `storageConfig` is respected.
Location overrides from the panel change the current page only.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'bottom-right'`, `'bottom-left'`, `'top-right'` or `'top-left'`|`'bottom-right'`|Corner of the panel's toggle.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|one of the tabs above|`'consents'`|The tab it opens on.|
|`maxEvents`|`number`|`100`|How many events the `events` tab keeps.|
|`getConsentCategories`|`() => AllConsentNames[]`|the provider's categories|Categories the `consents` tab lists.|
|`getPresentation`|`() => ConsentPresentation`|the provider's `presentation`|Presentation used for the panel's diagnostics.|
|`clearRecords`|`() => void`|the provider's own|Replaces what the clear action does.|
|`shadow`|`boolean`|`true`|`false` mounts the panel without a shadow root.|

By default the panel renders inside a shadow root with its own stylesheet,
so your CSS does not restyle it and its CSS does not leak into the page.
`shadow={false}` mounts the panel in the light DOM instead and puts its
stylesheet in `<head>`.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar with
a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end of the
toolbar farthest from its corner. The panel opens just past the toolbar,
aligned with its outer edge, and follows it when a visitor drags the toolbar
to another corner. `position` applies again once no trigger is visible. The
trigger that `ConsentDialog`'s `showTrigger` prop renders behaves the same
way.

DevTools brings its launcher back whenever no trigger is visible, for example
with `showWhen="never"` or while the dialog is open. A production build that
loads DevTools only in development shows no DevTools button in the trigger.

## Keep it out of production

The panel can clear consent and change the location the policy resolves for.
Render it in development only. Importing `@c15t/svelte/devtools` statically
puts the panel in every bundle that imports the file, so import it
dynamically behind a development check, as the example above does.

# Iab Consent Banner
URL: https://c15t.com/docs/shared/svelte/components/iab-consent-banner
`IABConsentBanner` is the first layer of the IAB TCF 2.4 consent flow. It lists the purposes, special features and number of vendors from the Global Vendor List, and offers Accept All, Reject All and Customize. It renders only for visitors whose resolved policy uses the `iab` model, so render it next to the standard `ConsentBanner`, which covers everyone else:

## Show the TCF banner

`IABConsentBanner` is the first layer of the IAB TCF 2.4 consent flow. It
lists the purposes, special features and number of vendors from the Global
Vendor List, and offers Accept All, Reject All and Customize. It renders only
for visitors whose resolved policy uses the `iab` model, so render it next to
the standard `ConsentBanner`, which covers everyone else:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

Turn IAB on with the provider's `iab` prop first; [IAB TCF](../iab) covers the
CMP ID, the vendor list and the provider options.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'accept'`, `'reject'` or `'customize'`|`'customize'`|Which button gets the primary style.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models the banner renders for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`disableAnimation`|`boolean`|provider's value|Shows and hides without a transition.|
|`scrollLock`, `trapFocus`|`boolean`|from `presentation`|Lock page scroll or trap focus while the banner shows.|
|`class`|`string`|none|Extra class on the root element.|

The banner has no text props. Its copy comes from the IAB translations, in the
visitor's language.

## Behavior

* The banner stays hidden until an IAB policy resolves and the vendor list is
  available. Forcing it does not create either.
* Accept All and Reject All record the visitor's TCF choice and write the TC
  String. The banner closes as soon as the click is handled. It comes back
  only if nothing could be recorded, such as when the vendor list failed to
  load, so the visitor can try again. A failed backend request never reopens
  it.
* Customize opens `IABConsentDialog`, so render it too. The partners link in
  the description opens the dialog on the vendors tab.
* The `__tcfapi` function is available once the TCF add-on loads, whether or
  not the banner is showing, so vendor scripts can read the TC String.

## Accessibility

The banner card is a `region` labelled with the banner title. When focus
trapping is on, through `trapFocus` or a blocking presentation, it becomes a
`dialog` with `aria-modal="true"`. The title is an `h2`, and every control is
a native `<button>`.

## Style the banner

`IABConsentBanner` reads the `iabConsentBanner` theme slot and needs
`@c15t/svelte/iab/styles.css`, loaded after `@c15t/svelte/styles.css`, with
`styles={false}` on the provider.
Buttons carry `data-testid="iab-consent-banner-accept-button"`,
`iab-consent-banner-reject-button` and `iab-consent-banner-customize-button`.

# Iab Consent Dialog
URL: https://c15t.com/docs/shared/svelte/components/iab-consent-dialog
`IABConsentDialog` is the IAB TCF 2.4 preference center. It has two tabs: purposes, with stacks, special features and legitimate interest objections, and vendors, with each vendor's purposes, data retention and privacy policy. Render it next to `IABConsentBanner`; the banner's Customize button opens it:

## Show the TCF preference center

`IABConsentDialog` is the IAB TCF 2.4 preference center. It has two tabs:
purposes, with stacks, special features and legitimate interest objections,
and vendors, with each vendor's purposes, data retention and privacy policy.
Render it next to `IABConsentBanner`; the banner's Customize button opens it:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`open`|`boolean`|follows the consent state|Controls visibility yourself.|
|`initialTab`|`'purposes'` or `'vendors'`|`'purposes'`|The tab it opens on, for example from a "See our partners" link.|
|`hideBranding`|`boolean`|`false`|Hides the "Secured by" tag.|
|`models`|`Model[]`|`['iab']`|Policy models it opens for.|
|`noStyle`|`boolean`|provider's `noStyle`|Drops c15t's classes.|
|`class`|`string`|none|Extra class on the root element.|

## Behavior

* It opens when the active surface is `'dialog'` under an IAB policy, the
  same state `ConsentDialog` uses for other policies. Opening preferences
  from `ConsentDialogLink` therefore shows this dialog to IAB visitors and
  `ConsentDialog` to everyone else.
* Switches change purpose consent, legitimate interest, special feature
  opt-ins and vendor consent in the TCF state. Save writes a new TC String.
* It needs the Global Vendor List. While the list loads,
  `getConsentManager().iab.isLoadingGVL` is `true`.

## Accessibility

The preference center is a `dialog` labelled with its title, with a close
button labelled from the `common.close` translation. Escape closes it. While
it is blocking, which is the default, focus stays inside it and the page does
not scroll. The purposes and vendors tabs are keyboard-operable tabs.

## Style the dialog

It needs `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css`, with
`styles={false}` on the provider. The root carries
`data-testid="iab-consent-dialog-root"`.

# Primitives
URL: https://c15t.com/docs/shared/svelte/components/primitives
The stock consent components are built from a set of unstyled, accessible building blocks that `@c15t/svelte` also exports. Reach for them when you build your own preference dialog or settings page with the [headless getters](../headless) and want the same keyboard and focus behavior as the stock dialog. For the consent state itself, use `getConsentManager()`; the primitives know nothing about consent.

## When to use the primitives

The stock consent components are built from a set of unstyled, accessible
building blocks that `@c15t/svelte` also exports. Reach for them when you
build your own preference dialog or settings page with the
[headless getters](../headless) and want the same keyboard and focus behavior
as the stock dialog. For the consent state itself, use `getConsentManager()`;
the primitives know nothing about consent.

Their rules load with the stock `ConsentDialog`. A page that renders the
primitives without the stock dialog needs `@c15t/svelte/styles.css`: import it
and set `styles={false}` on the provider. Each part accepts `class` and passes
other HTML attributes to its element.

## Compound components

Import each as one object and use its parts, such as `Dialog.Root` and
`Dialog.Content`. Every part is also exported on its own.

|Component|Parts|Root props|
|--|--|--|
|`Dialog`|`Root`, `Portal`, `Backdrop`, `Positioner`, `Content`, `Title`, `Description`, `CloseTrigger`|`open` (bindable, default `false`), `closeOnEscape` (`true`), `closeOnInteractOutside` (`true`), `trapFocus` (`true`), `preventScroll` (`false`), `lazyMount` (`false`), `unmountOnExit` (`false`)|
|`Switch`|`Root`, `Control`, `Thumb`, `HiddenInput`|`checked` (bindable, default `false`), `disabled`, `type` (`'button'`)|
|`Tabs`|`Root`, `List`, `Trigger`, `Content`|`value` (bindable), `orientation` (`'horizontal'`), `loop` (`true`), `disabled`|
|`Accordion`|`Root`, `Item`, `ItemTrigger`, `ItemContent`|`type` (`'single'` or `'multiple'`, required), `value` (bindable), `collapsible` (`false`)|
|`Collapsible`|`Root`, `Trigger`, `Content`, `Indicator`|`open` (bindable, default `false`), `disabled`|
|`PreferenceItem`|`Root`, `Trigger`, `Leading`, `Header`, `Title`, `Meta`, `Auxiliary`, `Control`, `Content`|`open` (bindable, default `false`), `disabled`, `noStyle`|

`Portal` renders its children into another element, `document.body` by
default. Pass `target` as an element or a selector.

## Actions

Three Svelte actions apply the same behavior to your own elements:

|Action|Use|Parameter|
|--|--|--|
|`focusTrap`|`use:focusTrap={open}`|`true`, `false`, or `{ enabled, initialFocus }`. Keeps Tab inside the element while enabled.|
|`scrollLock`|`use:scrollLock={open}`|`boolean`. Stops the page scrolling behind the element.|
|`portal`|`use:portal` or `use:portal={'#modals'}`|An element or selector, default `body`. Moves the element there and removes it when the component unmounts.|

The banner uses these three actions; the stock dialog uses `Dialog`.

## Check your custom dialog

Open it with the keyboard only. Tab and Shift+Tab stay inside it, Escape
closes it, and focus returns to the control that opened it. Each switch
announces its name and state in a screen reader. See the
[headless page](../headless) for the consent side of a custom dialog.

# Content Security Policy
URL: https://c15t.com/docs/shared/svelte/content-security-policy
A Content Security Policy has to allow each thing c15t or your vendors put on the page:

## What c15t adds to the page

A Content Security Policy has to allow each thing c15t or your vendors put on
the page:

|c15t does|Directive|Allow|
|--|--|--|
|Requests the policy from `/init` and saves choices to `/subjects`|`connect-src`|Your backend's origin. `'self'` covers a same-origin route such as `/api/c15t`.|
|Adds a `<script>` element for each allowed entry in `scripts`|`script-src`|Each vendor's script host, or the provider's `nonce`.|
|Lets vendor scripts load more scripts, pixels and requests|`script-src`, `img-src`, `connect-src`|The hosts each vendor documents.|
|Sets `src` on gated iframes, or mounts `ConsentGate` children|`frame-src`|Each embed's host, such as `https://www.youtube-nocookie.com`.|
|Adds its rules to `<head>` as `<style>` elements|`style-src`|The provider's `nonce`. With `styles={false}` and an imported `@c15t/svelte/styles.css`, `'self'`.|
|Fetches the Global Vendor List under an IAB policy|`connect-src`|The vendor list host the policy names, when it is not your own origin.|

The dev tools panel attaches a stylesheet to its shadow root. Keep the panel
out of production builds, as its page describes, and a production policy
does not need to allow it.

## Stamp a nonce on vendor scripts

If your server creates a nonce for each response and puts it in the
`Content-Security-Policy` header as `'nonce-<value>'`, pass the same value to
the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} nonce={cspNonce}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} nonce={cspNonce}>
```

The script loader then sets that nonce on every `<script>` it adds, for both
`src` and inline `textContent` scripts. A `nonce` on one `scripts` entry wins
for that script. The components put it on the `<style>` elements they add.
The provider reads `nonce` once, when it is created.

The nonce covers only the elements c15t creates. A script that a vendor's
script loads by itself does not get it; allow that host in `script-src`, or
add `'strict-dynamic'` so scripts loaded by a trusted script are trusted too.
With `'strict-dynamic'`, browsers ignore host allowlists in `script-src`, so
every script on the page needs the nonce or a hash.

## Verify the policy

Enforce the policy, not report-only, and open the console with site data
cleared:

1. The banner renders with its styles, and no `Refused to` message mentions a
   c15t element, a `<style data-c15t-styles>` element or
   `@c15t/svelte/styles.css`. Open the preference dialog and check again.
2. Allow a category. Its vendor scripts load, and none are refused. A refused
   script from a vendor's own host means that host is missing from
   `script-src`.
3. Save a choice. The request to `/subjects` succeeds; a `connect-src`
   violation means the backend's origin is missing.
4. Allow the category of a gated embed. It loads; a `frame-src` violation
   names the host to add.

# Customize
URL: https://c15t.com/docs/shared/svelte/customize
The provider's `colorScheme` prop switches on the dark token set: `'dark'` always, `'system'` when the operating system prefers dark, `'light'` never. It toggles a `c15t-dark` class on `<html>`. Left unset, the provider copies a `dark` class on `<html>` into `c15t-dark`, so an app with its own dark mode toggle gets the dark tokens without the prop. Pass `null` if your app sets `c15t-dark` itself. Override dark values under `:root.dark` and `:root.c15t-dark` in your stylesheet. [Dark mode](/docs/customization/dark-mode) covers a dark first paint.

## Switch to dark tokens

The provider's `colorScheme` prop switches on the dark token set: `'dark'`
always, `'system'` when the operating system prefers dark, `'light'` never. It
toggles a `c15t-dark` class on `<html>`. Left unset, the provider copies a
`dark` class on `<html>` into `c15t-dark`, so an app with its own dark mode
toggle gets the dark tokens without the prop. Pass `null` if your app sets
`c15t-dark` itself. Override dark values under `:root.dark` and
`:root.c15t-dark` in your stylesheet. [Dark mode](/docs/customization/dark-mode)
covers a dark first paint.

## Style one part with theme slots

The provider's `theme` prop still applies slot styles in the browser. A slot
takes a class name, or `{ className, style, noStyle }`. Svelte applies a
slot's class and `style` on every stock part, including the IAB banner and
dialog:

```ts
const theme = {
	slots: {
		consentBannerCard: 'brand-banner-card',
		consentBannerTitle: 'brand-banner-title',
	},
};
```

Pass it as `theme={theme}` on `ConsentProvider`. Define the class in a
global stylesheet, or with `:global(.brand-banner-card)` in a component,
because Svelte scopes component styles. The Svelte components read these
slots:

|Component|Slots|
|--|--|
|`ConsentBanner`|`consentBanner`, `consentBannerCard`, `consentBannerHeader`, `consentBannerTitle`, `consentBannerDescription`, `consentBannerFooter`, `consentBannerFooterSubGroup`, `consentBannerRights`, `consentBannerRightLink`, `consentBannerTag`, `consentBannerOverlay`|
|`ConsentDialog`|`consentDialog`, `consentDialogCard`, `consentDialogHeader`, `consentDialogTitle`, `consentDialogDescription`, `consentDialogContent`, `consentDialogTag`|
|`ConsentWidget`|`consentWidget`, `consentWidgetFooter`, `consentWidgetFooterSubGroup`, `consentWidgetTag`|
|`ConsentDialogTrigger`|`consentDialogTrigger`, `consentDialogTriggerIcon`|
|`IABConsentBanner`|`iabConsentBanner`, `iabConsentBannerTag`, `iabConsentBannerOverlay`|
|`ConsentGate`|`consentGate`, `consentGateTitle`, `consentGateButton`|
|Buttons in every component|`buttonPrimary`, `buttonSecondary`|

Slot names are not React's `components.banner.card` keys; do not copy a React
configuration. Use slots when one part should change and tokens when a value
should change everywhere. `class` on a component, such as
`<ConsentBanner class="...">`, goes on its root.
[Component parts](/docs/customization/slots) explains the attributes each
element carries, and [Tailwind CSS](/docs/customization/tailwind) shows the
Svelte and SvelteKit setups for Tailwind 4 and 3.

## Change button styles by action

`theme.consentActions` picks each button's style by what it does, whichever
order the policy puts the buttons in:

```ts
const theme = {
	consentActions: {
		default: { variant: 'neutral', mode: 'stroke' },
		primary: { variant: 'primary', mode: 'filled' },
		reject: { variant: 'neutral', mode: 'filled' },
	},
};
```

A per-action entry overrides `primary`, which overrides `default`. The policy
decides which action is primary.

## Change the banner shape and position

Set the shape on the banner itself, or for every surface with the provider's
`presentation` prop:

```svelte
<ConsentBanner variant="bar" position="bottom" />
```

|`variant`|Positions|
|--|--|
|`floating`|`bottom-left` (default), `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|
|`bar`|`bottom` (default), `top`|
|`widget`|`bottom-right` (default), `bottom-left`, `top-left`, `top-right`|
|`wall`|`center`|

`blocking` adds a backdrop, locks scrolling, traps focus and stops outside
clicks from closing the banner. `layout` and `primaryButton` change the button
order and emphasis. The policy wins where they conflict. A policy that requires
a reject button keeps it, whatever the layout says.

## Change the copy

For one banner, the text props on `ConsentBanner`, such as `title` and
`rejectButtonText`, replace the copy in every mode:

```svelte
<ConsentBanner title="Your privacy" rejectButtonText="Reject optional" />
```

For site-wide copy, pass the provider's `i18n` messages. In `offline()` mode
they merge over the bundled English copy. In `hosted()` mode they merge over
the backend's copy for the same language, key by key, so keys you leave out
keep the wording from your Inth project.
[Translations](./translations) covers both, the message keys and switching
languages. [Copy and translations](/docs/customization/translations) covers
wording for each action.

## Turn off animations

`disableAnimation` on the provider turns off the banner and dialog animations,
and the same prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner` or
`IABConsentDialog` overrides it for one surface. Left unset, the provider
follows the visitor's reduced motion setting.
[Motion and animation](/docs/customization/motion) covers the duration and
easing tokens.

## Remove c15t's styles

Set `noStyle` on one component or on the provider to render the same markup
and behavior without c15t's classes. Style the `data-*` attributes and your
slot classes instead. For different markup, see the headless page.

# Embeds
URL: https://c15t.com/docs/shared/svelte/embeds
A YouTube video, a map or a social post in an iframe contacts its vendor as soon as it loads. c15t offers two ways to keep it from loading before consent:

## Pick a way to gate the embed

A YouTube video, a map or a social post in an iframe contacts its vendor as
soon as it loads. c15t offers two ways to keep it from loading before
consent:

|Your markup|Use|Placeholder|
|--|--|--|
|A Svelte component you write|`ConsentGate` around the iframe|Built in, or your own snippet|
|HTML you do not control, such as CMS or Markdown content|The iframe blocker with `data-category` and `data-src`|None; the iframe stays empty|

Both use the visitor's effective permission for one category, and both
remove the embed again when the visitor withdraws that category.

## Wrap the iframe in ConsentGate

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

The iframe is absent from the DOM until measurement is allowed, so the
browser never requests it. The placeholder snippet replaces the built-in one
and includes a `ConsentDialogLink`, so a visitor can allow the category from
the embed's own spot. Keep `ConsentDialog` mounted for that link.
[ConsentGate](./components/consent-gate) lists its props.

Pick the category the vendor's embed needs. YouTube and maps usually fit
`measurement` or `marketing`; check what each vendor sets.

## Gate iframes you do not render

The provider's iframe blocker is on by default. It watches the page for
iframes with a `data-category` attribute:

```html
<iframe
  title="Store locations"
  data-category="functionality"
  data-src="https://www.google.com/maps/embed?pb=..."
></iframe>
```

* While the category is denied, the iframe has no `src`, so it loads nothing.
* When the category is allowed, the blocker copies `data-src` to `src`.
  Only `http` and `https` URLs are used.
* When the category is withdrawn, the blocker removes `src` again.

Iframes without `data-category` or `data-vendor` are never touched. Put
`data-src` in the HTML instead of `src`; an iframe that arrives with `src`
already starts loading before the blocker sees it. Add `data-vendor` with a
vendor slug to also keep the iframe empty while the visitor has that vendor
turned off.

The blocker has no placeholder. Style the empty iframe, or place a note and a
`ConsentDialogLink` next to it.

Pass `iframeBlocker={false}` on the provider to turn the blocker off.

## Vendor guides

The [YouTube](/docs/integrations/youtube) and
[Google Maps](/docs/integrations/google-maps) guides have ready embed
configurations. [Integrations](/docs/integrations/overview) lists the rest.

## Verify the embeds

Clear site data and reload with DevTools open:

1. The Network panel has no request to the embed's host, and the Elements
   panel shows the placeholder or an iframe without `src`.
2. Allow the category in preferences. The embed loads without a page reload.
3. Withdraw the category. The embed disappears, or its iframe loses `src`.

# Getters
URL: https://c15t.com/docs/shared/svelte/getters
Svelte has no consent hooks or stores. `@c15t/svelte` exports context getters instead. Call one at the top level of a component's `<script>`, inside `ConsentProvider`, and read its properties in markup or in `$derived`. The properties read the provider's `$state`, so the component updates when consent changes.

## Where getters work

Svelte has no consent hooks or stores. `@c15t/svelte` exports context getters
instead. Call one at the top level of a component's `<script>`, inside
`ConsentProvider`, and read its properties in markup or in `$derived`.
The properties read the provider's `$state`, so the component updates when
consent changes.

A getter uses Svelte's `getContext`, so it throws when you call it:

* in an event handler, an effect or a timer,
* in a component rendered outside the provider,
* in a plain `.ts` module.

Call it once at the top level and keep the returned object; its methods work
from event handlers later. The same getters are exported from
`@c15t/svelte/headless`.

|Getter|Returns|Use it to|
|--|--|--|
|`getConsentManager()`|`ConsentManagerState`|Read permissions and choices, and record choices. Start here.|
|`getHeadlessConsent()`|Surface state and actions|Build your own banner. See [headless](./headless).|
|`getIAB()`|`SvelteIABState` or `null`|Read or change IAB TCF consent.|
|`getConsentKernel()`|`ConsentKernel`|Subscribe to raw events or call low-level commands.|
|`getSnapshot()`|`ConsentSnapshot`|Read the full kernel snapshot once.|

## Read a permission or a recorded choice

A permission answers "may this run now?" A recorded choice answers "what did
the visitor decide?" They differ. Under an opt-out policy a category can be
allowed before the visitor chooses anything, and Global Privacy Control can
deny a category the visitor allowed. Load scripts and render optional
features from permissions; use the recorded choice only to show or report
what the visitor decided.

```svelte title="src/lib/consent-status.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	// Call getters at the top level of the component, inside the provider.
	const consent = getConsentManager();

	// A permission: may measurement code run now?
	const measurementAllowed = $derived(consent.has('measurement'));
	// A recorded choice: what did the visitor decide? `null` until they choose.
	const measurementChoice = $derived(
		consent.explicitChoice?.categories.measurement?.value
	);
</script>

<dl>
	<dt>Measurement may run</dt>
	<dd data-testid="measurement-permission">
		{measurementAllowed ? 'Yes' : 'No'}
	</dd>
	<dt>Visitor's measurement choice</dt>
	<dd data-testid="measurement-choice">
		{measurementChoice === undefined
			? 'Not chosen'
			: measurementChoice
				? 'Allowed'
				: 'Denied'}
	</dd>
</dl>
```

Before the visitor chooses, this component shows "No" and "Not chosen".
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

|Property or method|Answers|
|--|--|
|`has(condition)`|Whether a category, or a condition such as `{ and: ['measurement', 'marketing'] }` or `{ or: [...] }`, is allowed now.|
|`effectivePermissions`|Every category's permission, such as `effectivePermissions.measurement`.|
|`explicitChoice`|The visitor's recorded choice, or `null` before they choose. `explicitChoice.categories.measurement.value` is one category's answer.|
|`noticeDismissal`|Whether and when a notice was dismissed. Dismissing a notice is not consent.|
|`privacySignals`|Signals from the browser, such as `privacySignals.gpc.detected`.|
|`restrictions`|Per category, the reasons a recorded grant is overridden, such as GPC.|
|`vendorChoice`, `selectedVendors`|Recorded and draft grants for individual vendors outside IAB.|

## Read the policy and the UI state

|Property|Value|
|--|--|
|`hasPolicy`|`true` once a policy resolved for the visitor. Optional categories stay denied until then.|
|`policyPending`|`true` while the policy request is in flight.|
|`policyRule`|The resolved rule: `model`, `prompt`, `scope`, `rights` and more.|
|`resolution`|The resolution outcome, with `status` of `matched`, `failed` or another state.|
|`model`|`'opt-in'`, `'opt-out'`, `'iab'` or `'none'`.|
|`promptRequirement`|Whether the visitor owes a choice, a notice acknowledgement or nothing.|
|`hasConsentUi`|Whether the policy calls for any consent surface.|
|`hasConsentPreferences`|Whether a way back to preferences should show. `ConsentDialogLink` renders on this.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`location`|The country and region the policy resolved for.|
|`overrides`|The forced country, region, language or GPC value, if any.|
|`consentCategories`, `consentTypes`|The categories the preference UI offers, as names and as full definitions.|
|`translationConfig`, `translations`|The active copy and language.|
|`legalLinks`, `presentation`|The provider's `legalLinks` and `presentation` props.|
|`user`, `subject`|The identified user and the backend's subject for this visitor.|

## Record a choice

Call the methods from event handlers. Save methods return a promise.

```svelte title="src/lib/privacy-controls.svelte"
<script lang="ts">
	import { ConsentDialog, getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();

	// Record one category from your own button. setConsent changes the draft;
	// saveConsents('custom') records it.
	const allowAnalytics = async () => {
		consent.setConsent('measurement', true);
		await consent.saveConsents('custom');
	};
</script>

<button type="button" onclick={() => consent.setActiveUI('dialog')}>
	Privacy settings
</button>
<button type="button" onclick={allowAnalytics}> Allow analytics </button>
<ConsentDialog />
```

Clicking **Allow analytics** records measurement as allowed and leaves the
other categories as they were. **Privacy settings** opens the dialog.

|Method|Effect|
|--|--|
|`setActiveUI(surface)`|`'dialog'` opens preferences, `'banner'` shows the banner, `'none'` closes the open surface. Closing preferences brings the banner back while the policy still owes a choice. Records nothing.|
|`setConsent(category, value)`|Changes one category in the unsaved draft. `setSelectedConsent` is the same method.|
|`setSelectedVendor(vendorId, granted)`|Changes one vendor in the draft. Ignored for undeclared or disabled vendors.|
|`saveConsents('custom')`|Records the draft. Throws when the policy changed since the draft started; see [the draft](#work-with-the-draft).|
|`saveConsents('all')`|Records every category in scope as allowed.|
|`saveConsents('necessary')`|Records only `necessary`, rejecting the rest.|
|`dismissNotice()`|Records that the visitor dismissed a notice. Only works while a notice is due.|
|`setLanguage(code)`|Switches the language and resolves the policy again for it.|
|`getDisplayedConsents()`|The categories to render in your own preference UI.|
|`getDisplayedVendors(category)`|The vendors to list under one category. Empty under an IAB policy.|
|`isVendorAllowed(vendorId)`|`true` while a declared vendor's category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`subscribeToConsentChanges(listener)`|Calls `listener` with the permissions after every snapshot change. Returns an unsubscribe function.|

A save updates permissions in the same task, so registered scripts and
`ConsentGate` react before the backend request finishes. A failed request is
kept and retried; it does not undo the choice, and the provider's `onError`
callback reports it. When a save withdraws a category that was granted, the
provider reloads the page by default so code that already ran is gone. Set
`reloadOnConsentRevoked={false}` on the provider to handle that yourself.

Only call save methods from a visitor's action. Saving on page load records a
choice the visitor never made.

## Work with the draft

`consent.draft` is the unsaved state every preference surface on the page
shares: the dialog, `ConsentWidget` and your own UI.

|Member|Behavior|
|--|--|
|`values`|Each category's draft value. Starts from the recorded choice, or from the policy's defaults before a choice. A choice saved elsewhere moves the values the visitor has not touched. Categories outside `consentCategories` read `false`. `selectedConsents` is the same object.|
|`vendors`|Each declared vendor's draft grant.|
|`isStale`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change. A draft with no unsaved change follows the policy and is never stale.|
|`set(category, value)`, `setVendor(id, granted)`|The same as `setConsent` and `setSelectedVendor`.|
|`reset()`|Discards unsaved changes.|

The draft's code loads with the first preference surface, so a page that
only shows the banner does not ship it. `ConsentWidget` and `ConsentDialog`
bring it with them, and their switches render seeded on the first render,
on the server too. Headless code that reads or writes the draft without
either one starts the load itself: until it lands, `values` and `vendors`
are empty objects and `isStale` is `false`, and they update reactively once
it does. Writes made before then apply in order, `draft.reset()` drops
them, and `saveConsents('custom')` waits for the draft before it records.

When `isStale` is `true`, `saveConsents('custom')` throws "The policy changed.
Review your preferences before saving." Show the visitor the current
categories, call `draft.reset()`, and let them save again.

## Read and change IAB TCF consent

`getConsentManager().iab` is the live IAB state, or `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it; read `.iab` on
the manager for values that update.

|Member|Value or effect|
|--|--|
|`config.enabled`, `config.cmpId`|Whether the add-on is on, and the CMP ID.|
|`gvl`, `isLoadingGVL`|The Global Vendor List, and whether it is still loading.|
|`purposeConsents`, `vendorConsents`, `specialFeatureOptIns`|The visitor's TCF choices, staged or saved.|
|`tcString`|The saved TC String, or `null`.|
|`nonIABVendors`|Custom vendors outside the IAB list.|
|`acceptAll()`, `rejectAll()`|Accept All sets vendor and purpose consent for declared consent purposes, separate vendor and purpose legitimate-interest signals for declared legitimate-interest purposes, and opt-ins for declared special features. Reject All clears these signals.|
|`setPurposeConsent(id, value)`, `setPurposeLegitimateInterest(id, value)`|Change one purpose.|
|`setVendorConsent(id, value)`, `setVendorLegitimateInterest(id, value)`|Change one vendor.|
|`setSpecialFeatureOptIn(id, value)`|Change one special feature.|
|`save()`|Writes the TC String and records the choice.|
|`preferenceCenterTab`, `setPreferenceCenterTab(tab)`|The tab `IABConsentDialog` shows.|

Until the TCF add-on finishes loading, the action methods queue and replay.
See [IAB TCF](./iab) for setup.

## Listen to consent events

`getConsentKernel()` returns the consent kernel behind the provider. Its
`events.on(type, listener)` subscribes to one event and returns an
unsubscribe function. Subscribe in `$effect` so Svelte removes the listener
when the component unmounts:

```svelte title="src/lib/consent-events.svelte"
<script lang="ts">
	import { getConsentKernel } from '@c15t/svelte';

	// Read the kernel at the top level; subscribe in an effect so the
	// listener is removed when the component unmounts.
	const kernel = getConsentKernel();
	let lastRecorded = $state<string | null>(null);

	$effect(() =>
		kernel.events.on('choice:recorded', ({ snapshot }) => {
			const { measurement } = snapshot.effectivePermissions;
			lastRecorded = measurement ? 'measurement allowed' : 'measurement denied';
		})
	);
</script>

<p data-testid="last-recorded">
	{lastRecorded ?? 'No choice recorded on this page yet'}
</p>
```

`choice:recorded` fires for an explicit accept, reject or save.
`permissions:changed` fires for any change to what may run. For callbacks that
cover the whole app, use the provider's `callbacks` prop instead; see
[callbacks](./callbacks).

The kernel also has `subscribe(listener)`, which runs on every snapshot
change, `getSnapshot()`, and `commands` for `init()`, `save()`,
`dismissNotice()` and `identify()`. Prefer the manager's methods; they keep
the draft and the open surface in step, which the raw commands do not.
`getSnapshot()` from `@c15t/svelte` returns the snapshot at the moment you
call it and does not update.

## Other exports

|Export|Purpose|
|--|--|
|`manifest()`|The `mode` that resolves the policy in the browser from the manifest `consentManifest()` downloaded.|
|`hosted({ backendURL })`|The `mode` that asks an Inth or self-hosted backend's `/init` for every visitor.|
|`offline({ policyRules })`|The `mode` that resolves policies in the browser with no backend. Not recommended for production environments.|
|`custom(transport)`|The `mode` for your own transport.|
|`createConsentRuntime(options)`|Creates a runtime to share between providers, through their `runtime` prop.|
|`resolveConsentPresentation(input)`|Resolves the banner or dialog shape and actions a policy asks for, as `getHeadlessConsent()` does.|
|`defaultTranslationConfig`, `mergeTranslationConfigs`, `prepareTranslationConfig`, `detectBrowserLanguage`|Translation helpers.|

# Headless
URL: https://c15t.com/docs/shared/svelte/headless
Try [customization](/docs/customization/overview) first: tokens, slots, `presentation` and translations change most banners without new markup. Go headless when you need markup the stock components cannot produce.

## Choose how much to replace

Try [customization](/docs/customization/overview) first: tokens, slots,
`presentation` and translations change most banners without new markup. Go
headless when you need markup the stock components cannot produce.

|Goal|Approach|
|--|--|
|Keep the markup, drop c15t's styles|Set `noStyle` on the provider or on one component, and style the `data-*` attributes and slot classes.|
|Your own banner, stock dialog|`getHeadlessConsent()` for the banner, `ConsentDialog` for preferences. This page's example.|
|Your own dialog too|Add `getConsentManager()` for the category list and the draft.|

The provider, scripts, `ConsentGate` and the stored choice work the same with
any of them. You only replace the markup.

## Build a banner with getHeadlessConsent

`getHeadlessConsent()` returns the banner and dialog state and one method per
action. Call it at the top level of a component inside
`ConsentProvider`.

This banner renders the actions the policy allows, grouped and ordered the way
the policy asks, and hides itself when no banner is due:

```svelte title="src/lib/custom-consent-banner.svelte"
<script lang="ts">
	import { getHeadlessConsent } from '@c15t/svelte';
	import type { PresentationAction } from '@c15t/svelte';

	const consent = getHeadlessConsent();

	const labels: Record<PresentationAction, string> = {
		accept: 'Accept all',
		customize: 'Customize',
		dismiss: 'Got it',
		reject: 'Reject all',
		save: 'Save',
	};
</script>

{#if consent.banner.isVisible}
	<section class="custom-consent-banner" aria-label="Cookie consent">
		<p>
			We use cookies to measure traffic and show ads. Choose which ones can run.
		</p>
		<!-- The policy decides which actions this visitor gets, and in what order. -->
		{#each consent.banner.actionGroups as group, index (index)}
			<div>
				{#each group as action (action)}
					<button type="button" onclick={() => consent.performAction(action)}>
						{labels[action]}
					</button>
				{/each}
			</div>
		{/each}
	</section>
{/if}

<style>
	.custom-consent-banner {
		position: fixed;
		inset: auto 1rem 1rem;
		max-width: 32rem;
		padding: 1rem;
		border: 1px solid currentColor;
		border-radius: 0.5rem;
		background: white;
	}
	.custom-consent-banner div {
		display: flex;
		gap: 0.5rem;
		margin-top: 0.5rem;
	}
</style>
```

Render it where the stock `ConsentBanner` would go. The stock dialog still
handles Customize and the preferences link, so keep `ConsentDialog`. It adds
its own rules when it opens:

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
	import {
		ConsentDialog,
		ConsentDialogLink,
		ConsentProvider,
		hosted,
	} from '@c15t/svelte';

	import CustomConsentBanner from '#lib/custom-consent-banner.svelte';
	import { scripts } from '#lib/scripts.js';

	let { children } = $props();

	const mode = hosted({ backendURL: 'https://your-project.inth.app' });
</script>

<ConsentProvider {mode} {scripts}>
	{@render children()}
	<footer>
		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
	</footer>
	<CustomConsentBanner />
	<ConsentDialog />
</ConsentProvider>
```

In a Svelte app without SvelteKit, the same markup goes in the component that
renders the provider.

|Member|Purpose|
|--|--|
|`banner.isVisible`, `dialog.isVisible`|Whether that surface is due now.|
|`banner.actionGroups`, `banner.orderedActions`|The allowed actions, grouped or flat, in the order the policy asks for.|
|`banner.requiredActions`, `banner.primaryActions`|Actions you must show, and those to emphasize.|
|`banner.variant`, `banner.position`, `banner.blocking`|The resolved shape, position and blocking behavior, if you want to follow them.|
|`activeUI`|`'banner'`, `'dialog'` or `'none'`.|
|`performAction(action)`|`accept`, `reject`, `dismiss`, `save` or `customize`. Customize opens the dialog.|
|`openBanner()`, `openDialog()`, `closeUI()`|Show or hide a surface.|
|`saveCustomPreferences()`|Record the dialog's draft.|

Render from `actionGroups` or `orderedActions` rather than a fixed list. A
policy can require a reject button next to accept, or offer only a dismiss
button for a notice, and a hard-coded pair of buttons breaks those rules.

## Build your own preferences

For a custom dialog or settings page, read the category list and the unsaved
draft from `getConsentManager()`:

```svelte title="src/lib/cookie-preferences.svelte"
<script lang="ts">
	import { getConsentManager } from '@c15t/svelte';

	const consent = getConsentManager();
	const config = $derived(consent.translationConfig);
	const copy = $derived(config.translations[config.defaultLanguage ?? 'en']);
</script>

{#if consent.draft.isStale}
	<p role="alert">The cookie policy changed. Review your choices.</p>
{/if}
<fieldset>
	<legend>Cookie preferences</legend>
	{#each consent.getDisplayedConsents() as category (category.name)}
		<label>
			<input
				type="checkbox"
				checked={consent.selectedConsents[category.name] ?? false}
				disabled={category.name === 'necessary'}
				onchange={(event) =>
					consent.setConsent(category.name, event.currentTarget.checked)}
			/>
			{copy?.consentTypes?.[category.name]?.title ?? category.name}
		</label>
	{/each}
</fieldset>
<button
	type="button"
	disabled={consent.draft.isStale}
	onclick={() => consent.saveConsents('custom')}
>
	Save preferences
</button>
```

`setConsent` changes the draft only. `saveConsents('custom')` records it. If
the policy changes while the draft is open, `consent.draft.isStale` becomes
`true` and saving throws, so the example disables Save and shows a message.
Translated titles and descriptions are in `consent.translationConfig`.
[Context getters](./getters#work-with-the-draft) covers the draft.

`@c15t/svelte` exports `Dialog`, `Switch`, `Accordion`, `PreferenceItem` and
the `focusTrap`, `scrollLock` and `portal` actions if you want accessible
building blocks for the dialog itself; see [primitives](./components/primitives).

## Verify a custom UI

Run the same checks as the stock components: reject, reload and confirm no
optional vendor requests; allow one category and confirm only its vendors
load; reopen preferences from your footer link. Test keyboard focus and a
screen reader on your markup, because c15t no longer owns it.
[Verify consent](/docs/guides/verify-consent) has the full list.

# Iab
URL: https://c15t.com/docs/shared/svelte/iab
Use IAB TCF when your ad partners require a TC String. It needs an IAB policy in your Inth project and a CMP ID. IAB Europe assigns a CMP ID to a company when it registers as a CMP ([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC String names the CMP that wrote it, so an ID you did not register attributes your visitors' consent to someone else. Example CMP IDs in c15t demos are not production configuration.

## Before you turn on IAB TCF

Use IAB TCF when your ad partners require a TC String. It needs an IAB policy
in your Inth project and a CMP ID. IAB Europe assigns a CMP ID to a company
when it registers as a CMP
([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
String names the CMP that wrote it, so an ID you did not register attributes
your visitors' consent to someone else. Example CMP IDs in c15t demos are not
production configuration.

`@c15t/svelte` loads the TCF add-on from `@c15t/iab`, which it installs as a
dependency. The add-on is a separate chunk that apps without IAB never
download.

## Add the IAB components

Turn IAB on with the provider's `iab` prop, keeping your existing mode or `state`,
`scripts` and other props. `registeredCmpId` stands for the number IAB Europe
assigned to your company. The standard and IAB components add their styles
automatically:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} iab={{ cmpId: registeredCmpId }}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} iab={{ cmpId: registeredCmpId }}>
```

Then render `IABConsentBanner` and `IABConsentDialog` next to the standard
components.
The standard components cover visitors whose policy is not IAB, such as those
outside Europe:

```svelte title="src/lib/consent-surfaces.svelte"
<script lang="ts">
	import {
		ConsentBanner,
		ConsentDialog,
		IABConsentBanner,
		IABConsentDialog,
	} from '@c15t/svelte';
</script>

<!-- Visitors whose policy is not IAB get the standard banner and dialog. -->
<ConsentBanner />
<ConsentDialog />
<!-- Visitors under an IAB policy get the TCF banner and preference center. -->
<IABConsentBanner />
<IABConsentDialog />
```

The IAB banner adds its first-paint rules before its elements render. The
IAB dialog adds its rules when it opens, including the base rules it needs
when rendered without a banner. Each sheet appears once per page. On a
server-rendered SvelteKit page, `c15tHandle` writes the rendered components'
rules into `<head>` before hydration.

To run the CSS through Tailwind CSS 3 or put it in a named cascade layer,
set `styles={false}` on the provider and import
`@c15t/svelte/styles.css` followed by `@c15t/svelte/iab/styles.css`.
[Stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself)
explains when to use that option.

|`iab` option|Purpose|
|--|--|
|`cmpId`|Your registered CMP ID. A hosted backend can supply it instead.|
|`vendors`|Limit the Global Vendor List to these vendor IDs.|
|`customVendors`|Vendors outside the IAB list, with their purposes and data use.|
|`publisherRestrictions`|Override how vendors may use a purpose. See below.|
|`publisherCountryCode`|Your country, written into the TC String.|
|`gvl`, `gvlURL`|Supply the vendor list, or change where it is fetched from.|
|`enabled`|`false` keeps the configuration but leaves the add-on unmounted.|

Pass `iab={false}`, or omit it, to leave IAB off. If a visitor's policy
then uses the `iab` model and the backend sends its vendor list, the
provider throws an `IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`) while
rendering, on the server and in the browser: the standard banner does not
handle the IAB model, so the visitor would otherwise get no working consent
UI. Set `iab`, or remove the `iab` model from the policy. A backend that
answers `gvl: null` turns IAB off for the request, and the policy runs as
opt-in.

[IABConsentBanner](./components/iab-consent-banner) and
[IABConsentDialog](./components/iab-consent-dialog) list each component's
props.

`IABConsentBanner` and `IABConsentDialog` stay hidden until an IAB policy resolves for the visitor. Forcing the
dialog open does not create a policy or a vendor list, so check the policy
resolution and the vendor list request before changing how they render.

## Read the TCF state

`getConsentManager().iab` holds the live IAB state: the vendor list, purpose
and vendor consents, `isLoadingGVL`, and the actions `acceptAll()`,
`rejectAll()`, `setPurposeConsent()`, `setVendorConsent()`,
`setSpecialFeatureOptIn()` and `save()`. It is `null` when IAB is off.
`getIAB()` returns the same object at the moment you call it.
[Context getters](./getters#read-and-change-iab-tcf-consent) lists every
member.

For a custom IAB banner, `@c15t/svelte/headless` exports
`getIABBannerDisplayItems`, `processGVLData` and `getIABTranslations`.

## Restrict how vendors use a purpose

Pass publisher restrictions in the provider's `iab` option as
`publisherRestrictions`, for example
`[{ purposeId: 4, restrictionType: 0, vendorIds: [10, 755] }]` to stop vendors
10 and 755 using purpose 4. Use vendors from your own list whose declarations
allow each restriction.

Each restriction type has a requirement that depends on the vendor list:

|`restrictionType`|Meaning|Allowed when the vendor|
|--|--|--|
|`0`|Purpose not allowed on any legal basis|declares the purpose for consent or legitimate interest|
|`1`|Consent required|declares the purpose for legitimate interest and lists it in `flexiblePurposes`|
|`2`|Legitimate interest required|declares the purpose for consent and lists it in `flexiblePurposes`|

Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
only with consent. TCF allows restrictions only in service-specific TC strings.
c15t always writes those, so the deprecated `isServiceSpecific` option has no
effect on restrictions.
c15t copies the restrictions when the CMP starts, so changing your array
afterwards has no effect.

c15t checks restrictions when the vendor list loads and again before each TC
String is encoded. Unsupported restrictions include type `3`, which the spec
reserves, a vendor or purpose missing from the list, and a vendor with two
restriction types for one purpose. They are never dropped. Loading IAB
settings, saving and generating a TC String all reject with a
`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
written and no consent is recorded. Retrying `whenReady()` does not fetch
another vendor list. The error lasts until a new vendor list is set up: with an
explicit `gvl` option that never happens, so saving keeps failing even if the
kernel later holds a different list. When the CMP follows the kernel's list
instead, a replacement list is checked again and saving works once it accepts
the restrictions. When a replacement vendor list makes a restriction
unsupported, c15t also clears the TC authority confirmed under the previous
list, so gated scripts stop until the configuration is fixed. Whenever c15t
withdraws the authority it confirmed, it also removes the TC String from the
`euconsent-v2` cookie and localStorage entry. Because the check reads the
current vendor list, a vendor that stops declaring a purpose or its flexibility
makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
together.

Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
purpose ID, then vendor ID. A stored TC String whose restrictions differ from
the current configuration is not restored. If the visitor's stored choice is
otherwise current, the banner opens again, as it does after a policy change,
and closes once the visitor saves. IAB gates that depend on the TC String stay
denied until then. c15t also removes the superseded TC String from the
`euconsent-v2` cookie and localStorage entry, so vendors reading standard
storage do not pick it up. An unchanged configuration restores the stored TC
String without asking.
When reading a string written under TCF policy version 2 or 3, c15t accepts
type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
writes always follow the current policy.

The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
vendor under the legal basis the restrictions leave it. A vendor whose purpose
now requires legitimate interest gets an objection control instead of a
consent toggle, and a prohibited purpose no longer lists the vendor. A
purpose whose vendors all use legitimate interest has no consent switch,
because turning one off would change nothing the vendors rely on; its
objection control is the opt-out. Such a purpose does not decide its c15t
category: the category follows the purposes in it that the visitor can
consent to. Legitimate interest never grants a category on its own. If none of
a category's purposes has a consent basis, nothing can consent to them, Accept
All included, so the category stays denied. See
[categories under an IAB policy](/docs/concepts/consent-state#categories-under-an-iab-policy).
Stack switches
cover only the purposes some vendor processes on consent. Display-model rows
expose this as `hasConsentBasis`. Custom preference UIs can call
`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
declarations. The configured restrictions are on the kernel's IAB state as
`publisherRestrictions`.

Consent-gated scripts, network rules and iframes with a `vendorId` also apply
the confirmed restrictions for that vendor:

* Type `0` blocks a target that declares the purpose in `iabPurposes` or
  `iabLegIntPurposes`.
* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
  vendor consent. Legitimate interest no longer satisfies it.
* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
  legitimate interest. Consent no longer satisfies it.

Types `1` and `2` block the target when the vendor list does not mark the
purpose as flexible for that vendor. Targets without a `vendorId` ignore
restrictions. A target that uses only legitimate interest once restrictions
apply is not blocked by a refused category, since it needs no consent; its
legitimate interest signals and the visitor's objection decide. GPC and strict
scope still block it, and the category stays refused for scripts that depend on
it. Accept All grants the vendor signal a restriction moves a purpose to,
including legitimate interest for a vendor that declares none. Legitimate
interest a restriction introduces applies until the visitor objects: the
preference centres show it as allowed, and saving without touching it encodes
it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
those purposes and vendors for custom preference UIs.

## How the preference centre shows features

The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
locked section with a lock icon, because the visitor cannot object to them.

Features get their own section after the special purposes. It shows the IAB
standard text for features from the Global Vendor List's
`standardTexts.features`. If the list has no standard text, it shows the
`iab.preferenceCenter.features.description` translation. Each feature lists
its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
TCF forbids showing features next to a control that cannot be disabled.

The feature section follows the theme's spacing and typography tokens.
Its disclosure arrows are decorative and stay out of the accessibility tree.

A custom preference UI gets the same rows from
`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
the special purposes only. `featureRows` holds the features, with
`locked: false` and `toggle: 'none'`, so render them without a control.
`featuresStandardText` is the standard text, or `null` when you should use the
translation.

Each vendor's privacy policy and legitimate interest links come from its
`urls[]` entry in the Global Vendor List. The stock preference centres pick
the entry for the language the banner shows, then English. A custom UI gets
the same links from `resolveIABVendorUrls(vendor, language)` in
`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
older than GVL v3 have a single `policyUrl` field, which c15t still reads.

## Consent scope

c15t stores TCF choices per site and browser, which the TCF calls
service-specific scope. It does not sync TC strings across devices, and every
TC string it writes has `IsServiceSpecific` set to `1`.

Do not use `/consent/check` or your own account data to skip the TCF banner on
another device. That turns the choice into multi-device scope, which the TCF
requires you to disclose in the first layer, and c15t does not show that
disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
logs a warning when you pass `false`.

## Verify the TCF flow

Accept, reject and save purpose and vendor choices, then check in the console
that `__tcfapi('getTCData', 2, console.log)` returns a TC String that matches
what you chose. Reload and confirm it persists. Check the vendors' actual
requests too; a category banner test does not show that the IAB flow works.

# Network Blocker
URL: https://c15t.com/docs/shared/svelte/network-blocker
The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you list until their consent category is allowed. Use it as a backstop for tracking calls from code that is already on the page, such as your own analytics wrapper or an SDK you import. It is off until you configure it.

## When to use the network blocker

The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
list until their consent category is allowed. Use it as a backstop for
tracking calls from code that is already on the page, such as your own
analytics wrapper or an SDK you import. It is off until you configure it.

Load vendor SDKs through the provider's `scripts` prop first; see
[scripts](./scripts). A script that never loads sends nothing, which is
stronger than blocking its requests one by one.

## Configure the rules

Write the configuration in its own module:

```ts title="src/lib/network-blocker.ts"
import type { UseNetworkBlockerOptions } from '@c15t/svelte';

// Pass as `networkBlocker={networkBlocker}` on ConsentProvider.
export const networkBlocker: UseNetworkBlockerOptions = {
	onRequestBlocked: ({ method, url }) => {
		console.info('Blocked until consent', method, url);
	},
	rules: [
		{
			category: 'measurement',
			domain: 'google-analytics.com',
			id: 'google-analytics',
		},
		{
			category: 'marketing',
			domain: 'connect.facebook.net',
			id: 'meta-pixel',
			pathIncludes: '/signals',
		},
	],
};
```

Pass it to the provider:

```svelte
<!-- Svelte: src/App.svelte -->
<ConsentProvider mode={manifest()} {scripts} {networkBlocker}>

<!-- SvelteKit: src/routes/+layout.svelte -->
<ConsentRoot state={data.consent} {scripts} {networkBlocker}>
```

The provider reads `networkBlocker` once, when it is created. Remount the
provider to change the rules.

## Match requests with rules

Each rule names a `domain` and the consent `category` a request needs. The
domain also matches its subdomains: `google-analytics.com` covers
`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
contain a substring, and `methods` narrows it to HTTP methods. A request is
blocked when a matching rule's condition is not met by the visitor's
effective permissions.

`category` takes the same conditions as scripts:

```ts
{ category: 'measurement' }
{ category: { and: ['measurement', 'marketing'] } }
{ category: { or: ['measurement', 'marketing'] } }
```

Add `vendor` to also block the request while the visitor has turned that
vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
instead.

|Option|Default|Purpose|
|--|--|--|
|`rules`|required|Rules described above|
|`enabled`|`true`|Set `false` to keep the rules but stop blocking|
|`logBlockedRequests`|`true`|Log each blocked request with `console.warn`|
|`onRequestBlocked`|none|Called with `{ method, url, rule }` for each blocked request|

## What a blocked request looks like

A blocked `fetch` resolves to a response with status `451` and the status
text `Request blocked by consent`, and nothing is sent. A blocked
`XMLHttpRequest` is aborted and fires an `error` event. Requests that match no
rule are not delayed. With `logBlockedRequests` on, the default, each blocked
request is logged with `console.warn`; `onRequestBlocked` receives
`{ method, url, rule }`.

## When blocking starts

The provider starts holding matching requests when it is created in the
browser, before its children run their own code. The blocker module loads
when the provider mounts and then decides each held request:

* While the policy is still loading, a matching request waits instead of
  failing. When the policy arrives, with the visitor's stored choice applied,
  the request is sent if its category is allowed and blocked otherwise.
* If the policy fails to load, optional categories stay denied and the
  waiting requests are blocked.
* A synchronous XHR cannot wait. Before the blocker module loads, a matching
  one throws a `NetworkError` from `send()`.

When the visitor allows a category later, new requests to its domains go
through. Requests blocked earlier are not replayed.

## What it cannot stop

The blocker sees only `fetch` and `XMLHttpRequest` calls made after the
provider is created in the browser. It cannot stop:

* Scripts that run before the provider, such as tags in `index.html` or
  `app.html` and code at the top level of modules that load first.
* Code that kept its own reference to `fetch` or `XMLHttpRequest` from before
  the provider was created.
* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
  `<img>`, `<script>` and `<iframe>` elements, web workers and service
  workers.
* Requests your server makes, such as from a SvelteKit `load` or endpoint.

Keep tracking calls out of that window. Send them from event handlers or
effects, not at a module's top level, and check
`getConsentManager().has('measurement')` before you call a vendor from your
own code.

## Verify the blocker

Open DevTools, clear site data for your origin and reload:

1. Before you choose, requests matching a rule do not reach the network, and
   the console logs each blocked request.
2. Allow the rule's category. New matching requests appear in the Network
   panel.
3. Reject, reload and confirm they stay blocked.

`fetch('https://www.google-analytics.com/g/collect')` in the console returns a
response with status `451` while measurement is denied.

# Scripts
URL: https://c15t.com/docs/shared/svelte/scripts
The provider's `scripts` prop takes an array of script configurations. Each has a category. The loader adds a script to the page when its category becomes allowed and removes it when the category is withdrawn. Nothing optional loads while the policy is still resolving, or when it fails.

## How registered scripts load

The provider's `scripts` prop takes an array of script configurations. Each
has a category. The loader adds a script to the page when its category becomes
allowed and removes it when the category is withdrawn. Nothing optional loads
while the policy is still resolving, or when it fails.

Helpers in `@c15t/integrations`, such as `posthog()` from `@c15t/integrations/posthog`,
return a configuration with the right category and the vendor's own consent
calls. [Integrations](/docs/integrations/overview) lists every helper. For an
SDK without a helper, write a configuration with an `id`, `category` and `src`
as shown in [building integrations](/docs/integrations/building-integrations).

Remove the vendor's original `<script>` tag, `app.html` snippet or SDK import
before you register it. A banner does not block code that loads some other
way, and a vendor loaded twice sends events twice.

The `scripts` array is read when the provider is created. Build it once, at
the top level of the component, not inside an effect.

## Script options

Helpers set these for you. For a script without a helper, write the object
yourself:

|Option|Default|Behavior|
|--|--|--|
|`id`|required|A unique name. The loader uses it to add and remove the script once.|
|`category`|required|The category or condition, such as `'measurement'` or `{ and: ['measurement', 'marketing'] }`, that must be allowed.|
|`src` or `textContent`|none|The script's URL, or inline code.|
|`callbackOnly`|`false`|Adds no `<script>` element and only runs the callbacks. Use it to switch an SDK you load yourself on and off.|
|`alwaysLoad`|`false`|Loads at once, whatever the consent state. Only for scripts that apply consent themselves, such as a tag manager with Consent Mode.|
|`persistAfterConsentRevoked`|`false`|Keeps the element after withdrawal instead of removing it.|
|`target`|`'head'`|Where the element goes: `'head'` or `'body'`.|
|`async`, `defer`, `fetchPriority`, `attributes`, `nonce`|none|Set on the `<script>` element.|
|`anonymizeId`|`true`|Gives the element a random `id`, so ad blockers do not match it by name.|
|`vendor`|none|Also waits for this vendor to be allowed, for vendor-level consent outside IAB.|
|`onBeforeLoad`, `onLoad`, `onError`, `onConsentChange`, `onDispose`|none|Lifecycle callbacks. See [callbacks](./callbacks#script-callbacks).|

## Gate embeds

Iframes are not scripts. Wrap them in `ConsentGate`, which keeps the iframe
out of the DOM until its category is allowed:

```svelte title="src/YouTubeEmbed.svelte"
<script lang="ts">
	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
</script>

<!-- The iframe mounts only while measurement is allowed. -->
<ConsentGate category="measurement">
	{#snippet placeholder()}<div class="placeholder">
			<p>Allow measurement to load this YouTube video.</p>
			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
		</div>{/snippet}
	<iframe
		title="YouTube video"
		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
		allow="encrypted-media; picture-in-picture"
		allowfullscreen
	></iframe>
</ConsentGate>
```

For iframes from a CMS or Markdown, which you cannot wrap, use the iframe
blocker's `data-category` and `data-src` attributes. [Embeds](./embeds) covers
both.

## Block requests from code already on the page

The provider's `networkBlocker` option holds `fetch` and `XMLHttpRequest`
calls to the domains you list until their category is allowed. It is a
backstop for code you cannot move into `scripts`. [Network blocker](./network-blocker)
covers the rules and what it cannot stop.

## What happens when consent is withdrawn

Removing a script tag cannot stop code that already ran. So when a save
withdraws a category that was granted, the provider reloads the page after the
save request, and the new page starts with only the permitted code. Set
`reloadOnConsentRevoked: false` on the provider if you handle withdrawal
yourself, for example through a vendor's own opt-out call in
`onConsentChange`.

`ConsentGate` content unmounts without a reload. To delete first-party cookies
a vendor set, configure `clearOnRevocation`; see
[clearing data on revocation](./clear-on-revocation).

## Let visitors turn off one vendor

A visitor can allow marketing and still switch off one vendor in it. Pass
`vendors` to the provider; helpers from `@c15t/integrations` already carry their
vendor slug. See [vendor consent](./vendor-consent).

## Verify vendor loading

Open DevTools, clear site data for your origin and reload:

1. With the banner showing, the Network panel has no requests to your vendors,
   and gated iframes are absent from the Elements panel.
2. Allow one category in preferences. Only that category's vendors load, and
   its iframes appear.
3. Reject, reload, and confirm the vendor requests stay absent.
4. Withdraw a category you allowed. The page reloads and its vendors no longer
   load.

[Verify consent](/docs/guides/verify-consent) covers automated checks.

# Translations
URL: https://c15t.com/docs/shared/svelte/translations
The banner, dialog, widget, gate placeholder and IAB surfaces read their text from one set of translations for the visitor's language. Which set depends on the provider's `mode`:

## Where the copy comes from

The banner, dialog, widget, gate placeholder and IAB surfaces read their text
from one set of translations for the visitor's language. Which set depends on
the provider's `mode`:

|Mode|Copy comes from|Languages|
|--|--|--|
|`hosted()`|The backend's `/init` response, in the language the browser or server asked for, with the provider's `i18n` messages for that language on top|Every language the backend bundles: bg, cs, cy, da, de, el, en, es, et, fi, fr, ga, gu, he, hi, hr, hu, id, is, it, lb, lt, lv, mt, nb, nl, nn, pl, pt, rm, ro, sk, sl, sv and zh|
|`manifest()`|The manifest's translations over the base copy for the visitor's language, with the provider's `i18n` messages on top. Resolved on the server in SvelteKit, in the browser in Svelte.|English base copy is bundled; another language's base copy loads the first time a visitor needs it|
|`offline()`|The provider's `i18n` prop, merged over bundled English|English, plus any language you supply in full|

The browser bundle carries English only. Other languages arrive from the
backend, or from messages you pass.

## Change the copy for one banner

`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. These props
win in every mode:

```svelte
<ConsentBanner
	title="Cookies on this site"
	rejectButtonText="Reject optional"
/>
```

The props replace the text in every language, so pass values in the page's
language, or compute them from your own i18n library.

## Change the copy site-wide

Pass `i18n` to the provider. `messages` holds partial translations per
language; the keys you leave out keep c15t's copy:

```ts title="src/lib/consent-i18n.ts"
import type { I18nConfig } from '@c15t/svelte';

// Pass as `i18n={i18n}` on ConsentProvider. Messages merge over the
// bundled English copy, so list only the keys you change.
export const i18n: Partial<I18nConfig> = {
	locale: 'en',
	messages: {
		en: {
			common: { customize: 'Choose cookies', rejectAll: 'Reject optional' },
			cookieBanner: { title: 'Your privacy on this site' },
		},
	},
};
```

`locale` selects the language the provider starts in, `en` by default.

In `hosted()` mode, the backend's copy for the visitor's language is the base,
and your `i18n` messages for that language replace it key by key. Keys you do
not list keep the backend's copy, including copy edited in your Inth project.
The same applies to the copy SvelteKit's `loadConsent` resolves on the
server. c15t picks the
messages for the exact language first, then for its primary language, so a
visitor resolved to `de-AT` gets your `de` messages when there is no `de-AT`
entry. Messages for other languages are not applied.

A key only overrides the backend when your text differs from c15t's built-in
wording for that language. So passing the stock bundles from
`@c15t/translations/all` to enable languages keeps backend edits visible,
while a key you actually reworded stays pinned in code. Core bundles only
English; for other languages, import `@c15t/translations/all` so c15t can
recognize its stock wording. A
self-hosted backend takes `customTranslations` and `i18n` in its
[configuration](/docs/self-host/api/configuration).

In `offline()` mode, `i18n` is the only source of copy, and it applies from the
first render.

## Common message keys

|Key|Where it shows|
|--|--|
|`cookieBanner.title`, `cookieBanner.description`|Choice banner heading and body.|
|`cookieBanner.noticeTitle`, `cookieBanner.noticeDescription`|Notice banner heading and body.|
|`common.acceptAll`, `common.rejectAll`, `common.customize`, `common.save`|Banner and dialog buttons.|
|`common.acknowledge`|The notice's dismiss button.|
|`common.securedBy`|The "Secured by" tag.|
|`consentManagerDialog.title`, `consentManagerDialog.description`|Preference dialog heading and body.|
|`consentTypes.<category>.title`, `consentTypes.<category>.description`|A category's name and description, such as `consentTypes.measurement.title`.|
|`consentGate.title`, `consentGate.actionButton`|The `ConsentGate` placeholder. `{category}` is replaced by the category title.|

[Copy and translations](/docs/customization/translations) covers wording for
each action and testing long labels.

## Switch the language

`getConsentManager().setLanguage(code)` switches the language and resolves the
policy again, so a hosted backend returns copy in the new language and your
`i18n` messages for that language apply on top. Call it
from your language switcher's event handler. The visitor's language otherwise
comes from the `Accept-Language` header, or from `overrides.language` on the
provider.

The root of the banner, dialog and widget sets `dir` from the active
language, so right-to-left languages such as Hebrew lay out correctly.

## Verify the copy

Open the page with the browser language set to each language you support.
The banner, the dialog's category names and the gate placeholder all use that
language. Then choose a narrow window and zoom to 200%: long labels wrap
without cutting off.

# Troubleshooting
URL: https://c15t.com/docs/shared/svelte/troubleshooting
**Check.** Read `getConsentManager().policyRule.prompt` and `.location`, or open DevTools. In the Network panel, find the `/init` request.

## Why is there no banner?

**Check.** Read `getConsentManager().policyRule.prompt` and `.location`, or open
DevTools. In the Network panel, find the `/init` request.

**Fix.** Work through these causes in order:

1. **The policy asks for no prompt.** Visitors in regions without a consent
   law, and opt-out policies with no prompt, get no banner. See
   [why the banner may be absent](/docs/concepts/policies#why-the-banner-may-be-absent).
2. **A choice is already stored.** Clear site data for your origin, or use the
   DevTools panel, and reload.
3. **The backend request failed.** A CORS error means your site's origin is
   not in the Inth project's trusted origins. A 404 means the backend URL is
   wrong. While the request fails, optional categories stay denied and no
   banner shows.
4. **The component is outside the provider.** `ConsentBanner` must render
   inside `ConsentProvider`; outside it, Svelte throws
   `c15t: no v3 consent context`.

## Svelte throws "no v3 consent context"

**Check.** A getter or component ran without a `ConsentProvider` above
it.

**Fix.** Move it inside the provider.

**Check.** Look for a getter called in an event handler or effect. Getters use
Svelte's `getContext`.

**Fix.** Call getters at the top level of a component's `<script>`.

**Check.** If the provider is there, check that the app resolves one copy of
`@c15t/svelte`. Two copies create two separate contexts.

**Fix.** Make the app resolve a single copy of `@c15t/svelte`.

## Theme colors are ignored

**Check.** The provider's `theme` prop applies slot styles and `consentActions`
only. Colors, radius, typography and other tokens in `theme` are not turned
into CSS in the browser, and in development the provider logs a warning about
it.

**Fix.** Set the `--c15t-*` variables on `:root` in a stylesheet, or render
`generateThemeCSS()` output as `<style id="c15t-theme">`. The customize page
shows both.

**Check.** If your values still lose, inspect the element. A generated theme
uses `:root:root`, so it beats your own `:root` rule.

**Fix.** Write your rule on `:root:root` too, or move the value into the theme.

## The dialog or banner has no styles

**Check.** Look in `<head>` for `<style data-c15t-styles>` elements, and in
the console for a Content Security Policy error. On a server-rendered
SvelteKit page, check that `src/hooks.server.ts` exports `c15tHandle`.

**Fix.**

* No c15t `<style>` element: the provider sets `styles={false}` or
  `noStyle`. With `styles={false}`, import `@c15t/svelte/styles.css` once,
  in the component that renders the provider or in your global stylesheet.
* The SvelteKit banner is unstyled until hydration: add `c15tHandle` from
  `@c15t/svelte/kit` to `src/hooks.server.ts`, or set `styles={false}` and
  import `@c15t/svelte/styles.css`.
* The console reports a blocked inline style: pass the provider a `nonce`, or
  set `styles={false}` and import the stylesheet. The Content Security Policy
  page covers both.
* IAB TCF surfaces are unstyled with automatic styles disabled: import
  `@c15t/svelte/styles.css` and `@c15t/svelte/iab/styles.css` together. With
  automatic styles enabled, check the policy and IAB configuration, the
  provider's `noStyle` option, and CSP errors.

## A vendor loads before consent, or twice

**Check.** The vendor is still loaded some other way: a `<script>` tag in
`index.html` or `app.html`, a tag manager, or an SDK import in your code. Check
the Network panel with site data cleared; nothing from the vendor should load
before you allow its category.

**Fix.** Remove the other loader and keep only the `scripts` registration.

## The page reloads after saving

**Check.** When a save withdraws a category that was granted, the provider
reloads the page so code that already ran is gone. This is expected.

**Fix.** Set `reloadOnConsentRevoked: false` on the provider only if every
registered vendor stops itself through its consent API.

# Callbacks
URL: https://c15t.com/docs/shared/upgrade-v3/callbacks
Callbacks stay under `callbacks` in your options, with new names:

## Replace callbacks

Callbacks stay under `callbacks` in your options, with new names:

|v2 callback|v3 callback|
|--|--|
|`onConsentSet`|`onPermissionsChanged` to react to what may run now. `onChoiceRecorded` to react to the visitor's accept, reject or save.|
|`onConsentChanged`|`onChoiceRecorded`. See the note below the table.|
|`onBannerFetched`|No callback. In React and Next.js, read `usePolicyResolution()` to know when the policy has resolved. In JavaScript, read `resolution` from the kernel snapshot.|
|`onError`, `onBeforeConsentRevocationReload`|Unchanged|

The `callbacks-to-v3` codemod renames `onConsentChanged` to
`onChoiceRecorded`. It leaves a `TODO(c15t v3)` comment there about the new
payload, and on `onConsentSet` and `onBannerFetched`, which it can't choose a
replacement for:

```bash
npx @c15t/cli@alpha codemods callbacks-to-v3 --dry-run --json
```

v2's `onConsentChanged` fired only when a save changed at least one category's
value, and passed `preferences` and `previousPreferences`. v3's
`onChoiceRecorded` fires for every accept, reject or save that confirms a
category, including one that saves the same values again, because each save
renews the choice's confirmation time. Its payload carries `snapshot`,
`confirmed` and `actionAt`. v3 has no callback that fires only when a save
changes a value. If you need the before and after values, use
`onPermissionsChanged`: it passes `previous` and the new `snapshot` whenever
effective permissions change, whether a save or something else changed them.

v2's `onConsentSet` also fired on initialization and hydration. In v3,
`onChoiceRecorded` runs only when the visitor acts, and `onPermissionsChanged`
runs when effective permissions change for any reason, including expiry, a
policy update or a privacy signal. Neither runs at startup if the resolved
permissions match the defaults, such as an opt-in policy that leaves every
category denied. If an external API needs the starting state, read it once at
startup as well: in React and Next.js from `useEffectivePermissions()` in an
effect, which also runs on later changes, and in JavaScript from
`kernel.events.on('init:applied', ({ snapshot }) => ...)`.

```ts title="After (v3): callbacks in your options"
callbacks: {
  onChoiceRecorded(event) {
    console.log('Visitor recorded a choice', event);
  },
  onPermissionsChanged(event) {
    console.log('Effective permissions changed', event);
  },
},
```

# Check
URL: https://c15t.com/docs/shared/upgrade-v3/check
codemod fail the build until you resolve them.

## Check the migration

1. Run your typecheck and build. Remaining `TODO(c15t v3)` comments from the
   codemod fail the build until you resolve them.
2. Load the app with a v2 consent cookie from before the upgrade. The banner
   stays closed if that choice still applies, and a rejected category stays
   blocked.
3. In a private window, check in DevTools Network that vendor requests wait for
   consent, start after you accept, and stay absent after you reject and
   reload.
4. Reopen preferences from your privacy settings link and change a category.

The [verification guide](/docs/guides/verify-consent) has the full release
checklist.

# Cli
URL: https://c15t.com/docs/shared/upgrade-v3/cli
reads sessions saved by v2.

## Update the CLI

* Run `c15t login` again. The CLI signs in through Inth now and no longer
  reads sessions saved by v2.
* `c15t setup` no longer writes `.env.local` or `.env.example` and no longer
  accepts `--env`. It writes the backend URL into the files it generates.
* `c15t setup` no longer detects Remix or Gatsby. Pick a guide from
  [Choose your setup](/docs/concepts/choose-your-setup) for those apps.

# Earlier Alpha Frame
URL: https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-frame
Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside production, log a one-time warning such as `` c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead. ``

### Deprecated, still working

Only React's v2 `Frame` names remain. They render `ConsentGate` and, outside
production, log a one-time warning such as
`` c15t: `Frame` is deprecated and will be removed in a future major release. Use `ConsentGate` instead. ``

|Package|Deprecated|Use instead|
|--|--|--|
|`c15t/react`, `c15t/next`, `c15t/tanstack-start`|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, and the `FrameProps` type|`ConsentGate` and its parts, and `ConsentGateProps`|

v2's `ConsentManagerProvider` and string modes such as `mode: 'hosted'` are
handled by the `consent-provider-options` codemod, not by aliases.

# Earlier Alpha Intro
URL: https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-intro
The v3 alphas renamed and removed APIs that never shipped in a stable release. Names that were in stable v2 keep a deprecated alias. Every other renamed name is removed with no alias, so a build that still uses one fails to type-check or throws at runtime.

## Upgrade from an earlier v3 alpha

The v3 alphas renamed and removed APIs that never shipped in a stable release.
Names that were in stable v2 keep a deprecated alias. Every other renamed name
is removed with no alias, so a build that still uses one fails to type-check
or throws at runtime.

# Earlier Alpha Modes
URL: https://c15t.com/docs/shared/upgrade-v3/earlier-alpha-modes

|Removed|Use instead|
|--|--|
|`hosted({ url })`|`hosted({ backendURL })`, or the framework's backend URL variable|
|`createManifestTransport({ manifest })`|`createManifestTransport({ snapshot })`|
|`assertDecisionInputs` defaulting to `false` on `hosted()`|It now defaults to `true` whenever `initURL` is set. Pass `false` to turn it off.|
|`hostedModes` from `c15t/runtime/provider`|`readHostedMode(mode)`|
|`buildManifest: true` in Astro and Nuxt|`onBuildError: 'fail'`, the default for production builds. `buildManifest: false` is `manifest({ source: 'runtime' })`.|
|A generated `c15t-manifest.ts` and its `.gitignore` entry|`import { snapshot } from 'c15t/generated'`. Most apps no longer import it at all.|
|The build options `outputFile`, `exportName`, `importSource` and `rootDir`|Removed. The snapshot is a virtual module, or a file under `node_modules/.cache/c15t/` in Next.js.|

# Headless
URL: https://c15t.com/docs/shared/upgrade-v3/headless
`useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`. The `root-exports-to-subpaths` codemod moves the import. Some of its methods take different arguments:

## Update headless UI code

`useHeadlessConsentUI()` keeps its name and moves to `c15t/react/headless`.
The `root-exports-to-subpaths` codemod moves the import.
Some of its methods take different arguments:

|v2|v3|
|--|--|
|`performAction(action, { surface })`|`performAction(action)`. It also accepts `'dismiss'` and `'customize'`.|
|`openBanner({ force })`|`openBanner()`|
|`saveCustomPreferences({ uiSource })`|`saveCustomPreferences()`, `saveCustomPreferences('all')` or `saveCustomPreferences('none')`|
|`banner.layout`, `dialog.layout`, `hasPolicyHints`|`banner` and `dialog` carry `variant`, `position`, `rights`, `requiredActions` and `diagnostics`|

The `UseHeadlessConsentUIResult` type is no longer exported. Use
`ReturnType<typeof useHeadlessConsentUI>` if you need it.

# Iab
URL: https://c15t.com/docs/shared/upgrade-v3/iab
React, Next.js and TanStack Start no longer take an `iab` provider option. Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or `ConsentRoot`, around the IAB components. Its props are the options you passed to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new `publisherRestrictions`.

## Move IAB setup to `IABProvider`

React, Next.js and TanStack Start no longer take an `iab` provider option.
Render `IABProvider` from `c15t/react/iab` inside `ConsentProvider` or
`ConsentRoot`, around the IAB components. Its props are the options you passed
to `iab()`, such as `cmpId`, `vendors`, `customVendors` and the new
`publisherRestrictions`.

The `iab-option-to-iab-provider` codemod marks the `iab` option with a
`TODO(c15t v3)` comment; move it by hand.

A `cmpId` that isn't an integer from 2 to 4095 now throws. Without a `cmpId`,
the CMP doesn't mount, so there is no `__tcfapi` and no TC string.

`@c15t/iab` no longer exports `createIABManager`, `decodeTCString`,
`generateTCString` or `c15tToIabPurposes`. Use `createIAB({ kernel, cmpId })`,
which returns a handle with `generateTCString()`, `acceptAll()`, `rejectAll()`
and `save()`. If your app depends on `@c15t/iab` directly, upgrade it to
`@c15t/iab@alpha` too, or your import resolves to the v2 package. Remove it if
`IABProvider` now covers everything you used it for.

Server integrations now send a reference to the Global Vendor List instead of
the list, and the browser fetches it when the IAB module mounts. If you set a
Content Security Policy, allow the list's origin in `connect-src`, or `'self'`
for same-origin routes.

# Integrations
URL: https://c15t.com/docs/shared/upgrade-v3/integrations
v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts` from your dependencies and install `@c15t/integrations` from the `alpha` dist-tag:

## Rename the integrations dependency

v3 renames `@c15t/scripts` to `@c15t/integrations`. Remove `@c15t/scripts`
from your dependencies and install `@c15t/integrations` from the `alpha`
dist-tag:

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

Replace the package name in each import. Vendor subpaths and helper names stay
the same.

Before, in v2:

```ts
import { googleTagManager } from '@c15t/scripts/google-tag-manager';
import { posthog } from '@c15t/scripts/posthog';
```

After:

```ts
import { googleTagManager } from '@c15t/integrations/google-tag-manager';
import { posthog } from '@c15t/integrations/posthog';
```

The `scripts` configuration option and the `Script` type keep their names.

Two helper behaviors change. A helper that needs an ID, such as `metaPixel`,
`googleTagManager` or `posthog`, now logs an error and skips its script when
the ID is empty or only whitespace, where v2 loaded a broken script. And if
your code reads `@c15t/integrations/registry`, an entry's `consentCategory` can
now be a compound condition such as `{ and: ['marketing', 'measurement'] }`,
not only a category name.

`@c15t/scripts` stays available as a deprecated compatibility package for all
of v3. It re-exports the implementation and types of `@c15t/integrations`, so
you can migrate imports separately from the rest of the upgrade. Compatibility
ends in v4; versions already published stay on npm.

To preview the import changes in JavaScript and TypeScript files:

```bash
npx @c15t/cli@alpha codemods scripts-to-integrations --dry-run --json
```

Review the output, then run it again without `--dry-run`. The codemod runs
only when you name it. It does not change `package.json`, lockfiles, or
imports inside `.vue`, `.svelte` or `.astro` files; update those by hand, then
reinstall dependencies and build the app.

# Options And Components
URL: https://c15t.com/docs/shared/upgrade-v3/options-and-components
The `consent-provider-options` codemod renames `ConsentManagerProvider` and its option and prop types, turns `mode` and `backendURL` into `hosted()` or `offline()`, and renames `iframeBlockerConfig`. v2 still accepted the deprecated `translations` option; the `translations-to-i18n` codemod moves it to `i18n`.

## Rename options and components

|v2|v3|
|--|--|
|`translations`|`i18n`|
|`backendURL`, `mode: 'hosted'`|`mode: hosted({ backendURL })` from `c15t/react` on `ConsentProvider`. Next.js `ConsentRoot`: `NEXT_PUBLIC_C15T_BACKEND_URL` and `c15t.config.ts`.|
|`ssrData` (Next.js)|`ConsentRoot` with `state` from `resolveConsent()`|
|`iframeBlockerConfig`|`iframeBlocker`, or `false` to turn it off|
|`Frame`, `FrameRoot`, `FrameTitle`, `FrameButton`, `FrameProps`|`ConsentGate` and its parts. The `Frame` names still work as deprecated aliases and log a one-time warning outside production.|
|`frame` translations, such as `frame.title`|`consentGate`, such as `consentGate.title`. Copy under `frame` still applies and logs a warning outside production.|
|`FrameTranslations`|`ConsentGateTranslations`. `FrameTranslations` still works as a deprecated alias.|
|`--frame-*` CSS variables|`--consent-gate-*`, with the same suffixes, such as `--consent-gate-placeholder-background-color`. The old names no longer apply.|
|`YouTubeEmbed`, `GoogleMap`|Removed. Wrap your own embed in `ConsentGate`.|
|`useConsentScript()`|Removed. Register the script in `scripts` with a `@c15t/integrations` helper.|
|`useSSRStatus()`|Removed|
|`ConsentButton`|Removed. Use the `ConsentBanner` and `ConsentWidget` buttons, or call `useHeadlessConsentUI()` from your own button.|
|`@c15t/react/cookie-banner`|`c15t/react/consent-banner`|
|`retryConfig`|Removed|
|`store`, including `namespace`, `debug`, `initialConsentCategories` and `initialTranslationConfig`|Removed. Use the top-level `consentCategories` and `i18n` options. Debug information is on `window.c15t`.|
|`window.c15tStore`|`window.c15t`|
|`iab: iab({ ... })`|`IABProvider`. See [Move IAB setup](#move-iab-setup-to-iabprovider).|

The `consent-provider-options` codemod renames `ConsentManagerProvider` and
its option and prop types, turns `mode` and `backendURL` into `hosted()` or
`offline()`, and renames `iframeBlockerConfig`. v2 still accepted the
deprecated `translations` option; the `translations-to-i18n` codemod moves it
to `i18n`.

```bash
npx @c15t/cli@alpha codemods consent-provider-options translations-to-i18n --dry-run --json
```

`ConsentBanner`, `ConsentDialog`, `ConsentDialogLink`, `ConsentDialogTrigger`
and `ConsentWidget` keep their names. The `scripts`, `networkBlocker`,
`legalLinks`, `overrides`, `theme` and `colorScheme` options keep theirs too,
but `theme` tokens no longer produce CSS on their own. See
[Update styles and themes](#update-styles-and-themes).

`persistence` and `storageConfig` are read once, when the provider mounts. v2
moved a stored choice when the storage key changed. Remount the provider to
change storage. Reading a vendor that nothing declares, through `vendors`, a
script or the backend, returns `false`.

Some names left the root `c15t/react` entry:

|v2 import from the root|v3 import|
|--|--|
|`useHeadlessConsentUI`, `useConsentDialogTrigger`, `useColorScheme`, `useFocusTrap` and the translation helpers|`c15t/react/headless`|
|Flat banner parts such as `ConsentBannerCard` and `ConsentBannerAcceptButton`|`ConsentBanner.Card`, `ConsentBanner.AcceptButton` and the other compound parts, or the same names from `c15t/react/components/consent-banner`|
|`TriggerRoot`, `TriggerButton`, `TriggerIcon`, `TriggerText`, `useTriggerContext`, `useDraggable`|`c15t/react/consent-dialog-trigger`|
|Token types such as `ColorTokens` and `TypographyTokens`|`c15t/react/types`. `Theme` stays on the root.|
|`configureConsentManager`, `policyPackPresets`, `ConsentStoreState`, `ConsentManagerInterface`|Removed. Use `policyRulePresets` from `c15t`.|

The `root-exports-to-subpaths` codemod moves these imports to their new
entries and marks removed names with a `TODO(c15t v3)` comment:

```bash
npx @c15t/cli@alpha codemods root-exports-to-subpaths --dry-run --json
```

`ConsentGate` changes one behavior from `Frame`. When its category is granted,
the embed now mounts after hydration instead of in the server HTML, so an
iframe loads once instead of twice. Size the wrapper with `className` or
`style` to hold its space. Test ids change from `frame-placeholder` and
`frame-open-dialog` to `consent-gate-placeholder` and `consent-gate-button`.

# Policies
URL: https://c15t.com/docs/shared/upgrade-v3/policies
v2 policy packs become policy rules, and `policyPackPresets` becomes `policyRulePresets`, exported from `c15t`. Where the rules live depends on your backend:

## Move policy packs to policy rules

v2 policy packs become policy rules, and `policyPackPresets` becomes
`policyRulePresets`, exported from `c15t`. Where the rules live depends on your
backend:

* **Inth**: set the rules in your Inth project. Rules in client code do not
  change a hosted policy.
* **Self-hosted**: move the backend's `policyPacks` to `manifest.policyRules`.
  See [policy configuration](/docs/self-host/guides/policy-packs).
* **Offline**: move `offlinePolicy.policyPacks` to `offline({ policyRules })`.

```tsx title="After (v3): offline policy rules"
import { offline, policyRulePresets } from 'c15t';

const mode = offline({
	policyRules: [
		policyRulePresets.europeOptIn(),
		policyRulePresets.worldOptOutNoPrompt(),
	],
});
```

In Next.js, import `offline` from `c15t/next` instead and set the result as
`mode` in `c15t.config.ts`. Both take the same `policyRules`.

|v2 preset|v3 preset|
|--|--|
|`europeOptIn()`, `europeIab()`|Same names|
|`californiaOptIn()`, `californiaOptOut()`|Same names|
|`quebecOptIn()`|Same name|
|`worldNoBanner()`|`worldOptOutNoPrompt()`|

`worldNone()` is a separate, new preset: it shows nothing and grants no
rights, while `worldOptOutNoPrompt()` keeps v2's opt-out and preference rights.

The `policy-packs-to-policy-rules` codemod renames `policyPackPresets` and
`worldNoBanner()`, and moves the import to `c15t` where it came from
`c15t/react` or `c15t/next`. `consent-provider-options` moves
`offlinePolicy.policyPacks` into `offline({ policyRules })`. Preset calls need
no other change, but a hand-written v2 pack uses `consent` and `ui` keys,
which v3 rules replace with flat keys such as `model` and `prompt`; the
codemods mark those with a `TODO(c15t v3)` comment.

v3 adds presets for more regions. `offline()` without `policyRules` uses
`recommendedPolicyRules()`. Read [policies](/docs/concepts/policies) before you
change a rule's model or prompt, and
[how consent works](/docs/concepts/how-consent-works) for the difference
between a permission and a recorded choice.

# Stored Consent
URL: https://c15t.com/docs/shared/upgrade-v3/stored-consent
v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It does not rewrite them on page load; the next accept, reject or save writes a v3 record.

## Keep visitors' existing choices

v3 uses the same `c15t` cookie and storage key as v2 and reads v2 records. It
does not rewrite them on page load; the next accept, reject or save writes a
v3 record.

A v2 denial keeps restricting its category. A v2 grant keeps applying until
the policy's validity period runs out, and then c15t asks again. If the rule
comes from a preset and the v2 record noted the policy it was made under, c15t
also asks again when that policy has changed. Under custom rules, a v2 grant
applies until it expires. Do not copy permissions into new
records yourself; c15t decides which v2 choices still count.

# Styles
URL: https://c15t.com/docs/shared/upgrade-v3/styles
In v2 the provider built CSS from `options.theme` in the browser. In v3 it doesn't. Without a change, custom colors, fonts and radii fall back to the defaults, and you only see a development warning.

## Update styles and themes

### Render theme CSS

In v2 the provider built CSS from `options.theme` in the browser. In v3 it
doesn't. Without a change, custom colors, fonts and radii fall back to the
defaults, and you only see a development warning.

Render `ConsentTheme` with the same theme object, or put the output of
`generateThemeCSS(theme)` in your own stylesheet. Keep `options.theme` for
`consentActions` and `slots`. See
[customization](/docs/customization/overview) and
[tokens](/docs/customization/tokens).

The `theme-to-consent-theme` codemod marks a provider `theme` that sets
tokens with a `TODO(c15t v3)` comment.

A generated theme uses `:root:root`, so your own `--c15t-*` values on plain
`:root` lose to it. Put them in the theme instead, or raise your selector.

### Stylesheets

* Remove the c15t stylesheet import, such as `@c15t/react/styles.css` or
  `@c15t/nextjs/styles.css`. The stock components in `c15t/react`,
  `c15t/next` and `c15t/tanstack-start` render the rules they use as
  `<style>` elements, so no stylesheet request holds back the first paint. An
  import you keep still styles the components, but the rules ship twice and
  the stylesheet still delays the first paint.
* Keep an import of the v3 stylesheet, such as `c15t/react/styles.css`, only
  with Tailwind CSS 3 or a named cascade layer, and set
  `styles: false` in the provider options so the components add no second
  copy. See
  [stylesheets and CSS layers](/docs/customization/stylesheets#import-the-stylesheet-yourself).
  The `packages-to-c15t` codemod removes `@c15t/react` and `@c15t/nextjs`
  stylesheet imports. With Tailwind CSS 3 or a cascade layer it keeps them,
  pointed at `c15t`, with a `TODO(c15t v3)` comment.
* With manual styles, `iab/styles.css` no longer repeats the default tokens.
  Import it after `styles.css`. Automatic IAB styling needs neither import.
* Tailwind CSS 3 needs a PostCSS plugin for c15t's `styles.css`. Add
  `'c15t/postcss-tailwind3': {}` before `tailwindcss` in `postcss.config`,
  and set `styles: false`. See [Tailwind CSS 3](/docs/customization/tailwind#set-up-tailwind-css-3).
  Create React App can't run the plugin. The `postcss-tailwind3` codemod adds
  it to an object-form `postcss.config` and warns about configs it can't
  edit.

### CSS variables and slots

|v2|v3|
|--|--|
|`--consent-widget-*`|`--consent-manager-*`, used by `ConsentDialog` and `ConsentWidget`|
|`--consent-widget-accordion-*`|Removed. Set `--accordion-*` instead.|
|`--frame-*`|`--consent-gate-*`|
|`--consent-banner-entry-animation`, `--consent-banner-exit-animation`|Removed|
|`theme.slots.frame`|`consentGate`, `consentGateTitle` and `consentGateButton`|
|`theme.slots.consentDialogFooter`|`consentWidgetFooter`|

The `css-variables-to-v3` codemod renames `--consent-widget-*` and
`--frame-*` in stylesheets and inline styles, and marks
`--consent-widget-accordion-*` with a comment instead of renaming it, because
`--accordion-*` styles every accordion. `theme-to-consent-theme` renames
`theme.slots.consentDialogFooter` and marks `theme.slots.frame`.

```bash
npx @c15t/cli@alpha codemods theme-to-consent-theme css-variables-to-v3 postcss-tailwind3 --dry-run --json
```

`theme.slots` now applies in React. v2 accepted it in types and ignored it, so
check slots you set before the upgrade.

# Translations
URL: https://c15t.com/docs/shared/upgrade-v3/translations
Partial overrides through `i18n.messages` and objects typed as `Translations` need no change. A complete translation object typed as `CompleteTranslations` fails type-checking until you add the new sections and keys: `consentGate`, which replaces `frame`, `rights`, the notice and dismiss strings such as `common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves `frame` copy to `consentGate`.

## Update complete translation objects

Partial overrides through `i18n.messages` and objects typed as `Translations`
need no change. A complete translation object typed as `CompleteTranslations`
fails type-checking until you add the new sections and keys: `consentGate`, which
replaces `frame`, `rights`, the notice and dismiss strings such as
`common.acknowledge` and `cookieBanner.noticeTitle`, and the vendor list copy
under `consentManagerDialog.vendors`. `migrateLegacyTranslationKeys()` moves
`frame` copy to `consentGate`.

`i18n.messages` for the visitor's language now merge over the backend's copy
instead of being replaced by it.

# Use Consent Manager
URL: https://c15t.com/docs/shared/upgrade-v3/use-consent-manager
`useConsentManager()` returned the whole consent state, so every component that called it re-rendered on every change. v3 has one hook per field. Run the codemod first:

## Replace `useConsentManager()`

`useConsentManager()` returned the whole consent state, so every component
that called it re-rendered on every change. v3 has one hook per field. Run the
codemod first:

```bash
npx @c15t/cli@alpha codemods use-consent-manager-to-hooks --dry-run --json
```

Review the proposed files, then run it again without `--dry-run`. For this v2
component:

```tsx title="Before (v2): components/accept-button.tsx"
import { useConsentManager } from '@c15t/react';

export function AcceptButton() {
	const { activeUI, has, saveConsents } = useConsentManager();
	if (activeUI !== 'banner' || has('marketing')) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

the codemod writes:

```tsx title="After (v3): components/accept-button.tsx"
import { useActiveUI, useConsent } from '@c15t/react';
import { useHeadlessConsentUI } from '@c15t/react/headless';

export function AcceptButton() {
	const activeUI = useActiveUI() ?? 'none';
	const hasMarketing = useConsent('marketing');
	const { saveCustomPreferences: saveConsents } = useHeadlessConsentUI();
	if (activeUI !== 'banner' || hasMarketing) return null;
	return (
		<button type="button" onClick={() => void saveConsents('all')}>
			Accept
		</button>
	);
}
```

The codemod keeps the entry you imported from. Change `@c15t/react` to
`c15t/react` afterwards if you moved to the umbrella package. Fields it cannot
rewrite stay on a `useConsentManager()` call under a `TODO(c15t v3)` comment,
which fails the build until you replace them. The table lists the v2 fields
components read. The other fields held provider configuration, such as
`legalLinks`, `scripts` and `storageConfig`, or store internals; set
configuration through `ConsentProvider` props.
Import hooks from `c15t/react`, `c15t/next` or `c15t/tanstack-start`, and
`useHeadlessConsentUI` from the matching `/headless` entry.

|v2 field|v3 replacement|
|--|--|
|`activeUI`|`useActiveUI()`. It returns `null` until c15t picks a surface, where v2 returned `'none'`.|
|`setActiveUI(ui)`|`useSetActiveUI()`|
|`has(category)`|`useConsent(category)`, one call per category at the top of the component|
|`consents`|`useConsents()`|
|`saveConsents('all')`|`useHeadlessConsentUI().saveCustomPreferences('all')`|
|`saveConsents('necessary')`|`useHeadlessConsentUI().saveCustomPreferences('none')`|
|`saveConsents('custom')`|`useConsentDraft().save()`, or `useHeadlessConsentUI().saveCustomPreferences()` inside a `ConsentDraftProvider`|
|`selectedConsents`|`useConsentDraft().values`|
|`setSelectedConsent(name, value)`|`useConsentDraft().set(name, value)`|
|`setConsent(name, value)`|`useSaveConsents()`, called with `{ [name]: value }`|
|`consentInfo`|`useExplicitChoice()`|
|`hasConsented()`|`useExplicitChoice() !== null`|
|`consentCategories`, `consentTypes`, `getDisplayedConsents()`|`useConsentDraft().displayedCategories`, with labels from `useTranslations().consentTypes`|
|`policyCategories`|`usePolicyCategories()`. The v2 list started with `'necessary'`; this one does not.|
|`policyScopeMode`|`usePolicyScopeMode()`|
|`policyBanner`|`usePromptPresentation()`|
|`policyDialog`|`usePreferencesPresentation()`|
|`model`|`useModel()`. It returns `null` while no policy matches, where v2 returned `'opt-in'`.|
|`branding`|`useBranding()`. It returns `null` when unset, where v2 returned `'c15t'`.|
|`iab`|`useIABSnapshot()`|
|`locationInfo`|`useLocation()`|
|`overrides`, `setOverrides()`|`useOverrides()`, `useSetOverrides()`|
|`setLanguage()`|`useSetLanguage()`|
|`user`, `identifyUser()`|`useUser()`, `useIdentify()`|
|`translationConfig`|`useTranslations()` for the active strings|
|`subscribeToConsentChanges(listener)`|`useSubscribeToConsentChanges()`, or the `onPermissionsChanged` callback|
|`updateConsentCategories(categories)`|`useRegisterConsentCategories()`|
|`manager`|Nothing. Use the hooks above.|

`saveCustomPreferences()` saves the way the stock buttons do. It closes the
banner or dialog after a successful save. `useSaveConsents()` calls the engine
directly and does not close anything.

In v2, `useConsentManager()` kept one draft per component. In v3,
`useConsentDraft()` and `useHeadlessConsentUI()` share a draft only inside a
`ConsentDraftProvider`. Without one, `saveCustomPreferences()` saves a fresh
draft and ignores what `useConsentDraft().set()` staged, even in the same
component. Save with `useConsentDraft().save()`, or render the code that stages
and the code that saves inside one `ConsentDraftProvider`. `ConsentWidget`
already includes one. The codemod
adds a `TODO(c15t v3)` comment where this applies.

# Vite Build Manifest
URL: https://c15t.com/docs/shared/vite-build-manifest
`vite build` and `vite dev` fetch the manifest when they start. `vite preview` serves the last build without fetching. The plugin writes no file into your app, so there is nothing to keep out of Git. `c15t/generated` ships its own types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without a build first.

`vite build` and `vite dev` fetch the manifest when they start. `vite preview`
serves the last build without fetching. The plugin writes no file into your
app, so there is nothing to keep out of Git. `c15t/generated` ships its own
types, so `tsc`, `vue-tsc` and `svelte-check` pass on a fresh checkout without
a build first.

The plugin can't see the options your app passes to `manifest()`. When the
app passes `source: 'runtime'` or `manifestURL`, set
`consentManifest({ source: 'runtime' })` too. The build then downloads no
manifest, so it doesn't fail when the backend's `/manifest` is down.

# Vite Build Manifest Troubleshooting
URL: https://c15t.com/docs/shared/vite-build-manifest-troubleshooting
**Check.** `vite build` stops with an error from `consentManifest` that starts with the plugin's name, such as `@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite` for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps going. The part in parentheses names the cause:

## Why does the build fail to download the manifest?

**Check.** `vite build` stops with an error from `consentManifest` that
starts with the plugin's name, such as
`@c15t/core/build: could not fetch the consent manifest from <url> during the build`. The name is `@c15t/core/build` for `c15t/build` and `@c15t/vue/vite`
for `c15t/vue/vite`. `vite dev` logs the same message as a warning and keeps
going. The part in parentheses names the cause:

|Message|Cause|Fix|
|--|--|--|
|`fetch failed`, with `ENOTFOUND`, `ECONNREFUSED` or another network error|The build cannot reach the backend|Build where the backend is reachable|
|`no response within 10 seconds`|The backend did not answer in time|Check the backend, or build where it is reachable|
|`/manifest responded 404`|The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix|Copy the backend URL exactly as Inth shows it, or set `VITE_C15T_BACKEND_URL`|
|`/manifest returned an invalid consent manifest.`|The URL answered with something other than a consent manifest, such as an HTML page|Point `backendURL` at the backend itself, not your site or a dashboard page|

A failed download never reuses an old snapshot. To deploy while the backend
is down, run the build with `C15T_ON_BUILD_ERROR=runtime`. `snapshot` is then
`undefined`, and the browser fetches the policy from the backend at runtime.

Only a build that uses `manifest()` downloads the manifest. The plugin
fetches after Vite has dropped the code the app does not use, so a `hosted()`
or `offline()` build never contacts the backend and never fails this way.

An error or warning that says `no backend URL is set` means the plugin found
no `backendURL` option and no variable. Set `VITE_C15T_BACKEND_URL` (or
`VITE_INTH_PROJECT_URL`) in `.env` or the build environment, or pass the absolute backend URL from your Inth
project. The [troubleshooting guide](/docs/guides/troubleshooting#why-does-the-build-fail-to-download-the-manifest)
lists every message.

A notice that the build `skipped the consent manifest fetch` means the backend
URL is relative, such as `/api/c15t`. Pass the absolute backend URL instead.
With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL`.

## Why is snapshot undefined?

**Check.** `snapshot` from `c15t/generated` is `undefined`, and the browser
requests `${backendURL}/manifest` on page load.

**Fix.** `snapshot` is `undefined` when Vite has no policy to serve:

* `consentManifest` is missing from `plugins` in `vite.config.ts`. Without the
  plugin, `c15t/generated` still resolves, but exports `undefined`.
* The fetch failed in `vite dev`, or in a build with
  `C15T_ON_BUILD_ERROR=runtime`. The terminal shows a `could not fetch the consent manifest` warning.
* The backend URL is relative, so the plugin skipped the fetch.
* `consentManifest({ source: 'runtime' })` is set, so the plugin never
  fetches.

Fix the cause, then restart `vite dev` or rebuild. The plugin fetches once
when Vite starts.

# ConsentBanner
URL: https://c15t.com/docs/shared/vue/components/consent-banner
Shared ConsentBanner reference for the c15t Vue plugin and Nuxt module.

## What ConsentBanner renders

`ConsentBanner` renders the first-layer banner while `activeUI` is
`'banner'`. It renders nothing until the visitor's policy has resolved,
when the policy asks for no prompt, and when a `bannerModels` or `models`
option leaves out the policy's model.

The policy decides the buttons:

* A `choice` prompt shows Reject All, Accept All and Customize. Customize is
  the primary button by default, so Accept All and Reject All look the same.
* A `notice` prompt shows an OK button. When the policy grants an opt-out or
  preferences right, the banner adds a button styled as underlined text,
  labelled "Do not sell or share my data" or "Manage preferences", that
  opens preferences.
* A policy with prompt `none` shows no banner.

Each button runs one command. Accept All and Reject All record a choice for
every category the policy covers, and the banner closes. Customize sets
`activeUI` to `'manager'`, which opens `ConsentManager` if it is mounted.
OK records that the visitor dismissed the notice. Dismissing grants nothing
and leaves earlier refusals in place.

The text comes from the translations the backend resolved for the visitor:
`cookieBanner.title` and `cookieBanner.description` for a choice,
`cookieBanner.noticeTitle` and `cookieBanner.noticeDescription` for a
notice, and `common.acceptAll`, `common.rejectAll`, `common.customize` and
`common.acknowledge` for the buttons. `bannerLegalLinks` picks which of your
`legalLinks` appear under the description. The banner has no slots and no
text props.

`ConsentBanner` moves itself into `document.body` once it has mounted.
During server rendering it renders in place, so the banner can be part of
the server HTML.

## Variants and positions

The policy decides which actions the banner offers. The variant decides the
shape they take.

|Variant|Shape|Positions|Default position|
|--|--|--|--|
|`floating`|A card in a corner or centred on an edge. The default.|`bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center`|`bottom-left`|
|`bar`|A full-width bar along the top or bottom edge.|`top`, `bottom`|`bottom`|
|`widget`|A compact card with smaller type.|`bottom-left`, `bottom-right`, `top-left`, `top-right`|`bottom-right`|
|`wall`|A centred card over a backdrop that blocks the page.|`center`|`center`|

The policy has the last word. A choice `wall` always blocks. A notice never
blocks, and a notice `wall` falls back to `floating`. A position the variant
does not accept falls back to the variant's default. Each correction logs a
`[c15t]` warning in the browser console.

A default corner mirrors left and right for right-to-left languages. A
position you set is kept as written.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`variant`|`'floating' \|'bar' \|'widget' \|'wall'`|`presentation.prompt.variant`, else `'floating'`|Shape of the banner.|
|`position`|`PromptPosition`|`presentation.prompt.position`, else the variant's default|Where the banner sits. Must be valid for the variant.|
|`blocking`|`boolean`|`presentation.prompt.blocking`, else `true` for `wall` only|Backdrop, scroll lock and focus trap, as one value.|

A prop you set beats the matching `presentation.prompt` option. Leave a prop
unset to follow your c15t options. `PromptVariant` and `PromptPosition` are
exported as types from `c15t`.

## Accessibility and focus

* A non-blocking banner is a `region` labelled with the banner title. It does
  not trap focus or lock scrolling, so the page stays usable with a keyboard
  and a pointer.
* A blocking banner is a `dialog` with `aria-modal="true"`. It shows a
  backdrop, locks page scrolling, moves focus to the banner card and keeps
  Tab inside the card.
* The banner has no close button, and Escape does not dismiss it. The
  visitor answers with one of its buttons.
* Every action is a native `button`. The banner sets `dir` from the resolved
  language.

## Style the banner

[Theme tokens](/docs/customization/tokens) change colors, type, radius,
spacing and motion. The `components.banner` option adds attributes, such as
`class` or `style`, to these parts: `root`, `overlay`, `cardShell`, `card`,
`header`, `title`, `footer`, `actions`, `actionGroup`, `rights` and
`rightLink`. `components.description.banner` and `components.tag.banner`
reach the description and the branding tag.
[Component slots](/docs/customization/slots) lists every part.

The root element carries attributes you can target from CSS:

|Attribute|Values|
|--|--|
|`data-variant`|`floating`, `bar`, `widget`, `wall`|
|`data-position`|The resolved position|
|`data-prompt`|`choice`, `notice`|
|`data-model`|`opt-in`, `opt-out`, `iab`|
|`data-blocking`|`true`, present only while blocking|

`bannerHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the enter and exit
transitions.

## Verify

Open the page in a private window under a policy that asks for a choice.
The banner appears with Reject All and Accept All side by side. Tab through
it and confirm every button is reachable. Click Customize and the preference
dialog opens. Reject, reload, and confirm the banner stays closed. In the
Elements panel, the root element carries the `data-variant` and
`data-position` you set.

# ConsentDialogLink
URL: https://c15t.com/docs/shared/vue/components/consent-dialog-link
Shared ConsentDialogLink reference for the c15t Vue plugin and Nuxt module.

## What ConsentDialogLink renders

`ConsentDialogLink` renders one `button` that sets `activeUI` to
`'manager'`, which opens the preference dialog. It matches `ConsentDialogLink`
in the React adapter. It has no props. The default label is the
`consentManagerDialog.title` translation, "Privacy Settings" in English.
The link shows it in the visitor's language once init has delivered copy,
and in English until then. Its default slot replaces the label.

The button renders only while the visitor has somewhere to go:

* It is absent until the visitor's policy has resolved.
* It is absent when the policy owes no consent UI, such as a policy with no
  prompt and no rights.

The link opens the dialog only if something renders `ConsentManager`.
`ConsentRoot` does.

## Accessibility and styling

The component is a native `button` with `type="button"`, so it works with
Enter and Space and has no link semantics. Style it with your own classes on
the element: attributes you pass, such as `class`, go to the button. It
carries `data-testid="consent-dialog-link"` and `data-c15t-rights`, the
policy's rights separated by spaces.

## Verify

Load the page under a policy that asks for consent and click Privacy
Settings. The preference dialog opens. Under a policy with no prompt and no
rights, the button is absent from the DOM.

# ConsentDialogTrigger
URL: https://c15t.com/docs/shared/vue/components/consent-dialog-trigger
Shared ConsentDialogTrigger reference for the c15t Vue plugin and Nuxt module.

## What ConsentDialogTrigger renders

`ConsentDialogTrigger` renders a round floating button, fixed to a corner of
the viewport, that opens the preference dialog. Visitors can drag it to
another spot. It has no props. Your c15t options configure it.

The trigger renders in the browser only, after mount, in `document.body`. It
hides while the preference dialog is open, until the visitor's policy has
resolved, and when the policy owes no consent UI. Under the default
`triggerShowWhen: 'after-consent'`, it also stays hidden while the banner
waits for an answer, and appears once the visitor saves a choice or
dismisses a notice.

While `ConsentDevTools` is mounted, the trigger becomes a two-button
toolbar: the preferences button in the corner and a DevTools button beside
it that opens the DevTools panel next to the toolbar.

## Options

|Option|Type|Default|Behavior|
|--|--|--|--|
|`showTrigger`|`boolean`|`false`|Makes `ConsentRoot` render the trigger.|
|`triggerDefaultPosition`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Starting corner.|
|`triggerSize`|`'sm' \|'md' \|'lg'`|`'md'`|32, 40 or 48 pixels.|
|`triggerIcon`|`'branding' \|'fingerprint' \|'settings'`|`'fingerprint'`|The icon inside the button. `'branding'` shows the c15t or Inth mark.|
|`triggerPersistPosition`|`boolean`|`true`|Remembers where the visitor dragged it, in localStorage under `c15t:dialog-trigger-position`.|
|`triggerShowWhen`|`'always' \|'after-consent' \|'never'`|`'after-consent'`|`'after-consent'` shows the trigger once the policy owes no prompt: the visitor saved a choice or dismissed a notice. `'always'` also shows it while the banner is open. `'never'` hides it.|
|`triggerAriaLabel`|`string`|`'Open privacy settings'`|The button's accessible name.|

## Accessibility and styling

The trigger is a native `button` with `aria-label` set from
`triggerAriaLabel`. The icon is hidden from assistive technology. Set
`triggerAriaLabel` in the visitor's language, because the default is
English.

The `components.trigger` option adds attributes to `root`, `icon` and
`text`. Setting `components.trigger.text`, even to `{}`, shows
`triggerAriaLabel` as visible text next to the icon. The button carries
`data-size` and, while dragged, `data-dragging`.
The toolbar shown while `ConsentDevTools` is mounted takes `toolbar`,
`toolbarItem` and `toolbarIcon` instead.

## Verify

Load a page under a policy with a prompt and answer the banner. Confirm the
button appears in the corner you set. Click it and the preference dialog opens while the
button hides. Drag it, reload, and confirm it keeps its place when
`triggerPersistPosition` is on.

# ConsentGate
URL: https://c15t.com/docs/shared/vue/components/consent-gate
Shared ConsentGate reference for the c15t Vue plugin and Nuxt module.

## What ConsentGate renders

`ConsentGate` renders its default slot while the visitor's effective
permission for `category` is granted, and its `placeholder` slot otherwise.
It adds no wrapper element. While permission is denied, the default slot
does not exist in the DOM, so an iframe or widget inside it sends no
requests. When the visitor withdraws permission, Vue removes the slot
content.

Permission is the same value `useConsent()` returns for the category. It can
be granted under an opt-out policy before the visitor has recorded a choice,
and a privacy signal such as Global Privacy Control can deny a category the
visitor granted.

Without a `placeholder` slot, the gate renders the same placeholder as the
React and Svelte gates. It shows the `consentGate.title` text with the
category name, and a button labelled with `consentGate.actionButton` that
opens the preference dialog. Under a strict policy that leaves the category
out, no choice can allow the content, so the placeholder shows
`consentGate.policyBlocked` and no button. The text is in the visitor's
language once init has delivered copy, and in English until then. The
placeholder is a card styled by your theme tokens and the
`--consent-gate-placeholder-*` variables. A `placeholder` slot replaces it
entirely.

To restyle the built-in placeholder instead, set its parts under
`components['consent-gate']` in the options. `root` is the card, and
`title` and `button` are its text and button. Use Vue attribute names such as `class` and `style`. The
`consentGate`, `consentGateTitle` and `consentGateButton` theme slots reach
the same parts. The placeholder carries
`data-testid="consent-gate-placeholder"`, its title
`data-testid="consent-gate-title"` and its button
`data-testid="consent-gate-button"`.

`ConsentGate` also adds its `category` to the categories the preference
dialog lists, so the button opens a dialog where the visitor can allow it.

## Props and slots

|Name|Kind|Type|Behavior|
|--|--|--|--|
|`category`|Prop, required|`'necessary' \|'functionality' \|'measurement' \|'experience' \|'marketing'`|The category whose permission gates the default slot.|
|`default`|Slot||The gated content, such as an iframe.|
|`placeholder`|Slot||Shown while the category is denied.|

## Accessibility

Give the iframe a descriptive `title`. Keep a way to reach the content
without the embed, such as a link or a transcript, for visitors who decline
the category. A policy can fix a category as denied, so opening preferences
does not guarantee the visitor can allow it.

# ConsentManager
URL: https://c15t.com/docs/shared/vue/components/consent-manager
Shared ConsentManager reference for the c15t Vue plugin and Nuxt module.

## What ConsentManager renders

`ConsentManager` is the preference dialog, the component the React adapter
calls `ConsentDialog`. It opens while `activeUI` is `'manager'`. Anything
that sets `activeUI` to `'manager'` opens it: the banner's Customize button,
`ConsentDialogLink`, `ConsentDialogTrigger` and your own code. It
renders nothing until the visitor's policy has resolved, and nothing when
the policy owes no consent UI.

The dialog holds the same content as `ConsentWidget`: a list of the
categories the policy lets the visitor choose, each with a switch and a
description, and the vendors you declared under each category. Necessary is
always on. The footer shows Reject All, Accept All and Save Settings, with Save Settings as the
primary button.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* After a successful action the dialog closes. The banner comes back only if
  the policy still requires a choice.
* Escape closes the dialog without saving. The banner comes back if the
  policy still requires a choice.
* If the policy changes while the dialog is open, the dialog shows "Privacy
  choices have changed." with a button that reloads the switches from the
  new policy. Save stays blocked until the visitor reviews them.

The title comes from `consentManagerDialog.title` in the resolved
translations. `dialogLegalLinks` picks which of your `legalLinks` appear
under the description. The dialog has no props, slots or text props.

## Accessibility and focus

The dialog renders in `document.body` with `role="dialog"`, labelled by its
title and described by its description. By default it is modal: it shows a
backdrop, sets `aria-modal="true"`, locks page scrolling, moves focus to the
first control inside and keeps Tab inside the dialog. When it closes, focus
returns to the element that had it before. Set
`presentation.preferences.blocking` to `false` for a non-modal dialog with
no backdrop.

Each category switch is a `button` with `role="switch"`, `aria-checked` and
the category title as its label. Each category row expands with a button
that sets `aria-expanded` and `aria-controls`.

## Style the dialog

The `components.dialog` option adds attributes to `root`, `overlay`,
`container`, `card`, `header`, `title` and `content`. The category list
inside uses `components.manager`, `components.accordion`,
`components['accordion-item']`, `components.switch` and
`components['vendor-list']`. [Component slots](/docs/customization/slots)
lists every part. `presentation.preferences` sets the footer's `layout`,
`primaryActions`, `direction`, `uiProfile` and `blocking`.

`dialogHideBranding`, or `hideBranding` for every surface, hides the
"Secured by" tag. `disableAnimation` turns off the transitions.

## Verify

Open preferences, turn one optional category on and click Save. The dialog
closes. Reload and open preferences again: the switch is still on. Press
Escape with the dialog open and confirm it closes and focus returns to the
control that opened it.

# ConsentWidget
URL: https://c15t.com/docs/shared/vue/components/consent-widget
Shared ConsentWidget reference for the c15t Vue plugin and Nuxt module.

## What ConsentWidget renders

`ConsentWidget` renders the preference controls inline, in the page flow,
for a privacy or account settings page. It shows the categories the policy
lets the visitor choose, each with a switch that expands to its description
and declared vendors, and a footer with Reject All, Accept All and Save Settings.
Necessary is always on and its switch is disabled.

* Save records the switches as they are. Accept All and Reject All record a
  choice for every category the policy covers.
* The switches start from the visitor's recorded choice. Before any choice,
  they start from the policy's defaults: on under an opt-out policy or for
  preselected categories, otherwise off.
* A choice saved elsewhere, such as in the banner, updates switches the
  visitor has not touched and keeps the ones they moved.
* If the policy changes, the widget shows "Privacy choices have changed."
  with a button that reloads the switches. Save stays blocked until then.

The widget renders nothing until the visitor's policy has resolved, and
nothing when the policy owes no consent UI. It does not open or close any
other surface. `ConsentManager` renders the same widget inside the dialog.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`hideBranding`|`boolean`|`true`|Hides the "Secured by" tag.|
|`noStyle`|`boolean`|`false`|Drops the built-in classes from every part, so your own CSS starts from plain markup.|
|`language`|`string`|The resolved language|Sets the text direction. It does not change the text.|

## Accessibility

Each switch is a `button` with `role="switch"`, `aria-checked` and the
category title as its label. Each row expands with a button that sets
`aria-expanded` and `aria-controls`, and one row is open at a time. The
footer actions are native buttons. Give the page a heading that names the
widget, as in the example above.

## Style the widget

The widget reads `components.manager` for its root and footer,
`components.accordion` and `components['accordion-item']` for the rows,
`components.switch` for the switches and `components['vendor-list']` for
vendor rows. [Component slots](/docs/customization/slots) lists every part.
`presentation.preferences` sets the footer's `layout`, `primaryActions`,
`direction` and `uiProfile`, and applies to the dialog too.

## Verify

Open the page with the widget in a private window. Turn **Analytics** (the `measurement` category) on and
click Save. Reload: the switch is still on, and scripts gated on
measurement load. Turn it off and save, and the page reloads without them.

# ConsentDevTools
URL: https://c15t.com/docs/shared/vue/components/dev-tools
Shared ConsentDevTools reference for the c15t Vue plugin and Nuxt module.

## What ConsentDevTools renders

`ConsentDevTools` mounts a floating panel for the consent runtime your app
already created. It renders nothing into your component tree and mounts its
panel in `document.body`. It must render inside the app that set up c15t,
or it throws `[c15t] Kernel not found`.

|Panel|What it shows|
|--|--|
|Consents|Each category's value, with save, accept all and reject actions|
|Scripts|Your `scripts`, their loading status, and the scripts and iframes found in the page|
|Location|The resolved country and region|
|Policy|The resolved policy and presentation|
|IAB|Vendors, purposes and the TC String, under an IAB policy|
|Events|A timeline of consent changes and script events|
|Actions|Show the banner, open preferences, hide consent UI, or resolve the policy again|

Accept and reject in the Consents panel apply only to the categories the
policy covers, filtered by `consentCategories`. Necessary stays on.
`DevTools` and `C15TDevTools` are other names for the same component.

## Open DevTools from the consent trigger

While `ConsentDialogTrigger` is visible, it becomes a two-button toolbar
with a DevTools button, and DevTools hides its own floating launcher, so one
control occupies the corner. The DevTools button sits at the end farthest
from the trigger's corner. The panel opens just past the toolbar, aligned
with its outer edge, and follows it when a visitor drags the toolbar to
another corner. `position` applies again once no trigger is visible.

DevTools brings its launcher back whenever the trigger is hidden, for
example while `triggerShowWhen: 'after-consent'` waits for a choice. A
production build that loads DevTools only in development shows the single
trigger button.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`position`|`'top-left' \|'top-right' \|'bottom-left' \|'bottom-right'`|`'bottom-right'`|Corner of the toggle button.|
|`defaultOpen`|`boolean`|`false`|Opens the panel on load.|
|`defaultTab`|`'consents' \|'scripts' \|'location' \|'policy' \|'iab' \|'events' \|'actions'`|`'consents'`|Panel shown first.|
|`maxEvents`|`number`|`100`|How many events the Events panel keeps.|
|`getConsentCategories`|`() => readonly ConsentCategory[]`|`consentCategories`|Narrows the categories the Consents panel acts on. It cannot add categories outside the policy.|
|`getPresentation`|`() => ConsentPresentation \|undefined`|Your `presentation` option|Presentation the Policy panel resolves.|
|`clearRecords`|`() => void`|Clears the stored consent records|Runs when you clear records from the panel.|
|`shadow`|`boolean`|`true`|Mounts the panel inside a shadow root that carries its own stylesheet, so your page's CSS cannot restyle it. `:shadow="false"` mounts the panel in the light DOM and adds its stylesheet to `<head>`.|

Changing a prop destroys the panel and creates a new one, which clears its
event history.

## Embed the panel in your own page

`ConsentDevToolsPanel` from `c15t/vue/devtools` fills its parent element
instead of floating over the page. It has no launcher or close button and
starts open. Use it for your own debug page or another devtools host. Give
the parent a height:

```vue
<script setup lang="ts">
import { ConsentDevToolsPanel } from 'c15t/vue/devtools';
</script>

<template>
  <div style="height: 32rem">
    <ConsentDevToolsPanel default-tab="events" />
  </div>
</template>
```

It accepts `defaultTab`, `maxEvents`, `getConsentCategories`,
`getPresentation` and `clearRecords`, and must render inside the provider
that supplies the kernel.

# IABConsentBanner
URL: https://c15t.com/docs/shared/vue/components/iab-consent-banner
Shared IABConsentBanner reference for the c15t Vue plugin and Nuxt module.

## What IABConsentBanner renders

`IABConsentBanner` is the IAB TCF first layer. It renders while `activeUI`
is `'banner'`, the `iab` option is set, and the visitor's policy uses the
`iab` model with a vendor list. `ConsentRoot` renders it in place of
`ConsentBanner` under such a policy, so you only import it to compose the
surfaces yourself.

The banner lists the purposes, stacks and special features your vendors
use, with the vendor count as a link. Its footer has Reject All, Accept All
and Customize.

* Accept All and Reject All save an IAB choice and write the TC String. The
  banner waits for the full Global Vendor List before it saves. If the list
  fails to load, the banner stays open and nothing is granted.
* Customize opens the IAB preference centre on its Purposes tab.
* The vendor count link opens it on its Vendors tab.

Its text comes from the IAB translations the backend resolved. The component
loads its own styles.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`primaryButton`|`'reject' \|'accept' \|'customize'`|`'customize'`|Which action gets the primary style.|

Keep Accept All and Reject All at the same prominence unless your legal
review says otherwise.

## Accessibility and styling

The banner renders in `document.body`. When the prompt is blocking it is a
`dialog` with `aria-modal="true"` and traps focus. Otherwise it is a
`region`. The `components['iab-banner']` option adds attributes to its
parts, such as `root`, `card`, `title`, `purposeList`, `partnersLink` and
`footer`. `iabBannerHideBranding` hides the "Secured by" tag, and
`iabBannerModels` limits which policy models show it.

# IABConsentDialog
URL: https://c15t.com/docs/shared/vue/components/iab-consent-dialog
Shared IABConsentDialog reference for the c15t Vue plugin and Nuxt module.

## What IABConsentDialog renders

`IABConsentDialog` is the IAB TCF preference centre. It opens while
`activeUI` is `'manager'`, the `iab` option is set, and the policy uses the
`iab` model. `ConsentRoot` loads it in place of `ConsentManager` under such
a policy.

It has two tabs. Purposes lists each purpose, stack and special feature with
consent and legitimate-interest switches. Vendors lists every vendor,
including your custom vendors, with a search field and per-vendor switches.
The footer saves the selection, or accepts or rejects everything, and writes
the TC String.

To build your own preference centre instead, read and change the selection
with `useConsentIabSelection()` and save it with `useConsentIabSave()`.

## Props

|Prop|Type|Default|Behavior|
|--|--|--|--|
|`initialTab`|`'purposes' \|'vendors'`|The tab the banner asked for, else `'purposes'`|Which tab the dialog opens on.|

## Accessibility and styling

The dialog renders in `document.body` with `role="dialog"`. While blocking
it sets `aria-modal="true"`, locks scrolling and traps focus. It has a close
button. The `components['iab-dialog']` option adds attributes to parts such
as `root`, `card`, `header`, `tabsList`, `tabPanel` and `footer`, and
`components['iab-purpose-item']`, `components['iab-stack-item']` and
`components['iab-vendor-list']` reach the rows. `iabDialogHideBranding`
hides the "Secured by" tag.

# Vue and Nuxt composables
URL: https://c15t.com/docs/shared/vue/composables
Shared composable reference for the c15t Vue plugin and Nuxt module.

## Where composables work

Call the composables inside `setup` of a component that renders in the app
where c15t is installed. Anywhere else they throw an error such as
`[c15t] Kernel not found`. Most return a Vue `computed`, so read them with
`.value` in `<script setup>` and without it in the template. They update
whenever the consent runtime changes.

## Permission or recorded choice

`useConsent()` and `useHasConsent()` answer "may this run now?" Under an
opt-out policy a category can be allowed before the visitor has done
anything, and Global Privacy Control can deny a category the visitor
allowed. Use them to decide whether to run code or render optional content.

`useExplicitChoice()` answers "what did the visitor decide?" It stays
`null` until the visitor accepts, rejects or saves. Use it to show the
visitor's choice or to report consent rates. Loading a page never changes
it, and dismissing a notice does not set it.

Never save a choice on the visitor's behalf because a permission is `true`.
[How consent works](/docs/concepts/how-consent-works#a-permission-is-not-a-recorded-choice)
explains the difference.

## Read consent state

|Composable|Returns|Use it to|
|--|--|--|
|`useConsent()`|Computed `Record<category, boolean>`|Read every category's current permission, such as `consent.value.marketing`.|
|`useHasConsent()`|Computed array of allowed categories|List what may run now. The array keeps its identity until a category changes.|
|`useEffectivePermissions()`|Computed permissions|The same values as `useConsent()`, read from the snapshot field.|
|`useVendorAllowed(id)`|Computed `boolean`|Check whether one vendor may run: it is declared, its category is allowed and the visitor has not switched it off. `false` for an id nothing declares.|
|`useExplicitChoice()`|Computed recorded choice, or `null`|Read what the visitor decided.|
|`useStoredConsent()`|Computed recorded choice, or `null`|The same value as `useExplicitChoice()`.|
|`useNoticeDismissal()`|Computed dismissal record, or `null`|Check whether the visitor dismissed a notice.|
|`usePrivacySignals()`|Computed privacy signals|Read whether Global Privacy Control was detected and applied.|
|`useConsentRestrictions()`|Computed restrictions|See why a permission is limited, for example by the policy or a privacy signal.|
|`usePolicyRule()`|Computed policy rule|Read the `model`, `prompt`, `scope` and `rights` of the visitor's policy.|
|`usePolicyResolution()`|Computed resolution|Check that a policy matched. `status` is `'matched'` when one applies.|
|`useRequestRegion()`|Computed `{ country, region }`|Read the location the policy resolved for.|

## Record a choice

`useConsentSave()` returns a function that records a choice and resolves to
`{ ok }` once the backend has answered. c15t applies the choice in the page
before the request, so gated scripts start without waiting for it.

|Argument|Records|
|--|--|
|`'all'`|Every category the policy covers allowed.|
|`'none'`|Every optional category denied.|
|`['measurement']`|The listed categories allowed and every other optional category denied.|

`useDismissNotice()` returns the function that dismisses a notice. It
records an acknowledgement, grants nothing and leaves earlier refusals in
place. Use it only for a policy whose prompt is `notice`.

## Open the banner or preferences

`useConsentActiveUI()` returns a writable computed. Its value is
`'banner'`, `'manager'` or `null`. Set it to `'manager'` to open
preferences, to `'banner'` to show the banner again, or to `null` to close
both. The Vue adapter uses `'manager'` where the React adapter uses
`'dialog'`. `ConsentDialogLink` does the same as setting `'manager'` and
hides itself when the policy offers no preferences.

## Change the language

`useConsentLanguage()` returns a writable computed with the language
override, or `null`. Assigning a new language code stores it and runs init
again, so c15t fetches the banner and dialog text in that language.
Assigning the current language, or `null`, does nothing.

## Build a preference form

`useConsentDraft()` holds the switches of a preference form separately from
the recorded choice, so nothing is saved until the visitor clicks Save.

|Field|Type|Meaning|
|--|--|--|
|`displayedCategories`|`ComputedRef<category[]>`|The categories the policy lets the visitor choose, in the order necessary, functionality, measurement, experience, marketing.|
|`values`|`Ref<Partial<Record<category, boolean>>>`|One value per category. Bind switches to it with `v-model`; a write to `necessary` or to a category the policy does not offer snaps back.|
|`vendors`|`ComputedRef<Record<string, boolean>>`|One value per declared vendor. Change them with `setVendor(id, granted)`.|
|`isDirty`|`ComputedRef<boolean>`|`true` while any value differs from the recorded choice.|
|`isStale`|`ComputedRef<boolean>`|`true` when the policy, the displayed categories or the vendor list changed while the draft held an unsaved change.|
|`save()`|`() => Promise<{ ok: boolean }>`|Records `values` and changed vendors. Resolves `{ ok: false }` without saving while `isStale` is `true`.|
|`reset()`|`() => void`|Refills the draft from the recorded choice and the policy.|

The draft starts from the recorded choice. Before any choice, it starts
from the policy's defaults: on under an opt-out policy or for preselected
categories, otherwise off. A choice saved elsewhere updates the values the
visitor has not touched. `save()` does not close anything. Set `activeUI`
to `null` yourself after it.

## Render the actions the policy requires

|Composable|Returns|Use it to|
|--|--|--|
|`usePromptRequirement()`|Computed `{ kind }`, where `kind` is `'choice'`, `'notice'` or `'none'`|Decide whether to show a banner at all.|
|`useConsentPolicyActions(surface)`|Computed `actionGroups`, `primaryActions`, `variant`, `position`, `blocking`, `direction` and `preferenceControls`|Render the buttons a banner (`'prompt'`) or preference form (`'preferences'`) must show, in order.|
|`useHasConsentPolicy()`|Computed boolean|Check that a policy matched the visitor.|
|`useHasConsentUi()`|Computed boolean|Check that the policy owes any consent UI. Every stock surface hides while it is `false`.|
|`useHasConsentPreferences()`|Computed boolean|Check whether a preferences control should render.|

Under a notice, `actionGroups` holds `dismiss` instead of accept and
reject. `preferenceControls` lists extra buttons, `'opt-out'` or
`'preferences'`, that open preferences under a policy with those rights.

## IAB TCF

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentIabSelection()`|Writable computed with purpose, legitimate-interest, vendor and special-feature maps, and `preferenceCenterTab`|Read and change the visitor's IAB selection in a custom preference centre. Writing it updates gating live without saving.|
|`useConsentIabSave()`|`(input, tab?) => Promise<void>`|Save `'all'`, `'none'` or a selection. It waits for the Global Vendor List, then writes the TC String.|
|`useIabTranslations()`|Computed IAB copy|Read the IAB banner and dialog text for the visitor's language.|

## Advanced

|Composable|Returns|Use it to|
|--|--|--|
|`useConsentSnapshot()`|`Ref<ConsentSnapshot>`|Read any snapshot field, such as `policyPending`, `vendors` or `iab`.|
|`useConsentKernel()`|The consent kernel|Call `commands.init()`, `commands.save()`, `commands.identify(user)`, subscribe with `events.on(type, listener)`, or read `getSnapshot()`.|
|`useConsentConfig()`|Computed options, merged with defaults|Read the options you passed.|
|`useConsentInit()`|Computed `{ translations, location, branding, gvl, cmpId, customVendors }`, or `undefined` before the policy resolves|Read display data from the resolved policy.|
|`useConsentComponent(name)`|Computed slot attributes|Read the `components` option for one component, to reuse it in custom markup.|

`useConsentKernel().events.on()` returns an unsubscribe function. Call it in
`onUnmounted`. For choice and permission events, prefer the `callbacks`
option, which c15t wires once for the whole app.