Choose a flag type and variants
Pick the type that matches what your code needs, and define variants when a flag must serve more than on or off.
- Time
- About 8 min
- Who can do it
- Product manager, Developer, Release manager or Admin to define variants. Release manager or Admin to change a live value in production.
- Where
- New Flag, then the flag's Variants and Targeting & rollout tabs
- You finish with
- A flag that serves the right kind of value, with each environment choosing who gets which variant
What and why#
What it is#
Every flag answers a question for one person at a time. A Boolean flag answers yes or no. The other three types answer with a value your code can use directly: a text, a number or a small object. Each possible value is a variant with its own key.
When to use variants#
- Compare two or more versions of something, such as a checkout layout, and measure which one converts better.
- Control a setting without a deploy: a page size, a timeout or a rate limit as a Number, or a block of settings as JSON.
- Keep Boolean for anything that is simply on or off. It is the default, needs no variants and is the easiest to clean up.
How it works#
Variants are defined once per flag. Each environment then decides two things: which variant people get when the flag is off, and how people are split between variants (weights that add up to 100) when it is on. A person always lands on the same variant for the same flag.
Before you start#
- Know what your code will do with the answer: switch a feature, pick a text, set a number or read a small object.
- The type is chosen when you create the flag and cannot change, so decide first. If you chose wrong, create a new flag.
- Permission:
flags.createto create,flags.updateto edit variants, androllouts.updateto change an environment's split. In a production environment, Developers and Product managers cannot change the split.
The four types#
| Type | Variants | Description |
|---|---|---|
| Boolean | none | On or off. The default, and the right choice for most flags. |
| String | 2 to 20 | Serves a text value, such as a layout name or a button label. Up to 16,384 characters. |
| Number | 2 to 20 | Serves a finite number, such as a limit or a timeout. |
| JSON | 2 to 20 | Serves an object or an array, such as a set of settings, up to 16,384 characters once serialized. A plain string, number or null is refused. |
Walk through it#
Choose the type
Open New Flag. In the Create Flag form, set Type. For anything other than Boolean, a Variants section appears with two starting rows named
controlandtreatment. The hint under Type reads: “Serves a value. Define the variants below; each environment decides who gets which.”Define the variants
Each variant row has these fields. Choose Add variant for more and the remove button on a row to delete one.
Variant fields Field Limit Description Key required, 50 Lower case letters, numbers, hyphens and underscores, with no leading, trailing or doubled separators. Unique within the flag. What SDKs and rules refer to. Label (optional) 80 A friendlier name for the console. The placeholder reads Shown in the console. Value required Typed by the flag: text for String, a finite number for Number, and valid JSON (an object or array) for JSON. A flag needs at least 2 variants and can have up to 20. Create Flag stays disabled until every key and value is valid.
Variant rows for a Number flag. Each row has Key, Label (optional) and Value, and Number values must be finite numbers. Row errors appear under the field:
Key is required,Lowercase letters, numbers, hyphens and underscores only,Key is used twice,Value is required,Enter a valid number,Enter valid JSONandEnter a JSON object or array. A list problem readsAdd at least 2 variantsorAt most 20 variants. Switching Type resets the rows to two fresh starting rows (Number starts at 0 and 1, JSON at empty objects).You should see. The flag opens with a Variants tab next to Overview. Boolean flags never show it.Decide what each environment serves
Open the Targeting & rollout tab and pick an environment. Step 6, Variants, has two controls. Served when the flag is off picks the variant for people the flag is not on for (it is also served when the kill switch is active). Next to each variant, a Weight from 0 to 100 sets how people are split when the flag is on. The total shows under the list and must be exactly 100. Choose Save changes.
A new flag serves its first variant at 100% everywhere, and the first variant is the off variant. When you add a variant later, it starts at weight 0.
Step 6, Variants, for one environment: the off variant and a weight per variant. You should see. The total reads Total 100% and Save changes is enabled. Use Check who gets this flag with a test identifier to see the variant chosen.Edit variants later
On the Variants tab, change labels and values, add variants, then choose Save variants (or Discard). Saved keys are locked and cannot be renamed. A variant that any environment still serves, by weight or as its off variant, cannot be removed until you move its traffic to another variant.
Read the variant in code
The client evaluation response carries the variant for multivariate flags. Check it with one request, or use an SDK.
bash curl -s "https://flags.example.com/api/v1/evaluation/client?user_identifier=user-123" \ -H "Authorization: Bearer $KEY"200 OK { "environment": "development", "hashVersion": 1, "version": "f1c2", "flags": { "new-dashboard": { "enabled": true, "version": 2 }, "checkout-layout": { "enabled": true, "variant": "compact", "value": "compact", "version": 3 } } }Each flag has
enabledand, for a flag with variants,variantandvalue. SDKs offer calls such asgetVariantandgetValuefor this. Always pass a fallback value, because a flag check never throws.
Changing a saved value is live everywhere
rollouts.update in production) for a value change or a removal. Developers and Product managers are refused; Release managers and Admins are not.Do it with the API#
These are Dashboard API calls that use your session cookie and return the usual { status, message, data } envelope.
Replace the variants and set an environment's split
Sending the variant list replaces it: whatever you leave out is removed, subject to the rules above. The response is trimmed here. Variants are set at creation with the variants field of POST /api/flags. See the Flags API and Rollouts API.
# Replace the whole variant list (flags.update)
curl -X PUT "https://flags.example.com/api/flags/FLAG_ID/variants" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"variants":[
{"key":"classic","name":"Classic layout","value":"classic"},
{"key":"compact","name":"Compact layout","value":"compact"}
]}'
# Split people 50/50 in development (rollouts.update)
curl -X PATCH "https://flags.example.com/api/flags/FLAG_ID/environments/development" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"offVariant":"classic","allocation":{"classic":50,"compact":50}}'{
"status": "success",
"message": "Environment updated successfully",
"data": {
"id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
"name": "checkout-layout",
"type": "string",
"variants": [
{ "key": "classic", "name": "Classic layout", "value": "classic" },
{ "key": "compact", "name": "Compact layout", "value": "compact" }
],
"environments": {
"development": { "enabled": true, "offVariant": "classic", "allocation": { "classic": 50, "compact": 50 }, "version": 4 }
}
}
}What to check#
- The Variants tab appears on the flag, and only for non-boolean flags.
- The response shows the variant you expect for a test person, and the same person gets the same variant on the next request.
- The weights for each environment add up to 100.
Good to know#
Prefer Boolean when you can
Can I turn a Boolean flag into a String flag?
What does a person get when the flag is off?
Why can I not rename a variant key?
How do variants relate to rollout percentage?
If something goes wrong#
A string flag needs at least 2 variants
Why: Non-boolean flags must have 2 to 20 variants. The server answers 400 with this message (with your type in it).
Fix: Add another variant, or choose Boolean if you only need on and off.
Variant "x" needs a valid json value, or Enter a JSON object or array
Why: A JSON variant must be an object or array. A bare string, number or null is refused, as is invalid JSON or text over 16,384 characters.
Fix: Wrap the value, for example {"limit": 10}.
Allocation must add up to 100%
Why: The weights for the environment do not total 100, within two decimals.
Fix: Adjust the weights until the total under the list reads 100%.
Variant "x" is still served in production. Move its traffic to another variant first
Why: An environment still gives that variant a weight above 0 or uses it as the off variant (a 409).
Fix: Set its weight to 0 in each named environment, change the off variant if needed, save, then remove it.
Variant changes are refused in production
Why: Changing a value or removing a variant needs production write access, which Developers and Product managers do not have.
Fix: Ask a Release manager or Admin to make the change.