README.md

@posthog/react

React components and hooks for PostHog analytics integration.

SEE FULL DOCS

Installation

npm install @posthog/react posthog-js

Usage

Setting up the Provider

Wrap your application with PostHogProvider to make the PostHog client available throughout your app:

import { PostHogProvider } from '@posthog/react'

function App() {
    return (
        <PostHogProvider apiKey="<YOUR_PROJECT_API_KEY>" options={{ api_host: 'https://us.i.posthog.com' }}>
            <YourApp />
        </PostHogProvider>
    )
}

Or pass an existing PostHog client instance:

import posthog from 'posthog-js'
import { PostHogProvider } from '@posthog/react'

// Initialize your client
posthog.init('<YOUR_PROJECT_API_KEY>', { api_host: 'https://us.i.posthog.com' })

function App() {
    return (
        <PostHogProvider client={posthog}>
            <YourApp />
        </PostHogProvider>
    )
}

Hooks

usePostHog

Access the PostHog client instance to capture events, identify users, etc.

import { usePostHog } from '@posthog/react'

function MyComponent() {
    const posthog = usePostHog()

    const handleClick = () => {
        posthog.capture('button_clicked', { button_name: 'signup' })
    }

    return <button onClick={handleClick}>Sign Up</button>
}

useFeatureFlagEnabled

Check if a feature flag is enabled for the current user.

import { useFeatureFlagEnabled } from '@posthog/react'

function MyComponent() {
    const isEnabled = useFeatureFlagEnabled('new-feature')

    if (isEnabled) {
        return <NewFeature />
    }
    return <OldFeature />
}

useFeatureFlagVariantKey

Get the variant key for a multivariate feature flag.

import { useFeatureFlagVariantKey } from '@posthog/react'

function MyComponent() {
    const variant = useFeatureFlagVariantKey('experiment-flag')

    if (variant === 'control') {
        return <ControlVariant />
    }
    if (variant === 'test') {
        return <TestVariant />
    }
    return null
}

useFeatureFlagPayload

Get the payload associated with a feature flag.

import { useFeatureFlagPayload } from '@posthog/react'

function MyComponent() {
    const payload = useFeatureFlagPayload('feature-with-payload')

    return <div>Config: {JSON.stringify(payload)}</div>
}

useActiveFeatureFlags

Get all active feature flags for the current user.

import { useActiveFeatureFlags } from '@posthog/react'

function MyComponent() {
    const activeFlags = useActiveFeatureFlags()

    return (
        <ul>
            {activeFlags?.map((flag) => (
                <li key={flag}>{flag}</li>
            ))}
        </ul>
    )
}

Components

PostHogFeature

A component that renders content based on a feature flag's value. Automatically tracks feature views and interactions.

import { PostHogFeature } from '@posthog/react'

function MyComponent() {
    return (
        <PostHogFeature flag="new-cta" fallback={<OldButton />}>
            <NewButton />
        </PostHogFeature>
    )
}

// With variant matching
function MyComponent() {
    return (
        <PostHogFeature flag="experiment" match="test" fallback={<ControlVersion />}>
            <TestVersion />
        </PostHogFeature>
    )
}

// With payload as render function
function MyComponent() {
    return (
        <PostHogFeature flag="banner-config">
            {(payload) => <Banner title={payload.title} color={payload.color} />}
        </PostHogFeature>
    )
}

PostHogErrorBoundary

An error boundary that captures React errors and reports them to PostHog.

import { PostHogErrorBoundary } from '@posthog/react'

function App() {
    return (
        <PostHogProvider apiKey="<YOUR_PROJECT_API_KEY>">
            <PostHogErrorBoundary>
                <YourApp />
            </PostHogErrorBoundary>
        </PostHogProvider>
    )
}

Please see the main PostHog docs.

Questions?

Check out our community page.