# How Vercel Flags are evaluated

**Author:** Dominik Ferber

---

Vercel Flags lets you control which flag value each user, team, or other entity receives. You can release a feature to your team first, test it in production, and keep the feature off for everyone else until you're ready.

Vercel Flags evaluates a flag by checking the active environment, the supplied evaluation context, direct targets, rules, and fallback outcome.

## Evaluation order

Vercel Flags evaluates each flag in this order:

1. **Environment configuration**: Vercel Flags uses the flag configuration for the current environment.
   
2. **Direct targets**: If the evaluation context matches a directly targeted entity, Vercel Flags returns the assigned option.
   
3. **Rules**: If no direct target matches, Vercel Flags evaluates rules from top to bottom.
   
4. **Fallback outcome**: If no rules match, Vercel Flags returns the fallback outcome configured for the flag.
   

## Environments

Vercel Flags can use different flag behavior for each environment. Production, preview, and development environments share the same flags, but each environment can have its own targeting, rules, and fallback outcomes.

This lets you enable a flag in development while keeping it disabled in preview and production.

For more information, see [Feature Flag Configuration](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag).

## Entities

Vercel Flags requires an explicit evaluation context. An evaluation context is the data your application passes when evaluating a flag, such as the current user, team, account, or workspace.

Vercel Flags includes default entities for users and teams. You can extend these defaults and configure additional entities in the [Entities dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fflags%2Fentities&title=Go+to+Entities).

The entities you configure are used in the flag details UI. The UI adapts to the configured entities and their attributes, so your team can target and display the same context your application passes during evaluation.

## Evaluation context

Advanced configuration requires an evaluation context when your application evaluates a flag. Vercel Flags uses this context to match direct targets, evaluate rules, and calculate split outcomes.

When using the Flags SDK, provide the evaluation context with an `identify` function.

`import { dedupe, flag } from 'flags/next'; import { vercelAdapter } from '@flags-sdk/vercel'; type Entities = { user?: { id: string; email: string; plan: string; }; }; const identify = dedupe(async (): Promise<Entities> => { const session = await getSession(); // Provide attributes based on the current user session return { user: session?.user ? { id: session.user.id, email: session.user.email, plan: session.user.plan, } : undefined, }; }); export const premiumFeature = flag<boolean, Entities>({ key: 'premium-feature', adapter: vercelAdapter(), identify, });`

The `identify` function returns the entity attributes that Vercel Flags uses during evaluation.

Vercel Flags evaluates entities fresh for each flag call. If you don't provide an entity or attribute, rules that target that missing data won't match.

