React SDK

interface UseConsentReturn {
  /**
   * Effective consent per category (explicit decision, GPC, or implicit
   * grant by consent model), or null if not yet known
   */
  consent: Record<string, boolean> | null

  /** The loaded consent config, or null if not loaded */
  config: ConsentConfig | null

  /** Resolved region for the current visitor (e.g. "US-CA", "gdpr"), or null if unresolved */
  region: string | null

  /** True while the SDK is initializing */
  isLoading: boolean

  /** True once consent state is known and no error occurred */
  isReady: boolean

  /**
   * Whether an explicit consent decision exists (stored from a prior visit
   * or made this session). Use this, not `consent === null`, to decide
   * whether to render a custom banner: `consent` is effective consent and
   * is non-null even before the user has chosen.
   */
  hasDecision: boolean

  /** Error if SDK failed to load, null otherwise */
  error: Error | null

  /** Update consent programmatically, logs to the server */
  setConsent: (categories: Record<string, boolean>) => Promise<void>

  /** Check if a specific category has consent */
  hasConsent: (category: string) => boolean

  /** Programmatically show the consent banner */
  showBanner: () => void

  /** Open the preferences panel */
  showPreferences: () => void

  /** Close the preferences panel */
  hidePreferences: () => void

  /** Whether the preferences panel is currently open */
  isPreferencesOpen: boolean
}

function useConsentValue(category: string): boolean

import { useConsentValue } from '@consentstack/react'

function AnalyticsLoader() {
  const hasAnalytics = useConsentValue('analytics')
  if (!hasAnalytics) return null
  return <script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" async />
}

function useConsentEvent<T extends ConsentEventType>(
  event: T,
  callback: (data: ConsentEventData[T]) => void
): void

import { useConsentEvent } from '@consentstack/react'

function PreferencesTracker() {
  useConsentEvent('preferences:open', () => {
    analytics.track('consent_preferences_opened')
  })

  useConsentEvent('error', (error) => {
    console.error('SDK error:', error)
  })

  return null
}

function ConsentFallback() {
  const { error, isReady } = useConsent()

  if (error) {
    return <p>Consent system unavailable. Some features may be limited.</p>
  }

  if (!isReady) return null

  return <YourApp />
}

import { useEffect } from 'react'
import { useConsent } from '@consentstack/react'

function PageViewTracker() {
  const { isReady, hasConsent } = useConsent()

  useEffect(() => {
    if (isReady && hasConsent('analytics')) {
      trackPageView()
    }
  }, [isReady, hasConsent])

  return null
}

import { useConsentValue } from '@consentstack/react'
import Script from 'next/script'

function ThirdPartyScripts() {
  const analyticsAllowed = useConsentValue('analytics')
  const marketingAllowed = useConsentValue('marketing')

  return (
    <>
      {analyticsAllowed && (
        <Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" strategy="afterInteractive" />
      )}
      {marketingAllowed && (
        <Script src="https://connect.facebook.net/en_US/fbevents.js" strategy="afterInteractive" />
      )}
    </>
  )
}

<ConsentStackProvider siteKey="<YOUR_SITE_KEY>" mode="headless">
  {children}
</ConsentStackProvider>

import { useConsent } from '@consentstack/react'

function CookiePreferences() {
  const { consent, config, setConsent, isReady, showPreferences, hidePreferences } = useConsent()

  if (!isReady || !config) return null

  const handleToggle = (categoryId: string, enabled: boolean) => {
    setConsent({ ...consent, [categoryId]: enabled })
  }

  return (
    <div>
      <h2>Cookie Preferences</h2>
      {config.categories.map((cat) => (
        <label key={cat.id}>
          <input
            type="checkbox"
            checked={consent?.[cat.id] ?? cat.default}
            disabled={cat.required}
            onChange={(e) => handleToggle(cat.id, e.target.checked)}
          />
          <span>{cat.name}</span>
          <p>{cat.description}</p>
        </label>
      ))}
    </div>
  )
}

function CustomBanner() {
  const { isReady, hasDecision, setConsent } = useConsent()

  // Only show the banner when no explicit decision exists yet
  if (!isReady || hasDecision) return null

  return (
    <div role="dialog">
      <p>We use cookies for analytics and marketing.</p>
      <button onClick={() => setConsent({ essential: true, analytics: true, marketing: true })}>
        Accept all
      </button>
      <button onClick={() => setConsent({ essential: true, analytics: false, marketing: false })}>
        Reject all
      </button>
    </div>
  )
}

import type {
  ConsentConfig,
  ConsentCategory,
  ConsentStackAPI,
  ConsentEventType,
  ConsentEventData,
  UseConsentReturn,
  ConsentStackProps,
  ConsentStackProviderProps,
} from '@consentstack/react'