New features: This page contains new features. See DESY-168 for details.

Combobox multi select

The guideline content on this page is synced with Figma and can be used as a source of truth. Open in Figma

The combobox integrates a text field with a popover menu, enabling users to filter and select one or more options from a list or provide a custom value. It supports multi-selection, allowing for the collection of several distinct answers within a single component.

Anatomy

Label
Mandatory (optional)
Container
Helper text
Dropdown icon
Tag
Info icon (optional)

States

Enabled
Hover
Focused
Error
Error focused
Disabled
No results
Tag selected
Selected

Example
HTML

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/states.html

<div class="row">
    <!-- 1. Enabled -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">1</span>
            <label for="comboboxMultiStateEnabled">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateEnabled" placeholder="Text" aria-describedby="comboboxMultiStateEnabledHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiStateEnabledHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 2. Hover -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">2</span>
            <label for="comboboxMultiStateHover">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox hover" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateHover" placeholder="Text" aria-describedby="comboboxMultiStateHoverHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiStateHoverHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 3. Focused -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">3</span>
            <label for="comboboxMultiStateFocused">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox focus" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateFocused" placeholder="Text" aria-describedby="comboboxMultiStateFocusedHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiStateFocusedHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 4. Error -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required has-error">
            <span class="docs-state-number" aria-hidden="true">4</span>
            <label for="comboboxMultiStateError">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox has-error" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateError" placeholder="Text" aria-describedby="comboboxMultiStateErrorHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <span id="comboboxMultiStateErrorHelp" class="help-block d-flex align-items-center gap-4"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert"></span> Change this to a short description</span>
        </div>
    </div>

    <!-- 5. Error focused -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required has-error">
            <span class="docs-state-number" aria-hidden="true">5</span>
            <label for="comboboxMultiStateErrorFocused">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox has-error focus" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateErrorFocused" placeholder="Text" aria-describedby="comboboxMultiStateErrorFocusedHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <span id="comboboxMultiStateErrorFocusedHelp" class="help-block d-flex align-items-center gap-4"><span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert"></span> Change this to a short description</span>
        </div>
    </div>

    <!-- 6. Disabled -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">6</span>
            <label for="comboboxMultiStateDisabled">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox disabled" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateDisabled" placeholder="Text" aria-describedby="comboboxMultiStateDisabledHelp" disabled>
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1" disabled>
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiStateDisabledHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 7. No results -->
    <div class="col-6 col-lg-4 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">7</span>
            <label for="comboboxMultiStateNoResults">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox selected" aria-expanded="true">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateNoResults" value="Search" tabindex="-1" aria-describedby="comboboxMultiStateNoResultsHelp">
                    </div>
                </div>
                <button type="button" class="btn btn-icon btn-sm clear-btn show" aria-label="Clear search" aria-disabled="true" tabindex="-1">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
                <div class="combobox-dropdown show">
                    <ul role="listbox" class="combobox-list" aria-multiselectable="true">
                        <li><span class="combobox-info">No results found</span></li>
                    </ul>
                </div>
            </div>
            <p id="comboboxMultiStateNoResultsHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 8. Tag selected -->
    <div class="col-6 col-lg-6 mb-16">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">8</span>
            <label for="comboboxMultiStateTagSelected">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox" aria-expanded="false">
                    <span class="combobox-selected" tabindex="0">
                        <span class="combobox-selected-label">Label</span>
                        <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                        </button>
                    </span>
                    <span class="combobox-selected" tabindex="0">
                        <span class="combobox-selected-label">Label</span>
                        <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                        </button>
                    </span>
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateTagSelected" placeholder="" tabindex="-1" aria-describedby="comboboxMultiStateTagSelectedHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiStateTagSelectedHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 9. Selected (with dropdown open) -->
    <div class="col-6 col-lg-6 docs-open-dropdown-spacer">
        <div class="form-group required">
            <span class="docs-state-number" aria-hidden="true">9</span>
            <label for="comboboxMultiStateSelected">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox selected" aria-expanded="true">
                    <span class="combobox-selected" tabindex="0">
                        <span class="combobox-selected-label">Label</span>
                        <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                        </button>
                    </span>
                    <span class="combobox-selected" tabindex="0">
                        <span class="combobox-selected-label">Label</span>
                        <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                        </button>
                    </span>
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiStateSelected" value="Search" tabindex="-1" aria-describedby="comboboxMultiStateSelectedHelp">
                    </div>
                </div>
                <button type="button" class="btn btn-icon btn-sm clear-btn show" aria-label="Clear search" aria-disabled="true" tabindex="-1">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
                <div class="combobox-dropdown show">
                    <ul role="listbox" class="combobox-list" aria-multiselectable="true">
                        <li class="combobox-list-item" role="option">List item</li>
                        <li class="combobox-list-item" role="option">List item</li>
                        <li class="combobox-list-item" role="option">List item</li>
                        <li class="combobox-list-item" role="option">List item</li>
                        <li class="combobox-list-item" role="option">List item</li>
                        <li class="combobox-list-item" role="option">List item</li>
                    </ul>
                </div>
            </div>
            <p id="comboboxMultiStateSelectedHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>
