React SDK

The React SDK gives components direct access to the visitor’s consent. Components re-render when the choice changes, so you never have to read cookies or reload the page. It works with React 18 and later, including Next.js, Remix and Vite apps.

Installation

npm install @cookiesh/react

The SDK uses the Cookiesh script tag under the hood. Load it as early as possible, as shown in the quick start, then wrap your app in CookieshProvider.

CookieshProvider

import { CookieshProvider } from '@cookiesh/react';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <CookieshProvider siteId="ck_live_8f2a91" userId={session?.user.id}>
      {children}
    </CookieshProvider>
  );
}

Prop	Type	Description
siteId	string	Your site ID. Optional if the script tag already sets data-site-id.
userId	string | undefined	Links consent to a signed-in user so it follows them across devices. Passing undefined after sign-out calls reset().
language	string	Forces the banner language.
onChange	(state: ConsentState) => void	Called after every new choice.

useConsent

useConsent() returns the current state and the actions to change it:

import { useConsent } from '@cookiesh/react';

function PrivacySettingsLink() {
  const { openPreferences } = useConsent();
  return <button onClick={openPreferences}>Privacy settings</button>;
}

The returned object contains:

Field	Type	Description
ready	boolean	false until the consent state is known
necessary, preferences, analytics, marketing	boolean	The current value of each category
method	string	How the current state came about (see the JavaScript API)
acceptAll, rejectAll	() => Promise<ConsentState>	Store a choice for every category
setConsent	(choices) => Promise<ConsentState>	Store a choice for some categories
showBanner, openPreferences	() => void	Open the Cookiesh UI

ConsentGate

ConsentGate renders its children only when every listed category is allowed, and a fallback otherwise:

import { ConsentGate } from '@cookiesh/react';

<ConsentGate category="marketing" fallback={<VideoPlaceholder />}>
  <YouTubeEmbed id="dQw4w9WgXcQ" />
</ConsentGate>

Pass an array, such as category={['analytics', 'marketing']}, to require several categories.

Server rendering

The visitor’s choice lives in their browser, so it is unknown while a page renders on the server. During server rendering and the first client render, ready is false and every category except necessary is false. Consent-dependent content therefore renders after hydration, and nothing runs before consent.

To avoid layout shift, give ConsentGate a fallback with the same size as the content it replaces. In the Next.js App Router, components that call useConsent() must be client components ('use client').

Testing

In unit tests, wrap components in CookieshTestProvider to control the state without loading the script:

import { render, screen } from '@testing-library/react';
import { CookieshTestProvider } from '@cookiesh/react/testing';

render(
  <CookieshTestProvider consent={{ analytics: true, marketing: false }}>
    <Dashboard />
  </CookieshTestProvider>,
);