@c15t/browser API

Entry points

Install it with:

npm install @c15t/browser@alpha

pnpm add @c15t/browser@alpha

yarn add @c15t/browser@alpha

bun add @c15t/browser@alpha

In the ES module build the preference dialog code is a separate chunk. It starts loading in idle time once the banner or trigger is on screen, and at the latest when the dialog opens. Idle preloading can download it even when the visitor never opens preferences.

The script-tag files c15t.js, c15t.offline.js and c15t.iab.js each carry their complete stylesheet in one file. The default c15t.js uses the hosted client and requires a backend URL or hosted factory. c15t.offline.js uses the offline client. For manifest or custom mode with the stock UI, use the ES module root @c15t/browser, which takes any mode factory.

@c15t/browser is not part of the c15t package. Use one entry per page. Each creates its own client, and two clients on one page would each run the script loader and blockers.

Choose a bundle for one mode

Use @c15t/browser/hosted when Inth or a self-hosted backend supplies the policy. It excludes offline policy presets, offline resolution and manifest transport code. Hosted mode already resolves the visitor's policy on the server through /init; this entry removes unused client code without changing that request.

Use @c15t/browser/offline when the browser resolves bundled rules. It excludes hosted and manifest transport code. The default offline transport keeps choices in the browser's consent cookie and localStorage, with no consent backend requests or server records. Not recommended for production environments.

Both entries keep the banner, preference dialog, page hooks, script gating, blockers, callbacks and persistence. Their init() and createConsentClient() methods have the same lifecycle as the general entry.

Use @c15t/browser for manifest or custom mode, or when an application chooses its mode at runtime. Use @c15t/browser/iab for IAB TCF. The general entry imports no transport itself, so a bundle keeps only the factory it imports. It takes mode as a factory only: backendURL, manifest, manifestURL, policyRules and mode names such as 'hosted' are options of the /hosted and /offline entries and the script-tag builds.

Start the client

init(options) creates the client and starts it:

import { init, manifest } from '@c15t/browser';
import { posthog } from '@c15t/integrations/posthog';

init({
	mode: manifest(),
	scripts: [
		posthog({
			id: 'phc_your_project_key',
			initOptions: { cookieless_mode: 'never' },
			loadMode: 'after-consent',
		}),
	],
});

createConsentClient(options) creates the client without starting it. Construction reads no storage, sends no request and touches no DOM, so a module can create it at import time and call client.start() later:

import { createConsentClient, manifest } from '@c15t/browser';

export const consent = createConsentClient({ mode: manifest(), scripts });

start() reads stored choices, requests the policy, starts the script loader, the iframe blocker and any network blocker, listens for page hooks and mounts the UI. It mounts on DOMContentLoaded when <body> does not exist yet. A second start() does nothing. Options lists everything init and createConsentClient accept.

Read state

has() reads a permission, which says whether code may run now. Under an opt-out policy it is true before the visitor does anything. hasConsented() and getSnapshot().explicitChoice read the recorded choice, which says what the visitor decided. Gate code on permissions; report on recorded choices. How consent works explains the difference.

Record a choice

Call these only from a visitor's click or key press.

Each save applies in the browser and closes the banner or dialog before the backend request finishes. SaveResult.ok is false when the request failed; the choice stays in effect and c15t retries the request later.

Control the UI

Lifecycle and internals

Do not attach a second script loader, network blocker or iframe blocker to client.kernel. The client already runs one of each.

Events

on(event, listener) returns an unsubscribe function:

A ready listener added after the policy resolved runs at once with the snapshot from that moment. A ui listener added after that runs at once with the current surface. consent and error listeners only hear later changes.

Each event is also dispatched on document as c15t:ready, c15t:consent, c15t:ui and c15t:error, with the payload in event.detail. Callbacks compares events with the callbacks option.

Page hooks

A started client also wires markup on the page, with no code:

Helper exports

The general @c15t/browser entry exports all the helpers below. The hosted entry exports hosted; the offline entry exports offline and resolveRules. Both include the page action constants, gated script helpers, mountConsentUI and version.

The package also exports the ConsentClient, ConsentClientOptions, ConsentUIOptions, ConsentBannerOptions, ConsentDialogOptions, ConsentTriggerOptions, ConsentClientEventMap, ConsentSnapshot and ConsentState types.

The hosted and offline entries export HostedConsentClientOptions and OfflineConsentClientOptions, respectively. These types restrict connection options to the entry's mode. Runtime validation also checks a supplied transport factory's kind.

Check it works

1. Start the app and run await consent.ready() from code or a breakpoint. It resolves with a snapshot whose resolution.status is matched.
2. Click Reject All. consent.hasConsented() is true and consent.has('measurement') is false.
3. Call consent.openDialog(). The preference dialog opens with Analytics (the measurement category) off.