@c15t/react 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/react/iab/overview.md

@@ -1,128 +1,53 @@
 ---
-title: IAB TCF 2.3
-description: Implement IAB Transparency & Consent Framework 2.3 compliance for
-  programmatic advertising in EU/EEA jurisdictions.
+title: IAB TCF
+description: Mount the IAB TCF banner and dialog inside a React ConsentProvider
+  and configure the CMP ID, policy and vendor data.
 group: frameworks
 ---
-## What is IAB TCF?
 
-The [IAB Transparency & Consent Framework (TCF)](https://iabeurope.eu/tcf-2-0/) is a standardized protocol for communicating user consent choices to ad tech vendors in the programmatic advertising ecosystem. TCF 2.3 is the current version and is widely adopted across the EU/EEA.
+## Prepare the IAB configuration
 
-When your site participates in the IAB ecosystem (ad exchanges, SSPs, DSPs, DMPs), you need to:
+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.
 
-* Disclose which vendors process user data and for what purposes
-* Collect granular consent for each IAB-defined purpose
-* Generate a **TC String** — a standardized encoding of consent choices that ad tech vendors can read
-* Expose the `__tcfapi` CMP stub for vendor scripts to query consent status
+Install `@c15t/iab` alongside your framework adapter, then mount the IAB
+components inside an existing consent provider connected to Inth.
 
-## CMP Registration
+Import the components from `c15t/react/iab` and render them inside your
+existing `ConsentProvider` from `c15t/react`. Import `c15t/react/iab/styles.css`
+at your global stylesheet entry.
 
-[Inth](https://inth.com), c15t's hosted platform, is IAB TCF certified. When you use Inth as your backend with c15t's prebuilt IAB UI, the correct CMP ID is automatically provided to your client via the `/init` endpoint — no client-side configuration needed.
+```tsx title="src/iab-consent.tsx"
+import { IABProvider, IABConsentBanner, IABConsentDialog } from 'c15t/react/iab';
 
-If you self-host the c15t backend or want to operate as your own CMP, register your own CMP with IAB Europe and configure your CMP ID on the backend via `advanced.iab.cmpId` or on the client via the `iab.cmpId` option. Registering your own CMP may also involve IAB Europe fees, so check IAB Europe's current CMP registration terms and pricing before choosing this route. A valid (non-zero) CMP ID is required for IAB TCF compliance.
-
-> ⚠️ **Warning:**
-> If you heavily customize or build your own IAB banner or dialog instead of using the default IABConsentBanner and IABConsentDialog components, you cannot use Inth's CMP ID. You must register your own CMP with IAB Europe and use your own CMP ID.
-
-## How c15t Implements TCF
-
-c15t provides a complete IAB TCF 2.3 CMP (Consent Management Platform) implementation:
-
-1. **Global Vendor List (GVL)** — Automatically fetched from the c15t backend. Contains the official IAB vendor registry with purposes, features, and stacks.
-2. **IABConsentBanner** — A pre-built banner showing partner count, purpose summaries, and legitimate interest notices.
-3. **IABConsentDialog** — A tabbed preference center for granular purpose and vendor consent management.
-4. **TC String generation** — Consent choices are encoded into the standard TC String format.
-5. **`__tcfapi` stub** — The standard CMP API is exposed on `window` so vendor scripts can query consent.
-
-If you use the prebuilt styled IAB UI, add your framework's `iab/styles.css` entrypoint alongside the base c15t stylesheet. IAB CSS is published separately so apps that do not render IAB surfaces do not ship those component rules.
-
-## Quick Setup
-
-If you use the prebuilt styled IAB UI, import the IAB stylesheet alongside the base stylesheet in your global CSS entrypoint:
-
-```css title="src/index.css"
-@import "@c15t/react/styles.css";
-@import "@c15t/react/iab/styles.css";
-```
-
-```tsx
-import { type ReactNode } from 'react';
-import { iab } from '@c15t/iab';
-import { ConsentManagerProvider } from '@c15t/react';
-import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
-
-export default function ConsentManager({ children }: { children: ReactNode }) {
+export function IABConsent({ cmpId }: { cmpId: number }) {
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        iab: iab({
-          vendors: [1, 2, 10, 25],  // IAB vendor IDs you work with
-          // cmpId is automatically provided by the backend (inth.com).
-          // Only set this if you have your own CMP registration with IAB Europe.
-          // cmpId: 123,
-        }),
-      }}
-    >
+    <IABProvider cmpId={cmpId}>
       <IABConsentBanner />
-      <IABConsentDialog showTrigger />
-      {children}
-    </ConsentManagerProvider>
+      <IABConsentDialog />
+    </IABProvider>
   );
 }
 ```
 
-## IAB Configuration Options
-
-Configure IAB mode with `iab({ ... })` from `@c15t/iab`. The factory enables the addon and injects the runtime module automatically. The user-facing options are:
-
-|Option|Type|Description|
-|--|--|--|
-|`cmpId`|`number`|CMP ID registered with IAB Europe. Automatically provided by the backend when using Inth with the prebuilt IAB UI. Only set this if you have your own CMP registration.|
-|`vendors`|`number[]`|IAB vendor IDs that your site works with|
-|`customVendors`|`NonIABVendor[]`|Custom vendors not in the IAB registry|
-
-## Key Concepts
-
-### Purposes
-
-IAB defines 11 standard purposes for data processing (e.g., "Store and/or access information on a device", "Select basic ads", "Measure ad performance"). Each purpose can be consented to individually.
-
-### Stacks
-
-Purposes are grouped into **stacks** by the GVL for a simplified UI presentation. For example, "Advertising based on limited data" might group purposes 2, 7, and 10 together.
-
-### Special Features
-
-Features like precise geolocation or device scanning that require explicit opt-in beyond standard consent.
-
-### Legitimate Interest
-
-Some purposes can be processed under legitimate interest rather than consent. Users can object to legitimate interest processing per-vendor.
-
-### Vendors
-
-Each vendor in the GVL declares which purposes it uses, whether via consent or legitimate interest. The preference center lets users toggle consent per-vendor.
+Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
+preferences entry point through the surrounding consent provider.
 
-## Standard vs IAB Components
+## Resolve the policy before rendering
 
-|Feature|ConsentBanner / ConsentDialog|IABConsentBanner / IABConsentDialog|
-|--|--|--|
-|Consent model|opt-in / opt-out|IAB TCF 2.3|
-|Granularity|Category-level (measurement, marketing, etc.)|Purpose-level + vendor-level|
-|Vendor management|No|Yes (full GVL integration)|
-|TC String|No|Yes|
-|`__tcfapi`|No|Yes|
-|Legitimate interest|No|Yes|
-|Use when|General GDPR/CCPA compliance|Programmatic advertising in EU/EEA|
+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.
 
-## Components
+IAB presentation follows `presentation.prompt.blocking` and
+`presentation.preferences.blocking`. A blocking dialog needs focus management,
+scroll locking and a backdrop together. See [migration](../../../upgrade-v3.md) for
+legacy option behavior.
 
-|Component|Description|
-|--|--|
-|[IABConsentBanner](/docs/frameworks/react/iab/consent-banner)|TCF-compliant banner with partner disclosure|
-|[IABConsentDialog](/docs/frameworks/react/iab/consent-dialog)|Tabbed preference center for purposes and vendors|
+## Verify vendor and purpose choices
 
-> ℹ️ **Info:**
-> For lower-level custom IAB flows, use useHeadlessIABConsentUI() from @c15t/react/iab. useGVLData() is currently internal and is not part of the public package surface.
+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.

package/docs/frameworks/react/quickstart.md

@@ -1,139 +1,143 @@
 ---
 title: Quickstart
-description: Add consent management to your React app in under 5 minutes.
-variants:
-  - value: javascript
-    href: /docs/frameworks/javascript/quickstart
-    label: JavaScript
-  - value: react
-    href: /docs/frameworks/react/quickstart
-    label: React
-  - value: next
-    href: /docs/frameworks/next/quickstart
-    label: Next.js
+description: Connect a React application to Inth and add consent UI, persistence
+  and a preferences link.
 group: frameworks
 ---
-## Via CLI
 
-<PackageCommandTabs command="@c15t/cli" />
+## Connect Inth
 
-## Manual Installation
+[Create an Inth project](https://inth.com), configure policy rules and the app's
+allowed origin, and copy its backend endpoint. This guide uses a client-rendered
+React app with Vite. Applications with a framework server should use that
+framework's adapter for request prefetch.
 
-1. **Install package**
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install c15t @c15t/scripts` |
+| pnpm            | `pnpm add c15t @c15t/scripts`    |
+| yarn            | `yarn add c15t @c15t/scripts`    |
+| bun             | `bun add c15t @c15t/scripts`     |
 
