API Documentation

ListBox ⇐ ElementBase

A single-selection list box that supports selection highlighting (using the system highlight color) and keyboard navigation.

Live demo

The user can select an item with the mouse/touch or keyboard: Up/Down, Page Up/Down, Home/End.

Like other Basic Web Components, this can handle distributed content: you can include a content element inside a basic-list-box, and the list will navigate through the distributed content.

This component includes basic ARIA support to provide a reasonable default experience, e.g., for screen readers. The list component itself will be assigned an appropriate ARIA role (default is "listbox"). The ID of the selected item will be reflected in an "aria-activedescendant" attribute applied to the list. To support this feature, all items in the list need unique IDs. If an item does not have an ID, basic-list-box will automatically assign a default ID.

The keyboard interaction model generally follows that of Microsoft Windows' list boxes instead of those in OS X:

• The Page Up/Down and Home/End keys actually move the selection, rather than just scrolling the list. The former behavior seems more generally useful for keyboard users.

• Pressing Page Up/Down will move the selection to the topmost/bottommost visible item if the selection is not already there. Thereafter, the key will move the selection up/down by a page, and (per the above point) make the selected item visible.

Programmatically selecting an item (by setting the selected property) scrolls the item into view.

The user can also select an item by typing the beginning of an item's text.

Kind: global class Extends: ElementBase
Mixes: ClickSelection , ContentAsItems , DirectionSelection , DistributedChildrenAsContent , Generic , ItemsSelection , Keyboard , KeyboardDirection , KeyboardPagedSelection , KeyboardPrefixSelection , ObserveContentChanges , SelectionAriaActive , SelectionHighlight , SelectionInView , TargetInCollective

• ListBox ⇐ ElementBase
  • .applySelection(item, selected)
  • .applySelection(item, selected)
  • .canSelectNext : boolean
  • .canSelectPrevious : boolean
  • .content : Array.<HTMLElement>
  • "content-changed"
  • .contentChanged()
  • .generic : Boolean
  • .goDown()
  • .goEnd()
  • .goLeft()
  • .goRight()
  • .goStart()
  • .goUp()
  • .itemAdded(item)
  • .itemAdded(item)
  • .items : Array.<HTMLElement>
  • "items-changed"
  • .itemsChanged()
  • .keydown(event) ⇒ boolean
  • .navigationAxis : string
  • .pageDown()
  • .pageUp()
  • .scrollItemIntoView(item)
  • .scrollTarget : HTMLElement
  • .scrollTarget : HTMLElement
  • "selected-index-changed"
  • "selected-item-changed"
  • .selectedIndex : number
  • .selectedItem : object
  • .selectFirst()
  • .selectionRequired : boolean
  • .selectionWraps : boolean
  • .selectItemWithTextPrefix(prefix)
  • .selectLast()
  • .selectNext()
  • .selectPrevious()
  • .target : HTMLElement
  • .value : string
  • "value-changed"

listBox.applySelection(item, selected)

Apply the selection state to a single item.

Invoke this method to signal that the selected state of the indicated item has changed. By default, this applies a selected CSS class if the item is selected, and removed it if not selected.

Kind: instance method of ListBox. Defined by ContentAsItems mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | The item whose selection state has changed. | | selected | boolean | True if the item is selected, false if not. |

listBox.applySelection(item, selected)

Apply the indicate selection state to the item.

The default implementation of this method does nothing. User-visible effects will typically be handled by other mixins.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | the item being selected/deselected | | selected | boolean | true if the item is selected, false if not |

listBox.canSelectNext : boolean

True if the selection can be moved to the next item, false if not (the selected item is the last item in the list).

Kind: instance property of ListBox. Defined by ItemsSelection mixin.

listBox.canSelectPrevious : boolean

True if the selection can be moved to the previous item, false if not (the selected item is the first one in the list).

Kind: instance property of ListBox. Defined by ItemsSelection mixin.

listBox.content : Array.<HTMLElement>

The content of this component, defined to be the flattened array of children distributed to the component.

Kind: instance property of ListBox. Defined by DistributedChildrenAsContent mixin.

"content-changed"

This event is raised when the component's contents (including distributed children) have changed.

Kind: event emitted by ListBox. Defined by ObserveContentChanges mixin.

listBox.contentChanged()

Invoked when the contents of the component (including distributed children) have changed.

This method is also invoked when a component is first instantiated; the contents have essentially "changed" from being nothing. This allows the component to perform initial processing of its children.

Kind: instance method of ListBox. Defined by ObserveContentChanges mixin.

listBox.generic : Boolean

True if the component would like to receive generic styling.

This property is true by default — set it to false to turn off all generic styles. This makes it easier to apply custom styling; you won't have to explicitly override styling you don't want.

Kind: instance property of ListBox. Defined by Generic mixin. Default: true

listBox.goDown()

Invoked when the user wants to go/navigate down. The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.goEnd()

Invoked when the user wants to go/navigate to the end (e.g., of a list). The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.goLeft()

Invoked when the user wants to go/navigate left. The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.goRight()

Invoked when the user wants to go/navigate right. The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.goStart()

Invoked when the user wants to go/navigate to the start (e.g., of a list). The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.goUp()

Invoked when the user wants to go/navigate up. The default implementation of this method does nothing.

Kind: instance method of ListBox. Defined by KeyboardDirection mixin.

