unleash.unleash/website/docs/reference/strategy-variants.mdx

---
title: Strategy Variants
---

import VideoContent from '@site/src/components/VideoContent.jsx'

:::note Availability

**Version**: `5.4+` and [SDK compatibility](/reference/sdks#server-side-sdk-compatibility-table).

:::
## Overview

Variants let you expose different versions of a feature to users, for example, as part of A/B and multivariate testing. By defining variants, you can extend a feature flag's payload with additional data. 
Variants are configured within the feature flag's [activation strategies](/reference/activation-strategies).

<VideoContent videoUrls={["https://www.youtube.com/embed/M0oyGHtva0o"]}/>

A variant consists of three components:
-   Name:  unique identifier for the variant within the strategy. Use this to identify the variant in your clients.
-   Weight: The [variant weight](#variant-weight) determines the likelihood of users receiving a specific variant.
-   Optional payload: You can add a payload to deliver more data or context. Define this if you want to return data in addition to the `enabled`/`disabled` value of the flag. The payload has:
    - Type: The format of the data (`string`, `json`, `csv`, or `number`).
    - Value: The data itself, matching the specified type.

![Adding new strategy variants](/img/strategy-variant-creation-form.png)

## Variant weight

The weight of a variant specifies how often it will be assigned to users. Weights are numbers between 0 and 100, with up to one decimal place of precision.

For multiple variants, the total weight must equal 100. Based on the  [weight type](#weight-type), Unleash balances weights automatically.

### Weight type

There are two kinds of variant weight types: variable and fixed. At least one variant must use a variable weight.

- Variable weight: Adjusts automatically based on other variable weights and "unused" weight from fixed variants, if any. This is the default type.
- Fixed weight: Remains constant regardless of other variants.

### Weight calculation example

To calculate what the weight of a variable variant is, Unleash first subtracts the sum of fixed weights from 100 and then distributes the remaining weight evenly among the variable variants.

For instance, if you were to have three variable variants and two fixed variants weighted at 25 and 15 respectively, the process would look like this:
1. Subtract the fixed weight from the total available: 100 - (25 + 15) = 60
2. Divide the remainder by the number of variable variants: 60 / 3 = 20
3. Assign each variable variant the same (rounded to one decimal precision) weight: 20

## Variant payload

Variants can have an associated payload in a JSON, CSV, number, or string format. You can use this to add more context or data to a payload that you can access on the client.

### Variant stickiness

When you have one variant in an activation strategy, stickiness does not matter. In the case of multiple variants, variant stickiness is derived from the stickiness defined on the activation strategy.
[Stickiness](/reference/stickiness) is evaluated based on [context data](/reference/unleash-context) and it ensures that the same user consistently sees the same variant. If no context data is provided, the traffic is spread randomly for each request.

To reassign users to different variants using an existing stickiness parameter, modify the `groupId` of the activation strategy. This provides a different input to the stickiness calculation.

## Configure strategy variants

In the Admin UI, go to the feature flag you'd like to define variants for and do the following:
1. Select the environment you want to configure and click **Add strategy**.
2. Go to the **Variants** tab and click **Add variant**.
3. Enter the variant name and an optional payload.
4. Optionally, click **Add variant** again to add more variants.
5. Toggle **Custom percentage** for [fixed weights](#weight-type), if required.
6. Click **Save strategy**.


## Fallback variant

If no variant matches in the given context or if the flag is disabled, Unleash returns a fallback variant:

```json
{
  "name": "disabled",
  "enabled": false,
  "feature_enabled": false
}
```

## Activation strategy order

Unleash evaluates activation strategies in order. Therefore, when using multiple activation strategies with variants, define your most restrictive activation strategy first, followed by gradually broader activation strategies.

In the following example, we defined a new checkout flow with two activation strategies: one for internal users matching the company email address, and one for all users. We start by defining the internal activation strategy first, as it is more restrictive.
For this strategy, we defined a variant called `internal-sign-up-flow` that returns the string 'Sign up internally' in the payload. For the second strategy, we defined two variants: `new-sign-up-flow` and `old-sign-up-flow`, that return 'Sign up now' and 'Sign up today' strings respectively.

By defining the more restrictive strategy first, we ensure that all internal users get the 'Sign up internally' message, while all other users get a 50-50 split between the 'Sign up now' and 'Sign up today' versions.

![strategy_variants example](/img/strategy-variants-example.png)

## Environment-level variants

[Environment-level variants](./feature-toggle-variants) are deprecated. Use strategy variants instead.