-2. **Import styles** Import the prebuilt component stylesheet in your app-level CSS entrypoint. This is required for styled components to render correctly.
+Set `VITE_C15T_BACKEND_URL` to the endpoint from Inth. Vite embeds public values
+at build time, so rebuild when changing it. Keep management credentials out of
+public variables.
 
-   ```css
-   @import "@c15t/react/styles.css";
-   ```
+## Register consent-gated scripts
 
-   Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.With Tailwind v4, keep c15t at the end of the top-level @import block so Fumadocs, tw-animate-css, and other preset imports do not override c15t theme tokens.
+Include measurement and marketing categories in your policy for these vendors.
+Remove any existing loaders for them so each script loads once.
 
-   > ℹ️ Info:
-   > If you are using the headless API or fully custom styling, you can skip this import. src/main.tsx should keep importing ./index.css as usual.
+This setup uses Vite's public environment variables. Set the Inth endpoint and
+add your PostHog project key, PostHog API host and X Pixel ID in `.env.local`:
 
-3. **Create ConsentManager components** Create a provider component with the consent UI and a wrapper that re-exports it. This initializes the consent store and makes consent state available to all child components.
-
-   ```tsx
-   'use client';
-
-   import { type ReactNode } from 'react';
-   import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
-
-   export default function ConsentManagerClient({ children }: { children: ReactNode }) {
-     return (
-       <ConsentManagerProvider
-         options={{
-           mode: 'hosted',
-           backendURL: 'https://your-instance.c15t.dev',
-           consentCategories: ['necessary', 'measurement', 'marketing'],
-           // Shows banner during development. Remove for production.
-           overrides: { country: 'DE' },
-         }}
-       >
-         <ConsentBanner />
-         <ConsentDialog />
-         {children}
-       </ConsentManagerProvider>
-     );
-   }
-   ```
-
-   ```tsx
-   import type { ReactNode } from 'react';
-   import ConsentManagerProvider from './provider';
-
-   export function ConsentManager({ children }: { children: ReactNode }) {
-     return <ConsentManagerProvider>{children}</ConsentManagerProvider>;
-   }
-   ```
-
-   > ℹ️ Info:
-   > Hosted mode is the recommended production setup because the backend resolves jurisdiction and policy, keeps durable consent records, and lets c15t recover from temporary network failures by re-syncing later.
-   >
-   > ⚠️ Warning:
-   > Don't have a backend yet? You can use mode: 'offline' for local-only consent storage, but it gives up backend audit history, server-side consent awareness, and automatic jurisdiction detection. Review the browser-only storage consequences before choosing it for production.
-
-4. **Mount ConsentManager at the app root** Wrap your existing app tree with `ConsentManager` so all routes/components can access consent state.
-
-   ```tsx
-   import { ConsentManager } from './components/consent-manager';
-
-   export default function App() {
-     return (
-       <ConsentManager>
-         {/* your existing app */}
-       </ConsentManager>
-     );
-   }
-   ```
-
-5. **Verify it works** Start your development server and confirm:
-
-   1. A **consent banner** appears at the bottom of the page
-   2. Clicking **"Customize"** opens a dialog with toggles for each consent category
-   3. After accepting or rejecting, the banner dismisses and your choice persists across page reloads
+```dotenv title=".env.local"
+VITE_C15T_BACKEND_URL=
+VITE_POSTHOG_KEY=
+VITE_POSTHOG_HOST=
+VITE_X_PIXEL_ID=
+```
 
