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

Dropdown

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

A dropdown presents a user with a predetermined list (dataset) from which they can select one value.

Anatomy

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

States

Enabled
Hover
Selected
Error
Error focused
Read only
Disabled
Focused

Example
HTML

Label

development/documentation/docs/dropdown/examples/states.html

<div class="row">
    <!-- 1. Enabled -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">1</span>
            <label for="dropdown-state-enabled">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-enabled" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-enabled-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-enabled">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-enabled-help" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 2. Hover -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">2</span>
            <label for="dropdown-state-hover">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-hover" class="dropdown-toggle dropdown-field hover" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-hover-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-hover">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-hover-help" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 3. Selected / Open -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">3</span>
            <label for="dropdown-state-selected">Label</label>
            <div class="dropdown open">
                <button type="button" id="dropdown-state-selected" class="dropdown-toggle dropdown-field has-value" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true" aria-describedby="dropdown-state-selected-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-selected">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-selected-help" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 4. Error -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required has-error docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">4</span>
            <label for="dropdown-state-error">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-error" class="dropdown-toggle dropdown-field has-value" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-error-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-error">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-error-help" class="help-block">
                <span class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert" aria-hidden="true"></span>
                Change this to a short description
            </p>
        </div>
    </div>

    <!-- 5. Error focused -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required has-error docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">5</span>
            <label for="dropdown-state-error-focused">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-error-focused" class="dropdown-toggle dropdown-field has-value focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-error-focused-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-error-focused">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-error-focused-help" class="help-block">
                <span class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert" aria-hidden="true"></span>
                Change this to a short description
            </p>
        </div>
    </div>

    <!-- 6. Read only -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">6</span>
            <label for="dropdown-state-readonly">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-readonly" class="dropdown-toggle dropdown-field has-value readonly" aria-readonly="true" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-readonly-help">
                    Specify your name attribute
                </button>
            </div>
            <p id="dropdown-state-readonly-help" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 7. Disabled -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">7</span>
            <label for="dropdown-state-disabled">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-disabled" class="dropdown-toggle dropdown-field has-value" disabled data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-disabled-help">
                    Specify your name attribute
                </button>
            </div>
            <p id="dropdown-state-disabled-help" class="help-block">Change this to a short description</p>
        </div>
    </div>

    <!-- 8. Focused -->
    <div class="col-6 col-lg-6 mb-32">
        <div class="form-group required docs-form-state-width">
            <span class="docs-state-number" aria-hidden="true">8</span>
            <label for="dropdown-state-focused">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-state-focused" class="dropdown-toggle dropdown-field has-value focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-state-focused-help">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-state-focused">
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                    <li class="dropdown-item"><a href="#!">List item</a></li>
                </ul>
            </div>
            <p id="dropdown-state-focused-help" class="help-block">Change this to a short description</p>
        </div>
    </div>
</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

development/documentation/docs/dropdown/examples/label.html

<div class="form-group required">
    <label for="dropdown-label-example">Label</label>
    <div class="dropdown">
        <button type="button" id="dropdown-label-example" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-label-example-help">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-label-example">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
    <p id="dropdown-label-example-help" 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

development/documentation/docs/dropdown/examples/helper-text.html

<div class="form-group required">
    <label for="dropdown-helper-text">Label</label>
    <div class="dropdown">
        <button type="button" id="dropdown-helper-text" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-helper-text-help">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-helper-text">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
    <p id="dropdown-helper-text-help" 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

development/documentation/docs/dropdown/examples/required-optional.html

<div class="row">
    <!-- Required field -->
    <div class="col-6 col-lg-4 mb-32">
        <div class="form-group required">
            <label for="dropdown-required">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-required" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-required">
                    <li class="dropdown-item"><a href="#!">Option 1</a></li>
                    <li class="dropdown-item"><a href="#!">Option 2</a></li>
                </ul>
            </div>
        </div>
    </div>

    <!-- Optional field -->
    <div class="col-6 col-lg-4 mb-32">
        <div class="form-group">
            <label for="dropdown-optional">Label</label>
            <div class="dropdown">
                <button type="button" id="dropdown-optional" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                    Specify your name attribute
                </button>
                <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-optional">
                    <li class="dropdown-item"><a href="#!">Option 1</a></li>
                    <li class="dropdown-item"><a href="#!">Option 2</a></li>
                </ul>
            </div>
        </div>
    </div>
