references/react.md
React feature flags installation - Docs
-
1
Install the package
Required
Install
posthog-jsand@posthog/reactusing your package manager:PostHog AI
npm
npm install posthog-js @posthog/reactyarn
yarn add posthog-js @posthog/reactpnpm
pnpm add posthog-js @posthog/react -
2
Add environment variables
Required
Add your PostHog project token and host to your environment variables. For Vite-based React apps, use the
VITE_PUBLIC_prefix:.env
PostHog AI
VITE_PUBLIC_POSTHOG_PROJECT_TOKEN=<ph_project_token> VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com -
3
Initialize PostHog
Required
Wrap your app with the
PostHogProvidercomponent at the root of your application (such asmain.tsxif you're using Vite):main.tsx
PostHog AI
import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import './index.css' import App from './App.jsx' import { PostHogProvider } from '@posthog/react' const options = { api_host: import.meta.env.VITE_PUBLIC_POSTHOG_HOST, defaults: '2026-01-30', } as const createRoot(document.getElementById('root')).render( <StrictMode> <PostHogProvider apiKey={import.meta.env.VITE_PUBLIC_POSTHOG_PROJECT_TOKEN} options={options}> <App /> </PostHogProvider> </StrictMode> )defaults option
The
defaultsoption automatically configures PostHog with recommended settings for new projects. See SDK defaults for details. -
4
Accessing PostHog in your code
Recommended
Use the
usePostHoghook to access the PostHog instance in any component wrapped byPostHogProvider:MyComponent.tsx
PostHog AI
import { usePostHog } from '@posthog/react' function MyComponent() { const posthog = usePostHog() function handleClick() { posthog.capture('button_clicked', { button_name: 'signup' }) } return <button onClick={handleClick}>Sign up</button> }You can also import
posthogdirectly for non-React code or utility functions:utils/analytics.ts
PostHog AI
import posthog from 'posthog-js' export function trackPurchase(amount: number) { posthog.capture('purchase_completed', { amount }) } -
5
Send events
Recommended
Click around and view a couple pages to generate some events. PostHog automatically captures pageviews, clicks, and other interactions for you.
If you'd like, you can also manually capture custom events:
JavaScript
PostHog AI
posthog.capture('my_custom_event', { property: 'value' }) -
6
Use feature flags
Required
Using hooks
PostHog provides several hooks to make it easy to use feature flags in your React app. Use
useFeatureFlagEnabledfor boolean flags:import { useFeatureFlagEnabled } from '@posthog/react' function App() { const showWelcomeMessage = useFeatureFlagEnabled('flag-key') const payload = useFeatureFlagPayload('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> ) }Multivariate flags
For multivariate flags, use
useFeatureFlagVariantKey:import { useFeatureFlagVariantKey } from '@posthog/react' function App() { const variantKey = useFeatureFlagVariantKey('show-welcome-message') let welcomeMessage = '' if (variantKey === 'variant-a') { welcomeMessage = 'Welcome to the Alpha!' } else if (variantKey === 'variant-b') { welcomeMessage = 'Welcome to the Beta!' } 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> ) }Flag payloads
The
useFeatureFlagPayloadhook does not send a$feature_flag_calledevent, which is required for experiments. Always use it withuseFeatureFlagEnabledoruseFeatureFlagVariantKey:import { useFeatureFlagPayload, useFeatureFlagEnabled } from '@posthog/react' function App() { const variant = useFeatureFlagEnabled('show-welcome-message') const payload = useFeatureFlagPayload('show-welcome-message') return ( <> {variant ? ( <div className="welcome-message"> <h2>{payload?.welcomeTitle}</h2> <p>{payload?.welcomeMessage}</p> </div> ) : ( <div> <h2>No custom welcome message</h2> <p>Because the feature flag evaluated to false.</p> </div> )} </> ) }Using PostHogFeature component
The
PostHogFeaturecomponent simplifies code by handling feature flag related logic:App.tsx
PostHog AI
import { PostHogFeature } from '@posthog/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
matchprop 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 thefallbackprop.If your flag has a payload, you can pass a function to children whose first argument is the payload:
App.tsx
PostHog AI
<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> -
7
Running experiments
Optional
Experiments run on top of our feature flags. Once you've implemented the flag in your code, you run an experiment by creating a new experiment in the PostHog dashboard.
-
8
Next steps
Recommended
Now that you're evaluating flags, continue with the resources below to learn what else Feature Flags enables within the PostHog platform.
| Resource | Description | | --- | --- | | Creating a feature flag | How to create a feature flag in PostHog | | Adding feature flag code | How to check flags in your code for all platforms | | Framework-specific guides | Setup guides for React Native, Next.js, Flutter, and other frameworks | | How to do a phased rollout | Gradually roll out features to minimize risk | | More tutorials | Other real-world examples and use cases |
Community questions
Ask a question
Was this page useful?
HelpfulCould be better