Dropdown
General Guidelines
A dropdown is a component that allows the user to choose an option from a contextual list. A dropdown is used when a user needs to choose from options and apply it to an input field.
Voice and Tone
Every dropdown has a label. Labels should be clear, concise and display the type of input the field requires.
Standard dropdown options should be consolidated to single line of text that describes what is being selected.
Complex dropdown options appear in cases where it would help the user to have more information up to more lines of text and an avatar may be included (I.e. Bill Pay - choose payee, choose account). In these case extra information may help user to make a decision. When the selection is made on one line of text appears.

Grammar and Mechanics
- Labels are title case
- Options and placeholder text inside dropdown are sentence case (exception: when list includes formal names or titles; use title case in those cases)
- No punctuation
- When possible inputs are auto-filled for users’ convenience; when no item is preselected use placeholder text like “Select account,” this should tell the user what to expect to be selecting
- Sort in logical order such as alphabetical, most used or related groupings
Placement
By default a dropdown opens from the bottom of the input field. A dropdown may appear wider that the input it pertains to. It should never open out of view of the user, therefore it may open above the input.

Do's and Don'ts





How and When do I Use?
Refer to the diagram below to help you figure out when to use the checkbox component versus another similar component.

States

Decorators

Spacing, Color, and Typography

Examples
For details on when to use this component, please see the Usage tab.
<div class="iris-dropdown" id="test-iris-dropdown-default" name="dropdown" placeholder="Select a number">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
States
The states of this component are as follows:
Error
<div class="iris-dropdown iris-dropdown--error" data-size="large" id="test-iris-dropdown-error-large" name="dropdown" placeholder="Error State">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Disabled
<div class="iris-dropdown iris-dropdown--disabled" data-size="large" id="test-iris-dropdown-disabled-large" name="dropdown" placeholder="Disabled State">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Decorators
The decorators of this component are as follows:
Small
<div class="iris-dropdown" data-size="small" id="test-iris-dropdown-small" name="dropdown" placeholder="Small">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Medium
<div class="iris-dropdown" data-size="medium" id="test-iris-dropdown-medium" name="dropdown" placeholder="Medium">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Large
<div class="iris-dropdown" data-size="large" id="test-iris-dropdown-large" name="dropdown" placeholder="Large">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Multi-Select Dropdown
Add the multiple
attribute to enable multi-select functionality.
<div class="iris-dropdown" data-size="large" id="test-iris-dropdown-multiselect" name="dropdown" placeholder="Large" placeholder="Select values" multiple>
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Selected Value
Need a selected value? A value can be selected through markup by adding the selected
attribute to one of the iris-options.
<div class="iris-dropdown" id="test-iris-dropdown-default" name="dropdown" placeholder="Select a number">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4" selected> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
NOTE: If you are on a version of Iris before 1.6.0 you should use aria-selected="true"
instead of selected
.
Disabled Value
You may want to display an option but not allow it to be selected. This can be achieved by adding the disabled
attribute to one of the iris-options.
<div class="iris-dropdown" id="test-iris-dropdown-disabled-option" name="dropdown" placeholder="Select a number">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4" disabled> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Dropdowns and Forms
Dropdowns can be used in forms by adding the name
attribute. This will create an input that can be validated and pulled by the form. You can then submit the values to the form just like it was any other input element. In the following example we capture the values of the form and display them on the page to demonstrate this.
It's worth noting that a form reset triggers a dropdown reset as well.
<form id="form_name">
<div class="iris-dropdown" id="test-iris-dropdown-name" name="my_super_awesome_dropdown" placeholder="Select a number">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
<input type="hidden" name="my_super_secret_value" value="secret" />
<button type="submit" class="iris-button iris-button--primary">
<span class="iris-button__text">Submit</span>
</button>
<button type="reset" class="iris-button iris-button--primary">
<span class="iris-button__text">Reset</span>
</button>
</form>
Creating Rich Media Dropdowns
There are some cases where you would like to create dropdowns that have more than just text in them or that text is styled in a special way. This Dropdown component supports that.
<div class="iris-dropdown" data-size="large" id="test-iris-dropdown-media-large" name="dropdown" placeholder="Select a cat">
<ul class="iris-options-list">
<li class="iris-option" data-value="1" aria-label="Cat 1">
<img src="http://24.media.tumblr.com/tumblr_m4alnhJdvA1qay4n8o1_250.jpg" alt="Cat 1" />
</li>
<li class="iris-option" data-value="2" aria-label="Cat 2">
<img src="http://25.media.tumblr.com/tumblr_lmkaqiMBKk1qdth8zo1_250.jpg" alt="Cat 2" />
</li>
<li class="iris-option" data-value="3" aria-label="Cat 3">
<img src="http://24.media.tumblr.com/tumblr_m9raipGU3W1qargfho1_250.jpg" alt="Cat 3" />
</li>
<li class="iris-option" data-value="4" aria-label="Cat 4">
<img src="http://25.media.tumblr.com/qgIb8tERipvdznvpU4A5NYoNo1_250.jpg" alt="Cat 4" />
</li>
<li class="iris-option" data-value="5" aria-label="Cat 5">
<img src="http://25.media.tumblr.com/tumblr_m13r7dSGWO1qfgo5uo1_250.jpg" alt="Cat 5" />
</li>
</ul>
</div>
You might notice that the dropdown now encapsulates the entire image. This may not be what you want. In which case you can specify what the selected view looks like using <div class="iris-option__selected-view"></div>
.
<div class="iris-dropdown" data-size="large" id="test-iris-dropdown-media-large-2" name="dropdown" placeholder="Select a cat">
<ul class="iris-options-list">
<li class="iris-option" data-value="1" aria-label="Cat 1">
<img src="http://24.media.tumblr.com/tumblr_m4alnhJdvA1qay4n8o1_250.jpg" alt="Cat 1" />
<div class="iris-option__selected-view">
Cat 1
</div>
</li>
<li class="iris-option" data-value="2" aria-label="Cat 2">
<img src="http://25.media.tumblr.com/tumblr_lmkaqiMBKk1qdth8zo1_250.jpg" alt="Cat 2" />
<div class="iris-option__selected-view">
Cat 2
</div>
</li>
<li class="iris-option" data-value="3" aria-label="Cat 3">
<img src="http://24.media.tumblr.com/tumblr_m9raipGU3W1qargfho1_250.jpg" alt="Cat 3" />
<div class="iris-option__selected-view">
Cat 3
</div>
</li>
<li class="iris-option" data-value="4" aria-label="Cat 4">
<img src="http://25.media.tumblr.com/qgIb8tERipvdznvpU4A5NYoNo1_250.jpg" alt="Cat 4" />
<div class="iris-option__selected-view">
Cat 4
</div>
</li>
<li class="iris-option" data-value="5" aria-label="Cat 5">
<img src="http://25.media.tumblr.com/tumblr_m13r7dSGWO1qfgo5uo1_250.jpg" alt="Cat 5" />
<div class="iris-option__selected-view">
Cat 5
</div>
</li>
</ul>
</div>
Account Dropdown
Here is an example of how the Account Component can be used in the Dropdown Component.
<div class="iris-dropdown" data-size="large" id="test-iris-dropdown-account-large" name="dropdown" placeholder="Select an account">
<ul class="iris-options-list">
<li class="iris-option" data-value="1" aria-label="Steve's Checking Account">
<div class="iris-account iris-account--multi-line" data-color="account-color-0">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Steve's Checking Account">Steve's Checking Account</span>
</div>
<div class="iris-account__info iris-account__secondary-info" aria-hidden="true">
<span class="iris-account__account-number">**********123</span>
</div>
</div>
<div class="iris-account-balance iris-account-balance--available-balance">
<div class="iris-account-balance__row">
<span class="iris-account-balance__icon available-balance-icon"></span>
<span class="iris-account-balance__primary-info">$1,000.00</span>
</div>
</div>
</div>
<div class="iris-option__selected-view">
<div class="iris-account iris-account--single-line" data-color="account-color-0" data-size="small">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Steve's Checking Account">Steve's Checking Account</span>
</div>
</div>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__secondary-info">
<span class="iris-account__account-number">**********123</span>
</div>
</div>
</div>
</div>
</li>
<li class="iris-option" data-value="2" aria-label="Bob's Checking Account">
<div class="iris-account iris-account--multi-line" data-color="account-color-1" data-size="small">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Bob's Checking Account">Bob's Checking Account</span>
</div>
<div class="iris-account__info iris-account__secondary-info" aria-hidden="true">
<span class="iris-account__account-number">**********456</span>
</div>
</div>
<div class="iris-account-balance iris-account-balance--available-balance">
<div class="iris-account-balance__row">
<span class="iris-account-balance__icon available-balance-icon"></span>
<span class="iris-account-balance__primary-info">$930.00</span>
</div>
</div>
</div>
<div class="iris-option__selected-view">
<div class="iris-account iris-account--single-line" data-color="account-color-1" data-size="small">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Bob's Checking Account">Bob's Checking Account</span>
</div>
</div>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__secondary-info">
<span class="iris-account__account-number">**********456</span>
</div>
</div>
</div>
</div>
</li>
<li class="iris-option" data-value="3" aria-label="Amy's Savings Account">
<div class="iris-account iris-account--multi-line" data-color="account-color-2" data-size="small">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Amy's Savings Account">Amy's Savings Account</span>
</div>
<div class="iris-account__info iris-account__secondary-info" aria-hidden="true">
<span class="iris-account__account-number">**********789</span>
</div>
</div>
<div class="iris-account-balance iris-account-balance--available-balance">
<div class="iris-account-balance__row">
<span class="iris-account-balance__icon available-balance-icon"></span>
<span class="iris-account-balance__primary-info">$5,000,000.00</span>
</div>
</div>
</div>
<div class="iris-option__selected-view">
<div class="iris-account iris-account--single-line" data-color="account-color-2" data-size="small">
<span class="iris-account__color-bar"></span>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__primary-info">
<span class="iris-account__account-name" title="Amy's Savings Account">Amy's Savings Account</span>
</div>
</div>
<div class="iris-account__column iris-account__account-details">
<div class="iris-account__info iris-account__secondary-info">
<span class="iris-account__account-number">**********789</span>
</div>
</div>
</div>
</div>
</li>
</ul>
</div>
Accessibility
As always we want to keep all of the components in the application accessible. Please keep these notes in mind while using this component:
- Each dropdown MUST have a unique
id
and the correspondinglabel
must have afor
attribute in order to link the two together. - If the options are Rich Media, an
aria-label
is most likely appropriate. - Due to the ARIA spec, Dropdowns do not respect
aria-hidden
when reading selected options. Anaria-label
should be attached to these options. - Rich Media options should not contain interactive content. Some users may not be able to interact with this content.
Accessibility that Dropdown provides for you:
- Handles the roles for 'combobox', 'listbox', and 'option'.
- for all intents and purposes makes a rich media dropdown that acts like a select input for your accessible users.
- tries to standardize browser and screen reader inconsistencies such as announcing active and selected options.
API
Examples
Getting the DropdownComponent Object of an Element
var element = document.getElementById('test-iris-dropdown-default');
var dropdownComponent = Alkami.Iris.DropdownComponent.componentForElement(element);
//select a different value
dropdownComponent.value = dropdownComponent.options[0].value;
Setting up a Dropdown Change Event Listener
var element = document.getElementById('test-iris-dropdown-default');
element.addEventListener('iris.dropdown.change', function(event) {
console.log('User has selected value: ', event.detail.value);
});
Adding New Options to the DropdownComponent
var dropdownElement = document.getElementById('test-iris-dropdown-default');
var dropdownComponent = Alkami.Iris.DropdownComponent.componentForElement(dropdownElement);
var listOption = Alkami.Iris.ListOption.createListOptionElement(6, 'Six');
dropdownComponent.dataListElement.appendChild(listOption);
console.log(dropdownComponent.options);
Resetting Dropdown value
The UI itself doesn't allow a user to unselect a value when multiple
is not present. There could be a need to reset the dropdown value so it's possible programmatically.
var dropdownElement = document.getElementById('test-iris-dropdown-default');
var dropdownComponent = Alkami.Iris.DropdownComponent.componentForElement(dropdownElement);
dropdownComponent.value = null;
// or
dropdownComponent.selectedListOptions = [];
Events
Name | Description |
---|---|
iris.dropdown.change | Fires when a new value is selected in the dropdown. |
iris.dropdown.populate | Fires when options are added or removed from the dropdown. |
Constructors
new DropdownComponent(element)
element
- The element that contains the iris-dropdown.
Create a new DropdownComponent using the element. The constructor expects the DropdownComponent markup to be available in the specified element.
new ListOption(element)
element
- The element that contains the iris-dropdown.
Create a new ListOption using the element.
Methods
static DropdownComponent.init([nodeOrNodeList])
nodeOrNodeList
- The optional node or node list that will be configured to be dropdowns. Default: the query.iris-dropdown
is used.
static DropdownComponent.destroy(nodeOrNodeList)
nodeOrNodeList
- The node or node list that will be untied from the Dropdown.
static DropdownComponent.refresh([nodeOrNodeList])
nodeOrNodeList
- The optional node or node list that will be configured to be dropdowns. This will call a destroy if the component exists before initing again.- Default:* the query
.iris-dropdown
is used.
static DropdownComponent.componentForElement(element)
element
- The element that may be a Dropdown
Checks if a DOM element has a DropdownComponent object associated with it. Returns the DropdownComponent
object if one exists or null if one is not found.
static ListOption.createListOptionElement(value, textOrHtmlElement, [selectedView])
value
- The value of the ListOptiontextOrHtmlElement
- text or rich media HTML that represents the value.selectedView
- alternative text or rich media HTML that represents the value when selected.
Helper Function that creates an new List Element out of a value and text or element that you can insert into the Dropdown's optionListElement. You can optionally add a selectedView element to show when the option is selected in the dropdown. See the "Creating Rich Media Dropdowns" example for more information on selectedView.
Properties
dropdown.activeListOption
- ListOption
Gets/Sets the current active ListOption. The active ListOption is tracked through the aria-activedescendant
attribute.
dropdown.disabled
- boolean
Set/Get the disabled state of the Dropdown.
dropdown.expanded
- boolean
Set/Get the expanded state of the Dropdown.
dropdown.multiselect
- boolean
Set/Get the multi-select state of the Dropdown.
dropdown.options
- ListOptions[]
Gets options attached to the Dropdown. read-only
dropdown.optionsListElement
- HTMLElement
Gets the iris-options-list
element so that you may easily add new options through code. read-only
dropdown.required
- boolean
Set/Get if the Dropdown should be required when validating.
dropdown.selectedListOptions
- ListOption[]
Sets/Gets the currently selected ListOptions. If no value is selected then the getter returns an empty array.
dropdown.value
- string or string[]
Sets/Gets the currently selected value. If set to null, no value will be selected. If multiselect is true then value will return an array.
listoption.active
- boolean
Sets/Gets the ListOption's active state.
listoption.id
- string
Sets/Gets the ListOption's element's id.
listoption.selected
- boolean
Sets/Gets the ListOptions's selected state. denoted by selected
.
listoption.selectedViewElement
- HTMLElement
Gets the selected view Element of the ListOption, if it exists, null otherwise. read-only
listoption.text
- string
Gets the text rendering of the Option. If an aria-label
attribute exists on the element that will be used, otherwise the element's innerText
will be used. read-only
listoption.value
- string
Sets/Gets the value of the ListOption.
Variables
// Border variables
$dropdown-border: 1px solid $dove-gray !default;
$dropdown-border-error: $thunderbird !default;
$dropdown-border-disabled: transparentize($dove-gray, 0.5) !default;
$dropdown-border-readonly: transparent !default;
$dropdown-option-border: $alto;
// Text variables
$dropdown-font-size: 1.4rem !default;
$dropdown-text: $mine-shaft !default;
$dropdown-text-placeholder: $dove-gray !default;
$dropdown-text-disabled: transparentize($mine-shaft, 0.5) !default;
$dropdown-text-readonly: $mine-shaft !default;
$dropdown-line-height: 1.25 !default;
$dropdown-list-heading-font-size: 1.6rem !default;
$dropdown-list-heading-text: $mine-shaft !default;
// Background
$dropdown-option-selected: $alice-blue !default;
$dropdown-option-active: $wild-sand !default;
$dropdown-backdrop-background: transparentize($color: #000000, $amount: 0.6) !default;
$dropdown-list-background: $white !default;
// Box shadow variables
$dropdown-box-shadow-focus: $steel-blue !default;
$dropdown-box-shadow-error: $thunderbird !default;
$dropdown-box-shadow-disabled: none !default;
Themeability
Nothing is themeable in this component.
Variant: *Standard** | State: Static | Decorator: None*
<div class="iris-dropdown " id="test_iris_dropdown_Standard_Static_None" data-size="medium" name="dropdown" placeholder="Select a number.">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Variant: *Standard** | State: Error | Decorator: None*
<div class="iris-dropdown iris-dropdown--error" id="test_iris_dropdown_Standard_Error_None" data-size="medium" name="dropdown" placeholder="Select a number.">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>
Variant: *Standard** | State: Disabled | Decorator: None*
<div class="iris-dropdown iris-dropdown--disabled" id="test_iris_dropdown_Standard_Disabled_None" data-size="medium" name="dropdown" placeholder="Select a number.">
<ul class="iris-options-list">
<li class="iris-option" data-value="1"> One </li>
<li class="iris-option" data-value="2"> Two </li>
<li class="iris-option" data-value="3"> Three </li>
<li class="iris-option" data-value="4"> Four </li>
<li class="iris-option" data-value="5"> Five </li>
</ul>
</div>