Getting started

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. For a CookieChimp-managed project, start with Connect to CookieChimp. 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.

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

npm install @cookiechimp/core @cookiechimp/react @cookiechimp/nextjs

// 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;

// components/cookiechimp-banner.tsx
"use client";

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

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

// 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 for regions, the Pages Router, connected mode and strict CSP.

React

"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:

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

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().

<!-- 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.
Send Google Consent Mode v2 signals and block runtime-added scripts: see the reference.
Translate the banner: translations.

Use the platform JSON for category and vendor preferences

See Banner and vendor preferences 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.

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:

<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 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, and Clarity purposes follow its cookie documentation. 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.

Get started

Mobile

SDK reference

Next.js App Router

React

Plain JavaScript

Next steps

Use the platform JSON for category and vendor preferences

Motion

​Next.js App Router

​React

​Plain JavaScript

​Next steps

​Use the platform JSON for category and vendor preferences

​Motion

Next.js App Router

React

Plain JavaScript

Next steps

Use the platform JSON for category and vendor preferences

Motion