Dropdowns and menus

A Dropdown is a value control like a select field in a browser form: in preview a click opens a list of options, and the option the viewer picks becomes the instance's value. A Menu is a button that opens a list of commands: picking one runs its Pick event, and nothing of the choice is kept. Also called: select, popup menu, menu button. A list the viewer filters by typing, a combobox, is not one of them.

Both are component behaviors (→ Component behavior). Their items are instances of a second component set, with the Option behavior for a Dropdown and the Menu item behavior for a Menu, listed by a Repeater from an array.

Building a dropdown or a menu

1. Draw one item, a frame with a text in it, and give its set the Option behavior (Menu item for a menu). Bind the text's content to the built-in Label input.
2. Draw the closed trigger and give its set the Dropdown behavior (or Menu).
3. Add an Array input to the trigger's set, for example Options, holding the items (→ Array inputs).
4. In the header, use Add state to create the open states: :open, and for a Dropdown also :placeholder and :placeholder:open.
5. In each open state, draw a frame named LIST where the list should appear, outside the trigger's own box, and turn it into a Repeater of the item component (→ Making a Repeater). Bind its items to the Array input.

• LIST is written in capitals. It may be the Repeater itself, or a frame holding the Repeater beside a header or a footer.
• Only the open states hold a LIST. A closed state with one, an open state without one or with two, and a set missing any of its required states are listed in the Validation console, and while any of them is listed the instances don't open in preview (→ Validation console).
• When LIST sits in a Flex or Grid frame, turn on Use absolute positioning for it, so that opening never moves the trigger's own layers.
• Items come only from Repeaters in LIST: an Option or Menu item instance placed there by hand is listed in the Validation console and does nothing. A Repeater lists at most 100 items.

The items

Each item of the array is one item of the list. The Option and Menu item behaviors add these built-in inputs to the item's set, which the Repeater fills from the item's fields of the same names (→ The Repeater section):

Input	Field	What it is
Option value	value	The value a Dropdown takes when the option is picked. Options only.
Label	label	The text the item shows, and what typing a letter jumps to.
Disabled	disabled	A disabled item shows :disabled and can't be focused or picked.
Kind	kind	Empty for an item, separator or heading for one that only divides or titles.

[{ "kind": "heading", "label": "Sizes" }, { "value": "s", "label": "Small" }, { "value": "m", "label": "Medium" }, { "kind": "separator" }, { "value": "custom", "label": "Custom…", "disabled": true }]

• An array of plain strings, ["Small", "Medium", "Large"], fills both Option value and Label with each string.
• Draw the look of a separator and a heading as states of the item set: :separator and :heading. They are never focused, picked or selected.
• A Kind other than empty, separator or heading counts as an ordinary item and is reported.

States

Behavior	Required states	Also shown
Dropdown	Default, :open, :placeholder, :placeholder:open	:hover, :focus
Menu	Default, :open	:hover, :focus
Option	Default	:selected, :disabled, :separator, :heading, :focus
Menu item	Default	:disabled, :separator, :heading, :focus

• A Dropdown shows :placeholder while none of its options holds its Selected value, and Default while one does.
• :open shows while the list is open, and the list exists only there. It switches instantly, without a transition.
• On the trigger, :focus shows keyboard focus only. On an item, :focus marks the one item the pointer and the arrow keys point at.
• An Option shows :selected while its Option value is the Dropdown's Selected value, on the canvas too.

Selected value, Selected label and Placeholder text

Choosing Dropdown adds three built-in String inputs:

• Selected value holds the value of the chosen option. Bind it to a String or Number variable, and picking an option writes the variable (→ Two-way binding on controls).
• Selected label holds the Label of the option whose value is the Selected value, and is empty while none is. Bind the trigger's text to it. It can't be set: it follows the options, closed or open, on the canvas and in preview.
• Placeholder text (Select… by default) is for the text the :placeholder states show.

A Menu adds no inputs of its own.

In preview

• The list opens above everything, open modals included, at the place you drew it relative to the trigger, and nothing around the trigger clips it. Where it would leave the preview, it flips to the other side of the trigger, or scrolls when it fits on neither side.
• One list is open at a time. A list closes when its trigger moves out of view, or out of a frame that clips its content.
• A click on the trigger opens and closes the list. A click on an item picks it and closes the list. A click anywhere else closes the list and does nothing else.
• Hovering an item focuses it. Hovering a separator, a heading or a disabled item, or moving the pointer out of the list, leaves no item focused, and ↓ then starts again from the first item.

Key	With the trigger focused	With the list open
Enter, Space, ↓, ↑	Opens the list	Enter and Space pick the focused item; ↓ and ↑ move the focus
Home, End	—	Focus the first and the last enabled item
A letter	—	Focuses the next item whose Label starts with the letters typed
Escape	—	Closes the list
Tab	—	Closes the list and moves on

• On opening, a Dropdown focuses its selected option, unless that option is disabled. Otherwise, a list opened by key focuses its first enabled item.
• In a Menu, ↓ on the last item wraps to the first; in a Dropdown it stops.
• Letters typed in quick succession are read as one word, a space among them included: new j focuses New Jersey over New York. The same letter typed again moves on to the next item starting with it. Once typing pauses, Space picks again.
• An instance you placed in an :open state on the canvas still starts closed in preview.

The Pick event

Where: select an instance of a Dropdown or Menu set → Interactions → Add event → Pick.

Pick runs when the viewer picks an item. On a Dropdown it runs after the pick has become the Selected value, also when the viewer picks the option that was already selected. Its expressions read the picked item as $event.item and its position in the array as $event.index (→ Pick).

• A menu of commands handles each one with a Conditional on $event.item.value.
• Inside a component, an Emit Event in the Pick handler passes $event on, so a card's menu reports the picked command to the Repeater listing the cards (→ Component events).