Setting Up PostHog Feature Flags for Experiment Variants

Overview

How It Works

Step-by-Step

1. Step 1: Define Your Flag Key and Variant Keys

   Before you open PostHog, decide on your naming convention. The flag key is a machine-readable string that will appear in your code, your experiment configuration, and your analytics. Use a pattern like experiment-[feature]-[date], for example experiment-onboarding-wizard-2024-06. This key must be unique across your project.

   Next, decide your variant keys. For a simple A/B test, use control and test. For A/B/N tests with multiple treatments, use descriptive keys like control, short-wizard, and long-wizard. Write down each variant key and a one-sentence description of what the user will experience in that variant.

   This document becomes your experiment's source of truth and should be shared with anyone who touches the codebase or reviews results.

   Tip: Avoid generic flag keys like `test-1` or `new-feature`. When you have 30 flags in your project six months from now, descriptive keys save hours of debugging. Include a date or sprint identifier so you can quickly identify stale flags during cleanup.

2. Step 2: Create the Feature Flag in PostHog

   Navigate to the Feature Flags section in your PostHog project dashboard. Click "New feature flag" and enter your flag key exactly as you defined it in step 1. Capitalization and hyphens matter because your code will reference this string. " Boolean flags only support on/off, which technically works for two-variant experiments, but multivariate flags give you named variant keys that are more readable in code and more extensible if you add variants later.

   Add each variant key you defined, then set the description field to match your one-sentence variant descriptions. Save the flag but do not enable it yet.

   Tip: PostHog also lets you create flags automatically when you create an experiment in the Experiments tab. If you prefer that workflow, the experiment creator will generate the flag for you. However, creating the flag manually first gives you more control over release conditions and payloads, which is worth doing for complex experiments.

3. Step 3: Set Rollout Percentages for Each Variant

   With your multivariate flag open, set the rollout percentage for each variant. For a standard A/B test, set both control and test to 50%. PostHog's interface shows a visual bar that confirms the percentages sum to 100%. If you are running a riskier change, such as a new payment flow, consider starting with a 90/10 split where 90% of users see the control and only 10% see the test.

   This limits blast radius but requires significantly more traffic to reach significance, so plan your experiment timeline accordingly. For A/B/N tests with three or more variants, divide traffic as evenly as possible. A three-variant test at 33/33/34 is fine. Avoid allocating less than 10% to any single variant, because the small sample size makes that variant's results unreliable.

   Tip: If your experiment's minimum detectable effect (MDE) requires 5,000 users per variant, a 50/50 split needs 10,000 total users. Changing to 80/20 means you need 25,000 users to get 5,000 in the smaller bucket. Always calculate sample size before deciding on an unequal split.

4. Step 4: Configure Release Conditions to Target the Right Segment

   Release conditions determine which users are eligible for the experiment. Click "Add release condition" to define property-based filters. For an onboarding experiment targeting new users, you might filter on a person property like signed_up_after greater than your experiment start date, or account_age_days less than 7. You can combine multiple conditions with AND logic, for example plan equals free AND country equals US.

   Each condition evaluates against PostHog person properties, so confirm that your tracking code sets these properties before the feature flag is evaluated on the client side. If the property does not exist for a user, the condition will not match, and that user will be excluded from the experiment. Test a few known user profiles in PostHog's person view to confirm their properties match your release conditions before proceeding.

   Tip: A common pitfall is setting release conditions based on properties that arrive asynchronously. If your flag evaluates on page load but the `plan` property is set by a server-side event that fires 2 seconds later, the flag will return the default value (no variant) for those 2 seconds. Use PostHog's `posthog.onFeatureFlags` callback to wait for flag evaluation to complete before rendering.

5. Step 5: Add Payloads for Variant-Specific Configuration (Optional)

   If your variants differ by more than just showing or hiding a component, attach JSON payloads to each variant. Open the payload editor for each variant key and enter a JSON object. For example, the control variant might have {"wizard_steps": 5, "show_video": true} while the test variant has {"wizard_steps": 3, "show_video": false}. Your application code retrieves the payload along with the variant assignment, so you can pass these values directly to your component props or configuration.

   This approach keeps variant configuration centralized in PostHog instead of buried in conditional branches across your codebase. Payloads are especially useful for multivariate tests where each variant tweaks several parameters, because the alternative is a growing chain of if-else blocks. Keep payloads small and flat. Nested objects work but are harder to update and debug.

   Tip: Payloads are returned as strings by some SDKs, so remember to parse them with JSON.parse() in JavaScript or the equivalent in your language. Test that your parsing handles edge cases like empty payloads or malformed JSON gracefully.

