1. framework components
  2. ›
  3. combobox

Combobox

A combobox is an input widget with an associated popup that enables users to select a value from a collection of possible values.

Groups

Organize items into categorized groups.

Auto Highlight

Search for any option, then tap Enter on your keyboard to automatically select it.

Multiple

To maintain filtering functionality and improve clarity for users, we recommend displaying each selected value outside the perimeter of the Combobox component.

Disabled Item

Custom Filter

Try mistyping apple or banana to see the custom filter using the fuzzy search from Fuse.js in action.

Direction

Set the text direction ( ltr or rtl ) using the dir prop.

Guidelines

Z-Index

By default we do not take an opinionated stance regarding z-index stacking. The result is the component can sometimes be occluded beneath other elements with a higher index. The Z-Index can controlled by applying a utility class to the Content component part.

tsx 
<Combobox.Content className="z-50" />

Max Items

We recommend no more than 500 items max. For normal usage, a few dozen will provide the best performance.

Anatomy

Here’s an overview of how the Combobox component is structured in code:

tsx 
import { Combobox, Portal } from '@skeletonlabs/skeleton-react';

export default function Anatomy() {
	return (
		<Combobox>
			<Combobox.Label />
			<Combobox.Control>
				<Combobox.Input />
				<Combobox.Trigger />
			</Combobox.Control>
			<Combobox.ClearTrigger />
			<Portal>
				<Combobox.Positioner>
					<Combobox.Content>
						<Combobox.ItemGroup>
							<Combobox.ItemGroupLabel />
							<Combobox.Item>
								<Combobox.ItemText />
								<Combobox.ItemIndicator />
							</Combobox.Item>
						</Combobox.ItemGroup>
					</Combobox.Content>
				</Combobox.Positioner>
			</Portal>
		</Combobox>
	);
}

API Reference

Root

Prop Default Type
open — boolean | undefined

The controlled open state of the combobox
defaultOpen — boolean | undefined

The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.
ids — Partial<{ root: string; label: string; control: string; input: string; content: string; trigger: string; clearTrigger: string; item: (id: string, index?: number | undefined) => string; positioner: string; itemGroup: (id: string | number) => string; itemGroupLabel: (id: string | number) => string; }> | undefined

The ids of the elements in the combobox. Useful for composition.
inputValue — string | undefined

The controlled value of the combobox's input
defaultInputValue "" string | undefined

The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.
name — string | undefined

The `name` attribute of the combobox's input. Useful for form submission
form — string | undefined

The associate form of the combobox.
disabled — boolean | undefined

Whether the combobox is disabled
readOnly — boolean | undefined

Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it
invalid — boolean | undefined

Whether the combobox is invalid
required — boolean | undefined

Whether the combobox is required
placeholder — string | undefined

The placeholder text of the combobox's input
defaultHighlightedValue — string | null | undefined

The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.
highlightedValue — string | null | undefined

The controlled highlighted value of the combobox
value — string[] | undefined

The controlled value of the combobox's selected items
defaultValue [] string[] | undefined

The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.
inputBehavior "none" "autohighlight" | "autocomplete" | "none" | undefined

Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated
selectionBehavior "replace" "clear" | "replace" | "preserve" | undefined

The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved
autoFocus — boolean | undefined

Whether to autofocus the input on mount
openOnClick false boolean | undefined

Whether to open the combobox popup on initial click on the input
openOnChange true boolean | ((details: InputValueChangeDetails) => boolean) | undefined

Whether to show the combobox when the input value changes
allowCustomValue — boolean | undefined

Whether to allow typing custom values in the input
alwaysSubmitOnEnter false boolean | undefined

Whether to always submit on Enter key press, even if popup is open. Useful for single-field autocomplete forms where Enter should submit the form.
loopFocus true boolean | undefined

Whether to loop the keyboard navigation through the items
positioning { placement: "bottom-start" } PositioningOptions | undefined

The positioning options to dynamically position the menu
onInputValueChange — ((details: InputValueChangeDetails) => void) | undefined

Function called when the input's value changes
onValueChange — ((details: ValueChangeDetails<any>) => void) | undefined

Function called when a new item is selected
onHighlightChange — ((details: HighlightChangeDetails<any>) => void) | undefined

Function called when an item is highlighted using the pointer or keyboard navigation.
onSelect — ((details: SelectionDetails) => void) | undefined

Function called when an item is selected
onOpenChange — ((details: OpenChangeDetails) => void) | undefined

Function called when the popup is opened
translations — IntlTranslations | undefined

Specifies the localized strings that identifies the accessibility elements and their states
collection — ListCollection<any> | undefined

The collection of items
multiple — boolean | undefined

Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container.
closeOnSelect — boolean | undefined

Whether to close the combobox when an item is selected.
openOnKeyPress true boolean | undefined

Whether to open the combobox on arrow key press
scrollToIndexFn — ((details: ScrollToIndexDetails) => void) | undefined

Function to scroll to a specific index
composite true boolean | undefined

Whether the combobox is a composed with other composite widgets like tabs
disableLayer — boolean | undefined

Whether to disable registering this a dismissable layer
navigate — ((details: NavigateDetails) => void) | null | undefined

Function to navigate to the selected item
dir "ltr" "ltr" | "rtl" | undefined

The document's text/writing direction.
getRootNode — (() => ShadowRoot | Node | Document) | undefined

A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
onPointerDownOutside — ((event: PointerDownOutsideEvent) => void) | undefined

Function called when the pointer is pressed down outside the component
onFocusOutside — ((event: FocusOutsideEvent) => void) | undefined

Function called when the focus is moved outside the component
onInteractOutside — ((event: InteractOutsideEvent) => void) | undefined

Function called when an interaction happens outside the component
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Provider

Prop Default Type
value — ComboboxApi<PropTypes, any>

element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Context

Prop Default Type
children — (combobox: ComboboxApi<PropTypes, any>) => ReactNode

Label

Prop Default Type
element — ((attributes: HTMLAttributes<"label">) => Element) | undefined

Render the element yourself

Control

Prop Default Type
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Input

Prop Default Type
element — ((attributes: HTMLAttributes<"input">) => Element) | undefined

Render the element yourself

Trigger

Prop Default Type
element — ((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

ClearTrigger

Prop Default Type
element — ((attributes: HTMLAttributes<"button">) => Element) | undefined

Render the element yourself

Positioner

Prop Default Type
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Content

Prop Default Type
element — ((attributes: HTMLAttributes<"ul">) => Element) | undefined

Render the element yourself

ItemGroup

Prop Default Type
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

ItemGroupLabel

Prop Default Type
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself

Item

Prop Default Type
persistFocus — boolean | undefined

Whether hovering outside should clear the highlighted state
item — any

The item to render
element — ((attributes: HTMLAttributes<"li">) => Element) | undefined

Render the element yourself

ItemText

Prop Default Type
element — ((attributes: HTMLAttributes<"span">) => Element) | undefined

Render the element yourself

ItemIndicator

Prop Default Type
element — ((attributes: HTMLAttributes<"div">) => Element) | undefined

Render the element yourself
View page on GitHub