Creating feature flags

Before you can evaluate a feature flag in your application code, you need to create it in PostHog. You need to configure the following for a new flag:

Step 1. Create a new feature flag (required)

To create a new feature flag, navigate to the feature flags tab in PostHog and click the Create feature flag button to create a new flag.

This presents you with a form where you can complete the details of your new flag:

Step 2. Add feature flag key and description (required)

This is the unique key you use in your code to evaluate the feature flag. Some examples of feature flag keys are new-landing-page, betaFeature, or bigger_callout_button.

You will later evaluate the feature flag in your code using expressions like

• posthog.isFeatureEnabled('new-landing-page')
• posthog.getFeatureFlag('betaFeature')

Use a descriptive key that fits your code and is easy to understand. You should also include a description to help you and your team understand the purpose of the feature flag.

Step 3. Choose a feature flag type (required)

In the Served value section, you can configure the type of feature flag you want to create. There are three types of feature flags:

You can select the type of feature flag by toggling between the selectors. Then, configure the payload and release conditions for the flag if applicable.

Payloads

A payload is an additional piece of information sent to your app when a flag is matched for a user. The returned value can be any valid JSON type (object, array, number, string, boolean, or null).

They enable you to configure functionality related to your flag inside PostHog, instead of having to make code changes or redeploy your app.

If you're using remote config flags, you can use payloads to pass configuration values to your application.

Release conditions

This specifies the conditions a user must meet to access the feature flag and receive a value. Release conditions do not apply to remote config flags.

Condition sets are evaluated from top to bottom, and the first condition set that matches will be used. A condition matches when all property filters pass and the target falls within the rollout percentage.

Percentage rollouts are available for all flags. More options depend on your PostHog setup:

• If GeoIP is enabled, you can target based on geographic location.

• If you capture identified events, you can target based on person properties and cohorts.

• If you enabled group analytics, you can target based on group properties.

Advanced release conditions

For more sophisticated feature rollouts, you can also create feature flag dependencies where one flag's activation depends on another flag's state. This enables complex scenarios like:

• Enabling features only for users in beta programs
• Creating conditional experiments based on other feature participation
• Setting up safety mechanisms where critical flags must be active first

Learn more about feature flag dependencies.

Step 4. Configure feature flag behavior (optional)

These are some optional toggles for feature flag behavior. This section describes what they do and their default values.

Enable feature flag (optional)

Default: Enabled

This determines whether your flag is enabled on creation. Disabled flags return undefined or null when evaluated. You can always re-enable or disable the flag later.

Create usage dashboard (optional)

Default: Enabled

Automatically track how often this flag is called and what values are returned. Creates a dashboard with call volume trends and variant distribution insights.

Persisting feature flags across authentication steps (optional)

Default: Disabled

Note: This is only relevant if your feature flag is shown to both logged out AND logged in users.

Feature flag values are calculated based on a user's properties. Since it's possible for a user to have different properties before and after login, they may receive different feature flag values before and after logging in.

By enabling the option to persist feature flags across authentication, you ensure that the flag value remains the same.

Note: This feature requires person_profiles: 'always' and calling posthog.identify from the JavaScript Web SDK to function as expected. Learn more about anonymous vs identified events here.

In our experience, the tradeoffs to enabling this are not worthwhile for the majority of our users. They include:

1. Slower feature flag response: Enabling this option introduces additional checks, which can slow down the response time when fetching feature flags.
2. Incompatible with local evaluation: It is necessary to perform the additional checks on the PostHog servers.
3. Incompatible with bootstrapping: Bootstrapping relies on local evaluation, which cannot correctly calculate persistent flag values.

Step 5. Configure evaluation runtime and environments (optional)

You can control where your feature flags are evaluated using the evaluation runtime and tags (evaluation environments) sections of the form. You can find a detailed explanation of how evaluation environments work in the evaluation environments documentation.

Evaluation runtime (optional)

Default: Both client and server

By default, feature flags will be evaluated in all (both client and server) environments.

Feature flags can be configured to evaluate in one of three runtime environments:

The system then filters which flags are returned based on their configured runtime, ensuring:

• Smaller payload sizes for client applications
• Reduced evaluation latency by eliminating irrelevant flags
• Prevention of feature flag bloat and better organization by environment
• Better security by keeping server-only flags away from client environments

If you're not sure which runtime to use, you can use the following guidelines:

1. Use server-only evaluation for:

   • Sensitive feature rollouts that shouldn't be exposed to clients
   • Backend system configurations
   • Internal features or admin capabilities

2. Use client-only evaluation for:

   • UI/UX experiments
   • Frontend-specific features
   • Visual changes that don't require backend logic

3. Use "All" (default) for:

   • Features that span both frontend and backend
   • Gradual rollouts that need consistent behavior across environments
   • When you're unsure or need maximum flexibility

Tags and evaluation environments (optional)

Tags are a way to categorize your feature flags. Use them to describe when/where the flag is used in your application. Some common examples are:

• Application type (e.g., "main-app", "marketing-site", "docs")
• Platform (e.g., "web", "mobile", "api")
• Product area (e.g., "checkout", "onboarding", "admin")

When evaluation environments are configured, the feature flag will only evaluate when the SDK provides matching evaluation environments in the /flags request.

You can use tags to accomplish:

• Environment isolation: Prevent flags from evaluating in unintended environments (e.g., marketing site vs. app vs. docs)
• Cost optimization: Reduce unnecessary flag evaluations and associated costs
• Better organization: Group flags by their intended usage context
• Backward compatible: Flags without evaluation environments continue to work as before
• Prevent bloat: Reduce unnecessary flag evaluations by only sending relevant flags to each environment

We recommend reading the evaluation environments documentation in detail before using it in production.