</div>

Multi-select

Multi-select comboboxes handle multiple inputs. Every value selected from the menu immediately converts into an input chip within the field.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/multi-select.html

<div class="form-group required">
    <label for="comboboxMultiSelectDemo">Label</label>
    <div class="combobox-wrapper">
        <div role="combobox" class="combobox" aria-expanded="false">
            <span class="combobox-selected" tabindex="0">
                <span class="combobox-selected-label">Label</span>
                <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
            </span>
            <span class="combobox-selected" tabindex="0">
                <span class="combobox-selected-label">Label</span>
                <button type="button" class="clear-btn" aria-label="Remove selection" aria-disabled="true" tabindex="-1">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
            </span>
            <div class="combobox-input">
                <input type="text" id="comboboxMultiSelectDemo" placeholder="" aria-describedby="comboboxMultiSelectDemoHelp">
            </div>
        </div>
        <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
    </div>
    <p id="comboboxMultiSelectDemoHelp" class="help-block">Change this to a short description</p>
</div>

Label

A label is mandatory for all text fields and should describe the field's purpose. Labels are included by default. If another element (such as a section title) already serves as a clear description, the default label can be visually hidden.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/basic.html

<div class="form-group required">
    <label for="comboboxMultiBasic">Label</label>
    <div class="combobox-wrapper">
        <div role="combobox" class="combobox" aria-expanded="false">
            <div class="combobox-input">
                <input type="text" id="comboboxMultiBasic" placeholder="Text" aria-describedby="comboboxMultiBasicHelp">
            </div>
        </div>
        <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
    </div>
    <p id="comboboxMultiBasicHelp" class="help-block">Change this to a short description</p>
</div>

Helper text

Helper text communicates requirements and disclaimers below the field. An error message will always replace the helper text when a field validation error is triggered.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/basic.html

<div class="form-group required">
    <label for="comboboxMultiBasic">Label</label>
    <div class="combobox-wrapper">
        <div role="combobox" class="combobox" aria-expanded="false">
            <div class="combobox-input">
                <input type="text" id="comboboxMultiBasic" placeholder="Text" aria-describedby="comboboxMultiBasicHelp">
            </div>
        </div>
        <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
    </div>
    <p id="comboboxMultiBasicHelp" class="help-block">Change this to a short description</p>
</div>

Required/optional fields

We use an asterisk to indicate a field is required.

The convention of using a red asterisk (*) in a label to denote a required field is a long-standing and widely adopted practice in User Experience (UX) and form design.

Example
HTML

Label

Change this to a short description

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/mandatory.html

