React session replay installation

  1. Install the package

    Required

    Install the PostHog JavaScript library using your package manager:

    npm install posthog-js
  2. Add environment variables

    Required

    Add your PostHog API key and host to your environment variables. For Vite-based React apps, use the VITE_PUBLIC_ prefix:

    .env
    VITE_PUBLIC_POSTHOG_KEY=<ph_project_api_key>
    VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
  3. Initialize PostHog

    Required

    Wrap your app with the PostHogProvider component at the root of your application (such as main.tsx if you're using Vite):

    main.tsx
    import { StrictMode } from 'react'
    import { createRoot } from 'react-dom/client'
    import './index.css'
    import App from './App.jsx'
    import { PostHogProvider } from 'posthog-js/react'
    const options = {
    api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST,
    defaults: '2025-11-30',
    } as const
    createRoot(document.getElementById('root')).render(
    <StrictMode>
    <PostHogProvider apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_KEY} options={options}>
    <App />
    </PostHogProvider>
    </StrictMode>
    )
    defaults option

    The defaults option automatically configures PostHog with recommended settings for new projects. See SDK defaults for details.

  4. Accessing PostHog in your code

    Recommended

    Use the usePostHog hook to access the PostHog instance in any component wrapped by PostHogProvider:

    MyComponent.tsx
    import { usePostHog } from 'posthog-js/react'
    function MyComponent() {
    const posthog = usePostHog()
    function handleClick() {
    posthog.capture('button_clicked', { button_name: 'signup' })
    }
    return <button onClick={handleClick}>Sign up</button>
    }

    You can also import posthog directly for non-React code or utility functions:

    utils/analytics.ts
    import posthog from 'posthog-js'
    export function trackPurchase(amount: number) {
    posthog.capture('purchase_completed', { amount })
    }
  5. Watch session recordings

    Recommended

    Visit your site or app and interact with it for at least 10 seconds to generate a recording. Navigate between pages, click buttons, and fill out forms to capture meaningful interactions.

    Watch your first recording →

  6. Next steps

    Recommended

    Now that you're recording sessions, continue with the resources below to learn what else Session Replay enables within the PostHog platform.

    ResourceDescription
    Watching recordingsHow to find and watch session recordings
    Privacy controlsHow to mask sensitive data in recordings
    Network recordingHow to capture network requests in recordings
    Console log recordingHow to capture console logs in recordings
    More tutorialsOther real-world examples and use cases

Community questions

Was this page useful?

Questions about this page? or post a community question.