Script Loader

The script loader manages third-party JavaScript based on consent state. You declare scripts in your provider's scripts option, and c15t decides when each script should load, stay loaded, unload, or receive a consent update.

Use it for analytics, pixels, tag managers, product analytics, and other vendor snippets that should not run until the right consent condition is satisfied. Prebuilt helpers live in @c15t/scripts; custom scripts can be declared directly when the vendor is specific to your app.

npm install @c15t/scripts

pnpm add @c15t/scripts

yarn add @c15t/scripts

bun add @c15t/scripts

Basic Usage

Pass an array of scripts to ConsentManagerProvider. Built-in helpers from @c15t/scripts return plain Script objects, so they sit beside app-specific scripts:

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

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

The provider registers those scripts when the consent runtime starts. From that point on, c15t owns the lifecycle: it checks consent, injects eligible scripts, unloads them when consent is revoked, and runs onConsentChange for scripts that stay loaded.

Recommended Structure

Define your script list once and keep it next to the consent provider so vendor setup stays declarative:

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

const scripts = [
  gtag({ id: 'G-XXXXXXX' }),
  metaPixel({ pixelId: '123456' }),
];

export function ConsentProvider({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: 'https://your-instance.c15t.dev',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}

If an integration is route-specific or tenant-specific, use dynamic script management instead of conditionally building this list per render.

Mental Model

Every script you register has the same lifecycle. c15t evaluates each script against the current consent state, then drives it through a small number of states:

1. Pending — registered but waiting for consent. Nothing is in the DOM yet.
2. Loaded — consent matched, c15t injected the script (or ran callbacks for callback-only scripts).
3. Updated — already loaded, consent state changed, onConsentChange ran so the SDK can react.
4. Unloaded — consent was revoked. c15t removed the script element unless you opted into persistence.

Four lifecycle callbacks let you hook into transitions: onBeforeLoad, onLoad, onConsentChange, and onError. Two flags — alwaysLoad and persistAfterConsentRevoked — change how c15t treats consent boundaries. Everything else (DOM placement, ad-block evasion, dynamic management) is a refinement on top of this core model.

Choose the Right Approach

Most projects mix more than one style. Pick the smallest one that keeps consent behavior obvious:

Script Types

Standard Scripts

Standard scripts load an external JavaScript file via a <script> tag. This is the default for most analytics and pixel SDKs:

{
  id: 'analytics',
  src: 'https://cdn.example.com/analytics.js',
  category: 'measurement',
}

Inline Scripts

Inline scripts execute JavaScript from textContent instead of loading a URL. Use these sparingly; a manifest-backed helper is usually better for reusable vendor code.

{
  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

Callback-only scripts do not inject a script tag. They run lifecycle callbacks when consent allows them to. Use this when another package has already loaded the SDK and c15t only needs to drive consent:

{
  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();
    }
  },
}

Manifest-Backed Helpers

Built-in integrations in @c15t/scripts are manifest-backed. A manifest describes vendor setup as structured phases, then c15t compiles it into a Script. Manifests keep queue stubs, script URLs, consent signaling, and post-load work consistent across apps and they are safe to ship from a server.

Use a manifest-backed helper when:

• the integration should be reused across projects,
• the vendor snippet has ordered setup steps,
• the vendor exposes a consent API,
• or you plan to contribute the integration back to c15t.

Read the custom integration guide for the manifest contract, phases, and testing checklist.

Iframe And Renderable Integrations

Some vendors are not just script tags. YouTube embeds, maps, calendars, and checkout widgets often need a visible component, a placeholder, or an iframe.

• For iframe-only embeds, gate the iframe src with the iframe blocking pattern instead of loading a script just to hide an iframe.
• For SDK-backed UI, use the script loader for the shared SDK and render the component only when consent and SDK readiness agree.
• Use YouTubeEmbed for the iframe-only YouTube candidate and GoogleMap for the callback-based SDK candidate.
• Use useConsentScript() when building custom wrappers. It registers scripts through the consent store, follows loadedScripts, and returns a promise-shaped readiness contract for callback-based SDKs.

Lifecycle Callbacks

Every script supports four callbacks. Each receives a ScriptCallbackInfo payload (id, element, hasConsent, consents):

• onBeforeLoad — runs before the script tag is injected. Create globals, queues, or vendor stubs here.
• onLoad — runs after the browser loads the script. Call vendor init() APIs here.
• onConsentChange — runs for loaded scripts when consent changes. Forward the new consent state to the vendor SDK.
• onError — runs when the script fails to load. Record diagnostics or render a fallback.

{
  id: 'analytics',
  src: 'https://analytics.example.com/v2.js',
  category: 'measurement',
  onBeforeLoad: ({ id }) => {
    window.analyticsQueue = window.analyticsQueue || [];
  },
  onLoad: () => {
    window.analytics.init('my-key');
  },
  onError: ({ error }) => {
    console.error('Failed to load analytics:', error);
  },
  onConsentChange: ({ hasConsent }) => {
    window.analytics.setConsent(hasConsent);
  },
}

