Combo box

ComboBox helps users to select an item from a large list of options without scrolling. The typeahead functionality makes this selection process quicker, easier and reduces errors. Users can see a list of available options when they click on the component and then filter the list as they type. Once they’ve made their selection, it populates the field and the overlay list closes.

Also known as: Typeahead, Editable Dropdown, List Box, Autocomplete, Autosuggest

View source code

Note: This tab list includes overflow; tab positions may be inaccurate or change when a tab is selected

Keyboard interactions

Key	Function
`Tab`	If the combo box is single-select and if focus is above the combo box, Tab sets focus on the component. When focused, combo box has a visible text cursor and the list is opened. If the combo box is multi-select and if the focus is above the combo box, Tab sets focus on the pill list if pills are present. If no pills are present then focus is set on the input. If the list is open, Tab moves focus to the next focusable element in the tab order and selects the current active option.
`Shift` + `Tab`	If the combo box is single-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is on the input, this action sets focus on the pill list if pills are present. If no pills are present the previous focusable element in the tab order is focused. If the list is open, Tab moves focus to the previous focusable element in the tab order and selects the current active option.
`Enter`	If the list is open and focus is on a option that is not disabled, Enter makes a selection. If the combo box is single-select, the list closes. If the combo box is multi-select, the list remains open.
`Space`	Space types a space character into the input field.
`Escape`	If the list is open, closes the list without making a selection, existing text in input field remains. Focus remains on combo box. If the list is closed, does nothing. Focus remains on combo box.
`Up arrow`	If the list is open, moves visual focus to the previous option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the last option in the list.
`Down arrow`	If the list is open, moves visual focus to the next option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the first option in the list.
`Left arrow` / `Right arrow`	This action moves focus between the input and the pill list in a multi-select combo box.
`Home`	When focus is within the combo box, this action moves focus to the first option.
`End`	When focus is within the combo box, this action moves focus to the last option.
`Page up`	When focus is within the dropdown, this action moves focus to the item before the first visible option.
`Page down`	When focus is within the dropdown, this action moves focus to the item after the last visible option.

Accessibility considerations

Update 12/17/24: This issue has been resolved in MacOS 15.

Browser/Assistive Technology Combination Issue: We have identified an accessibility issue when using Safari and VoiceOver that affects the usability of combo boxes. This issue is not related to our design system but is a known limitation in the interaction between these specific technologies and can be confirmed using the ARIA Authoring Practices Guide (APG) example on the World Wide Web Consortium (w3c) Who created the Web Content Accessibility Guidelines (WCAG) which is the industry standard on accessibility.

Issue Details:

Affected Components: Combobox (role=listbox)
OS: MacOS 14
Browser: Safari v15+
Assistive Technology: VoiceOver
Issue Confirmed on: 10/8/24
Problem: Focus is not managed correctly when using VoiceOver to select options from the combo box drop-down in Safari

User Impact: VoiceOver users using Safari may experience difficulties when interacting with combo boxes across various websites and applications, not limited to those using our design system.

Steps To Reproduce Using APG:

Go to APG Select-Only Combobox Example using Safari
Turn on VoiceOver
Navigate to the example
Open the combo box using space/enter
Try to navigate and select an option.

Recommendations:

Use Chrome or Firefox, or update to MacOS 15.1+

Resources:

Keyboard interactions

Key	Function
`Tab`	If the combo box is single-select and if focus is above the combo box, Tab sets focus on the component. When focused, combo box has a visible text cursor and the list is opened. If the combo box is multi-select and if the focus is above the combo box, Tab sets focus on the pill list if pills are present. If no pills are present then focus is set on the input. If the list is open, Tab moves focus to the next focusable element in the tab order and selects the current active option.
`Shift` + `Tab`	If the combo box is single-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is on the input, this action sets focus on the pill list if pills are present. If no pills are present the previous focusable element in the tab order is focused. If the list is open, Tab moves focus to the previous focusable element in the tab order and selects the current active option.
`Enter`	If the list is open and focus is on a option that is not disabled, Enter makes a selection. If the combo box is single-select, the list closes. If the combo box is multi-select, the list remains open.
`Space`	Space types a space character into the input field.
`Escape`	If the list is open, closes the list without making a selection, existing text in input field remains. Focus remains on combo box. If the list is closed, does nothing. Focus remains on combo box.
`Up arrow`	If the list is open, moves visual focus to the previous option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the last option in the list.
`Down arrow`	If the list is open, moves visual focus to the next option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the first option in the list.
`Left arrow` / `Right arrow`	This action moves focus between the input and the pill list in a multi-select combo box.
`Home`	When focus is within the combo box, this action moves focus to the first option.
`End`	When focus is within the combo box, this action moves focus to the last option.
`Page up`	When focus is within the dropdown, this action moves focus to the item before the first visible option.
`Page down`	When focus is within the dropdown, this action moves focus to the item after the last visible option.

