Script Loader

The script loader manages third-party scripts based on consent state. Scripts are defined in the provider's scripts option and are automatically loaded when their required consent category is granted, and unloaded when consent is revoked.

c15t has a collection of premade scripts available on the @c15t/scripts package. It's recomended to check if a pre-built integration exists before manually creating a script, see the integrations overview.

npm install @c15t/scripts

Info

We recommend using the pre-built integrations when possible.

Basic Usage

Pass an array of Script objects to the provider:

import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/nextjs';
import { metaPixel } from '@c15t/scripts/meta-pixel';

export function ConsentManager({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'c15t',
        backendURL: '/api/c15t',
        scripts: [
          metaPixel({ pixelId: '123456' }),
          {
            id: 'custom-analytics',
            src: 'https://cdn.example.com/analytics.js',
            category: 'measurement',
          },
        ],
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}

Script Types

Standard Scripts

Load an external JavaScript file via a <script> tag. Use src to specify the URL.

Inline Scripts

Execute inline JavaScript code. Use textContent instead of src:

{
  id: 'gtag-config',
  textContent: `
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'G-XXXXXX');
  `,
  category: 'measurement',
}

Callback-Only Scripts

Don't inject any <script> tag - just execute callbacks based on consent changes. Useful for controlling libraries that are already loaded:

{
  id: 'posthog-consent',
  callbackOnly: true,
  category: 'measurement',
  onLoad: ({ hasConsent }) => {
    if (hasConsent) {
      posthog.opt_in_capturing();
    }
  },
  onConsentChange: ({ hasConsent }) => {
    if (hasConsent) {
      posthog.opt_in_capturing();
    } else {
      posthog.opt_out_capturing();
    }
  },
}

The category field accepts a HasCondition - either a simple string or a logical expression:

// Simple: requires measurement consent
{
  category: 'measurement';
}

// AND: requires both measurement and marketing
{
  category: {
    and: ['measurement', 'marketing'];
  }
}

// OR: requires either measurement or marketing
{
  category: {
    or: ['measurement', 'marketing'];
  }
}

Script Callbacks

Every script supports four lifecycle callbacks:

Callback	When	Use Case
`onBeforeLoad`	Before the script tag is injected	Set up global variables
`onLoad`	Script loaded successfully	Initialize the library
`onError`	Script failed to load	Log error, load fallback
`onConsentChange`	Consent state changed (script already loaded)	Toggle tracking on/off

{
  id: 'analytics',
  src: 'https://analytics.example.com/v2.js',
  category: 'measurement',
  onBeforeLoad: ({ id }) => {
    console.log(`Loading script: ${id}`);
  },
  onLoad: ({ element }) => {
    window.analytics.init('my-key');
  },
  onError: ({ error }) => {
    console.error('Failed to load analytics:', error);
  },
  onConsentChange: ({ hasConsent, consents }) => {
    window.analytics.setConsent(hasConsent);
  },
}

Advanced Options

Always Load

Scripts that manage their own consent internally (like GTM in consent mode):

{
  id: 'google-tag-manager',
  src: 'https://www.googletagmanager.com/gtm.js?id=GTM-XXXX',
  category: 'measurement',
  alwaysLoad: true, // Loads regardless of consent state
}

Persist After Revocation

Keep the script loaded even after consent is revoked (the page won't reload for this script):

{
  id: 'error-tracking',
  src: 'https://errors.example.com/track.js',
  category: 'measurement',
  persistAfterConsentRevoked: true,
}

Script Placement

Control where in the DOM the script is injected:

{
  id: 'widget',
  src: 'https://widget.example.com/embed.js',
  category: 'experience',
  target: 'body', // 'head' (default) or 'body'
}

Ad Blocker Evasion

Script element IDs are anonymized by default to avoid ad blocker pattern matching:

{
  id: 'analytics',
  src: '...',
  category: 'measurement',
  anonymizeId: true, // default: true
}

Dynamic Script Management

Add, remove, or check scripts at runtime via useConsentManager():

import { useConsentManager } from '@c15t/nextjs';

function ScriptManager() {
  const { setScripts, removeScript, isScriptLoaded, getLoadedScriptIds } =
    useConsentManager();

  // Add scripts dynamically
  setScripts([{ id: 'dynamic', src: '...', category: 'measurement' }]);

  // Remove a script
  removeScript('dynamic');

  // Check if a script is loaded
  const loaded = isScriptLoaded('google-analytics');

  // Get all loaded script IDs
  const allLoaded = getLoadedScriptIds();
}

API Reference

Property

Types

Loading…

Script Loader

Basic Usage

Script Types

Standard Scripts

Inline Scripts

Callback-Only Scripts

Consent Conditions

Script Callbacks

Advanced Options

Always Load

Persist After Revocation

Script Placement

Ad Blocker Evasion

Dynamic Script Management

API Reference

anonymizeId?Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockersboolean | undefined

async?Whether to use async loadingboolean | undefined

attributes?Additional attributes to add to the script elementRecord<string, string>

categoryConsent category or condition required to load this scriptrequiredHasCondition<AllConsentNames>

defer?Whether to defer script loadingboolean | undefined

fetchPriority?Priority hint for browser resource loading"high" | "low" | "auto" | undefined

iabLegIntPurposes?IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.{} | undefined

iabPurposes?IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.{} | undefined

iabSpecialFeatures?IAB TCF special feature IDs this script requires. Special features require explicit opt-in: 1: Use precise geolocation data 2: Actively scan device characteristics for identification {} | undefined

idUnique identifier for the scriptrequiredstring

nonce?Content Security Policy noncestring | undefined

onBeforeLoad?Callback executed before the script is loaded((info: ScriptCallbackInfo) => void) | u...

onConsentChange?Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.((info: ScriptCallbackInfo) => void) | u...

onError?Callback executed if the script fails to load((info: ScriptCallbackInfo) => void) | u...

onLoad?Callback executed when the script loads successfully((info: ScriptCallbackInfo) => void) | u...

persistAfterConsentRevoked?Whether the script should persist after consent is revoked.boolean | undefined

src?URL of the script to loadstring | undefined

textContent?Inline JavaScript code to executestring | undefined

vendorId?IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over category when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.string | number | undefined

anonymizeId?Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockersboolean | undefined

async?Whether to use async loadingboolean | undefined

attributes?Additional attributes to add to the script elementRecord<string, string>

categoryConsent category or condition required to load this scriptrequiredHasCondition<AllConsentNames>

defer?Whether to defer script loadingboolean | undefined

fetchPriority?Priority hint for browser resource loading"high" | "low" | "auto" | undefined

iabLegIntPurposes?IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.{} | undefined

iabPurposes?IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.{} | undefined

iabSpecialFeatures?IAB TCF special feature IDs this script requires. Special features require explicit opt-in: 1: Use precise geolocation data 2: Actively scan device characteristics for identification {} | undefined

idUnique identifier for the scriptrequiredstring

nonce?Content Security Policy noncestring | undefined

onBeforeLoad?Callback executed before the script is loaded((info: ScriptCallbackInfo) => void) | u...

onConsentChange?Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.((info: ScriptCallbackInfo) => void) | u...

onError?Callback executed if the script fails to load((info: ScriptCallbackInfo) => void) | u...

onLoad?Callback executed when the script loads successfully((info: ScriptCallbackInfo) => void) | u...

persistAfterConsentRevoked?Whether the script should persist after consent is revoked.boolean | undefined

src?URL of the script to loadstring | undefined

textContent?Inline JavaScript code to executestring | undefined

vendorId?IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over category when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.string | number | undefined

consentsThe current consent staterequiredRecord<AllConsentNames, boolean>

element?The script element (for load/error callbacks) Will be undefined for callback-only scriptsHTMLScriptElement

elementIdThe actual DOM element ID used (anonymized if enabled)requiredstring

error?Error information (for error callbacks)Error

hasConsentHas consentrequiredboolean

idThe original script IDrequiredstring

consentsThe current consent staterequiredRecord<AllConsentNames, boolean>

element?The script element (for load/error callbacks) Will be undefined for callback-only scriptsHTMLScriptElement

elementIdThe actual DOM element ID used (anonymized if enabled)requiredstring

error?Error information (for error callbacks)Error

hasConsentHas consentrequiredboolean

idThe original script IDrequiredstring

consentsThe current consent staterequiredRecord<AllConsentNames, boolean>

element?The script element (for load/error callbacks) Will be undefined for callback-only scriptsHTMLScriptElement

elementIdThe actual DOM element ID used (anonymized if enabled)requiredstring

error?Error information (for error callbacks)Error

hasConsentHas consentrequiredboolean

idThe original script IDrequiredstring

consentsThe current consent staterequiredRecord<AllConsentNames, boolean>

element?The script element (for load/error callbacks) Will be undefined for callback-only scriptsHTMLScriptElement

elementIdThe actual DOM element ID used (anonymized if enabled)requiredstring

error?Error information (for error callbacks)Error

hasConsentHas consentrequiredboolean

idThe original script IDrequiredstring