Select

Select is a compound consisting of a select field and Listbox. It allows users to select one or more options.

Listbox

The below documentation is about listboxes. A listbox displays a list of selections on an elevated surface. It is triggered by a select. Seeselectdesign for details.

1. Anatomy

The listbox component is broken down into listbox items and listbox groups to make the complexity and flexibility manageable.

1.1 Listbox

Aria attributes

See Listbox on W3 for more details

Value	Purpose
role= “listbox”	Indicates the role of the listbox
aria-expanded	Indicates whether the container controlled by the disclosure button is visible.
aria-current	Indicates that the page referenced by the link is currently displayed.
aria-label	Shows the name of the listbox.
aria-controls	Labels the name of the listbox associated with the input.

1.2 List item

Aria attributes

See option(role) on W3 for more details

Value	Purpose
role= “option”	Defines the option role.
aria-selected	Indicates the selection state.
aria-posinset	Places the position in the set.
aria-setsize	Shows the total number of items in the listbox.
aria-controls	Labels the name of the listbox associated with the input.

2. Configurations

2.1 Listbox type

There are two types of menu: single-select and multi-select. They have different interactivity and behavior.See 3. Behavior for details.

2.2 Listbox grouping

Grouping introduces a header and top divider to separate one from another. You can intentionally turn off the header or divider.

2.3 List item

Menu item is a smaller unit within the menu. It has 3 attributes that designers can customize the component: subtext, tags, and prefix. For prefix, a designer can choose either an avatar or an icon.

2.4 Width

Enter a value to define the width of the listbox. There is a minimum width of 112px.

2.5 Select-all

Select-all is a model sitting on top of the multi-select listbox that allows users to operate in bulk. It is optional. The default state has no select-all modal.

Please note only multi-select listbox supports this feature.

3. Behavior

3.1 Single select

Users can only click one item at a time. The listbox disappears on click.

3.2 Multi-select

Users can select and unselect a checkbox by clicking on the check or label. Users can dismiss the listbox by clicking on an empty space.

4. States

Listbox has four states: initial, selected, hover and focus.

5. Keyboard experience

5.1 Open a listbox

5.2 Exit the listbox

Below are the options if a user wants to exit the listbox without selecting an option. The same interaction applies to both single and multi-select listbox.