> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cookiechimp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Install the SDK and show a consent banner.

Use matching versions of the CookieChimp packages. The platform JSON banner and
vendor preferences require SDK 1.1.0 or newer. See [versions and deployment](https://docs.cookiechimp.com/docs/sdk/release-status.md).

For a CookieChimp-managed project, start with
[Connect to CookieChimp](https://docs.cookiechimp.com/docs/sdk/connected-backend.md). It shows a runnable example of
dashboard config retrieval and consent delivery to the backend, including receipts
and retries. The local setup below also works without an account.

The quickest route is the CLI. It detects your framework, installs the right
packages and writes starter files. It never edits files you already have.

```sh theme={null}
npx @cookiechimp/cli init
npx @cookiechimp/cli doctor
```

The sections below show what it sets up, if you prefer to do it by hand.

## Next.js App Router

```sh theme={null}
npm install @cookiechimp/core @cookiechimp/react @cookiechimp/nextjs
```

```ts theme={null}
// cookiechimp.config.ts
import type { ConsentConfig } from "@cookiechimp/core";

// "necessary" is added automatically and is always on.
export const consentConfig = {
  categories: { analytics: false, marketing: false },
} satisfies ConsentConfig;
```

```tsx theme={null}
// components/cookiechimp-banner.tsx
"use client";

import { CookieBanner } from "@cookiechimp/react/banner";

export function CookieChimpBanner() {
  return <CookieBanner />;
}
```

```tsx theme={null}
// app/layout.tsx
import "@cookiechimp/react/styles.css";
import { CookieChimpProvider } from "@cookiechimp/nextjs/server";
import type { ReactNode } from "react";
import { CookieChimpBanner } from "../components/cookiechimp-banner";
import { consentConfig } from "../cookiechimp.config";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CookieChimpProvider config={consentConfig}>
          {children}
          <CookieChimpBanner />
        </CookieChimpProvider>
      </body>
    </html>
  );
}
```

`CookieChimpProvider` is a server component. It reads the consent cookie, so a
returning visitor never sees the banner flash. See [Next.js](https://docs.cookiechimp.com/docs/sdk/nextjs.md)
for regions, the Pages Router, connected mode and strict CSP.

## React

```tsx theme={null}
"use client";

import "@cookiechimp/react/styles.css";
import { ConsentProvider } from "@cookiechimp/react";
import { CookieBanner } from "@cookiechimp/react/banner";
import type { ReactNode } from "react";
import { consentConfig } from "./cookiechimp.config";

export function CookieChimp({ children }: { children: ReactNode }) {
  return (
    <ConsentProvider config={consentConfig}>
      {children}
      <CookieBanner />
    </ConsentProvider>
  );
}
```

When you server render, pass `initialState` so hydration matches. Read consent
in components with the hooks:

```tsx theme={null}
import { useCategory, usePreferences } from "@cookiechimp/react";

function AnalyticsStatus() {
  const analytics = useCategory("analytics");
  const preferences = usePreferences();
  return (
    <button type="button" onClick={preferences.show}>
      Analytics {analytics ? "on" : "off"}
    </button>
  );
}
```

## Plain JavaScript

```ts theme={null}
import { createConsent } from "@cookiechimp/core";
import { gateScripts } from "@cookiechimp/core/gate";

export const consent = createConsent({
  categories: { analytics: false, marketing: false },
});
gateScripts(consent);

consent.subscribe((state) => console.log(state.categories));
// Wire your own buttons to consent.acceptAll(), consent.rejectAll() and consent.set().
```

```html theme={null}
<!-- Stays inert until analytics is allowed. -->
<script
  type="text/plain"
  data-cc-category="analytics"
  data-cc-src="https://www.googletagmanager.com/gtag/js?id=G-EXAMPLE123"
></script>
```

## Next steps

* Gate vendor tags with the [script presets](https://docs.cookiechimp.com/docs/sdk/scripts.md).
* Send Google Consent Mode v2 signals and block runtime-added scripts: see the
  [reference](https://docs.cookiechimp.com/docs/sdk/reference.md).
* Translate the banner: [translations](https://docs.cookiechimp.com/docs/sdk/translations.md).

## Use the platform JSON for category and vendor preferences

See [Banner and vendor preferences](https://docs.cookiechimp.com/docs/sdk/platform-ui.md) for the complete JSON
contract, consent state, backend delivery, appearance controls and playground.

The opt-in `@cookiechimp/react/platform` UI uses the same offline/config JSON
bundle as the existing widget. There is no second category or vendor list.

```tsx theme={null}
import { PlatformConsentProvider, CookieBanner, CookiePreferences, RecallButton } from "@cookiechimp/react/platform";
import "@cookiechimp/react/platform.css";
import bundle from "./cookiechimp.config.json";

export function ConsentUi() {
  return (
    <PlatformConsentProvider bundle={bundle} region="IE" locale="en">
      <CookieBanner />
      <CookiePreferences />
      <RecallButton />
    </PlatformConsentProvider>
  );
}
```

The provider selects `banners`, `translations`, `country_banner_map` and
`default_banner` from the existing bundle. It consumes `categories[].slug`,
`name`, `description`, `required`, `services[]` and `storage_items[]`. Vendor
details keep `id`, `name`, `description`, `company`, `privacy_policy_url`,
`accepted_by_default` and `storage_items`, including each storage item's `name`,
`type`, `description`, `duration` and `company`. Nested `translations` supply
localized names and descriptions. The adapter derives an internal `consent_key`
to map runtime service keys back to the original platform IDs. Never add that
field to the input JSON.

`useConsent().services` includes every configured vendor with its effective
boolean value before and after a decision. It is `{}` when no services are
configured. Values follow required categories, category defaults, saved vendor
choices and GPC, without saving consent or sending a log just to display them.

Set the existing `preferences_gui_options.control_level` to
`category_and_services` for per-vendor controls. `category_only` keeps category
controls, with vendor details when `show_services` is true. Category switches
update all vendors; an individual vendor updates the category when any vendor
is allowed. Changes are staged until Save; Close discards them. Required
categories and their vendors stay enabled, and GPC cannot be bypassed through
a vendor override. Button labels, visibility, colors and radii use the existing
JSON keys. Descriptions preserve safe formatting and links as React elements; executable HTML and arbitrary attributes are discarded.

Supply trusted region context from your application. The SDK performs no
location lookup. For SSR, pass the server `initialState` as with
`ConsentProvider`. The platform UI is a separate entry to preserve the default
banner bundle size.

Run the React/Vite workspace example and open `/platform.html` for a complete
category/vendor demo. It uses the existing redacted bundle, with the canonical
`category_and_services` control level, realistic Google Analytics, Microsoft
Clarity and Meta Pixel disclosures, and a separate demo cookie. It loads no
tracking tags and sends no consent records. Production logging stays explicit.

### Motion

The platform stylesheet includes short entrance, disclosure and switch animations
by default. No animation package or additional import is needed. The UI automatically
disables motion for visitors who request reduced motion in their operating system.
To disable animations for all visitors, keep the same stylesheet and pass
`motion={false}` to the provider:

```tsx theme={null}
<PlatformConsentProvider bundle={bundle} region="IE" motion={false}>
  <CookieBanner />
  <CookiePreferences />
  <RecallButton />
</PlatformConsentProvider>
```

This changes only presentation; consent choices and keyboard behavior are unchanged.
Collapsed details are inert and excluded from focus navigation, including while
their closing transition runs. Developers building a custom UI can use
`@cookiechimp/react/headless` with their own stylesheet instead.

The playground includes 16 presets, an isolated actual-SDK preview, desktop/mobile
sizes, JSON export, consent state and saved-choice replay. It includes controls
for all platform layouts, positions, button placements,
button swapping, equal weight, side panels, color schemes and radii. They modify
the same JSON consumed by the SDK. See the [JSON compatibility matrix](https://github.com/cookiechimp/cookiechimp-sdk/blob/main/docs/platform-json-compatibility.md)
for the exact supported presentation fields and runtime integration boundaries.

The example JSON is illustrative, rather than an inventory of tags on a live site.
Google cookie details follow its [GA4 documentation](https://support.google.com/analytics/answer/11397207?hl=en),
and Clarity purposes follow its [cookie documentation](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-cookies).
Durations are example settings and may differ by site or browser. Vendor privacy
links in the JSON point to the vendors' own policies.

This entry supplies category/vendor consent and presentation. Optional protocol
integrations, script gating and consent delivery still require their explicit
SDK integrations; reading their dashboard flags does not activate them.