Version 5.2.0

Combo box

Combo boxes combine a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query.

Anatomy#


 Image illustrating through labels the component parts of a combo box in both its open and closed states, including its input field, label, value, required asterisk, value or placeholder, autocomplete suggestion, field button, validation marker, menu, menu options, and help text, description or error message. Image illustrating through labels the component parts of a combo box in both its open and closed states, including its input field, label, value, required asterisk, value or placeholder, autocomplete suggestion, field button, validation marker, menu, menu options, and help text, description or error message.

Options#


Key example of combo box correctly including a label. The combo box is labeled Topic and has value Art history.

Label#

Combo boxes should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These combo boxes without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”).

Key example of the two label positions available for combo box. The first uses the label Topic in the top position above the text input area. The second uses the label Topic in the side position, appearing before the text input area on the same line.

Label position#

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.

Key example of a placeholder in a combo box. The combo box is labeled Topic and the placeholder text "Select a topic..." appears in the input field because no value has been chosen.

Placeholder#

The placeholder text, also commonly known as “ghost text,” is temporary and disappears once a user enters text.

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, this text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. Help text is the preferred way to communicate this information.

Key example of a combo box showing a value. The combo box is labeled Topic and the text input shows a value of Art history.

Value#

The value shows a user’s entered text or the option they’ve selected.

Key example showing combo boxes with customizable width. Both examples are labeled Topic, with value Art history, but the second example is wider than the first.

Width#

The width of a combo box can be customized appropriately for its context.

Key example of a combo box which is not quiet, followed by one that is. Both are labeled Topic and value Art history. The component that is not quiet has a visible background and border around all sides of the input field and field button. The quiet component has no visible background and shows only a bottom border beneath the input field and field button.

Quiet#

By default, combo boxes have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons.

Alternatively, quiet combo boxes can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read.

Three combo boxes with labels demonstrating indications that they are required and optional. The first is labeled Topic (optional). The second is labeled Topic (required). The third is labeled Topic and accompanied by an asterisk to indicate that it is required.

Required or optional#

Combo boxes can be marked as optional or required, depending on the situation. For required combo boxes, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional combo boxes are either denoted with text added to the end of the label — “(optional)” — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

Key example of a combo box offering autocomplete suggestions. The component is labeled Topic and has a value AutoCAD. The last three letters are selected, and a menu shows suggestions for the value Auto: AutoCAD, Autocomplete, Autodidacts, Automobiles.

Autocomplete#

Combo boxes can automatically complete suggested results within the input field.

Three examples of combo boxes with each of the menu trigger options Input, Focus, and Manual. In the Input example a combo box labeled Topic shows a menu with the options AutoCad, Autocomplete, and Autodidacts after the user has entered the value Auto. In the Focus example a combo box labeled Topic shows a menu with the options AutoCad, Autocomplete and Autodidacts immediately, even though there is no value in the input field. In the Manual example a combo box labeled Topic has no value, and shows a menu with the options AutoCad, Autocomplete, and Autodidacts only after the field button has been activated by a user.

There are 3 options for how a combo box’s menu can be triggered: when a user starts typing (“input”), when focus is placed on the input field (“focus”), and manually when the user clicks or taps the field button (“manual”). These are used for different degrees of the information complexity and/or user familiarity of menu options.

By default, the menu is triggered when a user starts typing. This should be used when the content is readily familiar or commonplace enough to a user that they can begin populating values without seeing a list of all available options.

If the content of the combo box is unfamiliar or complex, the menu should be triggered when focus is placed on the input field because a user would benefit from seeing example content before selecting a value.

If the content of the combo box is highly familiar and autocomplete is sufficient to surface options, the menu can be set to trigger manually.

A combo box labeled Topic with value Art history shows a red border and a red alert icon in its input field to show that it is in an error state.

Error#

A combo box can be marked as having an error to show that a value needs to be entered in order to move forward, or that a value that was entered is invalid.

