Listbox API

API documentation for Listbox component

ListboxRoot#

Props#

Defines valid properties in Listbox component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxRootInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxRootInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxRootPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxRootInstance) => ReactNode)	null	The children to render.
checkmark	boolean	null	When enabled, displays a checkmark icon next to the selected option.
checkbox	boolean	null	When enabled, displays checkboxes for multiple selection mode.
invalid	boolean	null	When present, it specifies that the component should have invalid state style.
tabIndex	number	null	Index of the element in tabbing order.
listboxInstance	useListboxInstance	null	An existing listbox instance to use instead of creating a new one. This is used internally by components like AutoComplete that compose Listbox.
value	unknown	null	The current value of the listbox. For single selection, this is a single value. For multiple selection, this is an array of values.
defaultValue	unknown	null	The default value of the listbox when used in uncontrolled mode.
options	unknown[]	null	An array of options to display in the listbox.
optionKey	string	null	Unique key for each option.
optionLabel	string	null	Label field for each option.
optionValue	string	null	Value field for each option.
optionDisabled	string	null	Field to check if an option is disabled.
optionGroupLabel	string	null	Label field for option groups.
optionGroupChildren	string	null	Field that contains the children options in a group.
disabled	boolean	null	When present, it specifies that the listbox should be disabled.
locale	string	null	The locale to use for localization. Used for accessibility labels.
multiple	boolean	null	When present, allows selecting multiple options.
metaKeySelection	boolean	null	When enabled, requires holding the meta key (Ctrl/Cmd) to select/deselect items in multiple selection mode.
autoOptionFocus	boolean	null	When enabled, the focused option is automatically highlighted.
selectOnFocus	boolean	null	When enabled, the focused option is automatically selected.
focusOnHover	boolean	null	When enabled, the focused option changes on hover.
onValueChange	(event: useListboxValueChangeEvent) => void	null	Callback to invoke when the value changes.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

State#

Defines valid state in Listbox component.

name	type	default	description
value	unknown	null	The current value(s) selected in the listbox.
focused	boolean	null	Whether the listbox is currently focused.
focusedOptionIndex	number	null	The index of the currently focused option. -1 if no option is focused.

Exposes#

Defines the methods and properties exposed by Listbox component.