Accessibility considerations

Update 12/17/24: This issue has been resolved in MacOS 15.

Issue Details:

Affected Components: Combobox (role=listbox)
OS: MacOS 14
Browser: Safari v15+
Assistive Technology: VoiceOver
Issue Confirmed on: 10/8/24
Problem: Focus is not managed correctly when using VoiceOver to select options from the combo box drop-down in Safari

User Impact: VoiceOver users using Safari may experience difficulties when interacting with combo boxes across various websites and applications, not limited to those using our design system.

Steps To Reproduce Using APG:

Go to APG Select-Only Combobox Example using Safari
Turn on VoiceOver
Navigate to the example
Open the combo box using space/enter
Try to navigate and select an option.

Recommendations:

Use Chrome or Firefox, or update to MacOS 15.1+

Resources:

Keyboard interactions

Key	Function
`Tab`	If the combo box is single-select and if focus is above the combo box, Tab sets focus on the component. When focused, combo box has a visible text cursor and the list is opened. If the combo box is multi-select and if the focus is above the combo box, Tab sets focus on the pill list if pills are present. If no pills are present then focus is set on the input. If the list is open, Tab moves focus to the next focusable element in the tab order and selects the current active option.
`Shift` + `Tab`	If the combo box is single-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is below the combo box, this action sets focus on the input. If the combo box is multi-select and focus is on the input, this action sets focus on the pill list if pills are present. If no pills are present the previous focusable element in the tab order is focused. If the list is open, Tab moves focus to the previous focusable element in the tab order and selects the current active option.
`Enter`	If the list is open and focus is on a option that is not disabled, Enter makes a selection. If the combo box is single-select, the list closes. If the combo box is multi-select, the list remains open.
`Space`	Space types a space character into the input field.
`Escape`	If the list is open, closes the list without making a selection, existing text in input field remains. Focus remains on combo box. If the list is closed, does nothing. Focus remains on combo box.
`Up arrow`	If the list is open, moves visual focus to the previous option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the last option in the list.
`Down arrow`	If the list is open, moves visual focus to the next option in the list. Focus does not wrap. If the list is closed, opens the list and moves visual focus to the first option in the list.
`Left arrow` / `Right arrow`	This action moves focus between the input and the pill list in a multi-select combo box.
`Home`	When focus is within the combo box, this action moves focus to the first option.
`End`	When focus is within the combo box, this action moves focus to the last option.
`Page up`	When focus is within the dropdown, this action moves focus to the item before the first visible option.
`Page down`	When focus is within the dropdown, this action moves focus to the item after the last visible option.

Accessibility considerations

Update 12/17/24: This issue has been resolved in MacOS 15.

Issue Details:

Affected Components: Combobox (role=listbox)
OS: MacOS 14
Browser: Safari v15+
Assistive Technology: VoiceOver
Issue Confirmed on: 10/8/24
Problem: Focus is not managed correctly when using VoiceOver to select options from the combo box drop-down in Safari

User Impact: VoiceOver users using Safari may experience difficulties when interacting with combo boxes across various websites and applications, not limited to those using our design system.

Steps To Reproduce Using APG:

Go to APG Select-Only Combobox Example using Safari
Turn on VoiceOver
Navigate to the example
Open the combo box using space/enter
Try to navigate and select an option.

Recommendations:

Use Chrome or Firefox, or update to MacOS 15.1+

Resources: