Multivariate feature flags

Last updated:

Multivariate feature flags are only available when using PostHog >= 1.28 (if self-hosting) and posthog-js >= 1.13.

PostHog 1.28 introduced support for multivariate feature flags which can return string values according to a specified distribution.

Some examples for a 3-variant case would be 33/33/34%, 50/25/25%, or 70/20/10%. This is ideal for when you want to test multiple variants of the same interchangeable content, such as marketing taglines, colors, or page layouts.

Creating a feature flag with multiple variants

Create a multivariate feature flag just like you would a standard flag, and then change the "Served value" option to "a string value". You will then be prompted to enter a few keys with optional descriptions and set the distribution percentages for each.

Note that the rollout percentage of feature flag variants must add up to 100%. If you wish to exclude some users from your test, i.e. have some users receive no value at all, configure the release condition groups. While the release condition groups determine how many users will be bucketed into any of the given variants, the rollout percentage of each variant determines the portion of the overall release group that will be assigned to that particular variant.

Using multivariate feature flags in your code

With the latest version of our JS library, you can call:

if (posthog.getFeatureFlag('checkout-button-color') === 'black') {
// do something

getFeatureFlag also returns true or false for standard (Boolean) feature flags, meaning that the following statements are equivalent:

posthog.getFeatureFlag('new-beta-feature') === true


Just as you can call getFlags() to return an array of feature flags that are currently active, you can call:


getFlagVariants returns an object:

"new-beta-feature": true,
"checkout-button-color": "black"


onFeatureFlags(callback) now passes the feature flag variants object as the second argument to callback, which looks like this:

posthog.onFeatureFlags(function (flags, flagVariants) {
// do something useful
console.log(flags) // ["new-beta-feature", "checkout-button-color"]
console.log(flagVariants) // { "new-beta-feature": true, "checkout-button-color": "black" }

Note that getFlags() and the callback argument flags will include the key names of all truthy feature flags, including active multivariate feature flags.

Querying data by multivariate feature flag values

With the latest version of our JS library, we send each feature flag's value as a separate property on every event. This means the values can be used in filters and breakdowns in Insights queries or wherever else you may choose to filter incoming events.

We send the event properties as $feature/your-feature-name, for example $feature/checkout-button-color. Standard (Boolean) flags are captured in this format as well.

For example, if you have a Trends graph of button click events and you'd like to narrow it down to clicks only when the checkout button is blue, apply a filter to your graph series such that $feature/checkout-button-color = blue.

If you'd like to compare all variants for which we have data in one graph, apply a breakdown by $feature/checkout-button-color.


Was this page useful?

Next article

Common questions about feature flags

Why is my feature flag not working? Here's a list of suggestions to troubleshoot your flag: Check the feature flags tab on the persons page for your specific person. If the flag is showing up as disabled here, check the "match evaluation" column to know the reason why. If the flag is showing up as enabled here, the problem lies somewhere in the implementation (your code). Check if you're calling identify() before the flag is called to get to the right person on your website. Check if an ad…

Read next article