Consent Conditions

The category field accepts a HasCondition. It can be a single consent category 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'] } }

Consent categories use the same names as the rest of c15t (necessary, functionality, experience, measurement, marketing).

Persistence Options

Always Load

alwaysLoad loads the script regardless of whether its category is currently granted. Use it only when the vendor must be present early and has a reliable consent API of its own — Google Tag Manager with Consent Mode is the canonical example.

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

When alwaysLoad is on, onConsentChange becomes mandatory: it is how the loaded SDK learns about every transition.

Persist After Revocation

persistAfterConsentRevoked keeps a script in the page after consent is revoked instead of unloading it. Use it only when the vendor exposes a runtime consent toggle — otherwise unloading is safer because removing the element guarantees the SDK stops.

{
  id: 'error-tracking',
  src: 'https://errors.example.com/track.js',
  category: 'measurement',
  persistAfterConsentRevoked: true,
  onConsentChange: ({ hasConsent }) => {
    window.ErrorTracker.setConsent(hasConsent);
  },
}

As with alwaysLoad, onConsentChange is how the persisted SDK learns about consent updates.

alwaysLoad vs persistAfterConsentRevoked

These two flags answer different questions. Use this table to keep them straight:

DOM Placement

Control where the script is injected and whether the element id is anonymized:

{
  id: 'widget',
  src: 'https://widget.example.com/embed.js',
  category: 'experience',
  target: 'body',     // 'head' (default) or 'body'
  anonymizeId: true,  // default: true, hides the c15t script id from ad blockers
  nonce: 'abc123',    // optional CSP nonce
}

Set anonymizeId: false only when another script or test needs a stable DOM id. Pass nonce when your CSP requires it; c15t applies it directly to the generated <script> element.

You usually do not need a per-script nonce. Setting nonce once on the provider covers every injected script (and the theme stylesheet); a per-script value overrides it for that script alone.

Dynamic Management

Framework packages expose script-manager methods so integrations can be added, removed, or inspected at runtime. Use this for tenant-specific tools, feature-flagged scripts, or vendors that are configured after sign-in:

• setScripts(scripts) — registers script definitions and immediately evaluates them against consent.
• removeScript(id) — removes a definition and unloads its element if needed.
• isScriptLoaded(id) — returns whether c15t has loaded a script.
• getLoadedScriptIds() — returns every currently loaded script id.

Dynamic scripts should still use stable ids. If the same vendor is added repeatedly with different ids, c15t treats each call as a new script.

Calling Vendor APIs From Your App

The script loader controls when the vendor SDK loads. It does not intercept calls your application code makes to that SDK afterwards. Whether your event calls are safe before consent is granted depends on the script's persistence flags:

The safe pattern in React is to read consent state through useConsentManager().has(category) before calling the SDK:

import { useCallback } from 'react';
import { useConsentManager } from '@c15t/react';

function useTrackSignup() {
  const { has } = useConsentManager();

  return useCallback(() => {
    if (has('measurement')) {
      window.fathom?.trackEvent('signup');
    }
  }, [has]);
}

function SignupButton() {
  const trackSignup = useTrackSignup();

  return <button onClick={trackSignup}>Sign up</button>;
}

From non-React code, read the consent store directly:

import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime();

if (consentStore.getState().has('measurement')) {
  window.fathom?.trackEvent('signup');
}

Each integration page includes a vendor-specific Tracking events in your app block that names which pattern applies.

Debugging Checklist

When a script does not behave as expected:

1. Confirm the script's category matches the consent that has been granted.
2. Check whether the script is alwaysLoad or consent-gated.
3. Confirm onBeforeLoad creates any globals before the vendor code reads them.
4. Confirm onConsentChange updates persisted or always-loaded scripts when consent changes.
5. Check whether the browser or an ad blocker blocked the request.
6. Use c15t devtools to inspect script lifecycle events when available.

Dynamic Script Management

The shared guide above lists what the script-manager methods do. In React they are exposed through useConsentManager():

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

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

  // ...
}

Register dynamic scripts from an effect or event handler — never directly in the render body. Effects guarantee the call runs once per dependency change and gives you a tear-down path:

import { useEffect } from 'react';
import { useConsentManager } from '@c15t/react';

export function TenantAnalytics({ siteId }: { siteId: string }) {
  const { setScripts, removeScript } = useConsentManager();

  useEffect(() => {
    const scriptId = `tenant-analytics-${siteId}`;

    setScripts([
      {
        id: scriptId,
        src: `https://cdn.example.com/${siteId}.js`,
        category: 'measurement',
      },
    ]);

    return () => {
      removeScript(scriptId);
    };
  }, [siteId, setScripts, removeScript]);

  return null;
}

Renderable Integrations

Some vendors need a render surface as well as a script — maps, video players, calendars, and checkout widgets all fall in this bucket.

Use the built-in Google Maps and YouTube renderable helpers when they fit:

