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
andselectedItem
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
.
API
Used by classes AutoCompleteComboBox, Carousel, CarouselSlideshow, CarouselWithThumbnails, CenteredStrip, CrossfadeStage, CrossfadeStage, DropdownList, Explorer, FilterComboBox, FilterListBox, ListBox, ListComboBox, ListExplorer, ListWithSearch, Menu, Modes, MultiSelectListBox, OptionList, PlainAutoCompleteComboBox, PlainCarousel, PlainCarouselSlideshow, PlainCarouselWithThumbnails, PlainCenteredStrip, PlainCenteredStripHighlight, PlainCenteredStripOpacity, PlainCrossfadeStage, PlainCrossfadeStage, PlainDropdownList, PlainExplorer, PlainFilterComboBox, PlainFilterListBox, PlainListBox, PlainListComboBox, PlainListExplorer, PlainListWithSearch, PlainMenu, PlainModes, PlainMultiSelectListBox, PlainOptionList, PlainSlideshow, PlainSlideshow, PlainSlideshowWithPlayControls, PlainSlideshowWithPlayControls, PlainSlidingPages, PlainSlidingStage, PlainTabs, PlainTabStrip, Slideshow, Slideshow, SlideshowWithPlayControls, SlideshowWithPlayControls, SlidingPages, SlidingStage, Tabs, and TabStrip.
selected Index property
The index of the selected item, or -1 if no item is selected.
Type: number
selectedindexchange event
Raised when the selectedIndex
property changes.
selected Item property
The selected item, or null if no item is selected.
Type: Element