KeyboardPrefixCursorMixin

Lets a user navigate an item cursor by typing the beginning of items

Overview

Purpose: handles list box-style prefix typing, in which the user can type a string to move to the first item that begins with that string.

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

events → methodssetState → render DOM → post-render

Expects the component to provide:

  • [internal.state].texts state member containing an array of text strings corresponding to the text content of the current set of items. You can supply that with ItemsTextMixin.
  • currentIndex state member, e.g., via ItemsCursorMixin.
  • internal.keydown method, usually defined by KeyboardMixin.

Provides the component with:

  • Mappings of keyboard events to cursor operations.

Usage

import ItemsCursorMixin from "elix/src/base/ItemsCursorMixin.js";
import ItemsTextMixin from "elix/src/base/ItemsTextMixin.js";
import KeyboardMixin from "elix/src/base/KeyboardMixin.js";
import KeyboardPrefixCursorMixin from "elix/src/base/KeyboardPrefixCursorMixin.js";

class MyElement extends ItemsCursorMixin(
  ItemsTextMixin(KeyboardMixin(KeyboardPrefixCursorMixin(HTMLElement)))
) {}

Example

Acai
Akee
Apple
Apricot
Avocado
Banana
Bilberry
Black sapote
Blackberry
Blackcurrant
Blood orange
Blueberry
Boysenberry
Cantaloupe
Cherimoya
Cherry
Chico fruit
Clementine
Cloudberry
Coconut
Crab apple
Cranberry
Cucumber
Currant
Damson
Date
Dragonfruit
Durian
Elderberry
Feijoa
Fig
Goji berry
Gooseberry
Grape
Grapefruit
Guava
Honeyberry
Honeydew
Horned melon
Huckleberry
Jabuticaba
Jackfruit
Jambul
Japanese plum
Jostaberry
Jujube
Juniper berry
Kiwifruit
Kumquat
Lemon
Lime
Longan
Loquat
Lychee
Mandarin
Mango
Mangosteen
Marionberry
Miracle fruit
Mulberry
Nance
Nectarine
Orange
Papaya
Passionfruit
Peach
Pear
Persimmon
Pineapple
Pineberry
Plantain
Plum
Pluot
Pomegranate
Pomelo
Purple mangosteen
Quince
Rambutan
Raspberry
Redcurrant
Salak
Salal berry
Salmonberry
Satsuma
Soursop
Star apple
Star fruit
Strawberry
Surinam cherry
Tamarillo
Tamarind
Tangerine
Ugli fruit
Watermelon
White currant
White sapote
Yuzu
Demo: A list box that supports prefix typing

If this component receives the focus, and you press the "b" or "B" key, the "Banana" item will be selected, because it's the first item that matches the prefix "b". (Matching is case-insensitive.) If you now presses the "l" or "L" key quickly, the prefix to match becomes "bl", so "Blackberry" will be selected.

The prefix typing feature has a one second timeout — the prefix to match will be reset after a second has passed since you last typed a key. If, in the above example, you wait a second between typing "b" and "l", the timeout will reset the prefix to empty. When the "l" key is pressed, "Lemon" will be selected.

If you press the Backspace key, the last character is removed from the prefix under construction. This re-selects the first item that matches the new, shorter prefix. Suppose you type "c", and "Cantaloupe" is selected, then type "h" to select "Cherry". If you now immediately press Backspace (before the aforementioned one second timeout elapses), the prefix will revert to "C", and "Cantaloupe" will be reselected.

Extracting item text

To extract the text of an item, the mixin invokes a method internal.getItemText on each item. The default behavior of that method is to return the item's aria-label attribute, alt attribute or, if that does not exist, its textContent. This allows a component user to customize which text the prefix will be matched against.

API

Used by classes FilterListBox, ListBox, Menu, MultiSelectListBox, OptionList, PlainFilterListBox, PlainListBox, PlainMenu, PlainMultiSelectListBox, and PlainOptionList.

goToItemWithPrefix(prefix) method

Go to the first item whose text content begins with the given prefix.

Parameters:

  • prefix: stringThe prefix string to search for

Returns: boolean