@c15t/react 2.0.0-rc.3 → 2.0.0-rc.5

package/docs/components/consent-dialog-trigger.md

@@ -0,0 +1,103 @@
+---
+title: ConsentDialogTrigger
+description: A floating, draggable button that lets users re-open the consent dialog at any time.
+---
+`ConsentDialogTrigger` is a floating button that opens the consent dialog when clicked. Users can drag it to any corner of the screen, and the position persists across sessions. Use it to give users a persistent way to manage their privacy settings.
+
+## Basic Usage
+
+Use standalone or via the `showTrigger` prop on `ConsentDialog`:
+
+```tsx
+import { ConsentDialogTrigger } from '@c15t/react';
+
+// Standalone
+<ConsentDialogTrigger />
+
+// Via ConsentDialog
+<ConsentDialog showTrigger />
+```
+
+For inline footer links (instead of a floating button), use [`ConsentDialogLink`](/docs/frameworks/react/components/consent-dialog-link).
+
+## Icon Options
+
+```tsx
+{/* Built-in icons */}
+<ConsentDialogTrigger icon="branding" />    {/* c15t logo (default) */}
+<ConsentDialogTrigger icon="fingerprint" /> {/* Privacy icon */}
+<ConsentDialogTrigger icon="settings" />    {/* Gear icon */}
+
+{/* Custom icon */}
+<ConsentDialogTrigger icon={<MyCustomIcon />} />
+```
+
+## Visibility
+
+Control when the trigger is visible:
+
+```tsx
+{/* Always visible (default) */}
+<ConsentDialogTrigger showWhen="always" />
+
+{/* Only after user has made a consent choice */}
+<ConsentDialogTrigger showWhen="after-consent" />
+
+{/* Hidden (control visibility programmatically) */}
+<ConsentDialogTrigger showWhen="never" />
+```
+
+## Position
+
+Set the default corner and control persistence:
+
+```tsx
+<ConsentDialogTrigger
+  defaultPosition="bottom-left"
+  persistPosition={true} // Remembers user's drag position
+  onPositionChange={(position) => console.log('Moved to:', position)}
+/>
+```
+
+## Size
+
+```tsx
+<ConsentDialogTrigger size="sm" /> {/* Small */}
+<ConsentDialogTrigger size="md" /> {/* Medium (default) */}
+<ConsentDialogTrigger size="lg" /> {/* Large */}
+```
+
+## Compound Components
+
+Build fully custom trigger layouts using sub-components:
+
+```tsx
+<ConsentDialogTrigger.Root defaultPosition="bottom-right">
+  <ConsentDialogTrigger.Button size="md">
+    <ConsentDialogTrigger.Icon icon="settings" />
+    <ConsentDialogTrigger.Text>Privacy</ConsentDialogTrigger.Text>
+  </ConsentDialogTrigger.Button>
+</ConsentDialogTrigger.Root>
+```
+
+* `ConsentDialogTrigger.Root` — Portal wrapper with drag handling and position persistence
+* `ConsentDialogTrigger.Button` — Draggable button element with size variants
+* `ConsentDialogTrigger.Icon` — Icon display (branding, fingerprint, settings, or custom)
+* `ConsentDialogTrigger.Text` — Optional text label
+
+## Props
+
+### ConsentDialogTriggerProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|icon|TriggerIcon|Icon to display in the trigger button.|'branding'|Optional|
+|defaultPosition|CornerPosition \|undefined|Default corner position for the trigger. User can drag to any corner and the position will be remembered.|'bottom-right'|Optional|
+|persistPosition|boolean \|undefined|Whether to persist the user's position preference in localStorage.|true|Optional|
+|ariaLabel|string \|undefined|Accessible label for the trigger button.|'Open privacy settings'|Optional|
+|className|string \|undefined|Additional CSS class names.|-|Optional|
+|noStyle|boolean \|undefined|When true, removes default styling.|false|Optional|
+|showWhen|TriggerVisibility \|undefined|Controls when the trigger is visible.|'always'|Optional|
+|size|TriggerSize \|undefined|Size of the trigger button.|'md'|Optional|
+|onClick|(() => void) \|undefined|Callback fired when the trigger is clicked (before opening dialog).|-|Optional|
+|onPositionChange|((position: CornerPosition) => void) \|undefined|Callback fired when the corner position changes.|-|Optional|

