Privacy & Consent Components | Sylphx Documentation

CookieBanner

Cookie consent banner with customizable categories and GDPR compliance

ConsentPreferences

Detailed consent preferences panel for granular privacy control

GDPR Ready

Both components are designed for GDPR, CCPA, and ePrivacy compliance. They automatically handle consent storage, audit trails, and respect Global Privacy Control (GPC) signals.

Installation

import {
  CookieBanner,
  ConsentPreferences,
} from '@sylphx/platform-sdk/react'

CookieBanner

A fully customizable cookie consent banner that appears on first visit. Supports multiple positions, themes, and consent granularity. Automatically stores consent decisions and respects GPC signals.

GDPR Compliant

GPC Support

Themeable

Basic Usage

import { CookieBanner } from '@sylphx/platform-sdk/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <CookieBanner
          onAcceptAll={() => {
            console.log('All cookies accepted')
            // Initialize analytics, marketing scripts, etc.
          }}
          onDecline={() => {
            console.log('Optional cookies declined')
          }}
          onPreferencesChange={(consents) => {
            console.log('Consent preferences:', consents)
          }}
        />
      </body>
    </html>
  )
}

Props

Property	Type	Description
`onAcceptAll`	`() => void`	Callback fired when user accepts all cookies
`onDecline`	`() => void`	Callback fired when user declines optional cookies
`onPreferencesChange`	`(consents: ConsentState) => void`	Callback fired when consent preferences change
`onBannerShow`	`() => void`	Callback fired when banner is displayed
`onBannerHide`	`() => void`	Callback fired when banner is hidden
`categories`	`ConsentCategory[]`	Custom consent categories to display
`position`	`"bottom" \| "top" \| "bottom-left" \| "bottom-right" \| "center"`= "bottom"	Banner position on screen
`variant`	`"bar" \| "modal" \| "floating"`= "bar"	Banner visual style
`showPreferencesButton`	`boolean`= true	Show button to open detailed preferences
`showDeclineButton`	`boolean`= true	Show decline/reject button
`respectGPC`	`boolean`= true	Automatically respect Global Privacy Control signal
`respectDNT`	`boolean`= false	Respect Do Not Track browser setting
`forceShow`	`boolean`= false	Force banner to show (for testing)
`cookieName`	`string`= "sylphx_consent"	Name of consent storage cookie
`cookieExpiry`	`number`= 365	Consent cookie expiry in days
`privacyPolicyUrl`	`string`= "/privacy"	Link to privacy policy
`title`	`string`= "Cookie Preferences"	Banner title text
`description`	`string \| ReactNode`	Banner description text
`acceptAllLabel`	`string`= "Accept All"	Accept all button text
`declineLabel`	`string`= "Decline Optional"	Decline button text
`preferencesLabel`	`string`= "Manage Preferences"	Preferences button text
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

ConsentCategory Type

Property	Type	Description
`id`required	`string`	Unique category identifier
`name`required	`string`	Display name for the category
`description`required	`string`	Explanation of what this category covers
`required`	`boolean`= false	Whether consent is mandatory (always enabled)
`default`	`boolean`= false	Default state if user has not chosen
`cookies`	`string[]`	List of cookie names in this category
`scripts`	`string[]`	Third-party script domains in this category

Advanced Examples

<CookieBanner
  categories={[
    {
      id: 'necessary',
      name: 'Essential',
      description: 'Required for the website to function properly',
      required: true,
      default: true,
      cookies: ['session', 'csrf_token', 'sylphx_consent'],
    },
    {
      id: 'analytics',
      name: 'Analytics',
      description: 'Help us understand how visitors use our site',
      required: false,
      default: false,
      cookies: ['_ga', '_gid', '_gat'],
      scripts: ['google-analytics.com', 'plausible.io'],
    },
    {
      id: 'marketing',
      name: 'Marketing & Advertising',
      description: 'Used for targeted advertising and retargeting',
      required: false,
      default: false,
      cookies: ['_fbp', '_gcl_au'],
      scripts: ['facebook.com', 'doubleclick.net'],
    },
    {
      id: 'preferences',
      name: 'Preferences',
      description: 'Remember your settings and preferences',
      required: false,
      default: true,
      cookies: ['theme', 'language', 'timezone'],
    },
  ]}
/>

GDPR Requirements

Under GDPR, non-essential cookies must be opt-in by default. Set default: false for analytics, marketing, and targeting categories. The banner should be shown before any non-essential cookies are set.

ConsentPreferences

A detailed consent preferences panel for users to manage their privacy choices at any time. Can be embedded in settings pages or shown as a modal. Includes granular controls for each consent category.

Granular Control

Audit Trail

Cookie List

Basic Usage

import { ConsentPreferences } from '@sylphx/platform-sdk/react'

