---
title: Upgrade from v2
description: 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.
group: frameworks
lastModified: "2026-10-10T16:01:45+01:00"
---
**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.