For more information, see [Using the Flags SDK with Vercel Flags](https://vercel.com/docs/flags/vercel-flags/sdks/flags-sdk).

## Targeting

Direct targeting is evaluated before rules. If an entity is targeted directly, Vercel Flags does not evaluate any rules for that flag. The flag returns the option assigned to the targeted entity.

You can assign direct targets to specific variants. You can also add an optional note explaining why the target was assigned to that variant. Notes help teammates understand the reason for the assignment.

## Rules

If no direct target matches, Vercel Flags evaluates rules next. Rules use the entities you configured and the evaluation context your application passed when evaluating the flag.

Rules let you define more detailed targeting logic than direct assignment. Rules can be reordered, but direct targeting always runs before rules.

Rules are evaluated from top to bottom. A rule matches when all of its filters match the evaluation context. Each rule must have at least one filter.

When a rule matches, Vercel Flags returns that rule's outcome and stops evaluating the remaining rules. If no rules match, Vercel Flags returns the fallback outcome configured at the bottom of the flag.

For example, this evaluation context includes a user and team:

`{ "user": { "id": "user_123", "email": "ava@example.com", "plan": "pro" }, "team": { "id": "team_789", "name": "Acme" } }`

Given that context, Vercel Flags evaluates ordered rules like this:

| Order | Rule filter                                                                              | Outcome   | Result                                 |
| ----- | ---------------------------------------------------------------------------------------- | --------- | -------------------------------------- |
| 1     | [`user.email`](http://user.email) ends with [`@yourcompany.com`](http://yourcompany.com) | `enabled` | No match                               |
| 2     | `user.plan` equals `pro`                                                                 | `enabled` | Match. Vercel Flags returns `enabled`. |
| 3     | [`team.id`](http://team.id) equals `team_789`                                            | `beta`    | Not evaluated because rule 2 matched.  |

## Labels

Labels make common entity IDs easier to recognize in the Vercel Flags UI. You can configure labels for common IDs in the [Entities dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fflags%2Fentities&title=Go+to+Entities).

After you add a label, Vercel Flags displays the label instead of the raw ID in relevant parts of the UI. Add labels for commonly used IDs so teammates can understand targeting and rules without looking up each ID.

## Outcomes

An outcome is the value Vercel Flags returns after a target or rule matches. If no target or rule matches, Vercel Flags returns the fallback outcome.

A fixed outcome serves the same option to every user matched to it. Vercel Flags supports boolean, string, and number flags.

## Fixed outcomes

A fixed outcome always returns the same option for every evaluation context that reaches that outcome.

| Evaluation path                        | Fixed outcome | Returned value |
| -------------------------------------- | ------------- | -------------- |
| Direct target for `user_123`           | Enabled       | `true`         |
| Rule matching `user.plan` equals `pro` | Enabled       | `true`         |
| Fallback outcome                       | Disabled      | `false`        |

Use a fixed outcome when everyone who reaches that target, rule, or fallback should receive the same value.

## Weighted split outcomes

A weighted split outcome assigns evaluation contexts to variants based on the attribute you select. For example, if you split by user ID, Vercel Flags uses each user's ID to assign that user to a variant.

Choose an attribute that is unique for the entity being evaluated, such as a user ID or team ID. If the selected attribute is not unique, the split will not distribute evenly.

For example, these two users share the same `plan` value but have different `id` values:

`[{ "user": { "id": "user_123", "plan": "pro" } }, { "user": { "id": "user_456", "plan": "pro" } } ]` If the split is based on [`user.id`](http://user.id), these users can land in different buckets. If the split is based on `user.plan`, both users use the same split input, `pro`, and land in the same bucket.

| Base attribute              | Example values                     | Recommended for splits                               |
| --------------------------- | ---------------------------------- | ---------------------------------------------------- |
| [`user.id`](http://user.id) | `user_123`, `user_456`, `user_789` | Yes. Each user has a distinct value.                 |
| [`team.id`](http://team.id) | `team_123`, `team_456`, `team_789` | Yes, when you want teams to stay in the same bucket. |
| `user.plan`                 | `hobby`, `pro`, `enterprise`       | No. Many users share the same value.                 |

If the selected base attribute is not provided in the evaluation context, Vercel Flags returns the fallback value configured for the split.

[Weighted split outcomes](https://vercel.com/kb/guide/how-splits-work-in-vercel-flags) can be used as the outcome of a rule or as the fallback outcome when no direct targets or rules match.

## Progressive rollout outcomes

A progressive rollout outcome moves evaluation contexts from one variant to another over a configured schedule. For example, you can start with `Off`, roll out `On` to 10% of users, increase to 25% after one hour, then continue until the rollout reaches 100%.

Gradual rollouts are useful when you want Vercel Flags to increase exposure over time without manually editing the rollout percentage at each step.

A progressive rollout has:

- **Base attribute**
  
  The entity attribute used for bucketing, such as [`user.id`](http://user.id) or [`team.id`](http://team.id).
  
- **Starting variant**
  
  The value served before the rollout begins, such as `Off`.
  
- **Target variant**
  
  The value users move toward during the rollout, such as `On`.
  
- **Fallback variant**
  
  The value served if the base attribute is missing or is not a string.
  
- **Schedule**
  
  The percentages and durations Vercel Flags uses to move traffic toward the target variant.
  

For example:

`{ "user": { "id": "user_123", "plan": "pro" } }`

If the rollout is based on [`user.id`](http://user.id), Vercel Flags uses `user_123` to assign the user to a stable rollout bucket. As the rollout percentage increases, users already receiving the target variant stay in that variant, and additional users move from the starting variant to the target variant.

Use a stable, high-cardinality base attribute, such as [`user.id`](http://user.id) or [`team.id`](http://team.id). Avoid low-cardinality attributes such as `user.plan`, because many users share the same value and land in the same rollout bucket.

If the base attribute is missing or is not a string, Vercel Flags returns the fallback variant. Gradual rollout outcomes can be used as the outcome of a rule or as the fallback outcome when no direct targets or rules match.

## Segments

Segments are reusable targeting rules. You can create a segment for a group, such as team members, and reuse that segment across multiple feature flags and rules.

Segments help you maintain targeting logic in one place instead of recreating the same rule in multiple flags.

## 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)
  
- [Using the Flags SDK with Vercel Flags](https://vercel.com/docs/flags/vercel-flags/sdks/flags-sdk)

---

[View full KB sitemap](/kb/sitemap.md)