6. Step 6: Implement the Flag in Your Application Code

   In your application, use the PostHog SDK to evaluate the flag and render the appropriate experience. , 'control' or 'test') or undefined if the user does not match release conditions. Use a switch statement or if-else block to render the correct component for each variant. getFeatureFlagPayload('experiment-onboarding-wizard-2024-06')` to retrieve the JSON payload for the assigned variant.

   For server-side evaluation (Python, Node, Ruby, Go), use the corresponding SDK method and pass the user's distinct ID explicitly. Wrap your variant rendering in a loading state or fallback that handles the brief period before flags are evaluated, so users never see a flash of the wrong variant.

   Tip: In React, create a reusable hook like `useExperimentVariant(flagKey)` that returns `{ variant, payload, isLoading }`. This pattern prevents scattered flag evaluation calls and makes it trivial to add new experiments. It also centralizes the loading state so you can show a skeleton screen instead of the default experience during evaluation.

7. Step 7: Verify Flag Assignment with PostHog's Feature Flag Debugger

   Before enabling the flag for real traffic, verify that it works correctly. PostHog offers a feature flag debugger in the toolbar (if you have the PostHog toolbar enabled on your site) and in the person detail view. Navigate to the persons section, find a test user (or use your own distinct ID), and check which variant they are assigned to. Confirm that the variant matches what you expect based on the rollout percentage and release conditions.

   Also verify using multiple distinct IDs to ensure that different users get different variants. If every test user gets the same variant, your release conditions may be too restrictive, or your rollout percentages may be misconfigured. Check the flag evaluation log for any errors. Additionally, test that a user who does not match your release conditions gets undefined or false and sees the default experience, not one of the variants.

   Tip: Create 3-5 test persons in PostHog with different property combinations: one that matches all release conditions, one that matches none, one that matches partially. This matrix ensures your conditions work correctly at the boundaries, not just in the happy path.

8. Step 8: Enable the Flag and Confirm Live Traffic

   Once verification passes, enable the flag by toggling it on in the PostHog dashboard. Monitor the Events tab and filter for the $feature_flag_called event, which PostHog automatically emits when your code evaluates the flag. Within the first few minutes (depending on your traffic), you should see this event appearing with the flag key and variant properties. Check the distribution of variants across events.

   With a 50/50 split and enough events (at least 50-100), you should see a roughly equal distribution. If one variant dominates, revisit your release conditions and rollout percentages. , onboarding_completed, first_action_taken) are firing and include the feature flag property so PostHog can attribute them to variants in the experiment results.

   Tip: If you see zero `$feature_flag_called` events after enabling the flag, the most common cause is a deployment gap. Your application code referencing the flag may not be deployed yet, or the PostHog snippet may be cached. Clear caches and verify that the code path referencing the flag is reachable by real users.

9. Step 9: Connect the Flag to a PostHog Experiment

   With the flag live and traffic flowing, go to the Experiments section in PostHog and create a new experiment. When prompted for a feature flag, select your existing flag from the dropdown rather than creating a new one. PostHog will automatically pull in the variant keys and rollout percentages. Define your goal metric (the event that represents success) and any secondary metrics.

   Set the experiment's minimum sample size or duration based on your power analysis. Launch the experiment. PostHog will now track variant assignment alongside your goal events and compute statistical significance using either Bayesian or frequentist methods, depending on your project settings. From this point, the experiment is running and you should not modify the flag configuration until the experiment concludes.

   Any changes to rollout percentages, release conditions, or variant keys during the experiment will invalidate your results.

   Tip: If you accidentally created the flag through the Experiments tab earlier and also created one manually, you may have duplicate flags. Delete the unused one immediately. Two flags with similar keys is a recipe for confusion, especially if a developer references the wrong key in code.

Examples

Best Practices

• Use a consistent naming convention for all experiment flag keys across your team. A pattern like experiment-[area]-[change]-[YYYY-MM] (e.g., experiment-onboarding-cta-2024-06) makes it possible to search, filter, and audit flags months later. Without a convention, flag proliferation quickly becomes unmanageable and stale flags accumulate in production code.

• Always test your feature flag with multiple distinct IDs before enabling it for production traffic. A single test only confirms one code path. You need to verify that different users land in different variants, that users outside your release conditions are excluded, and that edge cases like anonymous users or users with missing properties behave as expected. Skipping this step means discovering assignment bugs after polluted data has already flowed into your experiment.

• Set release conditions based on properties that are available synchronously at flag evaluation time. If a property is set by an asynchronous event (a server-side API call, a webhook, a delayed identification call), the flag may evaluate before the property exists, causing the user to be excluded or assigned incorrectly. Audit the timing of property assignment relative to flag evaluation in your application's initialization flow.

• Document the mapping between each variant key and the user-visible experience in a shared location (experiment brief, ticket, or README). When a developer sees variant === 'test' in code, they should be able to look up exactly what 'test' means without reading through rendering logic. This documentation also helps experiment reviewers interpret results correctly, because "test" tells you nothing about what changed.

• Keep the total number of active experiment flags under 10 at any given time. Each active flag adds a conditional branch to your codebase, increases the surface area for interactions between experiments, and makes debugging harder. If two experiments affect the same user flow, their flags can interact in unexpected ways, producing results that are valid for neither experiment. Prioritize experiments and run them sequentially on the same surface rather than concurrently.

• Never modify a flag's rollout percentages or release conditions while an experiment is running. Changing the allocation mid-experiment introduces a temporal confound: users assigned before the change are a different population than users assigned after. PostHog cannot distinguish between these groups in its analysis, so your results will reflect a blended effect that misrepresents both the pre-change and post-change experiences.

• Use PostHog's $feature_flag_called auto-capture event as a health check during the first hours after launch. Filter events by flag key and check that the variant distribution matches your configured percentages within a reasonable margin. A 50/50 split should show roughly 45-55% per variant in the first few hundred events. Significant deviation (e.g., 70/30) indicates a configuration or targeting problem that should be investigated immediately before more data is collected.

• Plan for flag cleanup at experiment creation time, not after. Add a calendar reminder or ticket for the expected experiment end date. When the experiment concludes, remove the flag evaluation from your code, delete the flag in PostHog, and deploy. Orphaned flags are technical debt. The sibling skill on shipping winning variants and cleaning up flags covers this process in detail.

Common Mistakes

Frequently Asked Questions