List

Lists are a collection of elements that are related by context and a functional state.

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

Do break up data-intensive or lengthy lists

Do display list information in a logical way, in consecutive or alphabetical order

Don't display list items in a row

Do display list information in a logical way, in consecutive or alphabetical order

Lists are a collection of elements that are related by context and a functional state.

Coming soon...

Please enjoy a cat while you wait

Lists are a collection of elements that are related by context and a functional state.

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)

 The selected value is: Nothing 

<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 
 **123 
  $1,000.00 
 Bob's Checking Account 
 **456 
  $930.00 
 Amy's Savings Account 
 **789 
  $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 
 **123 
  $1,000.00 
 Bob's Checking Account 
 **456 
  $930.00 
 Amy's Savings Account 
 **789 
  $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 
 **123 
  $1,000.00 
 Bob's Checking Account 
 **456 
  $930.00 
 Amy's Savings Account 
 **789 
  $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.

RE: Application Status
RE: Application Status (1)
RE: Application Status (2)
RE: Application Status (3)

<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. An aria-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 - The iris-list Element.

Creates a new List Component.

new ListItem(element)

element = the iris-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 into data-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;