React Router V7 framework mode (Remix V3)

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 install --save posthog-js @posthog/react

yarn add posthog-js @posthog/react

pnpm add posthog-js @posthog/react

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:

PostHog AI

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.

In framework mode, you'll also need to set posthog-js and @posthog/react as external packages in your vite.config.ts file to avoid SSR errors.

// ... imports

export default defineConfig({
  plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
  ssr: {
    noExternal: ['posthog-js', '@posthog/react']
  }
});

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.

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

In framework mode, your app enters from the app/entry.client.tsx file. In this file, you'll need to initialize the PostHog SDK and pass it to your app through the PostHogProvider context.

import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";

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-05-30', 
  tracing_headers: [ window.location.hostname, 'localhost' ], 
}); 

startTransition(() => {
  hydrateRoot(
    document,
    {/* Pass PostHog client through PostHogProvider */}
    <PostHogProvider client={posthog}> 
      <StrictMode>
        <HydratedRouter />
      </StrictMode>
    </PostHogProvider>, 
  );
});

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. This adds the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers to requests sent to the configured hostnames, which we'll later use on the server-side.

useEffect(() => {
  posthog?.capture('test') // using optional chaining (recommended)

  if (posthog) {
    posthog.capture('test') // using an if statement
  }
}, [posthog])

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.

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.

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:

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.

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:

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.

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

import { usePostHog } from '@posthog/react'

export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
  const posthog = usePostHog();
  posthog?.captureException(error);

  // other error handling code...
  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{error.message}</p>
    </div>
  );
}

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

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:

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:

<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:

<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:

<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.

Install the PostHog Node SDK using your package manager. This is the SDK you'll use to capture server-side events.

npm install posthog-node --save

yarn add posthog-node

pnpm add posthog-node

bun add posthog-node

Use one PostHog client for a long-running Node server. Create it in a server-only module and import it from your middleware and tracing setup.

import { PostHog } from 'posthog-node';

export const posthog = new PostHog(process.env.VITE_POSTHOG_PROJECT_TOKEN!, {
  host: process.env.VITE_POSTHOG_HOST!,
});

In React Router 7, enable server middleware in react-router.config.ts:

export default {
  future: { v8_middleware: true },
};

React Router 8 enables server middleware by default. Add the following middleware. It reads PostHog tracing headers and keeps each request context separate. Missing or blank headers add no ID. Header IDs are analytics context and must not authorize access.

import { createContext, type MiddlewareFunction } from 'react-router';
import { posthog } from './posthog.server';

type RequestIds = { distinctId?: string; sessionId?: string };

export const posthogClientContext = createContext<typeof posthog>();
export const posthogErrorContext = createContext<RequestIds | undefined>(undefined);

function tracingId(value: string | null): string | undefined {
  return value?.replace(/[\x00-\x1F\x7F-\x9F]/g, '').trim().slice(0, 1000) || undefined;
}

export const posthogMiddleware: MiddlewareFunction<Response> = async ({ request, context }, next) => {
  const controller = new AbortController();
  const existing = posthog.getContext();
  const data: RequestIds = {
    distinctId: existing?.distinctId ?? tracingId(request.headers.get('x-posthog-distinct-id')),
    sessionId: existing?.sessionId ?? tracingId(request.headers.get('x-posthog-session-id')),
  };
  context.set(posthogClientContext, posthog);
  context.set(posthogErrorContext, data);

  return posthog.withContext(data, async () => {
    try {
      return await next();
    } finally {
      controller.abort();
    }
  }, { fresh: true, signal: controller.signal });
};

Register the middleware in app/root.tsx. Put an authentication middleware before it if you use posthog.withContext to establish a verified application identity. Existing application IDs take priority over header IDs.

import { posthogMiddleware } from './lib/posthog-middleware.server';

export const middleware: Route.MiddlewareFunction[] = [
  posthogMiddleware,
  // other middlewares...
];

The scope ends when next() settles. Work after that point, including a streamed response body, has no PostHog request context. Pass explicit context to separate jobs when needed. Flush queued events before your platform can stop server work. Call posthog.shutdown() once when the server stops.

To capture server errors, add the capture call to your existing handleError export in app/entry.server.tsx. The saved IDs remain available when a middleware error reaches this hook after the scope ends. Errors before this middleware runs have no saved request identity.

import type { HandleErrorFunction } from 'react-router';
import { posthog } from './lib/posthog.server';
import { posthogErrorContext } from './lib/posthog-middleware.server';

export const handleError: HandleErrorFunction = (error, { context }) => {
  const saved = context.get(posthogErrorContext);
  posthog.captureException(error, saved?.distinctId,
    saved?.sessionId ? { $session_id: saved.sessionId } : undefined);
};

Optional server span context

Use the optional posthog-node/otel entrypoint when your Node SDK supports ContextOptions.signal. Add new PostHogContextSpanProcessor(posthog) to the processors in your existing OpenTelemetry setup. Import the processor from posthog-node/otel and reuse the client from posthog.server.ts. Keep your provider, exporters, and sampler.

Import the helper in posthog-middleware.server.ts:

import { enrichCurrentSpan } from 'posthog-node/otel';

Inside the withContext callback, call it immediately before next():

enrichCurrentSpan(posthog);
      return await next();

The helper fills missing posthogDistinctId and sessionId attributes on the active span and its nearest recording server ancestor whose parent chain the processor observed. Explicit span attributes stay unchanged. The processor adds the request IDs to new child spans. If a sampler drops an intermediate span, the earlier server span stays unchanged because its parent chain cannot be verified.

React Router provides server instrumentation hooks for application-owned tracing. Their stable export, instrumentations, is available from 7.15.0. This setup does not create request spans. Configure those hooks or your existing server tracing to start a span before the middleware runs. This recipe was tested with React Router 7.15.0 and 8.4.0 on Node.

At this point, you should be able to capture server-side events and see them in your PostHog project.

In a route, you can access the PostHog client from the context and capture an event. The middleware assigns the session ID and the distinct ID. This ensures that the system associates events with the correct user and session.

import { posthogClientContext } from "../lib/posthog-middleware.server";

export async function action({ request, context }: Route.ActionArgs) {
  const body = await request.json();
  // ... existing code ...

  // Access the PostHog client from the context and capture an event
  const posthog = context.get(posthogClientContext);
  posthog?.capture({ event: 'checkout_completed' });
  
  return Response.json({ 
    success: true, 
    // ... existing code ...
  });
}

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.