import { GoogleMap, YouTubeEmbed } from '@c15t/react';

function Page() {
  const googleMapsApiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;

  return (
    <>
      {googleMapsApiKey && (
        <GoogleMap
          apiKey={googleMapsApiKey}
          authReferrerPolicy="origin"
          center={{ lat: 40.7128, lng: -74.006 }}
          className="overflow-hidden rounded-xl"
          consentCategory="measurement"
          mapId="YOUR_MAP_ID"
          zoom={12}
        />
      )}

      <YouTubeEmbed
        consentCategory="marketing"
        params={{ controls: true, playsinline: true }}
        title="Product demo"
        videoId="dQw4w9WgXcQ"
      />
    </>
  );
}

The design splits the problem into three layers:

1. Use the script loader to gate and load the shared SDK once.
2. Use useConsentScript() for SDK readiness when a vendor uses a callback-style loader.
3. Create the widget instance only after the SDK is ready and clean it up on unmount.

Google Maps is SDK-backed, so GoogleMap registers one shared Google Maps script through the c15t script manager and waits for the callback-shaped SDK readiness signal before creating each map instance. It uses the official Google Maps types and accepts the direct-loader options libraries, language, region, version, authReferrerPolicy, mapIds, channel, and solutionChannel.

YouTube is iframe-only, so YouTubeEmbed builds on the existing Frame consent boundary instead of loading the YouTube iframe API. That keeps iframe media separate from SDK widgets and avoids a second source of truth for script readiness.

GoogleMap has a default height of 320px; override style.height or supply a class that sets an inline-compatible height when your layout needs another size. mapId is construction-time configuration in the Google Maps API, so changing it recreates the map. Other controlled values such as center, zoom, and updateable options are applied to the existing instance.

The Maps JavaScript API is a page singleton. Before consent, c15t makes no Maps script request. After the first approved load, the SDK registration is retained for the consent-manager lifetime to avoid Google's duplicate-loader warning; map instances are still destroyed as soon as the component unmounts or consent becomes unavailable. All GoogleMap instances that share a scriptId must therefore use the same loader options. If another part of the application already loaded Maps, the component adopts that global API without injecting a second script.

GoogleMap reports network, timeout, constructor, and Google's global authentication failures through onError and errorFallback. Authentication errors commonly mean the browser key, billing, or allowed referrers need attention.

YouTubeEmbed defaults to a responsive, borderless 16:9 frame with stable placeholder dimensions, a localized loading state, native lazy loading, and the privacy-enhanced youtube-nocookie.com host. For overrides, className and the forwarded ref target the iframe while wrapperClassName and frameProps target the consent-gated Frame. Boolean values in params are serialized as YouTube's documented 1 and 0 values.

For custom SDK-backed widgets, call useConsentScript() with a c15t Script object. The hook uses the consent manager as the source of truth, shares compatible registrations inside that provider, and exposes status, consent, the ready SDK value, errors, and a promise:

import { useState } from 'react';
import { useConsentScript } from '@c15t/react';

export function VendorWidget() {
  const [retryKey, setRetryKey] = useState(0);
  const vendor = useConsentScript({
    script: {
      id: 'vendor-sdk',
      src: 'https://cdn.example.com/sdk.js',
      category: 'measurement',
    },
    resolveReady: () => window.vendorSdk ?? false,
    registerReadyCallback: ({ resolve }) => {
      window.onVendorReady = () => resolve(window.vendorSdk);

      return () => {
        delete window.onVendorReady;
      };
    },
    readinessKey: 'vendor-sdk-v1',
    retryKey,
    timeoutMs: 10_000,
    unmountBehavior: 'keep',
  });

  if (vendor.status === 'blocked') {
    return <p>Enable Analytics consent to use this widget.</p>;
  }

  if (vendor.status === 'loading') {
    return <p role="status">Loading widget…</p>;
  }

  if (vendor.status === 'error') {
    return (
      <div role="alert">
        <p>The widget could not be loaded.</p>
        <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
          Retry
        </button>
      </div>
    );
  }

  if (vendor.status !== 'ready' || !vendor.readyValue) {
    return null;
  }

  return <div ref={(node) => node && vendor.readyValue.mount(node)} />;
}

Inline script objects and lifecycle callbacks are safe. The hook compares the complete non-function script configuration, reads callbacks from the latest render, adopts a compatible script already owned by the provider, and never removes a registration it did not create. Use unmountBehavior: 'remove' (the default) for route-local scripts, or 'keep' for a genuine page-level singleton.

Change retryKey after a failed attempt to retry the same registration. Consumers sharing a script id must use identical script options, readinessKey, timeout, and unmount behavior. Conflicts throw ConsentScriptConflictError; choose another id only when the vendor genuinely supports multiple page-level loaders.

For iframe-only embeds, use the iframe blocking pattern or YouTubeEmbed instead of loading a JavaScript SDK to hide an iframe. For SDK-backed widgets, treat the SDK as a singleton and each rendered component as its own instance.

API Reference

Warning: ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.