name	type	default	description
state	useListboxState	null	The state of the useListbox.
listRef	RefObject<HTMLElement>	null	Reference to the list element of the listbox.
firstHiddenFocusableRef	RefObject<HTMLElement>	null	Reference to the first hidden focusable element for accessibility.
lastHiddenFocusableRef	RefObject<HTMLElement>	null	Reference to the last hidden focusable element for accessibility.
getOptions	() => unknown[]	null	Gets the list of options for the listbox.
getOptionId	(index: number) => string	null	Gets the unique ID for an option at a given index.
getOptionLabel	(option: unknown) => string	null	Gets the label for a given option.
getOptionValue	(option: unknown) => unknown	null	Gets the value for a given option.
isOptionDisabled	(option: unknown) => boolean	null	Checks if a given option is disabled.
isOptionGroup	(option: unknown) => boolean	null	Checks if a given option is a group header.
getOptionGroupLabel	(optionGroup: unknown) => string	null	Gets the label for a given option group.
getOptionGroupChildren	(optionGroup: unknown) => unknown[]	null	Gets the children options for a given option group.
getFocusedOptionId	() => string	null	Gets the ID of the currently focused option.
getAriaSetSize	() => number	null	Gets the total number of selectable options for ARIA.
getAriaPosInset	(index: number) => number	null	Gets the position of an option in the set for ARIA.
onFirstHiddenFocus	(event: FocusEvent) => void	null	Callback when the first hidden focusable element receives focus.
onLastHiddenFocus	(event: FocusEvent) => void	null	Callback when the last hidden focusable element receives focus.
onFocusOut	(event: FocusEvent) => void	null	Callback when focus leaves the listbox.
onListFocus	() => void	null	Callback when the list receives focus.
onListBlur	() => void	null	Callback when the list loses focus.
onListKeyDown	(event: KeyboardEvent) => void	null	Callback for keyboard events on the list.
onArrowDownKey	(event: KeyboardEvent) => void	null	Handles arrow down key press.
onArrowUpKey	(event: KeyboardEvent) => void	null	Handles arrow up key press.
onArrowLeftKey	(event: KeyboardEvent, pressedInInputText?: boolean) => void	null	Handles arrow left key press.
onEnterKey	(event: KeyboardEvent) => void	null	Handles enter key press.
onOptionSelect	(event: KeyboardEvent<Element> \| MouseEvent<Element, MouseEvent>, option: unknown, index?: number) => void	null	Callback when an option is selected.
onOptionMouseDown	(event: MouseEvent, index: number) => void	null	Callback when mouse button is pressed on an option.
onOptionMouseMove	(event: MouseEvent, index: number) => void	null	Callback when mouse moves over an option.
onOptionTouchEnd	() => void	null	Callback when touch ends on an option.
onFilterChange	() => void	null	Callback when the filter value changes.
onFilterBlur	() => void	null	Callback when the filter input loses focus.
onFilterKeyDown	(event: KeyboardEvent) => void	null	Callback for keyboard events on the filter input.
isOptionMatched	(option: unknown) => boolean	null	Checks if an option matches the search value.
isValidOption	(option: unknown) => boolean	null	Checks if an option is valid (not disabled and not a group).
isValidSelectedOption	(option: unknown) => boolean	null	Checks if an option is valid for selection.
isSelected	(option: unknown) => boolean	null	Checks if an option is currently selected.
changeFocusedOptionIndex	(event: KeyboardEvent<Element> \| MouseEvent<Element, MouseEvent>, index?: number) => void	null	Changes the focused option index.
findSelectedOptionIndex	() => number	null	Finds the index of the selected option.
findFirstFocusedOptionIndex	() => number	null	Finds the index of the first focused option.
scrollInView	(index?: number) => void	null	Scrolls the option at the given index into view.
updateModel	(event: SyntheticEvent, value: unknown) => void	null	Updates the listbox model with a new value.
autoUpdateModel	() => void	null	Automatically updates the model based on option selection.
equalityKey	string	null	Property name used for equality comparison.
hasValue	() => boolean	null	Checks if the listbox has a value.
isEquals	(value1: unknown, value2: unknown) => boolean	null	Checks if two values are equal using the equality key.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of Listbox component.

name	type	default	description
root	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.
firstHiddenFocusable	ListboxRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the first hidden focusable element's DOM element.
lastHiddenFocusable	ListboxRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the last hidden focusable element's DOM element.
header	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the header's DOM element.
footer	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the footer's DOM element.
list	ListboxRootPassThroughType<HTMLAttributes<HTMLUListElement>>	null	Used to pass attributes to the list's DOM element.
empty	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the empty message's DOM element.
optionGroup	ListboxRootPassThroughType<HTMLAttributes<HTMLLIElement>>	null	Used to pass attributes to the option group's DOM element.
option	ListboxRootPassThroughType<HTMLAttributes<HTMLLIElement>>	null	Used to pass attributes to the option's DOM element.
selection	ListboxRootPassThroughType<HTMLAttributes<HTMLElement>>	null	Used to pass attributes to the selection's DOM element.
filter	ListboxRootPassThroughType<HTMLAttributes<HTMLElement>>	null	Used to pass attributes to the filter's DOM element.

Types#

Instance

Instance of Listbox component.

values
ComponentInstance<ListboxRootProps, ListboxRootState, ListboxRootExposes>

ListboxHeader#

Props#

Defines valid properties in ListboxHeader component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxHeaderInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxHeaderInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxHeaderPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxHeaderInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxHeader component.

name	type	default	description
root	ListboxHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxHeader component.

