Property overrides for flag evaluation
Property overrides let you provide person or group properties directly to PostHog for feature flag evaluation, instead of relying on properties stored on the server. This is useful when properties are set from a different client (like a backend service setting a property that your frontend needs immediately), or when multiple clients setting the same property could cause inconsistent flag evaluations.
Why use property overrides?
Property overrides are useful when:
Properties are set elsewhere: Properties can come from different parts of your application, like a backend service or another client. Your frontend might not know if they have been processed. If several clients set the same property, the value in PostHog can change unexpectedly as updates arrive from various sources.
Values are transient or context-specific: You might need to evaluate flags using values that shouldn't be saved on the person record. This includes session-specific context, derived values, or information you prefer not to retain.
Testing and debugging: You can test flag behavior using specific property values. This way, you won't need to change the actual user's properties.
Property overrides bypass server-stored properties. They send properties directly with the flag evaluation request. This way, results are immediate and consistent.
Client-side SDKs
Client-side SDKs can automatically include device and environment properties in every feature flag evaluation request. This ensures flags targeting properties like browser, OS, or app version work correctly without waiting for server-side processing.
Automatic overrides
Client-side SDKs automatically cache properties from identify() and group() calls for use in flag evaluation. You don't need to do anything special for these to work. Client-side SDKs also include common device and environment properties by default. The methods below give you additional control when needed.
From identify calls
When you call identify() with person properties, those properties are automatically cached for flag evaluation. This means flags can use the properties immediately without waiting for server-side processing.
From setPersonProperties calls
setPersonProperties() persists the property on the person profile and caches it for flag evaluation. This means a flag can target the property right after you set it, without waiting for the property to be ingested.
On web and React Native, setPersonProperties() also reloads feature flags. On iOS, Android, and Flutter it doesn't, so call reloadFeatureFlags() yourself.
The reload is async, so a flag check on the line straight after setPersonProperties() can still return the value cached before the property was set. It's usually fast, but reading the flag in an onFeatureFlags() callback avoids the race.
Identical calls are ignored. If you set the same properties for the same distinct ID twice in a row, the second call does nothing: no $set event and no flag reload.
Note:
setPersonProperties()creates a person profile if one doesn't exist yet, so subsequent events for that user are captured as identified events. If you only need the property for flag evaluation, usesetPersonPropertiesForFlags()instead.
From group calls
Similarly, when you call group() with group properties, those properties are cached for flag evaluation:
Default properties in the web SDK
By default, the web SDK sends initial session properties with flag requests:
| Property | Description |
|---|---|
$initial_referrer | First referrer URL |
$initial_referring_domain | First referring domain |
$initial_current_url | First page URL visited |
$initial_host | First hostname |
$initial_pathname | First URL pathname |
$initial_utm_source | First UTM source |
$initial_utm_medium | First UTM medium |
$initial_utm_campaign | First UTM campaign |
$initial_utm_content | First UTM content |
$initial_utm_term | First UTM term |
$initial_gclid | First Google Ads click ID |
$initial_fbclid | First Facebook click ID |
$initial_msclkid | First Microsoft click ID |
Other campaign parameters (gad_source, mc_cid, dclid, gbraid, wbraid, twclid, li_fat_id, ttclid, rdt_cid, etc.) are also included with the $initial_ prefix when present in the first page URL.
Including browser and device properties
To include current browser and device properties (like $browser, $os, $device_type) with flag requests, use the setAllPersonProfilePropertiesAsPersonPropertiesForFlags customization. Call it inside the loaded callback so it runs before the SDK's first flag request and those properties are included from the very first evaluation.
Using npm:
Using the snippet:
This adds the following properties to flag requests:
| Property | Description |
|---|---|
$browser | Browser name (e.g., "Chrome", "Safari") |
$browser_version | Browser version |
$os | Operating system name (e.g., "Windows", "Mac OS X") |
$os_version | Operating system version |
$device_type | Device type ("Desktop", "Mobile", "Tablet") |
$current_url | Current page URL |
$pathname | URL pathname |
$referrer | HTTP referrer |
$referring_domain | Referring domain |
$screen_height | Screen height in pixels |
$screen_width | Screen width in pixels |
$viewport_height | Browser viewport height |
$viewport_width | Browser viewport width |
$raw_user_agent | Raw user agent string |
utm_source, utm_medium, etc. | Current campaign parameters |
Default properties in mobile SDKs
Mobile SDKs (React Native, iOS, Android, and Flutter) include common device and app properties in every feature flag evaluation request. The setDefaultPersonProperties configuration option controls this behavior and defaults to true.
| Property | Description |
|---|---|
$app_version | App version from bundle/package info |
$app_build | App build number |
$app_namespace | App bundle identifier/namespace |
$os / $os_name | Operating system name ("macOS", "iOS", "iPadOS", "tvOS", "watchOS", "visionOS", "Android") |
$os_version | Operating system version |
$device_type | Device type ("Mobile", "Tablet", "TV", "CarPlay", "Desktop", "Vision") |
$lib | SDK identifier (e.g., "posthog-ios") |
$lib_version | SDK version |
Manual overrides with setPersonPropertiesForFlags
Use setPersonPropertiesForFlags() to explicitly set properties for flag evaluation. These properties are merged additively and persist in storage until you call resetPersonPropertiesForFlags() or reset().
Note: Properties set with
setPersonPropertiesForFlags()are additive. Each call merges new properties with existing ones rather than replacing them.
Unlike setPersonProperties(), this doesn't create a person profile and doesn't send a $set event. The properties stay in the SDK and are sent with each flag evaluation request, so you can target flags on person properties for users who are still anonymous. They aren't saved on the person either, so they're not available anywhere else, like server-side evaluation or the same user on another device.
Controlling automatic flag reload
By default, calling setPersonPropertiesForFlags() triggers an automatic reload of feature flags. You can disable this if you plan to set multiple properties before reloading:
Resetting property overrides
To clear all manually set property overrides:
On mobile SDKs, this automatically triggers a feature flag reload. For Flutter, pass reloadFeatureFlags: false to reset without reloading. On web, flags are not automatically reloaded. Call reloadFeatureFlags() manually if needed.
Group property overrides
You can also override group properties for flag evaluation:
Use case: Targeting by browser or device
Web example: Target Chrome users on desktop
First, enable browser properties using the customization (see Including browser and device properties above). Then:
- Create a feature flag in PostHog
- Add filter conditions:
$browserequalsChromeAND$device_typeequalsDesktop - The flag automatically matches Chrome desktop users
Mobile example: Target app versions
With setDefaultPersonProperties enabled (the default), you can target app versions without any additional code:
- Create a feature flag in PostHog
- Add a filter condition using
$app_versionwith a semver operator – for example,$app_version >= (semver) 2.0.0 - The flag automatically matches users on version 2.0.0 and above
You can also use equals for exact version matching (e.g., $app_version equals 2.0.0), but semver operators give you more flexibility for version range targeting.
GeoIP property overrides
PostHog's servers automatically derive GeoIP properties from the user's IP address for feature flag evaluation. This enables geolocation-based flags without any manual setup on client-side SDKs.
Properties included
| Property | Description |
|---|---|
$geoip_city_name | City name |
$geoip_country_name | Country name |
$geoip_country_code | Two-letter country code |
$geoip_continent_name | Continent name |
$geoip_continent_code | Continent code |
$geoip_postal_code | Postal/ZIP code |
$geoip_time_zone | Time zone |
$geoip_subdivision_1_code | Primary subdivision code (e.g., state or province) |
$geoip_subdivision_1_name | Primary subdivision name |
$geoip_subdivision_2_code | Secondary subdivision code (e.g., county) |
$geoip_subdivision_2_name | Secondary subdivision name |
Use case: Geolocation targeting
Create a feature flag targeting users in specific countries:
- Create a feature flag in PostHog
- Add a filter condition:
$geoip_country_codeequalsUS - The flag automatically matches users accessing from the United States
No additional configuration is required on the client side.
Server-side SDKs
Server-side SDKs handle property overrides differently. Instead of persistent session-based overrides, you pass properties directly when evaluating flags.
GeoIP on server-side
Server-side SDKs disable GeoIP by default. This is because PostHog derives GeoIP properties from the request's IP address, which for server-side requests is your server's IP rather than your user's.
For geolocation-based flags, evaluate them on the client side where the user's actual IP is available.
Targeting a specific URL
Flags are evaluated when the SDK makes a request, not when the user opens a page, so they don't have a setting that limits them to a page. To make a flag apply only on a specific page, use one of these options:
- Check the URL in your code before you read the flag. This is the most reliable option.
- Pass the URL in the browser with
setPersonPropertiesForFlags(). - Pass the URL to a server-side SDK as a person property.
- On a site where each page is a full page load, set evaluation contexts from the page path.
- For an experiment, use a
$pageviewexposure event filtered to the page.
Check the URL in your code
Read the flag only on the page where it applies:
The SDK still returns the flag's value on every page, but your code uses it only on /pricing. Because the SDK sends $feature_flag_called when you read a flag, it also doesn't send that event from other pages.
Pass the URL in the browser
Set $current_url and $pathname as flag properties in the loaded callback and on each client-side route change:
Then add a release condition on the person property $pathname (for example, $pathname equals /pricing) or $current_url.
- The
loadedcallback runs before the SDK's first flag request, so that request sends the current URL. If you callsetPersonPropertiesForFlags()later in the page load, the first request sends the URL from the previous page, and your call adds a second billed request. - Each later call reloads flags, and each reload is a billed
/flagsrequest. This adds one request for each client-side route change. See cutting costs. - The reload is async. Until it responds, the flag returns the value for the previous page.
onFeatureFlags()doesn't wait for the reload: if flags have already loaded, it runs your callback right away with the previous values. If your code must have the value for the new page, check the URL in your code instead. - The values persist in storage until the next call,
resetPersonPropertiesForFlags(), orreset(). If you don't call it on a navigation, the flag uses the last URL you set.
The setAllPersonProfilePropertiesAsPersonPropertiesForFlags customization also sets $current_url and $pathname, but only when you call it. It doesn't update them on client-side route changes.
Pass the URL to a server-side SDK
When you evaluate flags on your server, pass the URL or path of the current request in personProperties, and target it with the same release condition. This works with local evaluation.
Pass the property on every call. If a remote evaluation doesn't include it, PostHog uses the value stored on the person, such as "Latest current URL". That stored value often isn't the page the user is on now.





