variant_picker
One choice out of a set that differs by size, colour or capacity.
The thing is chosen; the variant is not. variant_picker asks which size, which colour, which capacity, and nothing else.
It exists because asking in prose wastes a turn. "What size do you wear?" costs a round trip and a typed reply; a row of chips costs one tap, and the copilot already knows which sizes exist.
Re-rendered in the browser from the SDK’s own scales. Not a screenshot.
Rendered natively by the Flutter SDK and the Web SDK, both since 0.1.0.
When not to use it
Do not use it for a choice between different things, which is quick_replies or product_cards: a picker means the options differ by one attribute and nothing else.
Do not use it for a time, which is datetime_slots, and do not use it for several fields at once, which is form.
Props
Every block also carries type and a required fallback_text of 1 to 300 characters.
| Prop | Type | Required | Constraints |
|---|---|---|---|
title | string | No | Up to 120 characters. |
label | string | No | Up to 60 characters. What is being chosen, e.g. "Size". |
options | array | Yes | 2 to 24 entries. |
options[].id | string | Yes | 1 to 64 characters. |
options[].label | string | Yes | 1 to 24 characters. |
options[].available | boolean | No | false draws it faint and unselectable, still on screen. Absent means available. |
options[].action | action | No | { kind: "reply", text } or { kind: "open_url", url }. See Actions. Usually a reply naming the chosen variant. |
selected_id | string | No | Up to 64 characters. Matches an options[].id. |
On the wire
{
"id": "blk_22",
"type": "variant_picker",
"fallback_text": "Sizes 41 to 44, size 43 selected, 44 sold out.",
"props": {
"label": "Size",
"selected_id": "43",
"options": [
{ "id": "41", "label": "41" },
{ "id": "42", "label": "42" },
{ "id": "43", "label": "43" },
{ "id": "44", "label": "44", "available": false }
]
}
}Interaction
Tapping an available option fires its action. An option with available: false has no handler at all, so it dims and does not respond to a press rather than failing after the tap.
States
| State | What the SDK draws |
|---|---|
| Loading | Chips at their real height, so the row does not reflow on hydrate. |
| Selected | The accent fills the chosen chip; its label flips to the on-accent ink. |
| Sold out | Faint ink on a decorative hairline rather than the control boundary, not pressable, still on screen. |
| Empty | Fewer than two options fails validation and degrades to fallback_text. |
Accessibility
Chips are 44pt tall and spaced, so neighbouring sizes are not one mis-tap apart. Selection is announced, not only filled, and a sold-out option announces that it is unavailable before its label, so a reader knows not to bother with the rest of the sentence.
Keep sold-out options in the list. A reader who cannot find their size learns more from a chip they can see is gone than from a list that quietly omits it.