PostHog

Track page views, custom events, and session recordings with PostHog.

PostHog is an open-source product analytics platform that gives you full control over your data. Boltdocs injects the PostHog JavaScript snippet automatically when you configure it.

Property	Type	Default	Description
`apiKey`	`string`	✓	Your PostHog project API key (e.g. `'phc_xxx'`)
`host`	`string`	`'https://us.i.posthog.com'`	PostHog API host. Use `'https://eu.i.posthog.com'` for the EU cloud
`capturePageview`	`boolean`	`true`	Capture page views automatically
`capturePageleave`	`boolean`	`true`	Capture page leave events automatically
`sessionRecording`	`boolean`	`false`	Enable session recording
`autocapture`	`boolean`	`false`	Enable automatic click capture

integrations: {
  analytics: {
    posthog: {
      apiKey: 'phc_xxxxxxxxxxxxxxxxxxxx',
    },
  },
}

If your PostHog instance is in the EU region:

integrations: {
  analytics: {
    posthog: {
      apiKey: 'phc_xxxxxxxxxxxxxxxxxxxx',
      host: 'https://eu.i.posthog.com',
    },
  },
}

integrations: {
  analytics: {
    posthog: {
      apiKey: 'phc_xxxxxxxxxxxxxxxxxxxx',
      sessionRecording: true,
    },
  },
}

Event	Description
`$pageview`	Fires on every page navigation (including client-side navigation)
`$pageleave`	Fires when the user leaves a page

You can track custom events using the useTrackEvent() hook:

tsx

import { useTrackEvent } from 'boltdocs'

export function MyComponent() {
  const trackEvent = useTrackEvent()

  const handleClick = () => {
    trackEvent('button_click', {
      button_id: 'downloadPdf',
      button_location: 'sidebar',
    })
  }

  return <button onClick={handleClick}>Download PDF</button>
}

Access the full analytics API:

tsx

import { useAnalytics } from 'boltdocs'

function MyComponent() {
  const { trackEvent, trackPageView } = useAnalytics()

  // Track a custom event
  trackEvent('search', { query: 'installation' })

  // Track a page view manually
  trackPageView('/docs/guides/getting-started/installation', 'Installation')
}

Simplified page view tracking:

tsx

import { useTrackPageView } from 'boltdocs'

function DocPage({ title, path }) {
  const trackPageView = useTrackPageView()

  useEffect(() => {
    trackPageView(path, title)
  }, [path, title])
}

Track arbitrary events:

tsx

import { useTrackEvent } from 'boltdocs'

function SearchBox() {
  const trackEvent = useTrackEvent()

  return (
    <input
      onChange={(e) => {
        trackEvent('search_input', { query: e.target.value })
      }}
    />
  )
}

PostHog supports opting out of data capture. You can use the PostHog API to respect user consent:

tsx

import { useEffect } from 'react'

function ConsentHandler({ hasConsent }) {
  useEffect(() => {
    if (window.posthog) {
      if (hasConsent) {
        window.posthog.opt_in_capturing()
      } else {
        window.posthog.opt_out_capturing()
      }
    }
  }, [hasConsent])

  return null
}

Verify the API key is correct (starts with phc_)
Check the browser console for errors
Use PostHog's Live Events panel to see real-time events

PostHog scripts are only injected in production builds. Run boltdocs build && boltdocs preview to test locally.

Page views are tracked automatically on navigation. Don't call trackPageView manually unless necessary.

Make sure integrations.analytics.posthog.apiKey is a non-empty string.

Jesús Alcalá

Last updated on October 18, 2026

PostHog

Configuration Reference

Minimal Example

EU Cloud

With Session Recording

What Gets Tracked

Automatic Events

Custom Events

Using the Hooks

`useAnalytics()`

`useTrackPageView()`

`useTrackEvent()`

Respecting User Privacy

Troubleshooting

Events don't appear

Scripts don't appear in development

Duplicate page views

Build errors

Was this page helpful?