A disabled combo box with the label Topic and no value. The text and background are faint to indicate that the component is not currently active or available for interaction.

Disabled#

A combo box in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later.

Key example of read-only combo boxes. Label, Topic. Selected value, AutoCAD. Combo box shows visual change when moused over, but text can still be selected.

Read-only#

Combo boxes have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed. A combo box does not have a read-only option if no selection has been made.

Key example of help text, description or error message option. 2 required combo boxes. First combo box label Topic. Help text in grey color, Choose a topic. Add a new topic by typing it in the field, then selecting “Enter.” Second combo box label Topic. Error text in red color, Choose or add at least one topic.

Help text (description and error message)#

A combo box can have help text below the input field to give extra context or instruction about what a user should input. The help text area has two options: a description and an error message. The description communicates a hint or helpful information, such as specific requirements for what to choose. The error message communicates an error for when the input requirements aren’t met, prompting a user to adjust what they had originally selected.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text / nothing
label position
top / side
top
placeholder
text
value
text / nothing
width
number
is quiet
yes / no
no
is required
yes / no
no
necessity indicator
text / icon / nothing
icon
has autocomplete
yes / no
no
menu trigger
input / focus / manual
input
is error
yes / no
no
is disabled
yes / no
no
is read-only
yes / no
no
description
text / nothing
nothing
error message
text / nothing
nothing

Behaviors#


Two combo boxes, both with the top label State and the value CA, in the not quiet and quiet variants. Both fields are set to the minimum width.

Minimum width#

The minimum width for a combo box is 2.5× the height of the field button for standard style, and 2× the height of the field button for quiet style. This minimum width guarantees that small combo boxes are readable and easy to target on touch devices.

