# React Router V7 data mode - Docs 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](/docs/libraries/react-router.md). If you're using React with another framework, go to the [React integration guide](/docs/libraries/react.md). 1. 1 ## Install client-side SDKs Required First, you'll need to install [`posthog-js`](https://github.com/posthog/posthog-js) and `@posthog/react` using your package manager. These packages allow you to capture **client-side** events. PostHog AI ### npm ```bash npm install --save posthog-js @posthog/react ``` ### Yarn ```bash yarn add posthog-js @posthog/react ``` ### pnpm ```bash pnpm add posthog-js @posthog/react ``` ### Bun ```bash bun add posthog-js @posthog/react ``` 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](https://us.posthog.com/settings/project). If you're using Vite, including `VITE_PUBLIC_` in their names ensures they are accessible in the frontend. .env.local PostHog AI ```shell VITE_PUBLIC_POSTHOG_TOKEN= VITE_PUBLIC_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 PostHog AI ```jsx 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_PUBLIC_POSTHOG_TOKEN, { api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST, defaults: '2026-01-30', }); const router = createBrowserRouter([...]); createRoot(document.getElementById("root")!).render( {/* Pass PostHog client through 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: React PostHog AI ```jsx 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](/docs/product-analytics/autocapture.md). 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 PostHog AI ```jsx import { usePostHog } from '@posthog/react' function App() { const posthog = usePostHog() return } ``` You should see these events in a minute or two in the [activity tab](https://app.posthog.com/activity/explore). 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: TSX PostHog AI ```jsx import { usePostHog } from '@posthog/react' function App() { const posthog = usePostHog() return } ``` For a complete list of available methods, see the [posthog-js documentation](/docs/libraries/js.md). 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: TSX PostHog AI ```jsx 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 (
{/* ... existing code ... */}
); } ``` 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 PostHog AI ```jsx 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:** React PostHog AI ```jsx import { PostHogCaptureOnViewed } from '@posthog/react' function App() { return (
Your important content here
 ) } ``` **With custom properties:** You can include additional properties with the event to provide more context: React PostHog AI ```jsx ``` **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: React PostHog AI ```jsx ``` 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`: React PostHog AI ```jsx