<div class="row">
    <!-- Required -->
    <div class="col-12">
        <div class="form-group required">
            <label for="comboboxMultiMandatoryRequired">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiMandatoryRequired" placeholder="Text" aria-describedby="comboboxMultiMandatoryRequiredHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiMandatoryRequiredHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- Optional -->
    <div class="col-12">
        <div class="form-group">
            <label for="comboboxMultiMandatoryOptional">Label</label>
            <div class="combobox-wrapper">
                <div role="combobox" class="combobox" aria-expanded="false">
                    <div class="combobox-input">
                        <input type="text" id="comboboxMultiMandatoryOptional" placeholder="Text" aria-describedby="comboboxMultiMandatoryOptionalHelp">
                    </div>
                </div>
                <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
                    <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
                </button>
            </div>
            <p id="comboboxMultiMandatoryOptionalHelp" class="help-block">Change this to a short description</p>
        </div>
    </div>
</div>

No search results

When a user types a value that does not match any option in the list, the combobox will display zero results. The popover menu will either close or show a "No results found" message, clearly indicating that the entered text did not successfully filter the predetermined dataset.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/no-search-results.html

<div class="form-group required">
    <label for="comboboxMultiNoResults">Label</label>
    <div class="combobox-wrapper">
        <div role="combobox" class="combobox selected" aria-expanded="true">
            <div class="combobox-input">
                <input type="text" id="comboboxMultiNoResults" value="Search" tabindex="-1" aria-describedby="comboboxMultiNoResultsHelp">
            </div>
        </div>
        <button type="button" class="btn btn-icon btn-sm clear-btn show" aria-label="Clear search" aria-disabled="true" tabindex="-1">
            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
        </button>
        <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
        <div class="combobox-dropdown show">
            <ul role="listbox" class="combobox-list" aria-multiselectable="true">
                <li><span class="combobox-info">No results found</span></li>
            </ul>
        </div>
    </div>
    <p id="comboboxMultiNoResultsHelp" class="help-block">Change this to a short description</p>
</div>

Accessibility

Keyboard interaction

All buttons should be reachable via Tab and Shift+Tab keys.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/accessibility.html

<div class="form-group required">
    <label for="comboboxMultiAccessibility">Label</label>
    <div class="combobox-wrapper">
        <div role="combobox" class="combobox focus" aria-expanded="false">
            <div class="combobox-input">
                <input type="text" id="comboboxMultiAccessibility" placeholder="Text" aria-describedby="comboboxMultiAccessibilityHelp">
            </div>
        </div>
        <button type="button" class="combobox-btn" aria-label="Open list" tabindex="-1">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
    </div>
    <p id="comboboxMultiAccessibilityHelp" class="help-block">Change this to a short description</p>
</div>

Specs

Combobox multi select specifications with spacing and radius annotations

Developer reference

The following sections describe supported functionality that is not part of the Figma design specification.

The functionality for this component, i.e. the script, is not provided. The documentation has a demo functionality that you can draw inspiration from in your work. For the full interactive combobox (single selection, header/footer sections, combogrid), see the Combobox page.

Demo enabled on this page! The enhanced keyboard-focus behaviour is active on this page — the .keyboard-focus class is added to each .form-group while a control is keyboard-focused, and removed on blur, click or typing. Try pressing Tab to navigate through the form fields. Read more in the Forms accessibility guidelines.

Enhanced mode

Multiple selection

For multi-selection, selected options are shown as tags (chips) in the text box. After a selection, the combobox remains open so the user can continue selecting.

Use aria-multiselectable="true" on the listbox element. Selected items are hidden from the dropdown list automatically.

Example
HTML

development/documentation/docs/combobox-multi-select/examples/multiple-selection.html

