How Splits Work in Vercel Flags

Splits let you serve a feature to a percentage of users while keeping it off for everyone else. You can start with a small percentage, monitor the result, and manually increase the rollout over time.

Splits also support A/B tests. For example, you can serve different variants of a feature to different user groups, then compare conversion rates, performance, or engagement before choosing which variant to ship.

A split divides evaluation contexts into buckets based on a stable attribute, such as a user ID. Each bucket receives a specific flag value.

For example, a 50/50 split for a boolean flag can serve false to half of users and true to the other half.

Because the split uses a consistent attribute, the same user receives the same variant across page loads, sessions, and server instances. This behavior is called sticky bucketing. Sticky bucketing keeps the user's experience stable without requiring a database or session store.

Before configuring a split, define an entity in the Vercel Flags dashboard. Entities represent information your application knows, such as users, teams, devices, or requests.

Each entity includes attributes that Vercel Flags can use for targeting and splits. For example, a User entity might include:

• id (string): A unique identifier for the user
• email (string): The user's email address
• plan (string): The user's account plan

The split uses one entity attribute to decide which bucket an evaluation context belongs to.

1. Open your flag in the Vercel Flags dashboard.
2. Select the environment you want to configure: Production, Preview, or Development.
3. Click the target icon next to the environment to enter targeting mode.

4. Set the fallback outcome to Weighted split.

   At the bottom of the targeting configuration, find When no other rules match, serve, then select a weighted split from the dropdown.

5. Choose the Based on attribute.

   Select the entity attribute Vercel Flags should use for bucketing. For example, select User › id to bucket by user ID.

6. Set the fallback variant.

   Choose which variant Vercel Flags should serve if the selected entity or attribute is not provided during evaluation. For example, if a request has no user ID, the fallback variant determines what value that request receives.

7. Set the weights for each variant.

   For example:

   • Off: 50 and On: 50 create a 50/50 split.
   • Off: 90 and On: 10 serve Off to about 90% of users and On to about 10%.
   • A: 1, B: 1, and C: 1 create an equal three-way split.

8. Save your changes.

   Click Review and save, confirm the affected environments, and optionally add a change message for the activity log.

When your application evaluates a flag with a split, Vercel Flags uses the selected base attribute, the flag seed, and the configured weights to choose a variant.

1. Read the base attribute: Vercel Flags looks up the attribute selected in the Based on field, such as User › id, from the evaluation context.
2. Hash the attribute value: Vercel Flags hashes the string value with xxHash32. The hash is seeded per flag, so the same user can land in different buckets for different flags. This helps avoid correlated experiments.
3. Map the hash to the weight ranges: The hash produces a number between 0 and 4,294,967,295. Vercel Flags normalizes your configured weights across that full range. With Off: 50 and On: 50, the first half of the range resolves to Off, and the second half resolves to On.
4. Return the matching variant: Vercel Flags returns the variant whose weight range contains the hash. If the base attribute is missing or is not a string, Vercel Flags returns the fallback variant configured for the split.

Because hashing is deterministic, the same input produces the same output. A user with the same user ID keeps the same split assignment until you change the split configuration.

For example, Vercel Flags can bucket this evaluation context by user.id:

{
  "user": {
    "id": "user_123",
    "email": "ava@example.com",
    "plan": "pro"
  }
}

If the split is based on user.id, Vercel Flags hashes user_123 and maps that hash to one of the configured weight ranges.

Choose an attribute with high cardinality and persistence. High cardinality means the attribute has many distinct values. Persistence means the value stays stable for the same user, team, device, or request over time.

A user ID is a good split attribute because each user has a distinct value. When Vercel Flags hashes many distinct values, those values distribute across the configured weight ranges.

Do not split on a low-cardinality attribute such as plan when the possible values are hobby, pro, and enterprise. Low-cardinality attributes produce only a few distinct hash inputs.

For example, these users have different IDs but the same plan:

[
  {
    "user": {
      "id": "user_123",
      "plan": "pro"
    }
  },
  {
    "user": {
      "id": "user_456",
      "plan": "pro"
    }
  }
]

If the split is based on user.id, each user can land in a different bucket. If the split is based on user.plan, both users use the same split input, pro, and land in the same bucket.

Use low-cardinality attributes in targeting rules instead. For example, create a rule for user.plan equals pro, then use a split as that rule's outcome if you want to run an experiment only for Pro users.

Vercel Flags maps each hash to a fixed point in the full hash range. When you change weights, the boundaries between variant ranges move. Some users may move from one variant to another.

For a two-variant rollout, you can grow the On variant by shrinking the Off variant. For example, changing from 50/50 to 30/70 moves the boundary between Off and On:

Before: |---------- Off 0-50% ----------|---------- On 50-100% ----------|
After:  |------ Off 0-30% ------|-------------- On 30-100% --------------|

In this example:

• Users with hashes in the 0-30% range stay in Off.
• Users with hashes in the 30-50% range move from Off to On.
• Users with hashes in the 50-100% range stay in On.

This makes splits useful for gradual rollouts. When you increase the On weight in this common two-variant pattern, users who already had the feature stay in the On variant, and additional users are added from the shrinking Off range.

You can use Splits in two places within a flag configuration:

• As the outcome of a targeting rule: A rule can serve a weighted split instead of a fixed variant. For example, you can match users on the Enterprise plan and split only those users 50/50 between two variants.
• As the fallback outcome: The When no other rules match, serve outcome can also be a weighted split. This catches every evaluation context that did not match a direct target or rule.

Vercel Flags evaluates flag configuration in this order:

1. Vercel Flags evaluates direct targets first. You can pin specific users, such as your QA team, to a particular variant.
2. Vercel Flags evaluates rules next, from top to bottom. Each rule can serve either a fixed variant or a weighted split.
3. The fallback outcome catches everyone else. The fallback can serve either a fixed variant or a weighted split.

This lets you run different experiments for different audiences. For example, you can run a 50/50 split for Enterprise users through a rule and a 90/10 gradual rollout for everyone else through the fallback outcome.

Use a 50/50 split between two variants, such as control and test. Then use Vercel Web Analytics or your own analytics platform to compare conversion rates, performance, or engagement for each group.

Use a progressive rollout to increase exposure automatically over time. Start with a small percentage, such as 10% On and 90% Off, then define stages such as 25%, 50%, 75%, and 100%.

Vercel Flags advances through the rollout schedule you configure, so you do not need to update the percentage manually at each stage. Monitor errors, regressions, and product metrics during the rollout, and stop the rollout if the target variant causes issues.

Use string, number, or JSON flag values to test more than two variants at once. Configure three or more variants with equal or custom weights to test designs, copy changes, configuration values, or model settings.

• Flag value types matter. Vercel Flags supports boolean, string, number, and JSON values. Boolean flags are useful for on/off rollouts, while string, number, and JSON flags are useful for multi-variant experiments.
• Weights are relative. Values of 1, 1, 1 and 33, 33, 34 both produce a roughly equal three-way split.
• The fallback variant is critical. If the selected entity attribute is missing or is not a string, Vercel Flags serves the fallback variant. Choose a fallback that is safe for unauthenticated users and incomplete evaluation contexts.
• Changes propagate globally. Vercel Flags configurations use active global replication, so weight changes take effect worldwide in milliseconds.
• Splits are per environment. You can run a 50/50 split in Production while keeping the flag fully enabled in Preview and Development.

• Vercel Flags
• Feature Flag Configuration
• Entities
• Segments
• Running an A/B test
• Vercel Flags now supports JSON values