Instrument Integration

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

React Router V7 data mode

Canonical URL: https://posthog.com/docs/libraries/react-router/react-router-v7-data-mode

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://us.posthog.com or https://app.posthog.com (app host for links).

On this page

• Install client-side SDKs

• Add your environment variables

• Add the PostHogProvider to your app

• Verify client-side events are captured

• Access PostHog methods

• Identify your user

• Create an error boundary

• Tracking element visibility

• Set up server-side analytics

• Next steps

This guide walks you through setting up PostHog for React Router V7 in data mode. If you're using React Router in another mode, find the guide for that mode in the React Router page. If you're using React with another framework, go to the React integration guide.

1. 1

   Install client-side SDKs

   Required

   First, you'll need to install posthog-js and @posthog/react using your package manager. These packages allow you to capture client-side events.

   npm

   Copy

   npm install --save posthog-js @posthog/react

   Yarn

   Copy

   yarn add posthog-js @posthog/react

   pnpm

   Copy

   pnpm add posthog-js @posthog/react

   Bun

   Copy

   bun add posthog-js @posthog/react

   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:

   Copy

   script-src 'self' https://*.posthog.com;
   connect-src 'self' https://*.posthog.com;
   worker-src 'self' blob: data:;

   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, or use a reverse proxy 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.

2. 2

   Add your environment variables

   Required

   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. If you're using Vite, prefixing variable names with VITE_ ensures they are accessible in the frontend.

   .env.local

   Copy

   VITE_POSTHOG_PROJECT_TOKEN=<ph_project_token>
   VITE_POSTHOG_HOST=https://us.i.posthog.com

3. 3

   Add the PostHogProvider to your app

   Required

   In data mode, you'll need to wrap your RouterProvider with the PostHogProvider context. This passes an initialized PostHog client to your app.

   app/index.tsx

   Copy

   import { StrictMode } from "react";
   import { createRoot } from "react-dom/client";
   import { createBrowserRouter, RouterProvider } from "react-router";
   import Root, { RootErrorBoundary } from "./app/root";
   
   import posthog from 'posthog-js';
   import { PostHogProvider } from '@posthog/react'
   
   posthog.init(import.meta.env.VITE_POSTHOG_PROJECT_TOKEN, {
     api_host: import.meta.env.VITE_POSTHOG_HOST,
     defaults: '2026-08-30',
   });
   
   const router = createBrowserRouter([...]);
   
   createRoot(document.getElementById("root")!).render(
     <StrictMode>
       {/* Pass PostHog client through PostHogProvider */}
       <PostHogProvider client={posthog}>
         <RouterProvider router={router} />
       </PostHogProvider>,
     );
   });

   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:

   Copy

   useEffect(() => {
     posthog?.capture('test') // using optional chaining (recommended)
   
     if (posthog) {
       posthog.capture('test') // using an if statement
     }
   }, [posthog])

   Typescript helps protect against these errors.

4. Verify client-side events are captured

   Checkpoint

   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.

   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.

   Copy

   import { usePostHog } from '@posthog/react'
   
   function App() {
     const posthog = usePostHog()
     return <button onClick={() => posthog?.capture('button_clicked')}>Click me</button>
   }

   You should see these events in a minute or two in the activity tab.

5. 4

   Access PostHog methods

   Required

   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:

   Copy

   import { usePostHog } from '@posthog/react'
   
   function App() {
     const posthog = usePostHog()
     return <button onClick={() => posthog?.capture('button_clicked')}>Click me</button>
   }

   For a complete list of available methods, see the posthog-js documentation.

6. 5

   Identify your user

   Recommended

   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:

   Copy

   export default function Login() {
     const { user, login } = useAuth();
     const posthog = usePostHog();
   
     const handleLogin = async (e: React.FormEvent) => {
       // existing code to handle login...
       const user = await login({ email, password });
   
       posthog?.identify(user.email,
         {
           email: user.email,
           name: user.name,
         }
       );
       posthog?.capture('user_logged_in');
     };
   
     return (
       <div>
         {/* ... existing code ... */}
         <button onClick={handleLogin}>Login</button>
       </div>
     );
   }

   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.

7. 6

   Create an error boundary

   Recommended

   PostHog can capture exceptions thrown in your app through an error boundary. React Router in data mode has a built-in error boundary that you can use to capture exceptions. You can create an error boundary by exporting RootErrorBoundary from your app/root.tsx file.

   app/root.tsx

   Copy

   import { usePostHog } from '@posthog/react'
   
   export function RootErrorBoundary() {
     const error = useRouteError();
   
     const posthog = usePostHog();
     if (error) {
       posthog.captureException(error);
     }
   
     // other error handling code...
   }

   This automatically captures exceptions thrown in your React Router app using the posthog.captureException() method.

8. 7

   Tracking element visibility

   Recommended

   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:

   Copy

   import { PostHogCaptureOnViewed } from '@posthog/react'
   
   function App() {
       return (
           <PostHogCaptureOnViewed name="hero-banner">
               <div>Your important content here</div>
           </PostHogCaptureOnViewed>
       )
   }

   With custom properties:

   You can include additional properties with the event to provide more context:

   Copy

   <PostHogCaptureOnViewed
       name="product-card"
       properties={{
           product_id: '123',
           category: 'electronics',
           price: 299.99
       }}
   >
       <ProductCard />
   </PostHogCaptureOnViewed>

   Tracking multiple children:

   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:

   Copy

   <PostHogCaptureOnViewed
       name="product-gallery"
       properties={{ gallery_type: 'featured' }}
       trackAllChildren
   >
       <ProductCard id="1" />
       <ProductCard id="2" />
       <ProductCard id="3" />
   </PostHogCaptureOnViewed>

   When trackAllChildren is enabled, each child element sends its own event with a child_index property indicating its position.

   Custom intersection observer options:

   You can customize when elements are considered "viewed" by passing options to the IntersectionObserver:

   Copy

   <PostHogCaptureOnViewed
       name="footer"
       observerOptions={{
           threshold: 0.5,  // Element is 50% visible
           rootMargin: '0px'
       }}
   >
       <Footer />
   </PostHogCaptureOnViewed>

   The component passes all other props to the wrapper div, so you can add styling, classes, or other HTML attributes as needed.

9. 8

   Set up server-side analytics

   Recommended

   Now that you've set up PostHog for React Router V7 in data mode, you can continue to set up server-side analytics. You can find our other SDKs in the SDKs page.

   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:

   Copy

   posthog.init(import.meta.env.VITE_POSTHOG_PROJECT_TOKEN, {
     api_host: import.meta.env.VITE_POSTHOG_HOST,
     defaults: '2026-08-30',
     tracing_headers: [ window.location.hostname, 'localhost' ],
   });

   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.

10. 9

    Next steps

    Recommended

    Now that you've set up PostHog for React Router, you can start capturing events and exceptions in your app.

    To get the most out of PostHog, you should familiarize yourself with the following:

    • PostHog Web SDK docs: Learn more about the PostHog Web SDK and how to use it on the client-side.

    • PostHog Node SDK docs: Learn more about the PostHog Node SDK and how to use it on the server-side.

    • Identify users: Learn more about how to identify users in your app.

    • Group analytics: Learn more about how to use group analytics in your app.

    • PostHog AI: After capturing events, use PostHog AI to help you understand your data and build insights.

    • Feature flags and experiments: Feature flag and experiment setup is the same as React. You can find more details in the React integration guide.