Widget: iconList

IconList is a ListBox where the items (options) in the list are arranged in a grid; across then down. All the items in the list must be the same size; height and width set with CSS. Arrow key movement is naturally extended to two dimensions. The number of columns depends on the width of the iconList element. The iconList does not handle scrolling the item contents but it can be put inside a container that does scroll.

The expected markup (for best accessibility) is a UL (or OL) containing LI elements, however it only depends on a single parent element where all the children are the items. The initially selected item(s) can be indicated by giving the item(s) a class of "is-selected". The contents of the item is mostly of no concern to this widget but typically include an icon and a label. The contents should not overflow (spill outside of) the item. The item content cannot have interactive elements such as inputs or buttons.

The primary purpose of an itemList is to allow the user to select one or more items. It also supports type to select, copy to clipboard, context menus, and item activation. Items are activated with double click (single click in navigation mode) or the Enter key. When activated the activate callback is called. This can be used to perform an action such as opening a dialog or navigating.

Navigation Mode

As an alternative to selection an iconList has a navigation mode where the list items are essentially links. A single click on the item will activate it. This is controlled with the iconList#navigation option. If the item is or contains an anchor the default behavior for activation is to navigate to the href value. (only one anchor per item is allowed.) When used for navigation the widget should be wrapped in an element with role navigation.

Selection

An iconList can support single or multiple selection. See option iconList#multiple.

It is also possible to include a checkbox for multiple selection using the iconList#itemSelector option. The item markup can include <span class="u-selector"></span> if checkbox selection is desired. Must also set option itemSelector to true. If the markup doesn't contain this u-selector span then it can be added for you if option iconList#addItemSelector is true.

On a touch enabled device where the user has interacted with touch a multi select iconList will automatically enable checkbox selection.

Like options in a select element the option items can have a value using the data-value attribute.

Context Menus

The iconList has easy integration with the menu widget to provide context menu support. The iconList#contextMenu option is used to provide a menu widget options object. When the contextMenu option is used the menu#event:beforeOpen event/callback ui argument has these additional properties:

• menuElement: The menu jQuery object.
• iconList: This iconList jQuery object.
• selection: A jQuery object with the selected items at the time the menu was opened.

Also the menu#event:afterClose event/callback will automatically focus the iconList if the menu action didn't take the focus and the ui argument has these additional properties:

• menuElement: The menu jQuery object.
• iconList: This iconList jQuery object.

If using the contextMenu option the iconList#contextMenuId option can be used to give the menu element an ID. This is useful if other code must refer to the menu element or widget.

You can reference an already existing menu widget by specifying the iconList#contextMenuId in place of the iconList#contextMenu option.

If for any reason you don't want to use the menu widget, the iconList#contextMenuAction option allows you to respond to mouse or keyboard interactions that typically result in a context menu. Specifically Right Mouse click (via contextmenu event), Shift-F10 key (via keydown event) and the Windows context menu key (via contextmenu event). The original event is passed to the contextMenuAction function. The event object can be used to position the menu. If you implement your own menu it is best if you put focus back on the iconList using the iconList#focus method when the menu closes (unless the menu action directs focus elsewhere).

Only one of iconList#contextMenuAction and iconList#contextMenu or iconList#contextMenuId can be specified. The contextMenu and contextMenuId options can only be set when the iconList is initialized and it can't be changed. The contextMenuAction cannot be set if the contextMenu or contextMenuId options were given when the iconList was created.

Accessibility

For accessibility the iconList should be labeled by using the aria-labelledby attribute to point to an element that contains the label. The widget will append text for screen readers only that indicates the number of rows and columns. For best accessibility when used for navigation the markup should be a div with anchor children as shown in second example in the initializer section.

For accessibility make sure that any images or icons used in the items have a text alternative if appropriate.

Keyboard End User Information

Key	Action
Up Arrow	Move focus to the item in the current column of the previous row.
Down Arrow	Move focus to the item in the current column of the next row.
Right Arrow	Move focus to the next item in the current row wrapping to the next row at the end.
Left Arrow	Move focus to the previous item in the current row wrapping to the previous row at the start.
Home	Move focus to the first item.
End	Move focus to the last item.
Space	Selects the focused item.
Enter	Activates the selected items.
printable characters	Sets focus to the next item with a label that starts with the typed character(s).

Typically when an item receives focus it is also selected. For a multiple selection iconList the Shift and Ctrl modifier keys can be used in combination with the home, end, and arrow keys to affect the selection. The Shift key extends the selection to include the items between the anchor item (the first single item selected) and the current focused item. The Ctrl key moves the focus without affecting the selection. The space key can then be used to select the focused item or Ctrl+Space to toggle the item selection.

Initializer

$(".selector").iconList(options)

Creates an iconList widget.

Parameters:

Name	Type	Description
options	Object	A map of option-value pairs to set on the widget.

Since:

• 5.0

Examples

Create a simple iconList for selecting multiple items.

HTML:
<h3 id="iconsLabel">My Icons</h3>
<ul id="icons1" aria-labelledby="iconsLabel">
    <li data-value="b"><span class="fa fa-bus"></span><span class="label">Bus</span></li>
    <li class="is-selected" data-value="c"><span class="fa fa-car"></span><span class="label">Car</span></li>
    <li data-value="t"><span class="fa fa-taxi"></span><span class="label">Taxi</span></li>
    ...
</ul>
JavaScript:
$("#icons1").iconList({
    multiple: true
});

This example creates an iconList for navigation. In this example #navList is the element that becomes the iconList widget.

HTML:
<h2 id="mainNav">Main Site Navigation</h2>
<div role="navigation">
  <div id="navList" aria-labelledby="mainNav">
      <a href=...>...</a>
      ...
  </div>
</div>
JavaScript:
$("#navList").iconList({
    navigation: true
});

$( ".selector" ).iconList({
    activate: function( event, data ) {}
});

$( ".selector" ).on( "iconlistactivate", function( event, data ) {} );

$( ".selector" ).iconList({
    selectionChange: function( event ) {}
});

$( ".selector" ).on( "iconlistselectionchange", function( event ) {} );