-> ℹ️ **Info:**
-> Want to improve startup performance? See Optimization for the decision guide, prefetch setup, and network tuning.
+Copy the exact backend endpoint from Inth. The vendor IDs are optional: leaving
+an ID empty disables that integration. When enabling PostHog, fill in both its project key and the API host
+shown in your PostHog project. Restart Vite after editing these values and
+rebuild for deployment. Other bundlers need their own configuration mechanism.
+
+Create `src/scripts.ts`. PostHog waits for measurement permission with
+`loadMode: 'after-consent'` and disables cookieless capture with
+`cookieless_mode: 'never'`. X Pixel waits for marketing permission.
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/scripts/posthog';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+const posthogKey = import.meta.env.VITE_POSTHOG_KEY;
+const xPixelId = import.meta.env.VITE_X_PIXEL_ID;
+
+export const scripts = [
+	...(posthogKey
+		? [
+				posthog({
+					apiHost: import.meta.env.VITE_POSTHOG_HOST,
+					id: posthogKey,
+					initOptions: { cookieless_mode: 'never' },
+					loadMode: 'after-consent',
+				}),
+			]
+		: []),
+	...(xPixelId ? [xPixel({ pixelId: xPixelId })] : []),
+];
+```
 
-## Optional: Add DevTools
+## Mount the provider and UI
+
+```tsx title="src/consent.tsx"
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentProvider,
+  hosted,
+} from 'c15t/react';
+import 'c15t/react/styles.css';
+import { scripts } from './scripts';
+
+const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+const mode = hosted({ url: backendURL });
+
+export function Consent({ children }: { children: ReactNode }) {
+  return (
+    <ConsentProvider options={{ mode, scripts }}>
+      {children}
+      <ConsentBanner />
+      <ConsentDialog />
+      <footer><ConsentDialogLink>Privacy settings</ConsentDialogLink></footer>
+    </ConsentProvider>
+  );
+}
+```
 
-Install DevTools only if you want a runtime inspector while building and debugging:
+```tsx title="src/main.tsx"
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import { Consent } from './consent';
 
