Skip to main content
Version: 1.x

fast-listbox

An implementation of a listbox. While any DOM content is permissible as a child of the listbox, only fast-option elements, option elements, and slotted items with role="option" will be treated as options and receive keyboard support.

The listbox component has no internals related to form association. For a form-associated listbox, see the fast-select component.

Setup

import {
provideFASTDesignSystem,
fastListbox,
fastOption,
} from "@microsoft/fast-components";

provideFASTDesignSystem().register(fastListbox(), fastOption());

Usage

Live Editor
<div>
    <label id="preferred-format">Preferred Format:</label>
    <br />
    <fast-listbox aria-labelledby="preferred-format" name="preferred-format">
        <fast-option value="vinyl">Vinyl Record</fast-option>
        <fast-option value="casette">Casette</fast-option>
        <fast-option value="cd">Compact Disc</fast-option>
        <fast-option value="digital">Digital</fast-option>
    </fast-listbox>
</div>
Result
Loading...

Create your own design

Listbox

import { Listbox, listboxTemplate as template } from "@microsoft/fast-foundation";
import { listboxStyles as styles } from "./my-listbox.styles";

export const myListbox = Listbox.compose({
baseName: "listbox",
template,
styles,
});

Option

See listbox-option for more information.

API

class: ListboxElement

Superclass

NameModulePackage
Listbox/src/listbox/listbox.js

Static Fields

NamePrivacyTypeDefaultDescriptionInherited From
slottedOptionFilterpublicA static filter to include only selectable options.Listbox

Fields

NamePrivacyTypeDefaultDescriptionInherited From
multiplepublicbooleanIndicates if the listbox is in multi-selection mode.
sizepublicnumberThe maximum number of options to display.
lengthpublicnumberThe number of options.Listbox
optionspublicListboxOption[]The list of options.Listbox
typeAheadExpiredprotectedListbox
disabledpublicbooleanThe disabled state of the listbox.Listbox
selectedIndexpublicnumber-1The index of the selected option.Listbox
selectedOptionspublicListboxOption[][]A collection of the selected options.Listbox
$presentationpublicComponentPresentation or nullA property which resolves the ComponentPresentation instance for the current component.FoundationElement
templatepublicElementViewTemplate or void or nullSets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.FoundationElement
stylespublicElementStyles or void or nullSets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition.FoundationElement

Methods

NamePrivacyDescriptionParametersReturnInherited From
setSelectedOptionspublicSets an option as selected and gives it focus.Listbox
selectFirstOptionpublicMoves focus to the first selectable option.voidListbox
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Attributes

NameFieldInherited From
multipleListbox
multipleListbox

class: Listbox

Superclass

NameModulePackage
FoundationElement/src/foundation-element/foundation-element.js

Static Fields

NamePrivacyTypeDefaultDescriptionInherited From
slottedOptionFilterpublicA static filter to include only selectable options.

Fields

NamePrivacyTypeDefaultDescriptionInherited From
lengthpublicnumberThe number of options.
optionspublicListboxOption[]The list of options.
typeAheadExpiredprotected
disabledpublicbooleanThe disabled state of the listbox.
selectedIndexpublicnumber-1The index of the selected option.
selectedOptionspublicListboxOption[][]A collection of the selected options.
$presentationpublicComponentPresentation or nullA property which resolves the ComponentPresentation instance for the current component.FoundationElement
templatepublicElementViewTemplate or void or nullSets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.FoundationElement
stylespublicElementStyles or void or nullSets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition.FoundationElement

Methods

NamePrivacyDescriptionParametersReturnInherited From
selectFirstOptionpublicMoves focus to the first selectable option.void
setSelectedOptionspublicSets an option as selected and gives it focus.
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Attributes

NameFieldInherited From
disabled

Slots

NameDescription
The default slot for the listbox options

class: DelegatesARIAListbox

Fields

NamePrivacyTypeDefaultDescriptionInherited From
ariaActiveDescendantpublicstring or nullSee https://www.w3.org/TR/wai-aria-1.2/#listbox for more information
ariaDisabledpublic"true" or "false" or string or nullSee https://www.w3.org/TR/wai-aria-1.2/#listbox for more information
ariaExpandedpublic"true" or "false" or string or nullSee https://www.w3.org/TR/wai-aria-1.2/#listbox for more information
ariaMultiSelectablepublic"true" or "false" or string or nullSee https://w3c.github.io/aria/#listbox for more information

Additional resources