Skip to main content

fast-combobox

As defined by the W3C:

A combobox is an input widget with an associated popup that enables users to select a value for the combobox from a collection of possible values. In some implementations, the popup presents allowed values, while in other implementations, the popup presents suggested values, and users may either select one of the suggestions or type a value. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical Open button adjacent to the combobox, which indicates availability of the popup. Activating the Open button displays the popup if suggestions are available.

Setup​

Basic Setup​

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

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

Customizing the indicator​

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

provideFASTDesignSystem().register(
    fastCombobox({
        indicator: `...your indicator...`,
    }),
    fastOption()
);

Usage​

Live Editor
Result
Loading...

Create your own design​

Combobox​

import {
    Combobox,
    ComboboxOptions,
    comboboxTemplate as template,
} from "@microsoft/fast-foundation";
import { comboboxStyles as styles } from "./my-combobox.styles";

export const myCombobox = Combobox.compose<ComboboxOptions>({
    baseName: "combobox",
    template,
    styles,
    shadowOptions: {
        delegatesFocus: true,
    },
    indicator: `...default indicator...`,
});
note

This component is built with the expectation that focus is delegated to the input element rendered into the shadow DOM.

Option​

See listbox-option for more information.

API​

Variables​

NameDescriptionType
ComboboxAutocompleteAutocomplete values for combobox.{ inline: "inline", list: "list", both: "both", none: "none", }

class: Combobox​

Superclass​

NameModulePackage
FormAssociatedCombobox/src/combobox/combobox.form-associated.js

Static Fields​

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

Fields​

NamePrivacyTypeDefaultDescriptionInherited From
autocompletepublicComboboxAutocomplete or undefinedThe autocomplete attribute.
filteredOptionspublicListboxOption[][]The collection of currently filtered options.
openpublicbooleanfalseThe open attribute.
optionspublicListboxOption[]The list of options.Listbox
placeholderpublicstringSets the placeholder value of the element, generally used to provide a hint to the user.
positionAttributepublicSelectPosition or undefinedThe placement for the listbox when the combobox is open.
positionpublicSelectPosition or undefinedThe current state of the calculated position of the listbox.
valuepublicThe value property.
proxyFormAssociatedCombobox
lengthpublicnumberThe number 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
positionChangedprotectedprev: SelectPosition or undefined, next: SelectPosition or undefinedvoid
filterOptionspublicFilter available options by text value.void
setPositioningpublicCalculate and apply listbox positioning based on available viewport space.forcevoid
selectFirstOptionpublicMoves focus to the first selectable option.voidListbox
setSelectedOptionspublicSets an option as selected and gives it focus.Listbox
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Events​

NameTypeDescriptionInherited From
changeFires a custom 'change' event when the value updates

Attributes​

NameFieldInherited From
autocompleteautocomplete
openopen
placeholderplaceholder
positionpositionAttribute
disabledListbox

CSS Parts​

NameDescription
controlThe wrapper element containing the input area, including start and end
selected-valueThe input element representing the selected value
indicatorThe element wrapping the indicator slot
listboxThe wrapper for the listbox slotted options

Slots​

NameDescription
startContent which can be provided before the input
endContent which can be provided after the input
controlUsed to replace the input element representing the combobox
indicatorThe visual indicator representing the expanded state
The default slot for the options

class: DelegatesARIACombobox​

Fields​

NamePrivacyTypeDefaultDescriptionInherited From
ariaAutoCompletepublic"inline" or "list" or "both" or "none" or string or nullSee https://www.w3.org/TR/wai-aria-1.2/#aria-autocomplete for more information.
ariaControlspublicstring or nullSee https://www.w3.org/TR/wai-aria-1.2/#aria-controls for more information.

Additional resources​