Dropdown

Dropdowns allow selecting one or more items from a list.

Examples

Selected Item:

Usage

Do

  • Use when there is not enough space to display a list of options
  • Use when all the options available can be grouped under one control
  • Keep text concise within the dropdown
  • Carefully consider the way options are grouped within the dropdown menu
  • Use a dropdown field: in forms, when editable interaction is needed
  • Use a dropdown button: in headers, when advanced selection is needed

Don’t

  • Use for navigation
  • Include punctuation in labels (question mark, colon, etc.)

Anatomy

When triggered, a dropdown exposes a list of options. Upon selecting an item, the value updates to display the selected item.

Dropdown field

Dropdown field is the default dropdown type. It looks like a text field, and behaves as the HTML <select> element. Use a dropdown field:

  • In forms
  • When editable interaction is needed
Anatomy of the dropdown field
  • (1) Dropdown field
  • (2) Placeholder: Can be used when the dropdown doesn’t have a selected value
  • (3) Value
  • (4) Dropdown menu: Open when the dropdown field is triggered
  • (5) Selected item in menu
  • (6) Icon: Can be static or change depending on the selected value
  • (7) Loading row: Used when needed in dropdowns with async states
Different states of the dropdown field
  • (1) Rest
  • (2) Hover
  • (3) Pressed (showing current selection)

Dropdown button

A dropdown button looks like a menu button (standard or subtle), but it changes its value with the selected item. Use a dropdown button:

  • In headers
  • When advanced selection is needed
Anatomy of the dropdown button
  • (1) Dropdown button
  • (2) Selected item in menu
  • (3) Dropdown menu
  • (4) Label: Permanent text visible in the dropdown button that helps to identify the element
  • (5) Label and icon (pressed state)
  • (6) Advanced dropdown menu: Supports extra features like inline search, tabs, and multi-selection. It must use a dropdown button as a trigger.
Different states of the dropdown button
  • (1) Rest
  • (2) Hover
  • (3) Active
  • (4) Pressed

Menu item states

Different states of the menu item
  • (1) Rest
  • (2) Hover
  • (3) Active
  • (4) Selected
  • (5) Selected hover, and selected active
  • (6) Disabled
  • (7) Disabled hover
  • (8) Focused

Icons and labels

Dropdowns can include icons and labels to help identify their application and states. Icons can be statically defined for the entire dropdown, or change according to the selected value.

Changing icons

Changing icons within a dropdown

In this example the icon changes according to the state.

  • (1) Rest
  • (2) Pressed
  • (3) Rest

Static icons

Static icons within a dropdown

In this example, the icon remains the same for all values.

  • (1) Rest
  • (2) Hover
  • (3) Active
  • (4) Pressed
  • (5) Rest

Async dropdown states

Dropdown with async states

Dropdowns may include async requests if necessary. Whenever possible, make sure interacting with the dropdown can be done as quickly as possible — preloading the results without the user having to wait for a loading screen is always better.

  • (1) Async loading on start
  • (2) Async loading on fetching search results

Related

APIs

IDropdownProps<T = {}>

