Instrument Feature Flags

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.com instead of https://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. 1

   Install the package

   Required

   Install posthog-js and @posthog/react using your package manager:

   npm

   Copy

   npm install posthog-js @posthog/react

   yarn

   Copy

   yarn add posthog-js @posthog/react

   pnpm

   Copy

   pnpm add posthog-js @posthog/react

   bun

   Copy

   bun add posthog-js @posthog/react

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

   Copy

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

3. 3

   Initialize PostHog

   Required

   Wrap your app with the PostHogProvider component at the root of your application (such as main.tsx if you're using Vite):

   main.tsx

   Copy

   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 defaults option automatically configures PostHog with recommended settings for new projects. See SDK defaults for details.

4. 4

   Accessing PostHog in your code

   Recommended

   Use the usePostHog hook to access the PostHog instance in any component wrapped by PostHogProvider:

   MyComponent.tsx

   Copy

   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 posthog directly for non-React code or utility functions:

   utils/analytics.ts

   Copy

   import posthog from 'posthog-js'
   
   export function trackPurchase(amount: number) {
       posthog.capture('purchase_completed', { amount })
   }

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

   Copy

   posthog.capture('my_custom_event', { property: 'value' })

6. 6

   Use feature flags

   Required

   Using hooks

   PostHog provides several hooks to make it easy to use feature flags in your React app. Use useFeatureFlagEnabled for boolean flags:

   Copy

   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:

   Copy

   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 useFeatureFlagPayload hook does not send a $feature_flag_called event, which is required for experiments. Always use it with useFeatureFlagEnabled or useFeatureFlagVariantKey:

   Copy

   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 PostHogFeature component simplifies code by handling feature flag related logic:

   App.tsx

   Copy

   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 match prop can be either true, 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 prop.

   If your flag has a payload, you can pass a function to children whose first argument is the payload:

   App.tsx

   Copy

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