references/adding-feature-flag-code.md
Adding feature flag code - Docs
Once you've created your feature flag in PostHog, the next step is to add your code:
Web
Boolean feature flags
Web
PostHog AI
if (posthog.isFeatureEnabled('flag-key') ) {
// Do something differently for this user
// Optional: fetch the payload
const matchedFlagPayload = posthog.getFeatureFlagPayload('flag-key')
}
Multivariate feature flags
Web
PostHog AI
if (posthog.getFeatureFlag('flag-key') == 'variant-key') { // replace 'variant-key' with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
const matchedFlagPayload = posthog.getFeatureFlagPayload('flag-key')
}
Ensuring flags are loaded before usage
Every time a user loads a page, we send a request in the background to fetch the feature flags that apply to that user. We store those flags in your chosen persistence option (local storage by default).
This means that for most pages, the feature flags are available immediately — except for the first time a user visits.
To handle this, you can use the onFeatureFlags callback to wait for the feature flag request to finish:
Web
PostHog AI
posthog.onFeatureFlags(function (flags, flagVariants, { errorsLoading }) {
// feature flags are guaranteed to be available at this point
if (posthog.isFeatureEnabled('flag-key')) {
// do something
}
})
Callback parameters
The onFeatureFlags callback receives the following parameters:
-
flags: string[]: An object containing the feature flags that apply to the user. -
flagVariants: Record<string, string | boolean>: An object containing the variants that apply to the user. -
{ errorsLoading }: { errorsLoading?: boolean }: An object containing a boolean indicating if an error occurred during the request to load the feature flags. This istrueif the request timed out or if there was an error. It will befalseorundefinedif the request was successful.
You won't usually need to use these, but they are useful if you want to be extra careful about feature flags not being loaded yet because of a network error and/or a network timeout (see feature_flag_request_timeout_ms).
Reloading feature flags
Feature flag values are cached. If something has changed with your user and you'd like to refetch their flag values, call:
Web
PostHog AI
posthog.reloadFeatureFlags()
Overriding server properties
Sometimes, you might want to evaluate feature flags using properties that haven't been ingested yet, or were set incorrectly earlier. You can do so by setting properties the flag depends on with these calls:
Web
PostHog AI
posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'})
Note: These are set for the entire session. Successive calls are additive: all properties you set are combined together and sent for flag evaluation.
Whenever you set these properties, we also trigger a reload of feature flags to ensure we have the latest values. You can disable this by passing in the optional parameter for reloading:
Web
PostHog AI
posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'}, false)
At any point, you can reset these properties by calling resetPersonPropertiesForFlags:
Web
PostHog AI
posthog.resetPersonPropertiesForFlags()
The same holds for group properties:
Web
PostHog AI
// set properties for a group
posthog.setGroupPropertiesForFlags({'company': {'property1': 'value', property2: 'value2'}})
// reset properties for a given group:
posthog.resetGroupPropertiesForFlags('company')
// reset properties for all groups:
posthog.resetGroupPropertiesForFlags()
Note: You don't need to add the group names here, since these properties are automatically attached to the current group (set via
posthog.group()). When you change the group, these properties are reset.
Automatic overrides
Whenever you call posthog.identify with person properties, we automatically add these properties to flag evaluation calls to help determine the correct flag values. The same is true for when you call posthog.group().
Default overridden properties
By default, we always override some properties based on the user IP address.
The list of properties that this overrides:
$geoip_city_name$geoip_country_name$geoip_country_code$geoip_continent_name$geoip_continent_code$geoip_postal_code$geoip_time_zone
This enables any geolocation-based flags to work without manually setting these properties.
Request timeout
You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.
JavaScript
PostHog AI
posthog.init('<ph_project_token>', {
api_host: 'https://us.i.posthog.com',
defaults: '2026-01-30'
feature_flag_request_timeout_ms: 3000 // Time in milliseconds. Default is 3000 (3 seconds).
})
Feature flag error handling
When using the PostHog SDK, it's important to handle potential errors that may occur during feature flag operations. Here's an example of how to wrap PostHog SDK methods in an error handler:
JavaScript
PostHog AI
function handleFeatureFlag(client, flagKey, distinctId) {
try {
const isEnabled = client.isFeatureEnabled(flagKey, distinctId);
console.log(`Feature flag '${flagKey}' for user '${distinctId}' is ${isEnabled ? 'enabled' : 'disabled'}`);
return isEnabled;
} catch (error) {
console.error(`Error fetching feature flag '${flagKey}': ${error.message}`);
// Optionally, you can return a default value or throw the error
// return false; // Default to disabled
throw error;
}
}
// Usage example
try {
const flagEnabled = handleFeatureFlag(client, 'new-feature', 'user-123');
if (flagEnabled) {
// Implement new feature logic
} else {
// Implement old feature logic
}
} catch (error) {
// Handle the error at a higher level
console.error('Feature flag check failed, using default behavior');
// Implement fallback logic
}
React
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. This sends a $feature_flag_called event. | | useFeatureFlagVariantKey | Returns the variant key of the feature flag. This sends a $feature_flag_called event. | | useActiveFeatureFlags | Returns an array of active feature flags. This does not send a $feature_flag_called event. | | useFeatureFlagPayload | Returns the payload of the feature flag. This does not send a $feature_flag_called event. Always use this with useFeatureFlagEnabled or useFeatureFlagVariantKey. |
Example 1: Using a boolean feature flag
React
PostHog AI
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>
);
}
export default App;
Example 2: Using a multivariate feature flag
React
PostHog AI
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>
);
}
export default App;
Example 3: Using a flag payload
Payload hook
The useFeatureFlagPayload hook does not send a $feature_flag_called event, which is required for the experiment to be tracked. To ensure the exposure event is sent, you should always use the useFeatureFlagPayload hook with either the useFeatureFlagEnabled or useFeatureFlagVariantKey hook.
React
PostHog AI
import { useFeatureFlagPayload } 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>
}
</>
)
}
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
PostHogProviderat the top level for this to work.
Here is an example:
React
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
matchon 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
fallbackattribute.
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:
React
PostHog AI
import { PostHogFeature } from '@posthog/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>
)
}
Request timeout
You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.
JavaScript
PostHog AI
posthog.init('<ph_project_token>', {
api_host: 'https://us.i.posthog.com',
defaults: '2026-01-30'
feature_flag_request_timeout_ms: 3000 // Time in milliseconds. Default is 3000 (3 seconds).
}
)
Error handling
When using the PostHog SDK, it's important to handle potential errors that may occur during feature flag operations. Here's an example of how to wrap PostHog SDK methods in an error handler:
JavaScript
PostHog AI
function handleFeatureFlag(client, flagKey, distinctId) {
try {
const isEnabled = client.isFeatureEnabled(flagKey, distinctId);
console.log(`Feature flag '${flagKey}' for user '${distinctId}' is ${isEnabled ? 'enabled' : 'disabled'}`);
return isEnabled;
} catch (error) {
console.error(`Error fetching feature flag '${flagKey}': ${error.message}`);
// Optionally, you can return a default value or throw the error
// return false; // Default to disabled
throw error;
}
}
// Usage example
try {
const flagEnabled = handleFeatureFlag(client, 'new-feature', 'user-123');
if (flagEnabled) {
// Implement new feature logic
} else {
// Implement old feature logic
}
} catch (error) {
// Handle the error at a higher level
console.error('Feature flag check failed, using default behavior');
// Implement fallback logic
}
Node.js
There are 2 steps to implement feature flags in Node:
Step 1: Evaluate the feature flag value
Boolean feature flags
Node.js
PostHog AI
const isFeatureFlagEnabled = await client.isFeatureEnabled('flag-key', 'distinct_id_of_your_user')
if (isFeatureFlagEnabled) {
// Your code if the flag is enabled
// Optional: fetch the payload
const matchedFlagPayload = await client.getFeatureFlagPayload('flag-key', 'distinct_id_of_your_user', isFeatureFlagEnabled)
}
Multivariate feature flags
Node.js
PostHog AI
const enabledVariant = await client.getFeatureFlag('flag-key', 'distinct_id_of_your_user')
if (enabledVariant === 'variant-key') { // replace 'variant-key' with the key of your variant
// Do something differently for this user
// Optional: fetch the payload
const matchedFlagPayload = await client.getFeatureFlagPayload('flag-key', 'distinct_id_of_your_user', enabledVariant)
}
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
There are two methods you can use to include feature flag information in your events:
Method 1: Include the $feature/feature_flag_name property
In the event properties, include $feature/feature_flag_name: variant_key:
Node.js
PostHog AI
client.capture({
distinctId: 'distinct_id_of_your_user',
event: 'event_name',
properties: {
'$feature/feature-flag-key': 'variant-key' // replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
},
})
Method 2: Set sendFeatureFlags to true
The capture() method has an optional argument sendFeatureFlags, which is set to false by default. This parameter controls whether feature flag information is sent with the event.
Basic usage
Setting sendFeatureFlags to true will include feature flag information with the event:
Node.js
PostHog AI
client.capture({
distinctId: 'distinct_id_of_your_user',
event: 'event_name',
sendFeatureFlags: true,
})
Advanced usage (v5.5.0+)
As of version 5.5.0, sendFeatureFlags can also accept an options object for more granular control:
Node.js
PostHog AI
client.capture({
distinctId: 'distinct_id_of_your_user',
event: 'event_name',
sendFeatureFlags: {
onlyEvaluateLocally: true,
personProperties: { plan: 'premium' },
groupProperties: { org: { tier: 'enterprise' } }
}
})
Performance considerations
-
With local evaluation: When local evaluation is configured, setting
sendFeatureFlags: truewill not make additional server requests. Instead, it uses the locally cached feature flags, and it provides an interface for including person and/or group properties needed to evaluate the flags in the context of the event, if required. -
Without local evaluation: PostHog will make an additional request to fetch feature flag information before capturing the event, which adds delay.
Breaking change in v5.5.0
Prior to version 5.5.0, feature flags were automatically sent with events when using local evaluation, even when sendFeatureFlags was not explicitly set. This behavior has been removed in v5.5.0 to be more predictable and explicit.
If you were relying on this automatic behavior, you must now explicitly set sendFeatureFlags: true to continue sending feature flags with your events.
Fetching all flags for a user
You can fetch all flag values for a single user by calling getAllFlags() or getAllFlagsAndPayloads().
This is useful when you need to fetch multiple flag values and don't want to make multiple requests.
Node.js
PostHog AI
await client.getAllFlags('distinct_id_of_your_user')
await client.getAllFlagsAndPayloads('distinct_id_of_your_user')
Sending $feature_flag_called events
Capturing $feature_flag_called events enable PostHog to know when a flag was accessed by a user and thus provide analytics and insights on the flag. By default, we send a these event when:
- You call
posthog.getFeatureFlag()orposthog.isFeatureEnabled(), AND - It's a new user, or the value of the flag has changed.
Note: Tracking whether it's a new user or if a flag value has changed happens in a local cache. This means that if you reinitialize the PostHog client, the cache resets as well – causing
$feature_flag_calledevents to be sent again when callinggetFeatureFlagorisFeatureEnabled. PostHog is built to handle this, and so duplicate$feature_flag_calledevents won't affect your analytics.
You can disable automatically capturing $feature_flag_called events. For example, when you don't need the analytics, or it's being called at such a high volume that sending events slows things down.
To disable it, set the sendFeatureFlagEvents argument in your function call, like so:
Node.js
PostHog AI
const isFeatureFlagEnabled = await client.isFeatureEnabled(
'flag-key',
'distinct_id_of_your_user',
{
'sendFeatureFlagEvents': false
})
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
Node.js
PostHog AI
await client.getFeatureFlag(
'flag-key',
'distinct_id_of_the_user',
{
personProperties: {
'property_name': 'value'
},
groups: {
"your_group_type": "your_group_id",
"another_group_type": "your_group_id",
},
groupProperties: {
'your_group_type': {
'group_property_name': 'value'
},
'another_group_type': {
'group_property_name': 'value'
}
},
}
)
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zone
Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
Request timeout
You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.
JavaScript
PostHog AI
const client = new PostHog('<ph_project_token>', {
api_host: 'https://us.i.posthog.com',
feature_flag_request_timeout_ms: 3000 // Time in milliseconds. Default is 3000 (3 seconds).
}
)
Error handling
When using the PostHog SDK, it's important to handle potential errors that may occur during feature flag operations. Here's an example of how to wrap PostHog SDK methods in an error handler:
JavaScript
PostHog AI
async function handleFeatureFlag(client, flagKey, distinctId) {
try {
const isEnabled = await client.isFeatureEnabled(flagKey, distinctId);
console.log(`Feature flag '${flagKey}' for user '${distinctId}' is ${isEnabled ? 'enabled' : 'disabled'}`);
return isEnabled;
} catch (error) {
console.error(`Error fetching feature flag '${flagKey}': ${error.message}`);
// Optionally, you can return a default value or throw the error
// return false; // Default to disabled
throw error;
}
}
// Usage example
try {
const flagEnabled = await handleFeatureFlag(client, 'new-feature', 'user-123');
if (flagEnabled) {
// Implement new feature logic
} else {
// Implement old feature logic
}
} catch (error) {
// Handle the error at a higher level
console.error('Feature flag check failed, using default behavior');
// Implement fallback logic
}
Python
There are 2 steps to implement feature flags in Python:
Step 1: Evaluate the feature flag value
Boolean feature flags
Python
PostHog AI
is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled:
# Do something differently for this user
# Optional: fetch the payload
matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')
Multivariate feature flags
Python
PostHog AI
enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key': # replace 'variant-key' with the key of your varian