actionsInherited From: IDropdownCalloutProps<T = {}>
IReadonlyObservableArray<IButtonProps> | IButtonProps[]
Actions to render in the footer of the dropdown.
activatablefalseInherited From: ITextFieldProps
boolean
Whether or not the input can be activated. Text will not be selectable and a cursor: pointer will be used.
anchorElementInherited From: ICalloutProps
HTMLElement
If the callout is being positioned relative to an existing element in the DOM the relative element should be supplied as the anchorElement. (anchorOrigin should be supplied with anchorElement)
anchorOffsetInherited From: ICalloutProps
IOffset
anchorOffset is used to shift the location of the callout from the defined location by a fixed amount. An example might be the tooltip callout defaults to an anchorOffset of { x: 8 y: 8 } from the mouse position.
anchorOriginInherited From: ICalloutProps
IOrigin
When an anchorElement is supplied the anchorOrigin is used to describe the relative location of the callout with respect to the anchorElement. A common example here is a dropdown button aligns the callout to the bottom-right of the button.
anchorPointInherited From: ICalloutProps
IPoint
Instead of using an anchorElement to position the callout, if can be positioned based on a fixed location. The anchorPoint defines the fixed position for the anchor.
ariaActiveDescendantInherited From: ITextFieldProps
string
aria-activedescendant on the input/textfield.
ariaAutoCompleteInherited From: ITextFieldProps
"none" | "list" | "inline" | "both"
aria-autocomplete on the input/textfield.
ariaControlsInherited From: ITextFieldProps
string
aria-controls on the input/textfield.
ariaDescribedByInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-describedby to the Expandable element.
ariaExpandedInherited From: ITextFieldProps
boolean
aria-expanded on the input/textfield.
ariaHasPopupInherited From: ITextFieldProps
boolean | "menu" | "listbox" | "tree" | "grid" | "dialog"
aria-hasPopup on the input/textfield.
ariaInvalidInherited From: ITextFieldProps
boolean
aria-invalid on the input/textfield.
ariaLabelInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-label to the Expandable element.
ariaLabelledByInherited From: IDropdownExpandableProps<T = {}>
string
Adds aria-labelled-by to the Expandable element.
ariaRoleDescriptionInherited From: ITextFieldProps
string
aria-roledescription on the input/textfield.
autoAdjustHeightfalse.Inherited From: ITextFieldProps
boolean
Adjust the textfield height as the contents change.
autoCompletefalse.Inherited From: ITextFieldProps
boolean
Should the input tag have autocomplete enabled. Ignored if multiline is set to true.
autoFocusInherited From: ITextFieldProps
boolean
autoFocus on the input/textfield.
autoSelectInherited From: IDropdownExpandableProps<T = {}>
boolean
Supply autoSelect to select all the text in the input when the textfield gets focus. This is useful if you want the user to copy the text, or replace the text upon typing instead of changing the current value.
blurDismissfalseInherited From: ICalloutProps
boolean
This will dismiss the callout once it gets and then loses focus. Callouts should dismiss when they lose focus unless they are intended to be modeless UI.
calloutContentClassNameInherited From: IDropdownCalloutProps<T = {}>
string
ClassName to pass to the callout content. Use this to override the width.
classNameInherited From: IDropdownExpandableProps<T = {}>
string
ClassName to pass to the Expandable.
columnsInherited From: IListBoxSharedProps<T = {}>
Optional tree columns if showTree is passed
containerClassNameInherited From: IListBoxSharedProps<T = {}>
string
className to pass to the listbox's container.
containerRefInherited From: IDropdownExpandableProps<T = {}>
React.RefObject<HTMLDivElement>
Ref to pass to the expandable's container element.
contentLocationInherited From: ICalloutProps
This needs to be supplied for a window relative layout. Otherwise the anchorElement is used as the location basis.
disabledInherited From: IDropdownExpandableProps<T = {}>
boolean
Set to true to make the expandable disabled.
dismissOnSelect
boolean
Set to false to keep the callout open when an item is selected. By default the callout will close on select unless multiselect or selectOnFocus is enabled on selection.
dropdownIdInherited From: IExpandableTextFieldProps
string
Optional Id that should be used on the dropdown to uniquely identify this element.
dropdownOriginInherited From: IExpandableTextFieldProps
IOrigin
Location on the dropdown to make relative to the button location.
editableInherited From: IExpandableTextFieldProps
boolean
Whether or not textField is editable and should be treated like a combobox.
enforceSingleSelect
boolean
A custom way to force single-select options in a multi-select selection.
excludeFocusZoneInherited From: ITextFieldProps
boolean
Set to true if you don't want focus managed by a FocusZone.
excludeTabStopInherited From: IDropdownExpandableProps<T = {}>
boolean
The element should not be tabable but still should be able to receieve focus.
expandKeyKeyCode.DownArrowInherited From: IExpandableSharedProps
KeyCode | KeyCode[]
The key used to expand the components callout.
expandableRefrequiredInherited From: IDropdownExpandableProps<T = {}>
React.RefObject<ExpandableButton | ExpandableTextField>
A ref to forward to the expandable.
filterByText: true
boolean
Set to false to not do any text filtering when the user types in the filter box. Do this if you want to control filtering through userFilteredItems.
filterItem
(filterText: string, item: IListBoxItem<T>, items: IListBoxItem<T>[]) => boolean | number[]
Optional method to perform a custom filter of items based on filter text. If not provided, it will filter items based on item.text.
filterPlaceholderTextInherited From: IDropdownCalloutProps<T = {}>
string
Text to show as a placeholder in the filter box.
filterThrottleWait
number
The throttle wait time to use when updating the filter. The text field will still update on every keystroke, but the updating the filter itself will be throttled by this amount. The default value is 0 ms. Passing a value of 0 here will cause this text field not to be throttled.
filteredNoResultsTextInherited From: IDropdownCalloutProps<T = {}>
string | IObservableValue<string>
Text to display when there are no filter results. Will be formatted with the current filter string.
focusTreatmentTextFieldFocusTreatmentBehavior.allInherited From: ITextFieldProps
Indicates how we should apply the focus treatment to the TextField. Default is to show the focus treatment when focused via keyboard or mouse. TextFields that do not wish to have focus treatment (e.g. in the filter bar) should use "none"
getUnselectableRanges
(items: IListBoxItem<T>[]) => ISelectionRange[]
This is called when updates are made to the listBox items to update the unselectbale items in the selection.
hideDropdownIconInherited From: IExpandableTextFieldProps
boolean
If hideDropdownIcon is supplied the button acts as a dropdown button without showing the dropdown arrows.
inputClassNameInherited From: ITextFieldProps
string
Classname passed to the input/textarea element.
inputElementInherited From: ITextFieldProps
React.RefObject<HTMLTextAreaElement & HTMLInputElement>
ref to get passed to the input element.
inputIdInherited From: IDropdownExpandableProps<T = {}>
string
Id to be applied to the expandable's input element.
inputTypetextInherited From: ITextFieldProps
"password" | "text" | "button" | "number"
Type that is passed to the <input> element, e.g. password, number, etc. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types for a full list
itemsrequiredInherited From: IListBoxSharedProps<T = {}>
IItemProvider<IListBoxItem<T>> | IListBoxItem<T>[] | string[]
The caller may supply the set of items to be shown through the ItemProvider or array. The IItemProvider allows the caller to store their items in the form that bests suits their needs but gives the listbox a well defined interface for requesting the items. This can include async fetching of items through observables. Use an IItemProvider or something that implements it like ObservableArray If the items will be changing.
labelInherited From: ITextFieldProps
React.ReactNode
Label to be rendered before the TextField. Will be wrapped in a <label> element and wired up with the appropriate aria attributes.
lightDismissInherited From: ICalloutProps
boolean
The callout element will trap mouse events and dismiss the callout when a click occurs. This will prevent the events from being handled by the underlying elements outside the callout's contents.
loadingInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean>
Set to true or false to trigger screen reader loading announcements. To show a loading indicator, pass an item of type ListBoxItemType.Loading in items.
maxLengthInherited From: ITextFieldProps
number
MaxLength on the input/textarea.
maxWidthInherited From: ITextFieldProps
number
The maximum width in px that the textfield will grow to.
minCalloutWidth
number
Provide a minimum width for the callout
multilineInherited From: ITextFieldProps
boolean
If true, uses a textarea instead of an input element.
noItemsTextInherited From: IDropdownCalloutProps<T = {}>
string
Text to show when there are no items in the listbox.
onBlurInherited From: ITextFieldProps
() => void
Called when blur event is fired by the input/textarea.
onChangeInherited From: ITextFieldProps
(event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>, value: string) => void
Called when the value of the input/textarea changes.
onClickInherited From: ITextFieldProps
(event: React.MouseEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the element is clicked.
onCollapseInherited From: IDropdownExpandableProps<T = {}>
() => void
Optional callback to call when the dropdown is collapsed.
onDismissInherited From: ICalloutProps
() => void
Method that is called when the callout is dismissed.
onExpandInherited From: IDropdownExpandableProps<T = {}>
() => void
Optional callback to call when the dropdown is expanded.
onFilterTextChangedInherited From: IDropdownCalloutProps<T = {}>
(e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement> | null, newValue: string) => void
A callback to notify when the filter text has changed. Do custom searching here and update the items.
onFocusInherited From: ITextFieldProps
(event: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the focus event is fired by the input/textarea.
onKeyDownInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key down event is fired by the input/textarea.
onKeyPressInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onKeyUpInherited From: ITextFieldProps
(event: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the key press event is fired by the input/textarea.
onPasteInherited From: ITextFieldProps
(event: React.ClipboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void
Called when the paste event is fired by the input/textarea.
onSelectInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onSelect is called when the row is selected. Selection occurs on the Space keystroke or click. @param event - This is the event that is causing the selection. @param item - Details about the list row being selected.
onToggleInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onToggle is called when an item is either expanded or collapsed. This will only do anything if the list box is being displayed as a tree. @param event - This is the event that is causing the toggle. @param treeItem - Details about the list item being toggled.
placeholderInherited From: IDropdownExpandableProps<T = {}>
string
Text to show within the DropdownExpandable when there is no selected value.
portalPropsInherited From: ICalloutProps
The portalProps allow the caller to control how the Callout's portal are configured. The default will create the portal as a full screen element rooted in the body.
prefixIconPropsInherited From: ITextFieldProps
Props for the icon to be rendered before the input/textarea.
readOnlyfalseInherited From: ITextFieldProps
boolean
If the TextField should be read-only.
renderBeforeContentInherited From: IDropdownCalloutProps<T = {}>
() => JSX.Element | null
Custom content to render before the listbox in the dropdown.
renderCallout
(props: IDropdownCalloutProps) => JSX.Element
Function which returns the callout for this dropdpown.
renderExpandable
(props: IDropdownExpandableProps) => JSX.Element
Function which returns the Expandable for this dropdown.
renderItemInherited From: IListBoxSharedProps<T = {}>
(rowIndex: number, columnIndex: number, tableColumn: ITableColumn<IListBoxItem<T>>, tableItem: IListBoxItem<T>) => JSX.Element
If provided, this will be called on each item to determine how it's rendered.
renderSelectedItems
(selection: IListSelection, items: IListBoxItem<T>[]) => JSX.Element | string
Renderer for selected items in the expandable. Defaults to rendering the selected item's text.
requiredfalse.Inherited From: IDropdownExpandableProps<T = {}>
boolean
Indicates whether dropdown is required or not.
resizabletrue if the TextField is multiline.Inherited From: ITextFieldProps
boolean
If the text area should be resizable. Only used if multiline is true.
role
string
Optional aria role
rowsInherited From: ITextFieldProps
number
Number of rows the text area should have. Only used if multiline is set to true.
searchResultsLoadingTextInherited From: IListBoxSharedProps<T = {}>
string
String to show when a search is in progress.
searchingInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean | null>
Set to true to show a searching indicator in place of the list and make a screenreader announcement. Set to null to cancel a search without making an announcement.
selectionInherited From: IListBoxSharedProps<T = {}>
The selection maintains the selected state and defines the selection behavior of the list box. Defaults to a ListSelection with selectOnFocus set to false if not provided. Selection should be specified on mount and not updated to a new object during the Listbox's lifecycle.
showCharacterCounterInherited From: ITextFieldProps
boolean
If the character counter against the limit in the lower right corner should be displayed. Only used if maxLength is provided.
showChecksColumn
boolean
Whether or not to display a column with checks or checkboxes for selected items.
showItemsWhileSearchingfalseInherited From: IListBoxSharedProps<T = {}>
boolean
Set to true to show any current items while searching for more.
showPrefixtrueInherited From: IDropdownExpandableTextFieldProps
boolean
If the list item has an icon show the icon as the prefix icon in the text field.
showTreeInherited From: IListBoxSharedProps<T = {}>
boolean
Whether or not to display items as a tree rather than a list ListBox will construct a tree using the parent field of ListBoxItems
spellCheckundefined which will default to the browser's default for the input and textarea tags.Inherited From: ITextFieldProps
boolean
When true or false, overrides the default spellCheck behavior of the browser.
styleTextFieldStyle.normalInherited From: ITextFieldProps
Changes visual appearance of TextField. Use TextFieldStyle.inline to style as an inline text field.
suffixIconPropsInherited From: ITextFieldProps
Props for the icon to be rendered after the input/textarea.
tabIndexInherited From: ITextFieldProps
number
Sets the tabindex on the input/textarea element.
tooltipPropsInherited From: ITextFieldProps
Tooltip to show when the button is hovered.
userFilteredItemsInherited From: IDropdownCalloutProps<T = {}>
IItemProvider<IListBoxItem<T>> | IListBoxItem<T>[]
Provide if you want to show a custom set of filtered items. The items will still be filtered by text in the filterbox unless filterByText is false.
userFilteredItemsIndexMapInherited From: IDropdownCalloutProps<T = {}>
IReadonlyObservableValue<number[]>
Provides the original item index for each item in userFilteredItems. Optional, if not provided then this will be computed by traversing items for match indices, which can be slow if there are a lot of items.
valueInherited From: ITextFieldProps
IReadonlyObservableValue<string | undefined> | string
Text value of the input/textarea. This prop is 100% controlled by the consumer. onChange must also be implemented in order to work properly. If this value is a raw string, the prop must be updated to cause the TextField to re-render. If this value is an ObservableValue, then changing its value will cause the TextField to re-render.
width
number
Supply for a custom width for the callout. By default, the callout's width will be the same as the expandable. To change the expandable width, set a className.

IFilterResults<T>

filterMatches
number[][]
An array of indices of matches within each given item (used to bold the matching text)
filteredIndexMap
number[]
An arrary mapping each filteredItem to its index in the original items array
filteredItems
The array of items matching the filter

IListBoxProps<T = {}>

ariaLabel
string
ariaLabel allows the caller to describe the elements contents to assistive technology.
className
string
className to pass to the listbox.
columnsInherited From: IListBoxSharedProps<T = {}>
Optional tree columns if showTree is passed
containerClassNameInherited From: IListBoxSharedProps<T = {}>
string
className to pass to the listbox's container.
didUpdate
() => void
Callback to be called after the listBox renders.
enforceSingleSelect
boolean
A custom way to force single-select options in a multi-select selection.
excludeFocusZone
boolean
Set to true to exclude all listbox rows from focus zones.
excludeTabStop
boolean
Set to true to remove tab stops from the listbox rows.
focuszoneProps
focuszoneProps allows the caller to manage the how the list box rows are focused.
getUnselectableRangesInherited From: IListBoxSharedProps<T = {}>
(items: IListBoxItem<T>[]) => ISelectionRange[]
This is called when updates are made to the listBox items to update the unselectbale items in the selection.
itemsrequiredInherited From: IListBoxSharedProps<T = {}>
IItemProvider<IListBoxItem<T>> | IListBoxItem<T>[] | string[]
The caller may supply the set of items to be shown through the ItemProvider or array. The IItemProvider allows the caller to store their items in the form that bests suits their needs but gives the listbox a well defined interface for requesting the items. This can include async fetching of items through observables. Use an IItemProvider or something that implements it like ObservableArray If the items will be changing.
loadingInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean>
Set to true or false to trigger screen reader loading announcements. To show a loading indicator, pass an item of type ListBoxItemType.Loading in items.
onActivate
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onActivate is called when the row is activated. Activation occurs on the Enter keystroke or double click. @param event - This is the event that is causing the activation. @param tableRow - Details about the table row being activated.
onSelectInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onSelect is called when the row is selected. Selection occurs on the Space keystroke or click. @param event - This is the event that is causing the selection. @param item - Details about the list row being selected.
onToggleInherited From: IListBoxSharedProps<T = {}>
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onToggle is called when an item is either expanded or collapsed. This will only do anything if the list box is being displayed as a tree. @param event - This is the event that is causing the toggle. @param treeItem - Details about the list item being toggled.
renderItemInherited From: IListBoxSharedProps<T = {}>
(rowIndex: number, columnIndex: number, tableColumn: ITableColumn<IListBoxItem<T>>, tableItem: IListBoxItem<T>) => JSX.Element
If provided, this will be called on each item to determine how it's rendered.
searchResultsLoadingTextInherited From: IListBoxSharedProps<T = {}>
string
String to show when a search is in progress.
searchingInherited From: IListBoxSharedProps<T = {}>
boolean | Observable<boolean | null>
Set to true to show a searching indicator in place of the list and make a screenreader announcement. Set to null to cancel a search without making an announcement.
selectionInherited From: IListBoxSharedProps<T = {}>
The selection maintains the selected state and defines the selection behavior of the list box. Defaults to a ListSelection with selectOnFocus set to false if not provided. Selection should be specified on mount and not updated to a new object during the Listbox's lifecycle.
showChecksColumn
boolean
Whether or not to display a column with checks or checkboxes for selected items. False by default, unless `props.selection.multiSelect` which makes it default true.
showItemsWhileSearchingfalseInherited From: IListBoxSharedProps<T = {}>
boolean
Set to true to show any current items while searching for more.
showTreeInherited From: IListBoxSharedProps<T = {}>
boolean
Whether or not to display items as a tree rather than a list ListBox will construct a tree using the parent field of ListBoxItems
width100%Inherited From: IListBoxSharedProps<T = {}>
number
The width of the listbox.

IListBoxSharedProps<T = {}>

columns
Optional tree columns if showTree is passed
containerClassName
string
className to pass to the listbox's container.
getUnselectableRanges
(items: IListBoxItem<T>[]) => ISelectionRange[]
This is called when updates are made to the listBox items to update the unselectbale items in the selection.
itemsrequired
IItemProvider<IListBoxItem<T>> | IListBoxItem<T>[] | string[]
The caller may supply the set of items to be shown through the ItemProvider or array. The IItemProvider allows the caller to store their items in the form that bests suits their needs but gives the listbox a well defined interface for requesting the items. This can include async fetching of items through observables. Use an IItemProvider or something that implements it like ObservableArray If the items will be changing.
loading
boolean | Observable<boolean>
Set to true or false to trigger screen reader loading announcements. To show a loading indicator, pass an item of type ListBoxItemType.Loading in items.
onSelect
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onSelect is called when the row is selected. Selection occurs on the Space keystroke or click. @param event - This is the event that is causing the selection. @param item - Details about the list row being selected.
onToggle
(event: React.SyntheticEvent<HTMLElement>, item: IListBoxItem<T>) => void
onToggle is called when an item is either expanded or collapsed. This will only do anything if the list box is being displayed as a tree. @param event - This is the event that is causing the toggle. @param treeItem - Details about the list item being toggled.
renderItem
(rowIndex: number, columnIndex: number, tableColumn: ITableColumn<IListBoxItem<T>>, tableItem: IListBoxItem<T>) => JSX.Element
If provided, this will be called on each item to determine how it's rendered.
searchResultsLoadingText
string
String to show when a search is in progress.
searching
boolean | Observable<boolean | null>
Set to true to show a searching indicator in place of the list and make a screenreader announcement. Set to null to cancel a search without making an announcement.
selection
The selection maintains the selected state and defines the selection behavior of the list box. Defaults to a ListSelection with selectOnFocus set to false if not provided. Selection should be specified on mount and not updated to a new object during the Listbox's lifecycle.
showItemsWhileSearchingfalse
boolean
Set to true to show any current items while searching for more.
showTree
boolean
Whether or not to display items as a tree rather than a list ListBox will construct a tree using the parent field of ListBoxItems
width100%
number
The width of the listbox.

IListBoxItem<T = {}>

ariaLabeloptional
string
ariaLabel allows the caller to describe the element to assistive technology.
classNameoptional
string
className to pass to the item's cell.
dataoptional
T
Optional item data to be used in custom render function.
disabledoptional
boolean
Disabled items will get a disabled style by default and be ignored by focus and selection.
enforceSingleSelectoptional
boolean
A custom way to force single-select options in a multi-select selection.
expandedoptional
boolean
Expand this item when ListBox builds the tree
groupIdoptional
string
Provide to indicate this item belongs to a group. Use a GroupedItemProvider to arrange grouped items. This id is passed to the header html element for the group so it should be a valid html id.
hrefoptional
string
Provide to render the item as a Link.
iconPropsoptional
Props specifying the icon to render beside the item text.
id
string
Unique identifier of the item.
parentoptional
Optional parent of this item, used to build a tree in ListBox
renderoptional
(rowIndex: number, columnIndex: number, tableColumn: ITableColumn<IListBoxItem<T>>, tableItem: IListBoxItem<T>) => JSX.Element
A function to render custom item content.
textoptional
string
Text to render in the item's row.
tooltipPropsoptional
Optional tooltip props to apply to the ListBox row for this item. By default, an overflow tooltip is rendered with the item's text.
typeoptional
The type of list item. Headers and Separators ignore focus and selection.

IListBoxGroup<T = {}>

id
string
Unique identifier for the group.
loadingoptional
boolean
Set to true to indicate this group is loading. The GroupedItemProvider will check this value and add a loading cell if true.
loadingItemoptional
Provide a custom loading item to be added if loading is true.
nameoptional
string
Display name for the group. Not needed if you are supplying your own header items.

ListBoxItemType

Row1
number
Header2
number
Divider3
number
Loading4
number

ILoadingCellProps<T>

columnIndexrequired
number
The index of the column this cell is being rendered in.
onMount
() => void
Function to call after the row has finished rendering. Use this to trigger data fetching.
tableColumnrequired
The column this cell is being rendered in.
tableItemrequired
The listbox item associated with this cell.

Loaded Dropdown page