-<PackageCommandTabs mode="install" command="@c15t/dev-tools" />
+const root = document.getElementById('root');
+if (!root) throw new Error('Missing #root element');
+createRoot(root).render(<Consent><App /></Consent>);
+```
 
-Then add it inside your existing provider:
+Keep `Consent` mounted across navigation. The banner appears when the resolved
+policy requires a prompt; not every region or returning visitor needs one.
+The dialog link keeps preferences reachable after the prompt closes.
 
-```tsx title="components/consent-manager/provider.tsx"
-import { DevTools } from '@c15t/dev-tools/react';
+## Gate optional functionality
 
-// ...
+```tsx
+import { useConsent } from 'c15t/react';
 
-<ConsentManagerProvider options={...}>
-  <ConsentBanner />
-  <ConsentDialog />
-  {process.env.NODE_ENV !== 'production' && <DevTools />}
-  {children}
-</ConsentManagerProvider>
+export function MarketingContent() {
+  return useConsent('marketing') ? <div>Optional marketing content</div> : null;
+}
 ```
 
-> ℹ️ **Info:**
-> Want to understand what's happening under the hood? See Initialization Flow for the lifecycle and Cookie Management for script/cookie behavior and revocation handling.
-
-## Optional: AI Agents
+This controls the rendered component. Move vendor SDKs into the
+[script loader](./script-loader.md) too. An independently
+loaded analytics script does not wait merely because a consent provider exists.
 
-Install c15t agent skills to let AI agents help with styling, i18n, scripts & other configuration.
+`useConsent` returns effective permission, not proof of an explicit grant.
+Read [consent state](../../guides/consent-state.md) when recording choice events.
 
-<PackageCommandTabs command="@c15t/cli skills" />
+## Verify and customize
 
-See [AI Agents](/docs/ai-agents) for bundled package docs and agent skills.
+Reject under an opt-in policy, reload and confirm optional requests stay blocked.
+Reopen preferences, save a different choice and test navigation. Follow
+[verification](../../guides/verify-consent.md), then
+[customization](../../customization/overview.md) to apply your design.
 
-## Next steps
+## Run the complete example
 
-* [Optimization](/docs/frameworks/react/optimization)
-* [Script Loader](/docs/frameworks/react/script-loader)
-* [Styling](/docs/frameworks/react/styling/overview)
-* [Consent Categories](/docs/frameworks/react/concepts/consent-categories)
-* [Components](/docs/frameworks/react/components/consent-banner)
-* [AI Agents](/docs/ai-agents)
+Try the [runnable example](https://c15t.com/docs/examples) with PostHog, X Pixel, a consent-gated
+YouTube video and a persistent preferences control. Use it to test rejection, permission changes and reloads.