references/react.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
React Feature Flags installation
Canonical URL: https://posthog.com/docs/feature-flags/installation/react
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host).
On this page
- Install with the wizard
- Install the package
- Add environment variables
- Initialize PostHog
- Accessing PostHog in your code
- Send events
- Use feature flags
- Running experiments
- Next steps
Install with the wizard
Run this command in your project directory to add PostHog to your React project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install the package
Required
Install
posthog-jsand@posthog/reactusing your package manager:npm
npm install posthog-js @posthog/reactyarn
yarn add posthog-js @posthog/reactpnpm
pnpm add posthog-js @posthog/reactbun
bun 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_prefix to expose them to the client:.env
VITE_POSTHOG_PROJECT_TOKEN=<ph_project_token> VITE_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
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_POSTHOG_HOST, defaults: '2026-08-30', } as const createRoot(document.getElementById('root')).render( <StrictMode> <PostHogProvider apiKey={import.meta.env.VITE_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
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
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.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
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
<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 |