American Express American Express |

Dropdowns

Purpose

A dropdown lets customers chose an item, or multiple items from a predefined list. A dropdown can be used within a form or as an action to filter or sort existing content.

Select

Usage

Use a select when customers can choose a single item from 5 or more items. For fewer than 5 items consider using radio buttons.

Example - Default

Copy
<div>
    <label for="dropdown" class="label-3">Label text</label>
    <div class="select form-control">
        <select id="dropdown">
            <option value=""></option>
            <option value="1">Selection 1</option>
            <option value="2">Selection 2</option>
            <option value="3">Selection 3</option>
            <option value="4">Selection 4</option>
            <option value="5">Selection 5</option>
        </select>
    </div>
</div>

Example - Selected item

Copy
<label for="dropdownSelected" class="label-3">Label text</label>
<div data-toggle="select">
    <div class="select form-control">
        <select id="dropdownSelected" aria-describedby="selectWarning" required>
            <option value=""></option>
            <option value="1" selected>Selected item</option>
            <option value="2">Selection 2</option>
            <option value="3">Selection 3</option>
            <option value="4">Selection 4</option>
            <option value="5">Selection 5</option>
        </select>
    </div>
    <div id="selectWarning" class="alert-form flex hidden" role="alert">
      <i class="margin-1-r" data-dls-icon="warning" data-dls-icon-size="sm" data-dls-icon-variant="filled" data-dls-icon-role="decorative"></i>
      A selection is required
    </div>
</div>

Example - Error with optional hint text

Hint text
Copy
<label for="dropdownWarning" class="label-3">Label text</label>
<span id="hint1" class="hint" tabindex="-1">Hint text</span>
<div data-toggle="select" class="has-warning">
    <div class="select form-control form-control-warning">
        <select id="dropdownWarning" required aria-describedby="selectAlert">
            <option></option>
            <option value="1">Selection 1</option>
            <option value="2">Selection 2</option>
            <option value="3">Selection 3</option>
            <option value="4">Selection 4</option>
            <option value="5">Selection 5</option>
        </select>
    </div>
    <div id="selectAlert" class="alert-form flex" role="alert">
      <i class="margin-1-r" data-dls-icon="warning" data-dls-icon-size="sm" data-dls-icon-variant="filled" data-dls-icon-role="decorative"></i>
      Error message
    </div>
</div>

Example - Disabled

Copy
<div>
    <label for="dropdownDisabled" class="label-3">Label text</label>
    <div class="select form-control disabled" disabled>
        <select id="dropdownDisabled" disabled>
            <option value=""></option>
            <option value="1">Selection 1</option>
            <option value="2">Selection 2</option>
            <option value="3">Selection 3</option>
            <option value="4">Selection 4</option>
            <option value="5">Selection 5</option>
        </select>
    </div>
</div>

Multi-select

Usage

Use a multi-select dropdown when a customer can select multiple items from a checklist or filter information from 5 or more items. For fewer than 5 items consider using checkboxes.

Optionally, dismissible tags can be displayed outside of the dropdown with the chosen items, providing visibility and quick dismissal of a section.

Example - Default

Copy
<label for="multiselect" class="label-3">Label text</label>
<div data-toggle="multiselect" style="max-width:18.75rem;">
    <div class="multiselect form-control">
        <select id="multiselect">
        </select>
    </div>
    <div class="multiselect-options border hidden">
        <div class="checkbox">
            <input class="form-control" id="multiselect1" type="checkbox">
            <label for="multiselect1">First item</label>
        </div>
        <div class="checkbox">
            <input class="form-control" id="multiselect2" type="checkbox">
            <label for="multiselect2">Middle item</label>
        </div>
        <div class="checkbox">
            <input class="form-control" id="multiselect3" type="checkbox">
            <label for="multiselect3">Middle item</label>
        </div>
        <div class="checkbox">
            <input class="form-control" id="multiselect4" type="checkbox">
            <label for="multiselect4">Middle item</label>
        </div>
        <div class="checkbox">
            <input class="form-control" id="multiselect5" type="checkbox">
            <label for="multiselect5">Middle item</label>
        </div>
        <div class="checkbox">
            <input class="form-control" id="multiselect6" type="checkbox">
            <label for="multiselect6">Last item</label>
        </div>
    </div>
</div>

Example - Error