listBox.itemAdded(item)

Handle a new item being added to the list.

The default implementation of this method simply sets the item's selection state to false.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | the item being added |

listBox.itemAdded(item)

This method is invoked whenever a new item is added to the list.

The default implementation of this method does nothing. You can override this to perform per-item initialization.

Kind: instance method of ListBox. Defined by ContentAsItems mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | The item that was added. |

listBox.items : Array.<HTMLElement>

The current set of items in the list. See the top-level documentation for mixin for a description of how items differ from plain content.

Kind: instance property of ListBox. Defined by ContentAsItems mixin.

"items-changed"

Fires when the items in the list change.

Kind: event emitted by ListBox. Defined by ContentAsItems mixin.

listBox.itemsChanged()

This method is invoked when the underlying contents change. It is also invoked on component initialization – since the items have "changed" from being nothing.

Kind: instance method of ListBox. Defined by ContentAsItems mixin.

listBox.keydown(event) ⇒ boolean

Handle the indicated keyboard event.

The default implementation of this method does nothing. This will typically be handled by other mixins.

Kind: instance method of ListBox. Defined by Keyboard mixin. Returns: boolean - true if the event was handled

| Param | Type | Description | | --- | --- | --- | | event | KeyboardEvent | the keyboard event |

listBox.navigationAxis : string

Indicates the direction of permitted navigation with the keyboard.

Accepted values are "horizontal", "vertical", or "both" (the default). If this property is "horizontal", the Up Arrow and Down Arrow keys will be ignored. Conversely, if this is "vertical", the Left Arrow and Right Arrow keys will be ignored.

Kind: instance property of ListBox. Defined by KeyboardDirection mixin.

listBox.pageDown()

Scroll down one page.

Kind: instance method of ListBox. Defined by KeyboardPagedSelection mixin.

listBox.pageUp()

Scroll up one page.

Kind: instance method of ListBox. Defined by KeyboardPagedSelection mixin.

listBox.scrollItemIntoView(item)

Scroll the given element completely into view, minimizing the degree of scrolling performed.

Blink has a scrollIntoViewIfNeeded() function that does something similar, but unfortunately it's non-standard, and in any event often ends up scrolling more than is absolutely necessary.

Kind: instance method of ListBox. Defined by SelectionInView mixin.

| Param | Type | Description | | --- | --- | --- | | item | HTMLElement | the item to scroll into view. |

listBox.scrollTarget : HTMLElement

The element that should be scrolled to bring an item into view.

The default value of this property is the element itself.

Kind: instance property of ListBox. Defined by SelectionInView mixin.

listBox.scrollTarget : HTMLElement

The element that should be scrolled with the Page Up/Down keys. Default is the current element.

Kind: instance property of ListBox. Defined by KeyboardPagedSelection mixin.

"selected-index-changed"

Fires when the selectedIndex property changes.

Kind: event emitted by ListBox. Defined by ItemsSelection mixin.

| Param | Type | Description | | --- | --- | --- | | detail.selectedIndex | number | The new selected index. |

"selected-item-changed"

Fires when the selectedItem property changes.

Kind: event emitted by ListBox. Defined by ItemsSelection mixin.

| Param | Type | Description | | --- | --- | --- | | detail.selectedItem | HTMLElement | The new selected item. | | detail.previousItem | HTMLElement | The previously selected item. |

listBox.selectedIndex : number

The index of the item which is currently selected.

If selectionWraps is false, the index is -1 if there is no selection. In that case, setting the index to -1 will deselect any currently-selected item.

Kind: instance property of ListBox. Defined by ItemsSelection mixin.

listBox.selectedItem : object

The currently selected item, or null if there is no selection.

Setting this property to null deselects any currently-selected item.

Kind: instance property of ListBox. Defined by ItemsSelection mixin.

listBox.selectFirst()

Select the first item in the list.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

listBox.selectionRequired : boolean

True if the list should always have a selection (if it has items).

Kind: instance property of ListBox. Defined by ItemsSelection mixin. Default: false

listBox.selectionWraps : boolean

True if selection navigations wrap from last to first, and vice versa.

Kind: instance property of ListBox. Defined by ItemsSelection mixin. Default: false

listBox.selectItemWithTextPrefix(prefix)

Select the first item whose text content begins with the given prefix.

Kind: instance method of ListBox. Defined by KeyboardPrefixSelection mixin.

| Param | Description | | --- | --- | | prefix | [String] The prefix string to search for |

listBox.selectLast()

Select the last item in the list.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

listBox.selectNext()

Select the next item in the list.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

listBox.selectPrevious()

Select the previous item in the list.

Kind: instance method of ListBox. Defined by ItemsSelection mixin.

listBox.target : HTMLElement

Gets/sets the current target of the component.

Set this to point to another element. That target element will be implicitly added to the component's collective. That is, the component and its target will share responsibility for handling keyboard events.

You can set this property yourself, or you can use the ContentFirstChildTarget mixin to automatically set the target to the component's first child.

Kind: instance property of ListBox. Defined by TargetInCollective mixin.

listBox.value : string

The text content of the selected item.

Setting this value to a string will attempt to select the first list item whose text content match that string. Setting this to a string not matching any list item will result in no selection.

Kind: instance property of ListBox

"value-changed"

Fires when the list's value property changes.

Kind: event emitted by ListBox