c15t/docs/integrations/microsoft-clarity.md

Headless JavaScript consent management platform for cookie banners, privacy preferences, consent storage, and script gating.

---
title: Microsoft Clarity
description: Session replay and behavior analytics with a prebuilt helper that
  keeps Clarity consent synchronized with c15t measurement state.
group: integrations
icon: microsoft-clarity
---
Microsoft Clarity gives you session recordings, heatmaps, and behavioral insights. The `clarity()` helper sets up Clarity's queue stub, loads the vendor bundle, and keeps Clarity's consent state in sync as c15t measurement consent changes.

## Integrate with c15t

**React**

```tsx
import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/react';
import { clarity } from '@c15t/scripts/microsoft-clarity';

const scripts = [
  clarity({
    id: 'abcdef1234',
  }),
];

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

**Next.js**

```tsx
'use client';

import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/nextjs';
import { clarity } from '@c15t/scripts/microsoft-clarity';

const scripts = [
  clarity({
    id: 'abcdef1234',
  }),
];

export function ConsentProvider({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: '/api/c15t',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}
```

**JavaScript**

```ts
import { getOrCreateConsentRuntime } from 'c15t';
import { clarity } from '@c15t/scripts/microsoft-clarity';

getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  scripts: [
    clarity({
      id: 'abcdef1234',
    }),
  ],
});
```

## How c15t loads it

* **Category:** `measurement` (Analytics)
* **Loads when:** measurement consent is granted
* **On revocation:** stays loaded (`persistAfterConsentRevoked: true`) and receives `clarity('consent', false)` so Clarity transitions into denied mode without tearing down the script.

## Configure the integration

You can queue an initial Clarity consent value before the script loads.

```ts
import { clarity } from '@c15t/scripts/microsoft-clarity';

clarity({
  id: 'abcdef1234',
  defaultConsent: false,
});
```

Use an object when you need to map granular consent categories into Clarity's boot-time consent payload:

```ts
clarity({
  id: 'abcdef1234',
  defaultConsent: {
    marketing: false,
    analytics: true,
  },
});
```

c15t queues that exact `defaultConsent` object during boot. Later consent changes are mapped to simple `true` or `false` values when c15t updates Clarity.

## Tracking events in your app

c15t gates the Clarity script from loading until `measurement` consent is granted. Your application code that calls Clarity's runtime API (`window.clarity(...)`) is **not** automatically gated - `window.clarity` does not exist until the script is loaded, so unguarded calls before consent throw.

Guard event calls by checking consent state. From React:

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

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

  const trackSignup = useCallback(() => {
    if (has('measurement')) {
      window.clarity?.('event', 'signup');
    }
  }, [has]);

  // Call trackSignup() from an event handler after signup succeeds.
}
```

From plain JavaScript:

```ts
import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime();

if (consentStore.getState().has('measurement')) {
  window.clarity?.('event', 'signup');
}
```

## Types

### ClarityOptions

|Property|Value|
|:--|:--|
|Type Name|\`ClarityOptions\`|
|Source Path|\`./packages/scripts/src/vendors/analytics/microsoft-clarity.ts\`|

\*ExtractedTypeTable: Could not extract "ClarityOptions" from "./packages/scripts/src/vendors/analytics/microsoft-clarity.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

### Script

|Property|Value|
|:--|:--|
|Type Name|\`Script\`|
|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|

\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*