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 in @c15t/scripts. Check the integrations overview first before manually building a script.

npm install @c15t/scripts

Info

We recommend using the pre-built integrations when possible.

Info

If you need a vendor we do not ship yet, see the custom integration guide. It covers both one-off Script objects and reusable manifest-backed integrations.

Info

For app-specific scripts, use a plain Script object. For reusable integrations, prefer a manifest-backed helper so startup phases, consent signaling, and future server-side loading support stay structured.

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: 'hosted',
        backendURL: '/api/c15t',
        scripts: [
          metaPixel({ pixelId: '123456' }),
          {
            id: 'custom-analytics',
            src: 'https://cdn.example.com/analytics.js',
            category: 'measurement',
          },
        ],
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}

Choose the Right Approach

Use a plain Script for one-off app code.
Use a manifest-backed helper in @c15t/scripts for reusable integrations, contributions, or anything that needs structured startup behavior.

If you are building something reusable, start with the custom integration guide before using raw callbacks.

Reusable Integrations

For app-specific use, raw Script objects are usually enough.

For reusable integrations, c15t uses a manifest-backed model in @c15t/scripts. That keeps startup phases, consent signaling, and vendor-specific boot logic structured instead of hidden inside large callback bodies.

If you are building an integration for multiple apps or contributing upstream, use the custom integration guide.

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

Description

Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed. This is useful for: Example use cases:

Full Type

boolean | undefined

Default

false

Usage

callbackOnly={...}

Loading…

Script Loader

Basic Usage

Choose the Right Approach

Reusable Integrations

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

plusminusalwaysLoad?boolean | undefined

plusminusanonymizeId?boolean | undefined

plusminusasync?boolean | undefined

plusminusattributes?Record<string, strin...

plusminuscallbackOnly?boolean | undefined

plusminuscategoryrequiredHasCondition<AllCons...

plusminusdefer?boolean | undefined

plusminusfetchPriority?"high" | "low" | "au...

plusminusiabLegIntPurposes?number[] | undefined

plusminusiabPurposes?number[] | undefined

plusminusiabSpecialFeatures?number[] | undefined

plusminusidrequiredstring

plusminusnonce?string | undefined

plusminusonBeforeLoad?((info: ScriptCallba...

plusminusonConsentChange?((info: ScriptCallba...

plusminusonError?((info: ScriptCallba...

plusminusonLoad?((info: ScriptCallba...

plusminuspersistAfterConsentRevoked?boolean | undefined

plusminussrc?string | undefined

plusminustarget?"head" | "body" | un...

plusminustextContent?string | undefined

plusminusvendorId?string | number | un...

plusminusalwaysLoad?boolean | undefined

plusminusanonymizeId?boolean | undefined

plusminusasync?boolean | undefined

plusminusattributes?Record<string, strin...

plusminuscallbackOnly?boolean | undefined

plusminuscategoryrequiredHasCondition<AllCons...

plusminusdefer?boolean | undefined

plusminusfetchPriority?"high" | "low" | "au...

plusminusiabLegIntPurposes?number[] | undefined

plusminusiabPurposes?number[] | undefined

plusminusiabSpecialFeatures?number[] | undefined

plusminusidrequiredstring

plusminusnonce?string | undefined

plusminusonBeforeLoad?((info: ScriptCallba...

plusminusonConsentChange?((info: ScriptCallba...

plusminusonError?((info: ScriptCallba...

plusminusonLoad?((info: ScriptCallba...

plusminuspersistAfterConsentRevoked?boolean | undefined

plusminussrc?string | undefined

plusminustarget?"head" | "body" | un...

plusminustextContent?string | undefined

plusminusvendorId?string | number | un...