SingleSelectAPIMixin

Overview

Purpose: Provides a public API for setting and retrieving the selected item.

This mixin works in the middle of the Elix render pipeline:

events → methods ➞ setState → render DOM → post-render

Expects the component to provide:

• items state member representing the items that can be selected. This is usually provided by ContentItemsMixin.
• currentIndex state member indicating the current item, which the mixin will interpret as the selected item. This is typically defined via ItemsCursorMixin.

Provides the component with:

• selectedIndex and selectedItem properties to read or manipulate the selected index.
• selectedindexchange event.

Usage

import ContentItemsMixin from "elix/src/base/ContentItemsMixin.js";
import ItemsCursorMixin from "elix/src/base/ItemsCursorMixin.js";
import SingleSelectAPIMixin from "elix/src/base/SingleSelectAPIMixin.js";

class MyElement extends ContentItemsMixin(
  ItemsCursorMixin(SingleSelectAPIMixin(HTMLElement))
) {}

SingleSelectAPIMixin is designed to support components that let the user select a single thing at a time. This is generally done to let the user select a value (e.g., as the target of an action, or in configuring something), or as a navigation construct (where only one page/mode is visible at a time).

Examples:

• List boxes such as ListBox.
• Dropdown lists and combo boxes
• Carousels such as Carousel.
• Slideshows
• Tab UIs (including top-level navigation toolbars that behave like tabs) such as Tabs.

Example

// A sample element that supports single-selection on its children.
class SimpleList extends SingleSelectAPIMixin(ReactiveMixin(HTMLElement)) {
  get items() {
    return this.children;
  }
}

const list = new SimpleList();
list.innerHTML = `
  <div>Zero</div>
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
  <div>Four</div>
`;
list.selectedIndex = 0; // Select the first item
list.selectedItem; // <div>Zero</div>
list.selectedItem = list.items.indexOf(list.items[1]);
list.selectedIndex; // 1

The following is a slightly expanded demo of the above, adding the ability to click an item to select it, and styling to highlight the selected item with color:

Here, the currently-selected item is tracked with SingleSelectAPIMixin.