Copy
<label for="multiselectWarning" class="label-3">Label text</label>
<div data-toggle="multiselect" class="has-warning" style="max-width:18.75rem;">
    <div class="multiselect form-control">
        <select id="multiselectWarning" required aria-describedby="multiselectAlert">
        </select>
    </div>
  <div class="multiselect-options border hidden">
    <div class="checkbox">
      <input class="form-control" id="multiselectError1" type="checkbox">
      <label for="multiselectError1">Item 1</label>
    </div>
    <div class="checkbox">
      <input class="form-control" id="multiselectError2" type="checkbox">
      <label for="multiselectError2">Item 2</label>
    </div>
    <div class="checkbox">
      <input class="form-control" id="multiselectError3" type="checkbox">
      <label for="multiselectError3">Item 3</label>
    </div>
    <div class="checkbox">
      <input class="form-control" id="multiselectError4" type="checkbox">
      <label for="multiselectError4">Item 4</label>
    </div>
    <div class="checkbox">
      <input class="form-control" id="multiselectError5" type="checkbox">
      <label for="multiselectError5">Item 5</label>
    </div>
    <div class="checkbox">
      <input class="form-control" id="multiselectError6" type="checkbox">
      <label for="multiselectError6">Item 6</label>
    </div>
  </div>
    <div id="multiselectAlert" class="alert-form flex" role="alert">
      <i class="margin-1-r" data-dls-icon="warning" data-dls-icon-size="sm" data-dls-icon-variant="filled" data-dls-icon-role="decorative"></i>
        <span>A selection is required</span>
    </div>
</div>

Example - Disabled

Copy
<div data-toggle="multiselect" style="max-width:18.75rem;">
    <label for="multiselectDisabled" class="label-3">Label text</label>
    <div class="multiselect form-control disabled" disabled>
        <select id="multiselectDisabled" disabled>
        </select>
    </div>
</div>

Dropdown Best Practices

Considerations

Sort lists of items in a way that makes the most sense to the customer. You can order lists alphabetically, numerically, or by most commonly selected item.

We reccomend showing 50% of the last item to indicate there is more to see within the dropdown.

Avoid long dropdowns that require scrolling, because they make it difficult view all items at a glance. If you have too many items to include consider using an autocomplete field that customers can type in to filter results, such as search input with typeahead.

Example - Fewer than 5 items

Do this.

Use radio buttons for fewer than 5 items.

Size

Don't do this.

Don't use a dropdown for fewer than 5 items.

Example - Default Text

Do this.

Use a blank dropdown field.

Don't do this.

Including default text such as 'select' text as a placeholder can cause users to think that the dropdown field is already filled out and skip over it.

Functionality

Dropdown components may require both dls.css and dls.js for validation, multi-select and two-lined functionality. If you are using dls.js, reference the attributes below for functionality.

Select & Two-lined Dropdown

Attribute Name Options Description
data-toggle select Creates a dropdown object; required for dls.js validation functionality and for two-lined dropdowns.
aria-describedby string Displays associated alert message (based on id) if there is no selection after validation.
required none Validates based on whether there is a selection or not. Displays associated error if no input value has been entered.

Multi-select

Attribute Name Options Description
data-toggle multiselect Creates a multiselect object; required for dls.js validation and keyboard navigation functionality.
aria-describedby string Displays associated alert message (based on id) if there is no selection after validation.
required none Validates based on whether there is a selection or not. Displays associated error if no input value has been entered.

Two-Lined Dropdowns

Example - Unselected Value for Two-Lined Dropdown

Copy
<label for="selectTwoLined" class="label-3">Bank account</label>
<div data-toggle="select">
  <div class="select select-two-lined form-control" >
    <label class="label-1"></label>
    <select id="selectTwoLined">
      <option value=""></option>
      <option value="1" data-label="Main Account">Account Starting in 6524</option>
      <option value="2" data-label="Secondary Account">Account Starting in 9854</option>
      <option value="3" data-label="Tertiary Account">Account Starting in 8673</option>
    </select>
  </div>
</div>

Example - Default Two-Lined Dropdown

Copy
<label for="selectTwoLinedDefault" class="label-3">Bank account</label>
<div data-toggle="select">
  <div class="select select-two-lined form-control">
    <label class="label-1"></label>
    <select id="selectTwoLinedDefault" aria-describedby="requiredAlert" required>
      <option value=""></option>
      <option value="1" data-label="Main Account" selected>Account Starting in 6524</option>
      <option value="2" data-label="Secondary Account">Account Starting in 9854</option>
      <option value="3" data-label="Tertiary Account">Account Starting in 8673</option>
    </select>
  </div>
  <div id="requiredAlert" class="alert-form flex hidden" role="alert">
    <i class="margin-1-r" data-dls-icon="warning" data-dls-icon-size="sm" data-dls-icon-variant="filled" data-dls-icon-role="decorative"></i>
    A selection is required
  </div>
</div>