First, you’ll need to install posthog-js (opens in a new tab) and @posthog/react using your package manager. These packages allow you to capture client-side events.
If your site sets a Content-Security-Policy, it needs to allow PostHog. This applies to the snippet and to package installs alike: the SDK lazy-loads extra bundles (session replay, surveys) from PostHog’s CDN, and sends events to the ingestion host. PostHog serves from subdomains of posthog.com that change over time, so allow the wildcard:
script-src covers the snippet and the lazy-loaded bundles, connect-src covers event ingestion and feature flags, and worker-src covers session replay. The toolbar needs a few more (opens in a new tab), or use a reverse proxy (opens in a new tab) so everything is first-party. Failing to do so causes silent failures where capture and identify calls never send, so the integration looks complete while zero events arrive. Remember connect-src falls back to default-src, so default-src 'self' blocks event delivery even when the script itself is bundled.
Add your environment variables to your .env.local file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project token and host in your project settings (opens in a new tab). If you’re using Vite, prefixing variable names with VITE_ ensures they are accessible in the frontend.
Confirm that you can capture client-side events and see them in your PostHog project
At this point, you should be able to capture client-side events and see them in your PostHog project. This includes basic events like page views and button clicks that are autocaptured (opens in a new tab).
You can also try to capture a custom event to verify it’s working. You can access PostHog in any component using the usePostHog hook.
TSX
jsx
import { usePostHog } from '@posthog/react'function App() {
On the client-side, you can access the PostHog client using the usePostHog hook. This hook returns the initialized PostHog client, which you can use to call PostHog methods. For example:
Now that you can capture basic client-side events, you’ll want to identify your user so you can associate users with captured events.
Generally, you identify users when they log in or when they input some identifiable information (e.g. email, name, etc.). You can identify users by calling the identify method on the PostHog client:
PostHog can capture exceptions thrown in your app through an error boundary. PostHog provides a PostHogErrorBoundary component that you can use to capture exceptions. You can wrap your app with this component to capture exceptions.
The PostHogCaptureOnViewed component enables you to automatically capture events when elements scroll into view in the browser. This is useful for tracking impressions of important content, monitoring user engagement with specific sections, or understanding which parts of your page users are actually seeing.
The component wraps your content and sends a $element_viewed event to PostHog when the wrapped element becomes visible in the viewport. It only fires once per component instance.
Basic usage:
React
jsx
import { PostHogCaptureOnViewed } from '@posthog/react'function App() { return ( <PostHogCaptureOnViewed name
Now that you’ve set up PostHog for React Router V7 in declarative mode, you can continue to set up server-side analytics. You can find our other SDKs in the SDKs page (opens in a new tab).
To help PostHog track your user sessions across the client and server, you’ll need to add the tracing_headers: ['your-backend-hostname1.com', 'your-backend-hostname2.com', ...] option to your PostHog initialization:
{/* Pass PostHog client through PostHogProvider */}
<PostHogProvider client={posthog}>
<BrowserRouter>
<Routes>
<Route path="/" element={<Root />}>
{/* ... Your routes ... */}
</Route>
</Routes>
</BrowserRouter>
</PostHogProvider>
</StrictMode>,
);
This initializes PostHog and passes it to your app through the PostHogProvider context.
TypeError: Cannot read properties of undefined
If you see the error TypeError: Cannot read properties of undefined (reading '...') this is likely because you tried to call a posthog function when posthog was not initialized (such as during the initial render). On purpose, we still render the children even if PostHog is not initialized so that your app still loads even if PostHog can’t load.
To fix this error, add a check that posthog has been initialized such as:
React
jsx
useEffect(() => { posthog?.capture('test') // using optional chaining (recommended) if (posthog) { posthog.capture('test') // using an if statement }}, [posthog])
PostHog automatically generates anonymous IDs for users before they’re identified. When you call identify, a new identified person is created. All previous events tracked with the anonymous ID link to the new identified distinct ID, and all future captures on the same browser associate with the identified person.
>
<BrowserRouter>
<Routes>
<Route path="/" element={<Root />}>
{/* ... Your routes ... */}
</Route>
</Routes>
</BrowserRouter>
</PostHogErrorBoundary>
</PostHogProvider>
</StrictMode>,
);
This automatically captures exceptions thrown in your React Router app using the posthog.captureException() method.
=
"hero-banner"
>
<div>Your important content here</div>
</PostHogCaptureOnViewed>
)
}
With custom properties:
You can include additional properties with the event to provide more context:
Use trackAllChildren to track each child element separately. This is useful for galleries or lists where you want to know which specific items were viewed:
This adds the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to requests sent to the configured hostnames, which you can later use on the server-side.