PostHog makes it easy to get data about traffic and usage of your React app. Integrating PostHog into your site enables analytics about user behavior, custom events capture, session recordings, feature flags, and more.
This guide will walk you through an example integration of PostHog using React and the posthog-js library.
Installation
For Next.js, we recommend following the Next.js integration guide instead.
- Install posthog-js using your package manager
yarn add posthog-js# ornpm install --save posthog-js
- Add your environment variables to your
.env.local
file and to your hosting provider (e.g. Vercel, Netlify, AWS). You can find your project API key in the PostHog app under Project Settings > API Keys.
REACT_APP_PUBLIC_POSTHOG_KEY=<ph_project_api_key>REACT_APP_PUBLIC_POSTHOG_HOST=<ph_instance_address>
- Integrate PostHog at the root of your app (
src/index.js
for the defaultcreate-react-app
).
// src/index.jsimport React from 'react';import ReactDOM from 'react-dom/client';import App from './App';import { PostHogProvider} from 'posthog-js/react'const options = {api_host: process.env.REACT_APP_PUBLIC_POSTHOG_HOST,}const root = ReactDOM.createRoot(document.getElementById('root'));root.render(<React.StrictMode><PostHogProviderapiKey={process.env.REACT_APP_PUBLIC_POSTHOG_KEY}options={options}><App /></PostHogProvider></React.StrictMode>);
Usage
PostHog Provider
The React context provider makes it easy to access the posthog-js
library in your app.
The provider can either take an initialized client instance OR an API key and an optional options
object.
With an initialized client instance:
// src/index.jsimport posthog from 'posthog-js';import { PostHogProvider} from 'posthog-js/react'posthog.init(process.env.REACT_APP_PUBLIC_POSTHOG_KEY,{api_host: process.env.REACT_APP_PUBLIC_POSTHOG_HOST,});const root = ReactDOM.createRoot(document.getElementById('root'));root.render(<React.StrictMode><PostHogProvider client={posthog}><App /></PostHogProvider></React.StrictMode>);
or with an API key and optional options
object:
// src/index.jsimport { PostHogProvider} from 'posthog-js/react'const options = {api_host: process.env.REACT_APP_PUBLIC_POSTHOG_HOST,}const root = ReactDOM.createRoot(document.getElementById('root'));root.render(<React.StrictMode><PostHogProviderapiKey={process.env.REACT_APP_PUBLIC_POSTHOG_KEY}options={options}><App /></PostHogProvider></React.StrictMode>);
Using posthog-js functions
By default, the posthog-js
library automatically captures pageviews, element clicks, inputs, and more. Autocapture can be tuned in with the configuration options.
If you want to use the library to identify users, capture events, use feature flags, or use other features, you can access the initialized posthog-js
library using the usePostHog
hook.
Do not directly import posthog
apart from installation as shown above. This will likely cause errors as the library might not be initialized yet. Initialization is handled automatically when you use the PostHogProvider
and hook.
All the methods of the library are available and can be used as described in the posthog-js documentation.
import { usePostHog } from 'posthog-js/react'import { useEffect } from 'react'import { useUser, useLogin } from '../lib/user'function App() {const posthog = usePostHog()const login = useLogin()const user = useUser()useEffect(() => {if (user) {// Identify sends an event, so you want may want to limit how often you call itposthog?.identify(user.id, {email: user.email,})posthog?.group('company', user.company_id)}}, [posthog, user.id, user.email, user.company_id])const loginClicked = () => {posthog?.capture('Clicked Log In')login()}return (<div className="App">{/* Fire a custom event when the button is clicked */}<button onClick={() => posthog?.capture('button clicked')}>Click me</button>{/* This button click event is autocaptured by default */}<button data-attr="autocapture-button">Autocapture buttons</button>{/* This button click event is not autocaptured */}<button className="ph-no-capture">Ignore certain elements</button><button onClick={loginClicked}>Login</button></div>)}export default App
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:
useEffect(() => {posthog?.capture('Test') // using optional chaining (recommended)if (posthog) {posthog.capture('Test') // using an if statement}}, [posthog])
Typescript helps protect against these errors.
Feature Flags
PostHog's feature flags enable you to safely deploy and roll back new features.
There are two ways to implement feature flags in React:
- Using hooks.
- Using the
<PostHogFeature>
component.
Method 1: Using hooks
PostHog provides several hooks to make it easy to use feature flags in your React app.
Hook | Description |
---|---|
useFeatureFlagEnabled | Returns a boolean indicating whether the feature flag is enabled. |
useFeatureFlagPayload | Returns the payload of the feature flag. |
useFeatureFlagVariantKey | Returns the variant key of the feature flag. |
useActiveFeatureFlags | Returns an array of active feature flags. |
Example 1: Using a boolean feature flag
import { useFeatureFlagEnabled } from 'posthog-js/react'function App() {const showWelcomeMessage = useFeatureFlagEnabled('flag-key')return (<div className="App">{showWelcomeMessage ? (<div><h1>Welcome!</h1><p>Thanks for trying out our feature flags.</p></div>) : (<div><h2>No welcome message</h2><p>Because the feature flag evaluated to false.</p></div>)}</div>);}export default App;
Example 2: Using a multivariate feature flag
import { useFeatureFlagVariantKey } from 'posthog-js/react'import { useState, useEffect } from 'react'function App() {const variantKey = useFeatureFlagVariantKey('show-welcome-message')const [ welcomeMessage, setWelcomeMessage ] = useState('')useEffect(() => {if (variantKey === 'variant-a') {setWelcomeMessage('Welcome to the Alpha!')} else if (variantKey === 'variant-b') {setWelcomeMessage('Welcome to the Beta!')}}, [variantKey])return (<div className="App">{welcomeMessage ? (<div><h1>{welcomeMessage}</h1><p>Thanks for trying out our feature flags.</p></div>) : (<div><h2>No welcome message</h2><p>Because the feature flag evaluated to false.</p></div>)}</div>);}export default App;
Example 3: Using a flag payload
import { useFeatureFlagPayload } from 'posthog-js/react'function App() {const payload = useFeatureFlagPayload('show-welcome-message')return (<>{payload?.welcomeMessage ? (<div className="welcome-message"><h2>{payload?.welcomeTitle}</h2><p>{payload.welcomeMessage}</p></div>) : <div><h2>No welcome message</h2><p>Because the feature flag evaluated to false.</p></div>}</>)}
Method 2: Using the PostHogFeature component
The PostHogFeature
component simplifies code by handling feature flag related logic.
It also automatically captures metrics, like how many times a user interacts with this feature.
Note: You still need the
PostHogProvider
at the top level for this to work.
Here is an example:
import { PostHogFeature } from 'posthog-js/react'function App() {return (<PostHogFeature flag='show-welcome-message' match={true}><div><h1>Hello</h1><p>Thanks for trying out our feature flags.</p></div></PostHogFeature>)}
The
match
on the component can be eithertrue
, or the variant key, to match on a specific variant.If you also want to show a default message, you can pass these in the
fallback
attribute.
If you wish to customise logic around when the component is considered visible, you can pass in visibilityObserverOptions
to the feature. These take the same options as the IntersectionObserver API. By default, we use a threshold of 0.1.
Payloads
If your flag has a payload, you can pass a function to children whose first argument is the payload. For example:
import { PostHogFeature } from 'posthog-js/react'function App() {return (<PostHogFeature flag='show-welcome-message' match={true}>{(payload) => {return (<div><h1>{payload.welcomeMessage}</h1><p>Thanks for trying out our feature flags.</p></div>)}}</PostHogFeature>)}
Bootstrapping Flags
Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This is detrimental if you want to do something like redirecting to a different page based on a feature flag.
To have your feature flags available immediately, you can initialize PostHog with precomputed values until PostHog has had a chance to fetch them. This is called bootstrapping.
For details on how to implement bootstrapping, see our bootstrapping guide
Experiments (A/B tests)
Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:
// You can either use the `useFeatureFlagVariantKey` hook,// or you can use the feature flags component - https://posthog.com/docs/libraries/react#feature-flags-react-component// Method one: using the useFeatureFlagVariantKey hookimport { useFeatureFlagVariantKey } from 'posthog-js/react'function App() {const variant = useFeatureFlagVariantKey('experiment-feature-flag-key')if (variant == 'variant-name') {// do something}}// Method two: using the feature flags componentimport { PostHogFeature } from 'posthog-js/react'function App() {return (<PostHogFeature flag='experiment-feature-flag-key' match={'variant-name'}><!-- the component to show --></PostHogFeature>)}// You can also test your code by overriding the feature flag:// e.g., posthog.feature_flags.override({'experiment-feature-flag-key': 'test'})
It's also possible to run experiments without using feature flags.