Combobox Preview
A combobox lets people choose one or more options from a list or enter text in a connected input. Entering text will filter options or allow someone to submit a free form answer.
Comboboxes work well in situations where the list of options is very long. If the list is not very long or you can't accept free form answers, try a dropdown or a select. For a standardized form component including helper text and validation styles, use the combobox field component.
Resources
Behavior
Placeholder text and default selection
If the placeholder prop is not set, comboboxes will show as empty until a selection is made. Use placeholder text as an extra hint that helps people understand the options in a combobox or what they can enter in the field. Don’t use placeholder text to label the combobox.
To display a default selection instead of placeholder text, use the defaultSelectedOptions prop.
Single select comboboxes
Selecting a closed field opens the list of options. Choosing an option from the list will close the field and the selected text replaces the placeholder text.
Multi-select comboboxes
For multi-select interactions, each list item is accompanied by a checkbox. The list of options won’t close until it is dismissed it, either by clicking off the list or by pressing Esc. Set the multiselect prop to true to enable multiple selections.
Because combobox inputs always allow people to enter information, the selections will not replace the placeholder text by default. For best usability, build in other ways to show people the selections they’ve made without opening the menu, like showing their choices as tags in the input.
Filtering and free form submission
Comboboxes allow people to filter the list of options as they type. If the someone types a string that doesn’t match any option in the list, you can allow submission of their free form entry by using the freeform prop.
Accessibility
The text prop
Use the text prop to define a string value for complex options, especially ones that contain JSX. Setting the text prop ensures that people can navigate dropdown options by typing a letter or string of letters to find matching options and that the closed dropdown will display the correct data once a selection’s been made.
Selecting with the Spacebar
Generally, people navigating via keyboard can use the Spacebar to enter a selection in a combobox. However, in situations where any options in the list may have multiple words, it’s important to count the space as part of the string for filtering. If the user navigates through the options using the keyboard, the Spacebar will select the highlighted option.
Optimize for screen readers
Set inlinePopup={true} when possible for better VoiceOver support. The inlinePopup prop will cause the listbox popup to be rendered immediately after the button in the DOM. Safari doesn’t support aria-owns, so this enables iOS VoiceOver swipe navigation between the button and options.
Content
Use descriptive labels that tell people what they can find in the menu. Single words or short phrases are best.
Write dropdown options using parallel construction, for example all nouns or all verbs, but don’t repeat the same word or phrase at the beginning of each option. If “none” is an option, include it.
Use sentence-style capitalization—only capitalize the first word. For more info, see Capitalization in the Microsoft Writing Style Guide.