values
ComponentInstance<ListboxHeaderProps, ListboxHeaderState, ListboxHeaderExposes>

ListboxFooter#

Props#

Defines valid properties in ListboxFooter component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxFooterInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxFooterInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxFooterPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxFooterInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxFooter component.

name	type	default	description
root	ListboxFooterPassThroughType<HTMLAttributes<HTMLDivElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxFooter component.

values
ComponentInstance<ListboxFooterProps, ListboxFooterState, ListboxFooterExposes>

ListboxOptions#

Props#

Defines valid properties in ListboxOptions component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxOptionsInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxOptionsInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxOptionsPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxOptionsInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxOptions component.

name	type	default	description
root	ListboxOptionsPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxOptions component.

values
ComponentInstance<ListboxOptionsProps, ListboxOptionsState, ListboxOptionsExposes>

ListboxOption#

Props#

Defines valid properties in ListboxOption component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxOptionInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxOptionInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxOptionPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxOptionInstance) => ReactNode)	null	The children to render.
group	boolean	null	When enabled, renders the option as a group header.
uKey	PropertyKey	null	Unique key for the option. Used for identification and selection.
index	number	null	Index of the option in the list.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxOption component.

name	type	default	description
root	ListboxOptionPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxOption component.

values
ComponentInstance<ListboxOptionProps, ListboxOptionState, ListboxOptionExposes>

ListboxSelection#

Props#

Defines valid properties in ListboxSelection component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxSelectionInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxSelectionInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxSelectionPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxSelectionInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxSelection component.

name	type	default	description
root	ListboxSelectionPassThroughType<HTMLAttributes<HTMLElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxSelection component.

values
ComponentInstance<ListboxSelectionProps, ListboxSelectionState, ListboxSelectionExposes>

ListboxFilter#

Props#

Defines valid properties in ListboxFilter component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxFilterInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxFilterInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxFilterPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxFilterInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxFilter component.

name	type	default	description
root	ListboxFilterPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxFilter component.

values
ComponentInstance<ListboxFilterProps, ListboxFilterState, ListboxFilterExposes>

ListboxEmpty#

Props#

Defines valid properties in ListboxEmpty component.

name	type	default	description
ref	Ref<unknown>	null	The reference to the component instance.
pIf	boolean	true	Whether the component should be rendered.
style	CSSProperties \| ((instance?: ListboxEmptyInstance) => CSSProperties)	null	The style to apply to the component.
className	string \| ((instance?: ListboxEmptyInstance) => string)	null	The class name to apply to the component.
as	string \| number \| bigint \| boolean \| ComponentClass<any, any> \| FunctionComponent<any> \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode, any, any> \| ReactPortal \| Promise<AwaitedReactNode>	null	The component type to render.
asChild	boolean	false	Whether the component should be rendered as a child component.
pt	SafeRecord<ListboxEmptyPassThrough>	null	The pass-through props to pass to the component
ptOptions	PassThroughOptions	null	The pass-through options to pass to the component
unstyled	boolean	null	Whether the component should be rendered without classes.
dt	unknown	null	The design token to use for the component.
styles	StylesOptions<ComponentInstance>	null	The styles to use for the component.
children	ReactNode \| ((instance: ListboxEmptyInstance) => ReactNode)	null	The children to render.
[key: string]	any	null
pt-{optionName}-*	-	null	Pass through attributes for customizing component. For more info, see Pass Through tab.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of ListboxEmpty component.

name	type	default	description
root	ListboxEmptyPassThroughType<HTMLAttributes<HTMLSpanElement>>	null	Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of ListboxEmpty component.

values
ComponentInstance<ListboxEmptyProps, ListboxEmptyState, ListboxEmptyExposes>

useListbox#

Types#

Instance

Instance of useListbox headless.

values
HeadlessInstance<useListboxProps, useListboxState, useListboxExposes>