---
title: How Splits Work in Vercel Flags
description: Use weighted splits in Vercel Flags to deterministically bucket users into variants by percentage for gradual rollouts and A/B testing
url: /kb/guide/how-splits-work-in-vercel-flags
canonical_url: "https://vercel.com/kb/guide/how-splits-work-in-vercel-flags"
last_updated: 2026-06-17
authors: Dominik Ferber
related:
  - /docs/analytics
  - /docs/flags/vercel-flags/dashboard/feature-flag
  - /docs/flags/vercel-flags
  - /docs/flags/vercel-flags/dashboard/entities
  - /docs/flags/vercel-flags/dashboard/segments
  - /docs/flags/vercel-flags/cli/run-ab-test
  - /changelog/vercel-flags-now-supports-json-values
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

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.

## What is a split?

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.

## Prerequisites

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.

## Configure a split

1. Open your flag in the [Vercel Flags dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fflags&title=Open+Vercel+Flags).
   
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.
   

## How bucketing works

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 the right attribute to split on

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`](http://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.

| Attribute      | Cardinality   | Use for splits                                                        |
| -------------- | ------------- | --------------------------------------------------------------------- |
| `user.id`      | High          | Yes. Each user has a distinct value.                                  |
| `team.id`      | High          | Yes, when all users on the same team should receive the same variant. |
| `device.id`    | High          | Yes, when the experience should stay stable per device.               |
| `user.plan`    | Low           | No. Many users share the same value.                                  |
| `user.country` | Low to medium | Usually no. Use a targeting rule for country-based behavior.          |

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.

## What happens when you change weights

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.

## Combine splits with targeting rules

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.

## Common use cases

### A/B testing

Use a 50/50 split between two variants, such as `control` and `test`. Then use [Vercel Web Analytics](https://vercel.com/docs/analytics) or your own analytics platform to compare conversion rates, performance, or engagement for each group.

### Progressive rollout

Use a [progressive rollout](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag#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.

### Multi-variant experiments

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.

## Important notes

- 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.
  

## Next Steps

- [Vercel Flags](https://vercel.com/docs/flags/vercel-flags)
  
- [Feature Flag Configuration](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag)
  
- [Entities](https://vercel.com/docs/flags/vercel-flags/dashboard/entities)
  
- [Segments](https://vercel.com/docs/flags/vercel-flags/dashboard/segments)
  
- [Running an A/B test](https://vercel.com/docs/flags/vercel-flags/cli/run-ab-test)
  
- [Vercel Flags now supports JSON values](https://vercel.com/changelog/vercel-flags-now-supports-json-values)