Chapter 109 · Feature Flags Next.js
Subchapter 109.4
references/react.mdMarkdown8 KBView on GitHub
Required
Install posthog-js (opens in a new tab) and @posthog/react using your package manager:
PostHog AI
npm install posthog-js @posthog/reactyarn add posthog-js @posthog/reactpnpm add posthog-js @posthog/react2
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.com3
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
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 defaults option automatically configures PostHog with recommended settings for new projects. See SDK defaults (opens in a new tab) for details.
4
Recommended
Use the usePostHog hook to access the PostHog instance in any component wrapped by PostHogProvider:
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 posthog directly 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
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
Required
PostHog provides several hooks to make it easy to use feature flags in your React app. Use useFeatureFlagEnabled for 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>
)
}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!'
The useFeatureFlagPayload hook does not send a $feature_flag_called event, which is required for experiments. Always use it with useFeatureFlagEnabled or useFeatureFlagVariantKey:
import { useFeatureFlagPayload, useFeatureFlagEnabled } from '@posthog/react'
function App() {
const variant = useFeatureFlagEnabled('show-welcome-message')
const payload = useFeatureFlagPayload('show-welcome-message')
return (
<>
{variant ? (
The PostHogFeature component 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>
</
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
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>
7
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
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 (opens in a new tab) | How to create a feature flag in PostHog |
| Adding feature flag code (opens in a new tab) | How to check flags in your code for all platforms |
| Framework-specific guides (opens in a new tab) | Setup guides for React Native, Next.js, Flutter, and other frameworks |
| How to do a phased rollout (opens in a new tab) | Gradually roll out features to minimize risk |
| More tutorials (opens in a new tab) | Other real-world examples and use cases |
Ask a question
HelpfulCould be better