Combo box usage guidelines

Combo box allows users to choose an option from a filterable list of options.

When to use

• Use when users need to select an item from a long list of options where being able to search the list of options will be faster.

When not to use

• Use checkboxes or radio buttons if there are 4 or fewer options in the list.
• Use checkboxes or radio buttons if there is a benefit to the user being able to see all options at once and compare what they have and have not selected.
• Use tag field when users should be able to select multiple options from the list.
• Do not use combo box for any kind of navigation. Instead, link, menu, or nav tab should be used.
• Use menu for action menus. Combo box should only be used to select an option from a list, not to take action in a UI.
• Use text fields when the intended value is a user-entered string.
• Use text field when typing a value will always be faster than looking through the list of options and there is not a high risk of user error by having the user enter the value.

Select vs. combo box
Select and combo box are very similar components that both allow users to select an item from a list of options. The primary functionality difference between the components is that combo box provides a visible search input that allows users to filter the list of options.

• Use combo box for user generated content where it’s unpredictable how long the list might be, and use cases where searching will enable users to be more efficient.
• Use select for lists that are short or lists that use predefined content not influenced by user input.

Usage

Combo box lists are composed of items and, optionally, list sections. For most use cases, a simple list of items without sections provides the clearest and most straightforward experience for users.

Preview

Favorite fruit

Code

import { ComboBox, ComboBoxItem } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <ComboBox label="Favorite fruit" placeholder="Select a fruit">
      <ComboBoxItem>Apple</ComboBoxItem>
      <ComboBoxItem>Banana</ComboBoxItem>
      <ComboBoxItem>Cherry</ComboBoxItem>
    </ComboBox>
  );
}

With sections

List sections are headings that can be used to categorize the items in a list if there’s a large number of options or if the added context helps users understand or differentiate list items. List section text should be short, distinct, and clearly label the category of list items.

Preview

Favorite fruit

Code

import { ComboBox, ComboBoxSection, ComboBoxItem } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <ComboBox label="Favorite fruit" placeholder="Select a fruit">
      <ComboBoxSection title="Berries">
        <ComboBoxItem>Strawberry</ComboBoxItem>
        <ComboBoxItem>Blueberry</ComboBoxItem>
        <ComboBoxItem>Raspberry</ComboBoxItem>
      </ComboBoxSection>
      <ComboBoxSection title="Citrus">
        <ComboBoxItem>Orange</ComboBoxItem>
        <ComboBoxItem>Lemon</ComboBoxItem>
        <ComboBoxItem>Lime</ComboBoxItem>
      </ComboBoxSection>
    </ComboBox>
  );
}

Formatting and layout

Placement

Combo box can either be left-aligned with the container it is placed in or, for smaller containers like modal dialogs and disclosures, it can span the full width of the container.

Spacing

• Combo boxes should have at least 16px of horizontal and vertical spacing between the combo box and other elements.

Form alignment

Combo box can be used in forms in conjunction with the other form components (text field, checkbox, and radio button for example). Form element width should be determined by the width of the container, not the specific content in the individual element. When combo boxes are stacked vertically with other elements (other combo boxes, or other form components), all of the components should have consistent widths.

Do

Name

Favorite fruit

Don't

Name

Favorite fruit

Content writing

Label

• Do use a short description of just one or two words for the label such as “Attribute”.
• Do not format labels in the form of a question such as “What attribute do you want to use?”
• Do not include verbs in your label such as “Select an attribute”.

Placeholder text

• Placeholder text can be used to provide an example of user input but should not duplicate the label text.
• Placeholder text is optional and should only be used where more context is necessary for the user to understand.

List items

• List items should be ordered intentionally to make finding an option easier for users. They can be organized from most selected to least selected or alphabetically.
• Section headings should be short and clearly state how the section has been categorized.
• Do list the default option first if there is one.

Description text

• Do provide description text whenever the label might not be enough context for a user to understand the purpose of the combo box.
• Do not provide unnecessary description text when the option to be selected is obvious based on the label.
• Do write clear and concise description text. Text should be limited to one sentence.
• End the description text with a period or equivalent punctuation mark. This helps screen reader users understand where the description ends, and it improves readability for all users.

Error text

• Do provide clear and concise error messaging.
• Do explain the issue and let the user know what they need to do to resolve it. Error messages should always provide users with a solution or a path to resolving the error.
• Error messages should use language that is easily understood rather than complex technical terms.
• End the error message with a period or equivalent punctuation mark. This helps screen reader users understand where the error message ends, and it improves readability for all users.

Behaviors

Default selection

If a combo box has a common or suggested option that most users select, it can be populated by default with that option. The user should still be able to interact with the combo box component and choose a different option.