---
title: PostHog
description: Load PostHog before or after measurement consent with the c15t
  posthog helper, choose its cookieless behavior, turn off PostHog modules you
  do not use, and sync consent with an SDK you already initialize.
icon: posthog
group: integrations
lastModified: "2026-10-10T16:01:45+01:00"
---
## Configure PostHog

Use the project token that starts with `phc_`, and the region of your PostHog
project. This example waits for measurement permission before requesting the
SDK, and turns off cookieless capture after a refusal.

|Package manager|Command|
|:--|:--|
|npm|`npm install @c15t/integrations@alpha`|
|pnpm|`pnpm add @c15t/integrations@alpha`|
|yarn|`yarn add @c15t/integrations@alpha`|
|bun|`bun add @c15t/integrations@alpha`|

```ts title="src/consent-scripts.ts"
import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	posthog({
		id: 'phc_YOUR_PROJECT_TOKEN',
		region: 'eu',
		loadMode: 'after-consent',
		initOptions: { cookieless_mode: 'never' },
	}),
];
```

The helper initializes PostHog itself. Remove any `posthog-js` initializer,
framework plugin or array snippet that also does, or follow
[use an existing PostHog SDK](#use-an-existing-posthog-sdk) instead.

## Register the scripts

Complete your [framework quickstart](/docs/frameworks) first. Keep its Inth
endpoint, policy, styles and consent UI. Remove the vendor's original script,
SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
in the Next.js guide, add the helper to that array instead of creating a
second file.
The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
point for your framework below. These are edits to that provider, not a second
provider.

**Next.js**

Add the configuration to `scripts` in `c15t.config.ts`, next to
`next.config.ts`:

```ts title="c15t.config.ts"
import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });
```

Keep the rest of your config, such as `mode` and `routePrefix`, in the
same call. `ConsentRoot` reads the config in the browser, so the layout
keeps passing only `state`. App Router, Pages Router and static export all
read the same file. See
[Next.js scripts and embeds](/docs/frameworks/next/scripts).

**TanStack Start**

Import the configuration into your root route and pass it to the existing
`ConsentRoot` as a top-level prop. Keep the loader from the
[TanStack Start quickstart](/docs/frameworks/tanstack-start/quickstart):

```tsx title="src/routes/__root.tsx"
import { scripts } from '../consent-scripts';

<ConsentRoot state={consent} scripts={scripts}>
```

Import vendor helpers in the root route module, not in a server function.
A server function's return value must be serializable, and script
configurations carry callbacks. See
[TanStack Start scripts](/docs/frameworks/tanstack-start/scripts).

**React**

Add the configuration to the existing `ConsentProvider` options, next to
`mode`:

```tsx title="src/consent.tsx"
import { scripts } from './consent-scripts';

<ConsentProvider options={{ mode, scripts }}>
```

`mode` is the `manifest()` value from the
[React quickstart](/docs/frameworks/react/quickstart). Keep the banner,
dialog and preferences link inside the provider. See
[React scripts and embeds](/docs/frameworks/react/scripts).

**Nuxt**

Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
relative import to where you created `consent-scripts.ts`:

```ts title="app/app.config.ts"
import { scripts } from '../src/consent-scripts';

export default defineAppConfig({
  c15t: { scripts },
});
```

The Nuxt module merges this over its options in `nuxt.config.ts` and starts
one script loader in the browser after hydration, once it has applied the
visitor's stored choice and privacy signals. Keep `scripts` out of
`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
callbacks. Write the vendor IDs into `consent-scripts.ts`. See
[Nuxt scripts and embeds](/docs/frameworks/nuxt/scripts).

**Vue**

Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:

```ts title="src/main.ts"
import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
import { scripts } from './consent-scripts';

app.use(c15tVue, {
  mode: manifest(),
  scripts,
});
```

Keep your existing `mode` and other options. The plugin starts one
script loader when the app mounts, after it has applied the visitor's stored
choice. Do not also call `createScriptLoader` from a component. See
[Vue scripts and embeds](/docs/frameworks/vue/scripts).

**Astro**

Add the scripts to the client entrypoint from the
[Astro quickstart](/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
which the integration finds on its own. Keep `astro.config.mjs` as it is.
If the module already exports scripts, combine the two arrays.

```ts title="src/c15t.client.ts"
import type { C15tClientOptionsExtension } from 'c15t/astro';
import { scripts } from './consent-scripts';

export default { scripts } satisfies C15tClientOptionsExtension;
```

Vendor helpers contain callbacks, and the integration options in
`astro.config.mjs` are serialized into the page, so do not put helpers in
the integration's `scripts` option. The integration passes the client
entrypoint to the one runtime every page shares, including across
`ClientRouter` navigation.

**Svelte**

Import the scripts in the component that owns your existing provider and
pass them as a top-level prop:

```svelte title="src/App.svelte"
<script lang="ts">
  import { ConsentProvider, manifest } from '@c15t/svelte';
  import { scripts } from './consent-scripts';
</script>

<ConsentProvider mode={manifest()} {scripts}>
  <!-- Keep your application, consent UI and preferences link here. -->
</ConsentProvider>
```

Retain the styles and consent UI from the [Svelte quickstart](/docs/frameworks/svelte/quickstart).
The provider owns the loader and disposes it on unmount.

**SvelteKit**

Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
handle and the layout load from the [SvelteKit quickstart](/docs/frameworks/sveltekit/quickstart).

```svelte title="src/routes/+layout.svelte"
<script lang="ts">
  import { ConsentRoot } from '@c15t/svelte';
  import { scripts } from '../consent-scripts';

  let { children, data } = $props();
</script>

<ConsentRoot state={data.consent} {scripts}>
  {@render children()}
  <!-- Keep your consent UI and preferences link here. -->
</ConsentRoot>
```

Import vendor helpers in the layout component, not in `+layout.server.ts`:
a server load cannot send functions to the browser. Prerendered, static and
SPA-mode pages use the same `scripts` prop. If you pass an externally owned
`runtime` to the provider, register scripts when creating that runtime instead.

**HTML**

The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
page that loads the c15t script tag, paste the vendor's own snippet instead
and keep it inert until its category is allowed:

```html
<script type="text/plain" data-c15t-category="measurement">
  // The vendor's snippet, unchanged
</script>
```

Use the category this guide names for the vendor. c15t runs the snippet
once that category is allowed, and reloads the page when the visitor
withdraws it. Helper options on this page, such as `loadMode`, do not apply
to a pasted snippet. See [HTML scripts](/docs/frameworks/html/scripts).

**JavaScript**

Pass the scripts to `init()` from `@c15t/browser`, next to your mode:

```ts
import { init, manifest } from '@c15t/browser';
import { scripts } from './consent-scripts';

const consent = init({
  mode: manifest(),
  scripts,
});
```

Keep the mode from your quickstart. With
`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
A kernel you create yourself needs a loader from
`c15t/modules/script-loader`. Attach one loader per kernel. See
[JavaScript scripts](/docs/frameworks/javascript/scripts).

## Options

|Option|Default|Behavior|
|--|--|--|
|`id`|Required|Project token, starting with `phc_`. The helper trims it. Empty or whitespace-only values log an error and the script does not load.|
|`region`|`'eu'`|`'eu'` or `'us'`. Picks the API, UI and loader hosts when you do not set them.|
|`apiHost`|`https://eu.i.posthog.com`|API host for a proxy or self-hosted PostHog. Without `scriptUrl`, the loader URL becomes `<apiHost>/static/array.js`.|
|`uiHost`|The region's UI host|UI host, for example `https://eu.posthog.com`. A custom `apiHost` with no `region` uses the API host.|
|`scriptUrl`|`https://eu-assets.i.posthog.com/static/array.js`|Loader URL override. A blank value falls back to the default.|
|`loadMode`|`'always'`|When the SDK loads. See the table below.|
|`features.surveys`|Unset|`false` sets `disable_surveys: true` and skips `surveys.js`. See [turn off features you do not use](#turn-off-features-you-do-not-use).|
|`features.heatmaps`|Unset, follows the project|Sets `capture_heatmaps`.|
|`features.deadClicks`|Unset, follows the project|Sets `capture_dead_clicks`.|
|`features.webVitals`|Unset, follows the project|Sets `capture_performance: { web_vitals }`. Replay network timing keeps following the project.|
|`features.featureFlags`|Unset, follows the project|`false` sets `advanced_disable_feature_flags: true` and stops `/flags` requests.|
|`initOptions`|`{ cookieless_mode: 'on_reject', defaults: '2026-01-30' }`|Options passed to `posthog.init`, merged over the defaults and `features`. The helper sets `api_host` and `ui_host` after your values, so change hosts with the options above.|

## Loading and revocation

|`loadMode`|When PostHog loads|Consent sync|
|--|--|--|
|`'always'`|On every page, before consent|Calls `opt_in_capturing` or `opt_out_capturing` at load and on every change|
|`'after-consent'`|Only while measurement is allowed|Calls `opt_in_capturing` at load and `opt_out_capturing` on revocation|
|`'disabled'`|Never|None. The helper returns an empty callback-only script|

`posthog` uses the `measurement` category. With the default
`cookieless_mode: 'on_reject'`, PostHog keeps capturing without cookies after a
refusal. That mode needs cookieless server hashing turned on in your PostHog
project; see
[PostHog's cookieless guide](https://posthog.com/tutorials/cookieless-tracking).
Set `cookieless_mode: 'never'`, as in the example, if a refusal must stop
capture.

## Turn off features you do not use

After `array.js` loads, PostHog reads your `posthog.init` options and the
project's remote config, then decides which extra modules to download and
whether to request `/flags`. Set a `features` switch to `false` for each
feature your site does not use:

```ts
posthog({
	id: 'phc_YOUR_PROJECT_TOKEN',
	region: 'eu',
	loadMode: 'after-consent',
	features: {
		surveys: false,
		heatmaps: false,
		deadClicks: false,
		webVitals: false,
		featureFlags: false,
	},
});
```

|Switch|`false` sets|What PostHog skips|
|--|--|--|
|`surveys`|`disable_surveys: true`|`surveys.js`, about 29 KB|
|`heatmaps`|`capture_heatmaps: false`|Heatmap capture. With `deadClicks: false` too, `dead-clicks-autocapture.js`|
|`deadClicks`|`capture_dead_clicks: false`|`dead-clicks-autocapture.js`, about 8 KB, once heatmaps are off too|
|`webVitals`|`capture_performance: { web_vitals: false }`|`web-vitals-with-attribution.js`, about 6 KB|
|`featureFlags`|`advanced_disable_feature_flags: true`|`/flags` requests. The remote config still loads|

Sizes are brotli-compressed, measured from posthog-js 1.436.1.

An unset switch adds nothing to `posthog.init`. For heatmaps, dead clicks, web
vitals and feature flags, PostHog then follows the setting in your PostHog
project. `true` sets the opposite value and overrides the project. For
`surveys` and `featureFlags`, `true` is PostHog's own default, so it behaves
the same as unset.

Surveys work differently. PostHog downloads `surveys.js` whenever the remote
config includes a `surveys` value, even when surveys are off in the project.
`surveys: false` is the only way to skip it.

`initOptions` wins over a switch that sets the same key. A
`capture_performance` value in `initOptions` replaces the whole object that
`webVitals` builds.

### Avoid PostHog's option traps

These rules also apply when you pass PostHog options yourself, in
`initOptions` or in your own `posthog.init`:

* Use `advanced_disable_feature_flags: true` to stop `/flags`, not
  `advanced_disable_flags: true`. The second also stops PostHog loading the
  remote config, so session replay never starts and other features fall back to
  local config.
* With feature flags off, surveys that target a feature flag never show.
  PostHog logs a warning about it. If you need those surveys, leave
  `featureFlags` unset and pass
  `advanced_only_evaluate_survey_feature_flags: true` instead. PostHog still
  requests `/flags`, but evaluates only survey flags.
* While heatmaps are on, in `posthog.init` or in the project, PostHog loads
  `dead-clicks-autocapture.js` whatever `capture_dead_clicks` says. Turn off
  both to skip it.
* `capture_performance: false` turns off web vitals and session replay network
  timing. `{ web_vitals: false }`, which `webVitals: false` sets, leaves network
  timing to the project. `capture_performance: true` forces both on.

Product tours (`product-tours.js`, about 36 KB) and exception autocapture
(`exception-autocapture.js`, about 6 KB) load only when the project turns them
on. To keep them off whatever the project says, pass
`disable_product_tours: true` or `capture_exceptions: false` in `initOptions`.

## Guard your own capture calls

Events your code sends need their own permission check. The `posthog` global
exists before the SDK loads, so its presence does not mean measurement is
allowed:

```ts title="src/track-signup.ts"
export function trackSignupStarted(measurementAllowed: boolean) {
	if (!measurementAllowed) return;
	window.posthog?.capture('signup_started');
}
```

Pass the current measurement permission from your framework, for example
`useConsent('measurement')` in React.

## Use an existing PostHog SDK

If your app already initializes `posthog-js`, keep that setup and register a
callback-only script instead of the helper. Initialize the SDK with
`opt_out_capturing_by_default: true` and `cookieless_mode: 'never'` so it
captures nothing before c15t reports a permission.

```ts title="src/posthog-consent.ts"
import type { Script, ScriptCallbackInfo } from 'c15t/modules/script-loader';

type PostHogConsentApi = {
	opt_in_capturing: () => unknown;
	opt_out_capturing: () => unknown;
};

export function posthogConsent(instance: PostHogConsentApi): Script {
	const sync = ({ hasConsent }: ScriptCallbackInfo) => {
		if (hasConsent) instance.opt_in_capturing();
		else instance.opt_out_capturing();
	};

	return {
		id: 'posthog-sdk-consent',
		category: 'measurement',
		callbackOnly: true,
		alwaysLoad: true,
		onBeforeLoad: sync,
		onConsentChange: sync,
	};
}
```

Add `posthogConsent(posthog)` to the `scripts` you register, passing your
initialized SDK instance. `callbackOnly` means c15t inserts no script element.
`alwaysLoad` makes `onBeforeLoad` run on the first page load even while
measurement is denied, so the SDK is told to opt out. `onConsentChange` runs on
every later change. This does not delay the SDK import or its first request.
`loadMode: 'disabled'` is not a substitute, because it syncs nothing.

`features` belongs to the helper, so it does nothing here. To skip modules you
do not use, pass the PostHog options from
[turn off features you do not use](#turn-off-features-you-do-not-use) to your
own `posthog.init`, for example `disable_surveys: true`.

## Measure opt-in rate

If you run a banner experiment, the backend already counts visitors and
choices per arm. To see the arm in PostHog as well, forward the `onSurfaceShown` and
`onChoiceRecorded` callbacks, which carry `experiment: { id, arm }`. See
[banner experiments](/docs/guides/banner-experiments#send-the-events-to-your-own-analytics-too).

## Verify PostHog

These checks assume `loadMode: 'after-consent'` from the example. After you
allow measurement, `array.js` loads and capture requests to your API host
follow. Trigger one guarded event and check that it is sent.

With `loadMode: 'always'`, `array.js` loads before a choice instead. Check that
no capture request is sent while measurement is denied, unless you chose
cookieless capture.

If you turned features off, allow measurement and filter the DevTools Network
panel by `posthog`. Reload the page. You should see `array.js`, the remote
config and capture requests, but no `/flags` request with `featureFlags: false`
and none of the modules you turned off, such as `surveys.js` or
`dead-clicks-autocapture.js`.

Test in a private window with an opt-in policy. Open DevTools Network, disable
the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script
   loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new
   page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop
code that already ran. The vendor's listeners, timers and queued events stay
alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
the vendor yourself. Register a callback-only script whose `onConsentChange`
calls the vendor's opt-out API, as shown in
[custom integrations](/docs/integrations/building-integrations), and check the
permission before each of your own event calls. The reload does not delete
cookies the vendor already set; see
[clear on revocation for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup).

The helper sets `vendor` to its script ID, so once you declare that vendor a
visitor can turn it off inside an allowed category. See
[vendor consent for your framework](/docs/integrations/overview#vendor-switches-and-cookie-cleanup). The
[consent verification guide](/docs/guides/verify-consent) covers navigation,
expiry and hosting checks.