package/docs/components/consent-dialog.md

@@ -0,0 +1,137 @@
+---
+title: ConsentDialog
+description: A modal dialog where users can toggle individual consent categories.
+---
+`ConsentDialog` is a modal that shows toggles for each consent category. In **opt-in jurisdictions**, it typically opens when users click "Customize" on `ConsentBanner`. It can also be controlled programmatically for use on settings pages regardless of jurisdiction.
+
+## Basic Usage
+
+```tsx
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+
+export function ConsentManager() {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
+      <ConsentBanner />
+      <ConsentDialog />
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Controlled State
+
+By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use the `open` prop for manual control:
+
+```tsx
+import { useState } from 'react';
+
+function SettingsPage() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Privacy Settings</button>
+      <ConsentDialog open={open} />
+    </>
+  );
+}
+```
+
+Or use the hook to open it programmatically:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function PrivacyLink() {
+  const { setActiveUI } = useConsentManager();
+
+  return (
+    <button onClick={() => setActiveUI('dialog')}>
+      Manage cookies
+    </button>
+  );
+}
+```
+
+## Floating Trigger
+
+Add a floating button that lets users re-open the dialog after dismissing the banner:
+
+```tsx
+{/* Default trigger */}
+<ConsentDialog showTrigger />
+
+{/* Custom trigger */}
+<ConsentDialog
+  showTrigger={{
+    icon: 'settings',
+    defaultPosition: 'bottom-left',
+    showWhen: 'after-consent',
+    size: 'sm',
+  }}
+/>
+```
+
+## Branding
+
+Hide the c15t branding in the dialog footer:
+
+```tsx
+<ConsentDialog hideBranding />
+```
+
+## Compound Components
+
+Build fully custom dialog layouts using sub-components:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.Overlay />
+  <ConsentDialog.Card>
+    <ConsentDialog.Header>
+      <ConsentDialog.HeaderTitle />
+      <ConsentDialog.HeaderDescription />
+    </ConsentDialog.Header>
+    <ConsentDialog.Content>
+      <ConsentWidget />
+    </ConsentDialog.Content>
+    <ConsentDialog.Footer />
+  </ConsentDialog.Card>
+</ConsentDialog.Root>
+```
+
+* `ConsentDialog.Root` — Portal container with focus trap, scroll lock, and animation
+* `ConsentDialog.Card` — Main dialog card
+* `ConsentDialog.Header` — Contains title and description
+* `ConsentDialog.HeaderTitle` — Dialog title
+* `ConsentDialog.HeaderDescription` — Description with optional `legalLinks`
+* `ConsentDialog.Content` — Main content area (typically contains `ConsentWidget`)
+* `ConsentDialog.Footer` — Footer with optional branding (`hideBranding` prop)
+* `ConsentDialog.Overlay` — Backdrop overlay
+
+For a quick pre-composed layout, use the shorthand card:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.ConsentCustomizationCard />
+</ConsentDialog.Root>
+```
+
+## Props
+
+### ConsentDialogProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|theme|undefined|Theme configuration override (deprecated)|-|Optional|
+|disableAnimation|boolean \|undefined|Disables all animations when true|-|Optional|
+|noStyle|boolean \|undefined|Removes default styles when true|-|Optional|
+|scrollLock|boolean \|undefined|Locks the scroll when true|-|Optional|
+|trapFocus|boolean \|undefined|Traps keyboard focus within a dialog when true|-|Optional|
+|open|boolean \|undefined|Control the open state. If omitted the dialog follows \`useConsentManager().activeUI === 'dialog'\`.|-|Optional|
+|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|hideBranding|boolean \|undefined|Controls whether to hide the branding in the dialog footer.|-|Optional|
+|showTrigger|ConsentDialogTriggerProps \|undefined|Show a floating trigger button to resurface the consent dialog. Useful for allowing users to re-open the dialog after dismissing. Options: \`true\` - Show trigger with default settings; \`false\` - Hide trigger (default); \`ConsentDialogTriggerProps\` - Show trigger with custom props|false|Optional|
+|models|Model \|undefined|Which consent models this dialog responds to.|\['opt-in', 'opt-out']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'dialog'|Optional|

package/docs/components/consent-manager-provider.md

@@ -0,0 +1,422 @@
+---
+title: ConsentManagerProvider
+description: The root provider component that initializes the consent system and makes consent state available to all child components.
+---
+`ConsentManagerProvider` is the root component for the c15t consent system. It initializes the consent store, detects the user's jurisdiction, resolves translations, and provides consent state to all child components via React context.
+
+Every other c15t component and hook must be rendered inside this provider.
+
+## Basic Usage
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        consentCategories: ['necessary', 'measurement', 'marketing'],
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Options Reference
+
+### CommonInlineStoreOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether c15t should be active.|true|Optional|
+|callbacks|[Callbacks \|undefined](https://v2.c15t.com/docs/frameworks/react/callbacks)|Event callbacks for consent actions.|-|Optional|
+|scripts|[Script \|undefined](https://v2.c15t.com/docs/frameworks/react/script-loader)|Dynamically load scripts based on consent state.|-|Optional|
+|legalLinks|Object \|undefined|Configuration for the legal links.|-|Optional|
+|storageConfig|StorageConfig \|undefined|Storage configuration for consent persistence.|-|Optional|
+|user|User \|undefined|The user's information. Usually your own internal ID for the user from your auth provider.|-|Optional|
+|overrides|Overrides \|undefined|Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.|-|Optional|
+|networkBlocker|[NetworkBlockerConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/network-blocker)|Configuration for the network request blocker.|-|Optional|
+|iab|[IABConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/iab/overview)|IAB TCF 2.3 configuration.|-|Optional|
+|ssrData|[Object \|undefined](https://v2.c15t.com/docs/frameworks/react/server-side)|SSR-prefetched data for hydration.|-|Optional|
+
+#### `callbacks` Callbacks
+
+Event callbacks for consent actions.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|onBannerFetched|Callback\<OnBannerFetchedPayload> \|undefined|Called when the consent banner is fetched.|-|Optional|
+|onConsentSet|Callback\<OnConsentSetPayload> \|undefined|Called when the consent is set.|-|Optional|
+|onError|Callback\<OnErrorPayload> \|undefined|Called when an error occurs.|-|Optional|
+|onBeforeConsentRevocationReload|Callback\<OnConsentSetPayload> \|undefined|Called before the page reloads when consent is revoked.|-|Optional|
+
+#### `scripts` Script
+
+Dynamically load scripts based on consent state.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Unique identifier for the script|-|✅ Required|
+|src|string \|undefined|URL of the script to load|-|Optional|
+|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
+|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|-|Optional|
+|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|-|Optional|
+|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|-|Optional|
+|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
+|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
+|async|boolean \|undefined|Whether to use async loading|-|Optional|
+|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
+|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
+|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|-|Optional|
+|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|-|Optional|
+|onBeforeLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed before the script is loaded|-|Optional|
+|onLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed when the script loads successfully|-|Optional|
+|onError|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed if the script fails to load|-|Optional|
+|onConsentChange|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
+|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
+|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
+|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
+|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
+
+#### `legalLinks`
+
+Configuration for the legal links.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|privacyPolicy|LegalLink \|undefined|-|-|✅ Required|
+|cookiePolicy|LegalLink \|undefined|-|-|✅ Required|
+|termsOfService|LegalLink \|undefined|-|-|✅ Required|
+
+#### `storageConfig` StorageConfig
+
+Storage configuration for consent persistence.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|storageKey|string \|undefined|Custom storage key for localStorage and cookies|-|Optional|
+|crossSubdomain|boolean \|undefined|Enable cross-subdomain cookies by default|-|Optional|
+|defaultDomain|string \|undefined|Custom default domain for cookies|-|Optional|
+|defaultExpiryDays|number \|undefined|Default cookie expiration in days|-|Optional|
+
+#### `user` User
+
+The user's information. Usually your own internal ID for the user from your auth provider.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Usually your own internal ID for the user from your auth provider|-|✅ Required|
+|identityProvider|string \|undefined|The identity provider of the user. Usually the name of the identity provider e.g. 'clerk', 'auth0', 'custom', etc.|-|Optional|
+
+#### `overrides` Overrides
+
+Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|country|string \|undefined|Country code to forcefully set|-|Optional|
+|region|string \|undefined|Region code to forcefully set|-|Optional|
+|language|string \|undefined|Language code to forcefully set|-|Optional|
+|gpc|boolean \|undefined|Override the Global Privacy Control (GPC) signal. When \`true\`, simulates GPC being active (opt-out of marketing/measurement). When \`false\`, suppresses the real browser GPC signal. When \`undefined\`, falls back to the browser's \`navigator.globalPrivacyControl\`.|-|Optional|
+
+#### `networkBlocker` NetworkBlockerConfig
+
+Configuration for the network request blocker.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|((info: BlockedRequestInfo) => void) \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+#### `iab` IABConfig
+
+IAB TCF 2.3 configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean|Enable IAB TCF 2.3 mode. Note: Only works in 'hosted' client mode (legacy alias: 'c15t') because it requires a backend. Options: Fetch GVL from gvl.consent.io; Initialize \_\_tcfapi CMP API; Generate TC Strings for IAB compliance|-|✅ Required|
+|cmpId|number \|undefined|CMP ID registered with IAB Europe. When using consent.io as the backend, this is automatically provided via the \`/init\` endpoint — no client-side configuration needed. Only set this if you self-host and have your own CMP registration. A valid (non-zero) CMP ID is required for IAB TCF compliance.|-|Optional|
+|cmpVersion|string \|number \|undefined|CMP version. When omitted, defaults to package version from \`\~/cmp-defaults\` (which uses \~/version).|-|Optional|
+|vendors|number\[] \|undefined|IAB-registered vendor IDs to include (optional). Used to scope the vendor list when fetching GVL or when hosted fallback paths are used (e.g. if GVL fetch fails).|-|Optional|
+|customVendors|NonIABVendor \|undefined|Custom vendors not registered with IAB. These are displayed separately in the consent UI with a note that they have different privacy practices than IAB vendors.|-|Optional|
+|publisherCountryCode|string \|undefined|Publisher country code (2-letter ISO).|-|Optional|
+|isServiceSpecific|boolean \|undefined|Whether consent is service-specific (not global).|-|Optional|
+|gvl|Object \|undefined \|null|Pre-loaded Global Vendor List for testing or SSR. Options: Testing (avoids network calls and mocking complexity); SSR (use server-fetched GVL); Offline/air-gapped deployments|-|Optional|
+
+#### `ssrData`
+
+SSR-prefetched data for hydration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|init|Object \|undefined \|null|Init endpoint response with jurisdiction, location, translations, and optional GVL.|-|✅ Required|
+|gvl|Object \|undefined \|null|Global Vendor List data for IAB TCF mode. Note: When init returns 200 without gvl, client IAB settings are overridden to disabled.|-|Optional|
+|metadata|SSRInitRequestMetadata \|undefined|Optional metadata for debugging SSR transport behavior.|-|Optional|
+
+### ConsentManagerContentOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|i18n|I18nConfig \|undefined|Preferred i18n configuration in c15t v2.|-|Optional|
+|translations|[TranslationConfig \|undefined](https://v2.c15t.com/docs/frameworks/react/internationalization)|Translation configuration to seed the store with.|-|Optional|
+|consentCategories|[AllConsentNames \|undefined](https://v2.c15t.com/docs/frameworks/react/concepts/consent-categories)|Consent categories to show in the consent banner.|-|Optional|
+
+#### `i18n` I18nConfig
+
+Preferred i18n configuration in c15t v2.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|messages|Record\<string, Partial\<Translations>> \|undefined|Translation message map keyed by language code (\`en\`, \`de\`, \`fr\`, ...).|-|✅ Required|
+|locale|string \|undefined|Preferred language code used as the initial fallback locale.|-|Optional|
+|detectBrowserLanguage|boolean \|undefined|Whether to auto-detect from browser language settings.|-|Optional|
+
+#### `translations` TranslationConfig
+
+Translation configuration to seed the store with.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|translations|Record\<string, Partial\<Translations>> \|undefined|-|-|✅ Required|
+|defaultLanguage|string \|undefined|-|-|Optional|
+|disableAutoLanguageSwitch|boolean \|undefined|-|-|Optional|
+
+### UIOptions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|theme|[Theme \|undefined](https://v2.c15t.com/docs/frameworks/react/styling/tokens)|Visual theme to apply.|-|Optional|
+|disableAnimation|boolean \|undefined|Whether to disable animations.|false|Optional|
+|scrollLock|boolean \|undefined|Whether to lock scroll when dialogs are open.|false|Optional|
+|trapFocus|boolean \|undefined|Whether to trap focus within dialogs.|true|Optional|
+|colorScheme|["light" \|"dark" \|"system" \|undefined](https://v2.c15t.com/docs/frameworks/react/styling/color-scheme)|Color scheme preference. With this option, you can force the theme to be light, dark or system. Otherwise, the theme will be detected if you have '.dark' classname in your document.|-|Optional|
+|noStyle|[boolean \|undefined](https://v2.c15t.com/docs/frameworks/react/headless)|Whether to disable default styles.|false|Optional|
+
+#### `theme` Theme
+
+Visual theme to apply.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|colors|ColorTokens \|undefined|Color palette for light mode.|-|Optional|
+|dark|ColorTokens \|undefined|Dark mode color overrides.|-|Optional|
+|typography|TypographyTokens \|undefined|Typography settings for text elements.|-|Optional|
+|spacing|SpacingTokens \|undefined|Spacing scale for internal padding and margins.|-|Optional|
+|radius|RadiusTokens \|undefined|Border radius scale for rounded corners.|-|Optional|
+|shadows|ShadowTokens \|undefined|Box shadow scale for depth and elevation.|-|Optional|
+|motion|MotionTokens \|undefined|Animation and transition timing.|-|Optional|
+|consentActions|Object \|undefined|Semantic button styling for consent actions.|-|Optional|
+|slots|ComponentSlots \|undefined|Component-specific style overrides.|-|Optional|
+
+## Mode: hosted vs offline
+
+```tsx
+// Hosted mode — persists to hosted backend
+<ConsentManagerProvider
+  options={{
+    mode: 'hosted',
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+
+// Offline mode — local cookie storage only
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+  }}
+>
+```
+
+See [Client Modes](/docs/frameworks/react/concepts/client-modes) for a detailed comparison.
+
+## Legal Links
+
+`legalLinks` defines the URLs shown in consent UI text (banner, dialog, and widget where applicable).
+Configure only the links you want to expose.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    legalLinks: {
+      privacyPolicy: {
+        href: '/privacy',
+        target: '_self',
+      },
+      cookiePolicy: {
+        href: '/cookies',
+        target: '_self',
+      },
+      termsOfService: {
+        href: 'https://example.com/terms',
+        target: '_blank',
+        rel: 'noopener noreferrer',
+        label: 'Terms of Service',
+      },
+    },
+  }}
+>
+```
+
+Notes:
+
+* Omitting a key (for example `termsOfService`) hides that link.
+* `label` overrides the translated text for that single link.
+* Use `_self` for internal pages and `_blank` + `rel="noopener noreferrer"` for external pages.
+* Control which of the configured links render in each component via the component's `legalLinks` prop.
+
+## Overrides
+
+`overrides` lets you force location/language signals instead of browser or network detection.
+This is useful for QA, local development, and preview environments.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      country: 'DE',
+      region: 'BY',
+      language: 'de-DE',
+    },
+  }}
+>
+```
+
+You can also override Global Privacy Control (GPC) behavior during testing:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+    overrides: {
+      gpc: true,
+    },
+  }}
+>
+```
+
+> ⚠️ **Warning:**
+> Treat overrides as an environment/testing tool. Avoid hard-coding production overrides unless that behavior is intentional for your deployment.
+
+## Policy Packs
+
+In hosted mode (recommended), the backend resolves the correct policy automatically — no frontend policy config needed:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+```
+
+### Fallback: Offline Policies
+
+When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    mode: 'offline',
+    offlinePolicy: {
+      i18n: {
+        defaultProfile: 'default',
+        messages: {
+          default: {
+            translations: {
+              en: { cookieBanner: { title: 'Privacy choices' } },
+            },
+          },
+          qc: {
+            fallbackLanguage: 'fr',
+            translations: {
+              en: { cookieBanner: { title: 'Quebec Privacy Settings' } },
+              fr: { cookieBanner: { title: 'Paramètres de confidentialité du Québec' } },
+            },
+          },
+        },
+      },
+      policyPacks: [
+        {
+          id: 'qc_opt_in',
+          match: { regions: [{ country: 'CA', region: 'QC' }] },
+          i18n: { messageProfile: 'qc' },
+          consent: { model: 'opt-in', expiryDays: 365 },
+          ui: { mode: 'banner' },
+        },
+        {
+          id: 'default_world',
+          match: { isDefault: true },
+          consent: { model: 'none' },
+          ui: { mode: 'none' },
+        },
+      ],
+    },
+    overrides: {
+      country: 'CA',
+      region: 'QC',
+    },
+  }}
+>
+```
+
+Notes:
+
+* `offlinePolicy` is only used in `offline` mode.
+* `offlinePolicy.i18n` lets offline mode mirror hosted `messageProfile` and profile-local `fallbackLanguage` behavior.
+* Omitting `offlinePolicy.policyPacks` uses the built-in synthetic opt-in fallback banner. Hosted network fallback uses the same opt-in banner.
+* `offlinePolicy: { policyPacks: [] }` is explicit no-banner mode.
+* In hosted mode, backend `policyPacks` remain the source of truth — frontend offline policies never override a live backend decision.
+
+Read the full guide at [Policy Packs](/docs/frameworks/react/policy-packs) and the conceptual model at [Policy Packs Concept](/docs/frameworks/react/concepts/policy-packs).
+
+## Props
+
+### ConsentManagerProviderProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|React children to render within the provider.|-|✅ Required|
+|options|[ConsentManagerOptions](https://v2.c15t.com/docs/frameworks/react/components/consent-manager-provider)|Configuration options for the consent manager. This includes core, React, store, and translation settings.|-|✅ Required|
+
+#### `options` ConsentManagerOptions
+
+Configuration options for the consent manager. This includes core, React, store, and translation settings.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|store|StoreOptions \|undefined|-|-|Optional|
+|offlinePolicy|OfflinePolicyConfig \|undefined|Top-level offline policy configuration.|-|Optional|
+|storageConfig|StorageConfig \|undefined|Storage configuration for consent persistence|-|Optional|
+|mode|"custom" \|"hosted" \|"c15t" \|"offline" \|undefined|Operating mode - custom endpoint implementation|-|Optional|
+|backendURL|string \|undefined|Backend URL is not used in custom mode|-|Optional|
+|enabled|boolean \|undefined|Whether c15t should be active.|-|Optional|
+|callbacks|Callbacks \|undefined|Event callbacks for consent actions.|-|Optional|
+|scripts|Script \|undefined|Dynamically load scripts based on consent state.|-|Optional|
+|legalLinks|Partial\<Record\<keyof LegalLinksTranslations, LegalLink>> \|undefined|Configuration for the legal links.|-|Optional|
+|user|User \|undefined|The user's information. Usually your own internal ID for the user from your auth provider.|-|Optional|
+|overrides|Overrides \|undefined|Forcefully set values like country, region, language for the consent manager. These values will override the values detected from the browser.|-|Optional|
+|networkBlocker|NetworkBlockerConfig \|undefined|Configuration for the network request blocker.|-|Optional|
+|iab|IABConfig \|undefined|IAB TCF 2.3 configuration.|-|Optional|
+|ssrData|Promise\<SSRInitialData \|undefined> \|undefined|SSR-prefetched data for hydration.|-|Optional|
+|theme|Theme \|undefined|Visual theme to apply.|-|Optional|
+|disableAnimation|boolean \|undefined|Whether to disable animations.|-|Optional|
+|scrollLock|boolean \|undefined|Whether to lock scroll when dialogs are open.|-|Optional|
+|trapFocus|boolean \|undefined|Whether to trap focus within dialogs.|-|Optional|
+|colorScheme|"light" \|"dark" \|"system" \|undefined|Color scheme preference. With this option, you can force the theme to be light, dark or system. Otherwise, the theme will be detected if you have '.dark' classname in your document.|-|Optional|
+|noStyle|boolean \|undefined|Whether to disable default styles.|-|Optional|
+|i18n|I18nConfig \|undefined|Preferred i18n configuration in c15t v2.|-|Optional|
+|translations|TranslationConfig \|undefined|Translation configuration to seed the store with.|-|Optional|
+|consentCategories|AllConsentNames \|undefined|Consent categories to show in the consent banner.|-|Optional|