Components

Combo box

A combo box helps users select an item from a large list of options.

Passed WCAG 2.1 AA 

<label class="usa-label" for="fruit">Select a fruit</label>
<div class="usa-combo-box">
  <select class="usa-select" name="fruit" id="fruit">
    <option value>Select a fruit</option>
    <option value="apple">Apple</option>
    <option value="apricot">Apricot</option>
    <option value="avocado">Avocado</option>
    <option value="banana">Banana</option>
    <option value="blackberry">Blackberry</option>
    <option value="blood orange">Blood orange</option>
    <option value="blueberry">Blueberry</option>
    <option value="boysenberry">Boysenberry</option>
    <option value="breadfruit">Breadfruit</option>
    <option value="buddhas hand citron">Buddha's hand citron</option>
    <option value="cantaloupe">Cantaloupe</option>
    <option value="clementine">Clementine</option>
    <option value="crab apple">Crab apple</option>
    <option value="currant">Currant</option>
    <option value="cherry">Cherry</option>
    <option value="custard apple">Custard apple</option>
    <option value="coconut">Coconut</option>
    <option value="cranberry">Cranberry</option>
    <option value="date">Date</option>
    <option value="dragonfruit">Dragonfruit</option>
    <option value="durian">Durian</option>
    <option value="elderberry">Elderberry</option>
    <option value="fig">Fig</option>
    <option value="gooseberry">Gooseberry</option>
    <option value="grape">Grape</option>
    <option value="grapefruit">Grapefruit</option>
    <option value="guava">Guava</option>
    <option value="honeydew melon">Honeydew melon</option>
    <option value="jackfruit">Jackfruit</option>
    <option value="kiwifruit">Kiwifruit</option>
    <option value="kumquat">Kumquat</option>
    <option value="lemon">Lemon</option>
    <option value="lime">Lime</option>
    <option value="lychee">Lychee</option>
    <option value="mandarine">Mandarine</option>
    <option value="mango">Mango</option>
    <option value="mangosteen">Mangosteen</option>
    <option value="marionberry">Marionberry</option>
    <option value="nectarine">Nectarine</option>
    <option value="orange">Orange</option>
    <option value="papaya">Papaya</option>
    <option value="passionfruit">Passionfruit</option>
    <option value="peach">Peach</option>
    <option value="pear">Pear</option>
    <option value="persimmon">Persimmon</option>
    <option value="plantain">Plantain</option>
    <option value="plum">Plum</option>
    <option value="pineapple">Pineapple</option>
    <option value="pluot">Pluot</option>
    <option value="pomegranate">Pomegranate</option>
    <option value="pomelo">Pomelo</option>
    <option value="quince">Quince</option>
    <option value="raspberry">Raspberry</option>
    <option value="rambutan">Rambutan</option>
    <option value="soursop">Soursop</option>
    <option value="starfruit">Starfruit</option>
    <option value="strawberry">Strawberry</option>
    <option value="tamarind">Tamarind</option>
    <option value="tangelo">Tangelo</option>
    <option value="tangerine">Tangerine</option>
    <option value="ugli fruit">Ugli fruit</option>
    <option value="watermelon">Watermelon</option>
    <option value="white currant">White currant</option>
    <option value="yuzu">Yuzu</option>
  </select>
</div>

Guidance

When to use the combo box component

  • More than 15 options. Use a combo box when there are more than 15 choices in a drop-down list. With so many options, users may find it difficult to navigate with scrolling only.
  • Limited space. Use a combo box for presenting options when screen real estate is limited.

When to consider something else

  • Limited choices. When the number of options is small, you can continue to use a select or radio element.

Usability guidance

  • Use option strings familiar to users. The combo box filters by matching strings. Include option text that includes familiar strings or spellings (for example, if using the combobox with a state list, include the postal abbreviation in the option text: District of Columbia (DC)).
  • Make sure to test. Test select menus thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many users find them confusing and difficult to use.
  • Avoid dependent options. Avoid making options in one select menu change based on the input to another. Users often don’t understand how choosing an item in one impacts another
  • Use a good default. When most users will (or should) pick a particular option, make it the default: <option selected="selected">Default</option>.
  • Avoid auto-submission. Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Offer a “submit” button at the end of the form instead. Users often change their choices multiple times. Auto-submission is also less accessible.

Accessibility guidance

Test the combo box component in your own project.