</div>

Error message

Upon validation failure, the helper text is replaced by a concise error message. This message includes an error icon and provides direct instructions to help the user satisfy the requirements.

Example
HTML

Label

development/documentation/docs/dropdown/examples/error-message.html

<div class="form-group required has-error">
    <label for="dropdown-error-message">Label</label>
    <div class="dropdown">
        <button type="button" id="dropdown-error-message" class="dropdown-toggle dropdown-field has-value" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-error-message-help">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-error-message">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Specify your name attribute</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
    <p id="dropdown-error-message-help" class="help-block">
        <span class="spirisicon spirisicon-sm spirisicon-filled spirisicon-alert" aria-hidden="true"></span>
        Select a value for this item
    </p>
</div>

Max width

Dropdown buttons and menus have a max width of 520px.

Example
HTML

development/documentation/docs/dropdown/examples/max-width.html

<div class="form-group">
    <div class="dropdown">
        <button type="button" id="dropdown-max-width" class="dropdown-toggle dropdown-field w-100" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-max-width">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
</div>

Accessibility

Keyboard interaction

All buttons should be reachable via TAB and SHIFT+TAB keys.

Example
HTML

Label

development/documentation/docs/dropdown/examples/accessibility.html

<div class="form-group required">
    <label for="dropdown-accessibility">Label</label>
    <div class="dropdown">
        <button type="button" id="dropdown-accessibility" class="dropdown-toggle dropdown-field focus" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-accessibility-help">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-accessibility">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
    <p id="dropdown-accessibility-help" class="help-block">Change this to a short description</p>
</div>

Specs

Specifications showing padding, spacing and border radius values for the dropdown component

Developer reference

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

The open/close and Arrow Up/Arrow Down keyboard navigation behaviour is not provided. The documentation has a demo script that you can draw inspiration from in your work.

Basic design

The dropdown component uses a <button> element with the .dropdown-toggle and .dropdown-field classes inside a .dropdown container. The dropdown menu uses the standard .dropdown-menu with .dropdown-item list items.

Wrap the dropdown in a .form-group with a <label> for proper accessibility and form integration.

Example
HTML

Label

development/documentation/docs/dropdown/examples/default.html

<div class="form-group required">
    <label for="dropdown-default">Label</label>
    <div class="dropdown">
        <button type="button" id="dropdown-default" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-default-help">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-default">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
            <li class="dropdown-item"><a href="#!">Option 4</a></li>
            <li class="dropdown-item"><a href="#!">Option 5</a></li>
        </ul>
    </div>
    <p id="dropdown-default-help" class="help-block">Helper text for this dropdown field</p>
</div>

Selected value

When a value is selected, add the .has-value class to the trigger button. This changes the text colour from placeholder (secondary) to primary. Update the button text to show the selected value.

Label

A value has been selected

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 clicking the icon does not toggle the dropdown, and mirror the tooltip text into a visually-hidden element that the trigger references via aria-describedby — that way 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

development/documentation/docs/dropdown/examples/info-icon.html

<div class="form-group required">
    <div class="label-with-info">
        <label for="dropdown-info-icon">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="Provide a clear, concise description so users understand what to select."></span>
    </div>
    <div class="dropdown">
        <button type="button" id="dropdown-info-icon" class="dropdown-toggle dropdown-field" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" aria-describedby="dropdown-info-icon-help dropdown-info-icon-info">
            Specify your name attribute
        </button>
        <ul class="dropdown-menu" role="menu" aria-labelledby="dropdown-info-icon">
            <li class="dropdown-item"><a href="#!">Option 1</a></li>
            <li class="dropdown-item"><a href="#!">Option 2</a></li>
            <li class="dropdown-item"><a href="#!">Option 3</a></li>
        </ul>
    </div>
    <p id="dropdown-info-icon-help" class="help-block">Change this to a short description</p>
    <span id="dropdown-info-icon-info" class="sr-only">Provide a clear, concise description so users understand what to select.</span>
</div>