export default function PrivacySettingsPage() {
  return (
    <div className="max-w-2xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Privacy Settings</h1>
      <ConsentPreferences
        onSave={(consents) => {
          console.log('Saved preferences:', consents)
          toast.success('Privacy preferences saved!')
        }}
        onChange={(category, enabled) => {
          console.log(`${category} is now ${enabled ? 'enabled' : 'disabled'}`)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onSave`	`(consents: ConsentState) => void`	Callback fired when user saves preferences
`onChange`	`(category: string, enabled: boolean) => void`	Callback fired when a category toggle changes
`onClose`	`() => void`	Callback fired when panel is closed (modal mode)
`categories`	`ConsentCategory[]`	Custom consent categories to display
`layout`	`"card" \| "flat" \| "accordion"`= "card"	Visual layout style
`showCookieList`	`boolean`= true	Show list of cookies per category
`showScriptList`	`boolean`= true	Show list of third-party scripts per category
`showAcceptAll`	`boolean`= true	Show "Accept All" button
`showDeclineAll`	`boolean`= true	Show "Decline All" button
`showSaveButton`	`boolean`= true	Show save button (vs auto-save)
`autoSave`	`boolean`= false	Auto-save on toggle change
`showConsentHistory`	`boolean`= false	Show consent change history
`showGPCStatus`	`boolean`= true	Show Global Privacy Control status
`showLastUpdated`	`boolean`= true	Show when consent was last updated
`title`	`string`= "Privacy Preferences"	Panel title
`description`	`string \| ReactNode`	Panel description text
`saveLabel`	`string`= "Save Preferences"	Save button text
`acceptAllLabel`	`string`= "Accept All"	Accept all button text
`declineAllLabel`	`string`= "Decline All"	Decline all button text
`privacyPolicyUrl`	`string`= "/privacy"	Link to privacy policy
`cookiePolicyUrl`	`string`= "/cookies"	Link to cookie policy
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

ConsentState Type

Types

interface ConsentState {
  necessary: boolean   // Always true (required)
  analytics: boolean
  marketing: boolean
  functional: boolean
  targeting: boolean
  [key: string]: boolean // Custom categories
}

interface ConsentRecord {
  timestamp: string      // ISO timestamp
  action: 'grant' | 'revoke' | 'update'
  categories: string[]   // Affected categories
  source: 'banner' | 'preferences' | 'api'
  gpcEnabled?: boolean   // GPC signal at time of consent
}

Advanced Examples

<ConsentPreferences
  layout="accordion"
  showCookieList={true}
  showScriptList={true}
  categories={[
    {
      id: 'necessary',
      name: 'Strictly Necessary',
      description: 'These cookies are essential for the website to function and cannot be disabled.',
      required: true,
      default: true,
      cookies: [
        'session - Maintains your logged-in session',
        'csrf_token - Protects against cross-site attacks',
        'sylphx_consent - Stores your cookie preferences',
      ],
    },
    {
      id: 'analytics',
      name: 'Analytics & Performance',
      description: 'These cookies help us understand how visitors interact with our website.',
      required: false,
      default: false,
      cookies: [
        '_ga - Google Analytics visitor ID',
        '_gid - Google Analytics session ID',
        '_gat - Google Analytics rate limiter',
      ],
      scripts: [
        'google-analytics.com',
        'googletagmanager.com',
      ],
    },
    {
      id: 'marketing',
      name: 'Marketing & Advertising',
      description: 'These cookies are used to deliver personalized advertisements.',
      required: false,
      default: false,
      cookies: [
        '_fbp - Facebook Pixel',
        '_gcl_au - Google Ads conversion tracking',
      ],
      scripts: [
        'facebook.com',
        'doubleclick.net',
        'adsrvr.org',
      ],
    },
  ]}
/>

Consent Audit Trail

The ConsentPreferences component automatically logs all consent changes with timestamps, user agent, and source. Use showConsentHistory={true} to display this history to users.

Integration with Analytics

Use the consent state to conditionally load analytics and marketing scripts.

Conditional Script Loading

'use client'

import { useConsent } from '@sylphx/platform-sdk/react'
import Script from 'next/script'

export function AnalyticsProvider({ children }) {
  const { hasConsent, isLoading } = useConsent()

  // Don't render scripts until consent state is loaded
  if (isLoading) return <>{children}</>

  return (
    <>
      {/* Only load Google Analytics if user consented */}
      {hasConsent('analytics') && (
        <>
          <Script
            src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX"
            strategy="afterInteractive"
          />
          <Script id="google-analytics" strategy="afterInteractive">
            {`
              window.dataLayer = window.dataLayer || [];
              function gtag(){dataLayer.push(arguments);}
              gtag('js', new Date());
              gtag('config', 'G-XXXXX');
            `}
          </Script>
        </>
      )}

      {/* Only load Facebook Pixel if user consented to marketing */}
      {hasConsent('marketing') && (
        <Script id="facebook-pixel" strategy="afterInteractive">
          {`
            !function(f,b,e,v,n,t,s)
            {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
            n.callMethod.apply(n,arguments):n.queue.push(arguments)};
            // ... pixel code
          `}
        </Script>
      )}

      {children}
    </>
  )
}

useConsent Hook

Access consent state and methods from anywhere in your app.

Hook Usage

import { useConsent } from '@sylphx/platform-sdk/react'

function MyComponent() {
  const {
    // State
    consents,           // Current consent state object
    hasResponded,       // Whether user has made a choice
    isLoading,          // Loading state
    gpcEnabled,         // Global Privacy Control signal detected
    lastUpdated,        // Timestamp of last consent update

    // Methods
    hasConsent,         // Check single category: hasConsent('analytics')
    setConsent,         // Set single: setConsent('analytics', true)
    setConsents,        // Set multiple: setConsents({ analytics: true, marketing: false })
    acceptAll,          // Accept all categories
    declineOptional,    // Decline all non-required categories
    resetConsent,       // Clear all consent (re-show banner)
    showBanner,         // Programmatically show banner
    showPreferences,    // Programmatically show preferences modal

    // History
    consentHistory,     // Array of ConsentRecord
  } = useConsent()

  const handleAnalyticsAction = () => {
    if (hasConsent('analytics')) {
      // Track the event
      analytics.track('button_clicked')
    } else {
      // Prompt for consent
      showPreferences()
    }
  }

  return (
    <button onClick={handleAnalyticsAction}>
      Track Me
    </button>
  )
}

Property	Type	Description
`consents`	`ConsentState`	Current consent state for all categories
`hasResponded`	`boolean`	Whether user has made any consent choice
`isLoading`	`boolean`	True while loading consent state from storage
`gpcEnabled`	`boolean`	True if Global Privacy Control signal is detected
`lastUpdated`	`Date \| null`	When consent was last updated
`consentHistory`	`ConsentRecord[]`	Array of consent change records
`hasConsent(id)`	`(id: string) => boolean`	Check if specific category is consented
`setConsent(id, value)`	`(id: string, value: boolean) => void`	Set consent for a single category
`setConsents(consents)`	`(consents: Partial<ConsentState>) => void`	Set multiple consents at once
`acceptAll()`	`() => void`	Accept all consent categories
`declineOptional()`	`() => void`	Decline all non-required categories
`resetConsent()`	`() => void`	Clear all consent data (triggers banner)
`showBanner()`	`() => void`	Programmatically show the cookie banner
`showPreferences()`	`() => void`	Programmatically show preferences panel

Theming

Both components support theming via the theme prop. Customize colors, fonts, and border radius to match your brand.

Custom Theme

import { CookieBanner, ConsentPreferences, type ThemeVariables } from '@sylphx/platform-sdk/react'

const privacyTheme: ThemeVariables = {
  colorPrimary: '#10b981',
  colorPrimaryHover: '#059669',
  colorBackground: '#ffffff',
  colorForeground: '#1f2937',
  colorMuted: '#f3f4f6',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  colorDestructive: '#ef4444',
  colorSuccess: '#22c55e',
  fontFamily: 'Inter, sans-serif',
  fontSize: '14px',
  borderRadius: '0.75rem',
}

// Apply to both components
<CookieBanner theme={privacyTheme} />
<ConsentPreferences theme={privacyTheme} />

Best Practices

Show Before Tracking

Display the consent banner before loading any non-essential cookies or tracking scripts.

Default to Opt-Out

For GDPR compliance, non-essential cookies should be disabled by default.

Respect GPC Signals

Enable respectGPC to automatically honor Global Privacy Control browser settings.

Provide Granular Control

Let users choose specific categories rather than just accept/reject all.

Maintain Audit Trails

Log consent changes with timestamps for regulatory compliance.

Easy Access to Settings

Make it easy for users to change their preferences at any time from settings or footer links.

Need server-side consent checking?

Use the consent API to check consent status server-side before sending marketing emails or tracking events.

Consent API Analytics Integration

Consent Management

Server-side consent API and data deletion

Analytics Tracking

Consent-aware event tracking

GDPR Ready

Consent Categories

CookieBanner

Props

ConsentCategory Type

Advanced Examples

GDPR Requirements

ConsentPreferences

Props

ConsentState Type

Advanced Examples

Consent Audit Trail

Integration with Analytics

useConsent Hook

Theming

Best Practices

Show Before Tracking

Default to Opt-Out

Respect GPC Signals

Provide Granular Control

Maintain Audit Trails

Easy Access to Settings

Need server-side consent checking?

Consent Management

Analytics Tracking