<div class="combobox-wrapper" style="max-width: 320px;">
    <label for="comboboxMultiInputE" id="comboboxMultiLabelE" class="combobox-label hidden" aria-label="Select from the list">Multiple selection</label>
    <div role="combobox" id="comboboxMultiE" class="combobox" aria-expanded="false" aria-owns="comboboxMultiListE" aria-haspopup="listbox">
        <div class="combobox-input">
            <span class="combobox-suggestion" option-selected=""></span>
            <input type="text" id="comboboxMultiInputE" placeholder="Enter selection" value="" spellcheck="false" aria-controls="comboboxMultiListE" aria-autocomplete="list" aria-activedescendant="" autofocus>
        </div>
    </div>
    <span class="spinner spinner-xs"></span>
    <button type="button" id="comboboxMultiClearE" class="btn btn-icon btn-sm clear-btn" aria-label="Delete selection in input">
        <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
    </button>
    <button type="button" id="comboboxMultiBtnE" class="combobox-btn" data-toggle="listbox" aria-label="Open country list">
        <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
    </button>
    <div class="combobox-dropdown">
        <ul role="listbox" id="comboboxMultiListE" class="combobox-list" aria-labelledby="comboboxMultiLabelE" aria-multiselectable="true"></ul>
    </div>
</div>

Info icon

Wrap the <label> and an info icon in .label-with-info to place the icon beside the label with the 8 px gap from the Figma anatomy. On hover or keyboard focus, the tooltip opens upwards (data-bs-placement="top") to reveal the supporting text.

Keep the icon outside the <label for> so activating it does not focus the combobox input, and mirror the tooltip text into a visually-hidden element that the input references via aria-describedby so assistive-tech users hear the same help text without depending on the tooltip.

Tooltip behaviour relies on Bootstrap's tooltip plugin (with Popper for positioning). See the Tooltips page for setup details.

Example
HTML

Label

Change this to a short description

development/documentation/docs/combobox-multi-select/examples/info-icon.html

<div class="form-group">
    <div class="label-with-info">
        <label for="comboboxMultiInputInfoIcon">Label</label>
        <span class="spirisicon spirisicon-sm spirisicon-info" tabindex="0" aria-label="More information about Label" data-bs-toggle="tooltip" data-bs-placement="top" title="Choose one or more options that best describe your scenario."></span>
    </div>
    <div class="combobox-wrapper">
        <div role="combobox" id="comboboxMultiInfoIcon" class="combobox" aria-expanded="false" aria-owns="comboboxMultiListInfoIcon" aria-haspopup="listbox" aria-multiselectable="true">
            <span class="combobox-selected" tabindex="0">
                <span class="combobox-selected-label">Label</span>
                <button type="button" class="clear-btn" aria-label="Remove selection">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
            </span>
            <span class="combobox-selected" tabindex="0">
                <span class="combobox-selected-label">Label</span>
                <button type="button" class="clear-btn" aria-label="Remove selection">
                    <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
                </button>
            </span>
            <div class="combobox-input">
                <input type="text" id="comboboxMultiInputInfoIcon" placeholder="Enter selection" value="" spellcheck="false" aria-controls="comboboxMultiListInfoIcon" aria-autocomplete="list" aria-activedescendant="" aria-describedby="comboboxMultiInputInfoIconHelp comboboxMultiInputInfoIconInfo">
            </div>
        </div>
        <button type="button" id="comboboxMultiClearButtonInfoIcon" class="btn btn-icon btn-sm clear-btn" aria-label="Delete selection in input">
            <span aria-hidden="true" class="spirisicon spirisicon-sm spirisicon-close"></span>
        </button>
        <button type="button" id="comboboxMultiButtonInfoIcon" class="combobox-btn" aria-label="Open list">
            <span class="spirisicon spirisicon-sm spirisicon-chevron-down"></span>
        </button>
        <div class="combobox-dropdown">
            <ul role="listbox" id="comboboxMultiListInfoIcon" class="combobox-list" aria-multiselectable="true"></ul>
        </div>
    </div>
    <span id="comboboxMultiInputInfoIconHelp" class="help-block">Change this to a short description</span>
    <span id="comboboxMultiInputInfoIconInfo" class="sr-only">Choose one or more options that best describe your scenario.</span>
</div>