Setup

Install TrackKit and wire event tracking into your app.

Follow these steps to add the provider, choose between the React API and data-attribute API, call advanced helpers, and send custom events or custom parameters.

Open Demo Open Playground

1. Install

Add the package

Install the package in your Next.js app and set your GTM container id in an environment variable.

npm install nextjs-trackkit

# .env.local
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX

2. Provider

Wrap your app

The provider initializes `window.dataLayer`, applies default consent, loads GTM when an id is present, and activates data-attribute click and viewport tracking. It also provides the context used by TrackKit React components and hooks.

// app/providers.tsx
"use client";

import { TrackKitProvider } from "nextjs-trackkit/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TrackKitProvider gtmId={process.env.NEXT_PUBLIC_GTM_ID}>
      {children}
    </TrackKitProvider>
  );
}

3. Layout

Use the provider in your root layout

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

4. React API

Track reusable components with less markup

Use this method for design systems, reusable CTAs, cards, and sections. Define content context once with `TrackKitSection`, then use `TrackKitLink`, `TrackKitButton`, or `useTrackKitCta` inside your components.

"use client";

import {
  TrackKitButton,
  TrackKitLink,
  TrackKitSection,
} from "nextjs-trackkit/react";

export function PricingHero() {
  return (
    <TrackKitSection
      view
      content={{
        name: "Pricing Hero",
        type: "Marketing Section",
        variant: "Primary",
        media: "Text",
      }}
    >
      <TrackKitLink href="/signup" cta={{ type: "Button" }}>
        Start free trial
      </TrackKitLink>

      <TrackKitButton cta={{ type: "Button" }} eventType="control">
        Open pricing preview
      </TrackKitButton>
    </TrackKitSection>
  );
}

5. Data Attributes

Track views and clicks directly in markup

Put shared context on a section and add click/view attributes to elements inside it. Use this method when you do not want to import TrackKit React components in each UI file.

<section
  data-track-context
  data-track-view
  data-track-content-name="Pricing Hero"
  data-track-content-type="Marketing Section"
  data-track-content-variant="Primary"
  data-track-content-media="Text"
>
  <a
    href="/signup"
    data-track-click
    data-track-cta-type="Button"
    data-track-destination="Internal"
  >
    Start free trial
  </a>
</section>

5b. Auto Discovery

Detect common clicks automatically (v1.3+)

Enable auto discovery when you want TrackKit to detect plain links, buttons, and submit controls without adding `data-track-click` on every element. Manual `data-track-*` attributes still win when present.

// app/providers.tsx
"use client";

import { TrackKitProvider } from "nextjs-trackkit/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TrackKitProvider
      gtmId={process.env.NEXT_PUBLIC_GTM_ID}
      declarativeOptions={{
        autoDiscovery: {
          enabled: true,
          includeSelectors: ["main"],
          excludeSelectors: [".cookie-banner", "[data-track-ignore]"],
        },
      }}
    >
      {children}
    </TrackKitProvider>
  );
}

View live examples

6. Manual Helpers

Fire advanced predefined events from client components

Use manual helpers when the event depends on custom component logic, video state, form completion state, or another workflow.

"use client";

import { trackContentCtaClick } from "nextjs-trackkit";

trackContentCtaClick({
  content: {
    name: "Pricing Hero",
    type: "Marketing Section",
    variant: "Primary",
    media: "Text",
  },
  cta: {
    type: "Button",
    text: "Start free trial",
  },
  navigateToUrl: "/signup",
});

7. Custom Parameters

Add extra data to predefined events

Use `customParameters` when your GTM variables need business or experiment metadata beyond the standard event shape.

trackContentCtaClick({
  content: {
    name: "Pricing Hero",
    type: "Marketing Section",
    media: "Text",
  },
  cta: {
    type: "Button",
    text: "Start free trial",
  },
  navigateToUrl: "/signup",
  customParameters: {
    campaign_id: "summer_launch",
    audience_segment: "developers",
    experiment_id: "pricing_cta_v2",
  },
});

8. Custom Events

Create any event name and parameter object

Use `trackCustomEvent` when your analytics design needs an event outside the predefined helpers.

import { trackCustomEvent } from "nextjs-trackkit";

trackCustomEvent({
  event: "signup_step_completed",
  parameters: {
    flow_name: "Onboarding",
    step_name: "Choose plan",
    step_number: 2,
    plan_type: "Starter",
  },
});

9. Validate

Inspect events in the browser

Install the DataLayer Checker extension in Google Chrome.
Test one React API component and one data-attribute example.
Open the Demo page and trigger each event type.
Use Playground to test custom event names and JSON parameters.
Create matching GTM Custom Event triggers and Data Layer Variables.

Go to Demo Go to Playground