USWDS tested the combo box component for accessibility. You should test your implementation, too.

Use combo box accessibility tests
  • Known assistive technology issues. Testing with people using assistive technology revealed usability concerns that require additional investigation. At this time, consider using a Select component instead of a Combo box. More research and testing is planned to better understand and address these accessibility issues. If you would like to contribute to improving this component, please join our community and share your feedback.
  • Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
  • Always use a label. Make sure your select element has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the menu read “Select a state” by default).
  • Avoid auto-submission. Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.

Using the combo box component

  • Properties. The following properties modify component functionality. These properties can be set or adjusted at any time before or after initialization in order to have an effect.

    Property Element Description

    data-filter

    .usa-combo-box

    The combo box will use this regular expression to filter the combo box options. You are declaring a case insensitive match over the entire option text, which means ^ and $ are added automatically. You can specify the inputted query with {{query}}. You can also declare a custom query filter as a data property as well, which can be used in the custom filter (data-number-filter="[0-9]" and then using data-filter="{{numberFilter}}.*"). The default filter is .*{{query}}.*, which is a simple “find anywhere within the option” text.

  • Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.

    Property Element Description

    required

    select

    The combo box component will be required in terms of native form validation.

    disabled

    select

    The combo box component will be disabled / read-only. You can re-enable it by executing the enable procedure on the component.

    data-placeholder

    .usa-combo-box

    To update the placeholder text of the combo box, use the data-placeholder attribute. We recommend using a label or hint instead of a placeholder.

    data-default-value

    .usa-combo-box

    The combo box will set this value as the default selection if it is found within the select options.

  • Procedures. The following static procedures update the component after initialization. These are in addition to the primary methods referenced in the JS customization documentation.

    Procedure Parameters Description

    enable

    .usa-combo-box

    The combo box component will be enabled.

    disable

    .usa-combo-box

    The combo box component will be disabled / read-only.

Combo box settings

This component has no settings.

Combo box variants

This component has no variants.

Accessibility test status

The USWDS team did 15 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
15 13 0 2 0

Overview of recent accessibility test results:

  • Passed: 13
  • Passed with exceptions: 0
  • Conditional: 2
  • Failed: 0

Learn more on the combo box accessibility tests page.

Package

  • Package usage: @forward "usa-combo-box";
  • Dependencies: usa-select, usa-icon

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-11-13 3.10.0
  • JavaScript
 No

Updated the order of combo box search results. The component now displays options that start with the query at the top of the list, followed by options that contain the query. This behavior more closely aligns with user expectations. More information: uswds#6122

2024-10-04 3.9.0
  • Accessibility
  • JavaScript
 No

Removed custom screen reader instructions. Combo box now relies on the default instructions provided by screen readers. More information: uswds#6022

2024-09-18 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2811

2024-03-13 N/A
  • Guidance
 No

Added known issues section. More information: uswds-site#2402

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2023-06-09 3.5.0
  • Accessibility
  • JavaScript
 No

Improved consistency of keyboard actions. Users can now to use Tab to escape the combo box selection without making a choice, and Space to select the current highlighted option when within the dropdown menu. More information: uswds#5160

2022-11-14 N/A
  • Guidance
 No

Added note on usability issues with assistive technology. Testing with people using assistive technology revealed usability concerns that require additional investigation. Until addressed, consider using a Select component instead of a Combo box. More information: uswds-site#1898

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-combo-box. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-13 N/A
  • Guidance
 No

Updated package name to form-controls. More information: uswds-site#1497

2022-04-11 2.13.3
  • Accessibility
  • Styles
 No

Added support for forced colors mode. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610

2022-03-07 2.13.2
  • Accessibility
  • JavaScript
 No

Added proper aria-controls to combo box. Now the combo box input gets the expected aria-controls property when it’s initialized. More information: uswds#4483

2021-11-01 2.12.2
  • JavaScript
 No

Added automatic sanitizing. The design system now automatically sanitizes content in elements we compose with JavaScript. This means that components like combo box, tooltip, file input, and date picker will sanitize any content passed to them. This helps protect any design system implementation against malicious XSS attacks through these components. More information: uswds#4329

2021-08-18 2.12.1
  • JavaScript
 No

Improved performance of date picker and combo box JavaScript. More information: uswds#4256

2021-08-18 2.12.1
  • JavaScript
 No

Improved how combo box parses and displays option text. More information: uswds#4256