Key example of text overflow for the parts of a combo box. The component has a long label Select the size you want this export to be, which wraps to a second line beginning with the word "export". The input field cannot display the full value, and so shows a truncated value of Large (select this... with ellipses indicating that the value continues beyond what's shown. The options menu is open to show values that wrap when unconstrained by the input field. The three options are Small (works best for mobile phones), Medium (all-purpose), and Large (select this one for printing).

Text overflow#

When the field label and menu text are too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the menu.

Key example of a combo box with help text, with text overflowing to 2 lines. Combo box, label Topic. Help text in grey color, Choose a topic. Add a new topic by typing it in the field, then selecting “Enter.”

Help text overflow#

When the help text is too long for the available horizontal space, it wraps to form another line.

Key example of combo boxes in Windows “high contrast black” theme with label “Combo box”, disabled combo box with label “Disabled combo box”, and selected combo box with menu displaying options labeled “Option”, “Selected option” in selected state, and “Disabled option” in disabled state.

Windows high contrast mode#

In Windows high contrast mode, combo box should be displayed using the high contrast theme-specified colors for buttons. By default, border color should be the same as the button text color and labels should use default text color. In hover and keyboard focus states, the border color should display as the button border color. In the disabled state, border and text color should display as the disabled color. Items in a combo box menu should display with default text color. A selected item should have the background and text colors defined for selected text.

Combo box (Windows high contrast mode) UI kit

Usage guidelines#


Combo box, picker, or radio buttons?#

The text input functionality of the combo box is meant to make large lists easier to search. If you have fewer than 6 items, use radio buttons. If you have more than 6 items, consider whether your list of selections is complex enough to merit searching and filtering. If it's not complex enough for a combo box, you can use a picker.

Key example of a scenario where a combo box is more appropriate than a picker or radio buttons. A component labeled Site traffic reports has the partial value B17 and the menu is open to show the selected value REPORT B17-308 and the available values REPORT B17-309, REPORT B17-341, and REPORT B17-344.
Key example of two scenarios where a combo box is not appropriate compared to a picker or radio button. In the first example a component labeled Shipping Option shows the value Express 1 day and an open menu with the selected option Express 1 day and the available option Economy 5 day.  In the second option a component labeled Shirt size shows the value Medium and an open menu with the options Small, Medium, Large, and Extra Large. The Medium menu option is selected.

Suppressing the popover#

It’s okay to suppress the popover when the combo box contains entries the user is familiar with, and when autocomplete is enabled. A suppressed popover can still be opened when the field button containing the chevron is clicked.

Key example of a combo box that suppresses the display of its menu. A component labeled Font has the value Helv. An animation shows the down arrow key being pressed to repeatedly cycle through autocomplete options Helvetica Light, Helvetica Regular, Helvetica Medium, Helvetica Bold, and Helvetica Black. This interaction modifies the value of the combo box without opening a menu.
Key example of inappropriately suppressing autocomplete options. A component labeled Font has the value Helv and the cursor still active in the input field. A caption explains that a user is pressing the down arrow to navigate options, but the graphic does not change because the autocomplete and popover menu have been configured not to appear, so there is no indication that the interface is changing.

Immediate popover launch#

Launch the popover immediately if your user is highly unfamiliar with the content in the combo box, or if the data is especially complex.

Key example of immediately launching a combobox menu. An animation shows a cursor click the input field of a component labeled Site traffic reports with the placeholder value Type here... which triggers the immediate display of a menu with the options REPORT B17-308, REPORT B17-309, REPORT B17-341, and REPORT B17-344.

Delayed popover launch#

Launch the popover on text change if your user can get started typing without seeing a long list of options.

Key example of delaying the launch of combobox menu. An animation shows a cursor click the input field of a component labeled State with the placeholder value Type here.... The field border indicates that it has received focus, and the key M is pressed, triggering the launch of a menu with options Maine, Maryland, Massachusetts, and Michigan. The value is updated to Ma and the options narrow to only Maine, Maryland, and Massachusetts.

Saving suggestions#

When a suggestion is appended to the end of typed text, it remains the selected value when focus leaves the field. This guards against the scenario when a user sees a word completed in a field, continues to another form component, and the failure to commit changes erases the suggestion.

When autocomplete is disabled, best matches get a hover style in the popover, but don’t get saved as a value unless they’re clicked on or "Enter" is pressed.

Key example of correctly saving autocomplete suggestions. A component labeled Font is in focus and has the value Helvetica Bold, with a selection around etica Bold indicating that it has been supplied by autocomplete. A caption shows that the field loses focus, resulting in an unfocused component that has the label Font and the value Helvetica Bold, which preserved the autocomplete suggestion.
Key example of incorrectly saving an autocomplete suggestion. A focused component labeled Site traffic reports has the value B17. A menu is open to show options REPORT B17-308, REPORT B17-309, REPORT B17-341, and REPORT B17-344. The first menu item is being hovered over but is not selected. A caption indicates that the field loses focus, resulting in an unfocused component with title Site traffic reports and value REPORT B17-308, which incorrectly saved a value that was hovered but not selected.

Include a label#

Every combo box should have a label. A combo box without a label is ambiguous and not accessible. In rare cases where a label could be absent, make sure to have the design reviewed and approved by an accessibility expert.

Key example of a combo box correctly including the label Font for a component with the value Helvetica Bold.
Key example of a combo box that incorrectly fails to provide a label for a component with the value Helvetica Bold.

Keep menu items concise#

Keep menu items short and concise. Long menu items that cause text to wrap to multiple lines are discouraged. If text wrapping becomes a frequent concern, consider revising the text or use alternative UI patterns that will give your content more space.

Key example of a combo box that correctly uses concise language. A component labeled Flavor has the value Vanilla. A menu is open showing the options Vanilla, Chocolate, and Strawberry. The Vanilla option is selected.
Key example of a combo box incorrectly using verbose language. A component with label Flavor has the value Imported french vanilla. A menu is open with options Fair trade locally sourced artisanal dark chocolate, Imported french vanilla, and Organic house-blended strawberry chunks. The option Imported french vanilla is selected.

Truncation#

Choose a width for your combo boxes that is likely to accommodate the majority of selections available within it. When a combo box is in focus and the typed input exceeds the width of the field, push the leftmost text out of sight while allowing text to continue to be entered towards the chevron. When a combo box is deselected, truncate the selected entry with ellipsis before it collides with the chevron button.

Key example of a combo box that correctly truncates text. In the first example a component with label Ad Placement shows a value of Place ad automatica... that truncates when it reaches the end of the input field. The second example shows a component with label Ad Placement and the value lace ad automatically. The cursor is active at the end of this value, so the beginning of the value has truncated to keep the cursor in view.

Follow capitalization rules#

Field labels, placeholder text, and menu items should be in sentence case.

Key example of a combobox correctly following capitalization rules. The label Country of birth and the value United States, both follow sentence case.
Key example of a combo box incorrectly following capitalization rules. The label Country of Birth, using title case when it should be sentence cased.

Mark the minority of combo boxes in a form as required or optional#

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the combo boxes are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the combo boxes are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a combo box is optional.

A series of combo boxes correctly denoting optional or required on a minority of items. The first component has label Country and value text United States. The second has a label State and the value text California. The third has a label City (optional) and no value text.
A series of combo boxes incorrectly denoting optional or required on the majority of items. The first component has label Country (required) and value text United States. The second has a label State (required) and the value text California. The third has a label City (optional) and no value text.

Use help text to show hints, formatting, and requirements#

The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:

  • An overall description of the input field
  • Hints for what kind of information needs to be input
  • Specific formatting examples or requirements

The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text.

Key example of correct usage of help text with a combo box. Combo box, label Topic. Help text in grey color, Choose a topic. Add a new topic by typing it in the field, then selecting “Enter.”
Key example of incorrect usage of help text with a combo box. Combo box, label Topic. Help text in grey color, Choose a topic.

Use help text instead of placeholder text#

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible, and should be avoided if possible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text.

Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, and especially if they're communicating the same thing.

Key example of correct usage of help text instead of placeholder text with a combo box. Combo box label, Topic. Help text, Separate new topics with commas.
Key example of incorrect usage of placeholder text with a combo box. Combo box label, Topic. Truncated placeholder text, Separate new topics with...

Switch help text with error text#

The help text area also displays an error message. When a combo box already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field.

Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other (e.g., minimum requirements).

Key example of correct usage of switching help text with error text. Required combo box, label Topic. Help text, Choose a topic. Add a new topic by typing it into the field, then selecting “Enter.” Error message text, Choose or add at least one topic.
Key example of incorrect usage of switching help text with error text. Required combo box, label Topic. Help text and error text have the same message, Choose or add a topic.

Write error text that shows a solution#

Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user.

Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For combo boxes, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a combo box that asks for them to choose a topic, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Choose at least one topic.”

Key example of correct way to write an error message. Required combo box, label Topic. Error text in red, Choose or add at least one topic.
Key example of incorrect way to write an error message. Required combo box, label Topic. Error text in red, Invalid field.

Internationalization#


Key example of a combo box with an inverted layout for an RTL language. The label, value, and three menu options display in Arabic, anchored on the right instead of the left. The field button and selection check on the first menu item appear on the left instead of the right. The position of these items is mirrored, but the icons themselves are not flipped.

RTL#

For RTL (right-to-left) languages, the layout of the combo box is mirrored. Texts are right-aligned while the chevron and checkmark are left-aligned.

Keyboard interactions#


KeyInteraction
TypingInitiates autocomplete or popover (unless suppressed).
Down ArrowIf the popover is unsuppressed and not already open, the down arrow opens the popover menu.
Up or Down ArrowsMove through selection of options in popover or autocomplete.
EscIf the popover is open, close the popover.

Changelog#


DateNumberNotes
Feb 29, 20205.2.0
  • Added read-only option
  • Updated border color to be more accessible
Aug 22, 20195.1.0
  • Added text overflow behavior
Aug 13, 20195.0.1
  • Changed selected item text color from blue 500 to gray 800
Apr 20, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.