List
General Guidelines
Lists are used to gather and display connected information in consecutive order, one element above the other. The elements of a list are usually laid out in alphabetical order and/or in ascending order (unless business requirements suggest to do otherwise).
Lists can be active or inactive and they can be composed of records, tiles, and/or checkable lists (see the Records, Tiles, and Checkboxes components for more information).
Usage
Configurations | When |
---|---|
Provide a visual indication that lists are active | When a user hovers into the list’s region. |
Break up data-intensive or lengthy lists | When performance would be improved by doing so. |
Use pagination, infinite scroll or See More functionality | When you need to break up data-intensive or lengthy lists. |
Do's and Don'ts




Coming soon...
Please enjoy a cat while you wait
Examples
For details on when to use this component, please see the Usage tab.
Static List
In its most basic state, a list is static without being interactive. Static lists can be used to visually display components in a read-only state.
- RE: Application Status
- RE: Application Status (1)
- RE: Application Status (2)
- RE: Application Status (3)
<ul class="iris-list iris-list--static">
<li class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status</div>
</li>
<li class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (1)</div>
</li>
<li class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (2)</div>
</li>
<li class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (3)</div>
</li>
</ul>
Actionable List
The most widely used type of list is the Actionable list. This type of list allows a user to select an item from the list to act on it.
- RE: Application Status
- RE: Application Status (1)
- RE: Application Status (2)
- RE: Application Status (3)
<ul id="actionable_list" class="iris-list iris-list--actionable">
<li class="iris-list-item" data-value="1">
<div class="iris-list-item__content">RE: Application Status</div>
</li>
<li class="iris-list-item" data-value="2">
<div class="iris-list-item__content">RE: Application Status (1)</div>
</li>
<li class="iris-list-item" data-value="3">
<div class="iris-list-item__content">RE: Application Status (2)</div>
</li>
<li class="iris-list-item" data-value="4">
<div class="iris-list-item__content">RE: Application Status (3)</div>
</li>
</ul>
<div class="border--all">
The selected value is: <span id="list_value">Nothing</span>
</div>
<script>
Alkami.Iris.dom.ready(function() { //Make sure dom is done loading
var listElement = document.getElementById('actionable_list');
listElement.addEventListener('change', function(event) { //when the user selects a list item
var valueElement = document.getElementById('list_value');
valueElement.innerText = event.detail.value;
});
});
</script>
Checkable List
Use a Checkable list when the user needs to be able to select multiple values from a list. Checkable is a variant iris-list--checkable
and the aria-multiselectable="true"
being set. If you don't mark the List as multiselectable, it will still act as an Actionable List and allow only one selection.
Checkable Lists will automatically find any Checkbox components inside the list and check or uncheck them as needed.
- RE: Application Status
- RE: Application Status (1)
- RE: Application Status (2)
- RE: Application Status (3)
<ul class="iris-list iris-list--checkable" aria-multiselectable="true" style="width: 290px;">
<li class="iris-list-item" data-value="1">
<div class="iris-list-item__content">
<div class="container-fluid pad--lg">
<div class="row">
<div class="no-gutter col-2 flex flex-justify--center">
<div class="iris-checkbox" >
<input class="iris-checkbox__input" type="checkbox" />
<label class="iris-checkbox__label" ></label>
</div>
</div>
<div class="no-gutter col-10">
<span>RE: Application Status</span>
</div>
</div>
</div>
</div>
</li>
<li class="iris-list-item" data-value="2" >
<div class="iris-list-item__content">
<div class="container-fluid pad--lg">
<div class="row">
<div class="no-gutter col-2 flex flex-justify--center">
<div class="iris-checkbox" >
<input class="iris-checkbox__input" type="checkbox" />
<label class="iris-checkbox__label" ></label>
</div>
</div>
<div class="no-gutter col-10">
<span>RE: Application Status (1)</span>
</div>
</div>
</div>
</div>
</li>
<li class="iris-list-item" data-value="3">
<div class="iris-list-item__content">
<div class="container-fluid pad--lg">
<div class="row">
<div class="no-gutter col-2 flex flex-justify--center">
<div class="iris-checkbox" >
<input class="iris-checkbox__input" type="checkbox" />
<label class="iris-checkbox__label" ></label>
</div>
</div>
<div class="no-gutter col-10">
<span>RE: Application Status (2)</span>
</div>
</div>
</div>
</div>
</li>
<li class="iris-list-item" data-value="4" >
<div class="iris-list-item__content">
<div class="container-fluid pad--lg">
<div class="row">
<div class="no-gutter col-2 flex flex-justify--center">
<div class="iris-checkbox" >
<input class="iris-checkbox__input" type="checkbox" />
<label class="iris-checkbox__label" ></label>
</div>
</div>
<div class="no-gutter col-10">
<span>RE: Application Status (3)</span>
</div>
</div>
</div>
</div>
</li>
</ul>
Using Tiles and Records
Lists don't necessarily need to use iris-list-item__content
. Other options are using iris-tile
or iris-record
to get the visual style you need for your application.
Tiles have full rounded borders around them, while records have linear separations found in lists like those on mobile.
In the following examples we will use the Account Component since it is a likely candidate for having lists.
Tile Example
- Steve's Checking Account$1,000.00
- Bob's Checking Account$930.00
- Amy's Savings Account$5,000,000.00
<ul class="iris-list iris-list--actionable">
<li class="iris-list-item" data-value="1" aria-label="Steve's Checking Account">
<div class="iris-tile">
<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>
</li>
<li class="iris-list-item" data-value="2" aria-label="Bob's Checking Account">
<div class="iris-tile">
<div class="iris-account iris-account--multi-line" data-color="account-color-1">
<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>
</li>
<li class="iris-list-item" data-value="3" aria-label="Amy's Savings Account">
<div class="iris-tile">
<div class="iris-account iris-account--multi-line" data-color="account-color-2">
<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>
</li>
</ul>
Shaded Tile Example
- Steve's Checking Account$1,000.00
- Bob's Checking Account$930.00
- Amy's Savings Account$5,000,000.00
<ul class="iris-list iris-list--actionable">
<li class="iris-list-item" data-value="1" aria-label="Steve's Checking Account">
<div class="iris-tile iris-tile--shaded">
<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>
</li>
<li class="iris-list-item" data-value="2" aria-label="Bob's Checking Account">
<div class="iris-tile iris-tile--shaded">
<div class="iris-account iris-account--multi-line" data-color="account-color-1">
<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>
</li>
<li class="iris-list-item" data-value="3" aria-label="Amy's Savings Account">
<div class="iris-tile iris-tile--shaded">
<div class="iris-account iris-account--multi-line" data-color="account-color-2">
<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>
</li>
</ul>
Record Example
- Steve's Checking Account$1,000.00
- Bob's Checking Account$930.00
- Amy's Savings Account$5,000,000.00
<ul class="iris-list iris-list--actionable">
<li class="iris-list-item" data-value="1" aria-label="Steve's Checking Account">
<div class="iris-record pad--lg">
<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>
</li>
<li class="iris-list-item" data-value="2" aria-label="Bob's Checking Account">
<div class="iris-record pad--lg">
<div class="iris-account iris-account--multi-line" data-color="account-color-1">
<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>
</li>
<li class="iris-list-item" data-value="3" aria-label="Amy's Savings Account">
<div class="iris-record pad--lg">
<div class="iris-account iris-account--multi-line" data-color="account-color-2">
<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>
</li>
</ul>
Disabled Items in List
You may want to display a list item but not allow it to be selected. This can be achieved by adding the disabled
attribute to one of the iris-list-item
.
- RE: Application Status
- RE: Application Status (1)
- RE: Application Status (2)
- RE: Application Status (3)
<ul id="actionable_list_disabled_item" class="iris-list iris-list--actionable">
<li class="iris-list-item" data-value="1">
<div class="iris-list-item__content">RE: Application Status</div>
</li>
<li class="iris-list-item" data-value="2" disabled>
<div class="iris-list-item__content">RE: Application Status (1)</div>
</li>
<li class="iris-list-item" data-value="3">
<div class="iris-list-item__content">RE: Application Status (2)</div>
</li>
<li class="iris-list-item" data-value="4">
<div class="iris-list-item__content">RE: Application Status (3)</div>
</li>
</ul>
Alternate Syntax List
The list doesn't have to be <ul>
<li>
structured either. We can use other list type elements or even plain <div>
if it makes sense. The component will make sure it makes sense to the screen readers.
<div class="iris-list iris-list--static">
<div class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status</div>
</div>
<div class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (1)</div>
</div>
<div class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (2)</div>
</div>
<div class="iris-list-item">
<div class="iris-list-item__content">RE: Application Status (3)</div>
</div>
</div>
Accessibility
As always, we want all of the components in the application to be accessible. Please keep the following notes in mind while using this component:
- If the List Items are Rich Media, an
aria-label
is most likely appropriate. - Due to the ARIA spec, Lists may not respect
aria-hidden
when reading selected options. Anaria-label
should be attached to these options. - Rich Media options should not contain interactive content unless using a Static List. Some users may not be able to interact with this content.
Accessibility that List provides for you:
- Handles the roles for the list items based on what variant of list you are using.
- for all intents and purposes makes the list act 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 ListComponent Object of an Element
var element = document.getElementById('test_iris_list');
var listComponent = Alkami.Iris.ListComponent.componentForElement(element);
Getting the selected value or values on change
var element = document.getElementById('test_iris_list');
element.addEventListener('change', function(event) {
var value = event.detail.value;
if(typeof value === 'string') {
console.log('The selected value is: ', value);
} else { // aria-multiselectable is enabled.
console.log('The selected values are: ', value);
}
});
Select a List Item Programmatically
There are two ways to select a list Item.
- By value - This is useful for times when you only have the value available to you such as by url parameter. A list with
aria-multiselectable
will be able to accept an array of values. - By List Item - This is generally useful when you are passing around the List Items directly such as default initialization. This method of selecting only accepts an array.
var myListItem = listComponent.listItems[0];
listComponent.value = myListItem.value; // can be array of strings as well.
// or
listComponent.selectedListItems = [ myListItem ];
Programmatically Add List Items to a List
var element = document.getElementById('test_iris_list');
var names = ['Steve', 'Bob', 'Amy'];
names.forEach(function(name, index) {
var listItemElement = Alkami.Iris.ListItem.createElement(index, name);
element.appendChild(listItemElement);
});
Events
Events fire on the source Element.
Name | Description |
---|---|
change | Fires when a new List Item is selected in the List. The detail property provides the value and component properties. |
Constructors
new ListComponent(element)
element
- Theiris-list
Element.
Creates a new List Component.
new ListItem(element)
element
= theiris-list-item
Element.
Creates a new List Item for use with the List Component.
Methods
static ListComponent.init()
Initializes any new List Components found. Returns an array of ListComponent
.
static ListComponent.componentForElement(sourceElement)
sourceElement
- The element that may be a ListComponent.
Checks if a DOM element has a ListComponent
object associated with it. Returns the ListComponent
object if one exists or null if one is not found.
static ListItem.createElement(value, textOrHtmlElement): HTMLLIElement
value
- The string value associated with the ListItem element put intodata-value
.textOrHtmlElement
- the text string or HTMLElement that will be inserted into the ListItem element.
Properties
static ListItem.VARIANTS
- VariantType
static, actionable, or checkable
list.activeListItem
- ListItem
Set/Get the List Item that is currently active for the keyboard user.
list.activeListItemIndex
- number
Get the index of the active List Item base on the component's listItem's array.
list.element
- HTMLElement
Get the element that is associated to the Component.
list.listItems
- ListItem[]
Get the List Items that are associated to this List. read-only
list.readonly
- boolean
Get if the list is readonly (static variant). read-only
list.selectedListItems
- ListItem[]
Set/Get the selected List Items.
list.value
- string or string[]
Set/Get the selected List Items by value. Takes a string[] if multiselectable or string if not.
list.variant
- VariantType
Set/Get the variant type of the list component.
listItem.active
- boolean
Set/Get the active state of the List Item.
listItem.disabled
- boolean
Set/Get the disabled state of the List Item.
listItem.element
- HTMLElement
Get the element associated to the List Item. read-only
listItem.id
- string
Set/Get the id associated to the List Item Element.
listItem.readonly
- boolean
Set/Get the read only state of the List Item.
listItem.selected
- boolean
Set/Get the selected state of the List Item.
listItem.text
- string
Get innerText or aria-label of the listItem. read-only
listItem.value
- string
Set/Get the value of the List Item.
Variables
The variables used in this component are as follows:
// Background
$list-item-selected: $alice-blue !default;
$list-item-active: $wild-sand !default;
// Border
$list-item-selected-border: $mystic-blue !default;
$list-item-active-border: $alto !default;
Themeability
The selected List Item on an Actionable List is themeable.
// Background
$list-item-selected: $alice-blue !default;
// Border
$list-item-selected-border: $mystic-blue !default;