Skip to content

ComboBox

Props

API reference for ComboBox. For usage examples, see the React tab.

Combobox.Root

NameTypeDefault
allowsCustomValueboolean

Whether the ComboBox allows a non-item matching input value to be set.

allowsEmptyCollectionboolean

Whether the combo box allows the menu to be open when the collection is empty.

childrenChildrenOrFunction<ComboBoxRenderProps>

The children of the component. A function may be provided to alter the children based on component state.

defaultFilter((textValue: string, inputValue: string) => boolean)

The filter function used to determine if an option should be included in the combo box list. By default, a language-sensitive "contains" filter from useFilter is used.

defaultItemsIterable<T>

The list of ComboBox items (uncontrolled).

disabledKeysIterable<Key>

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

disableIconAnimationboolean
formValue"key" | "text"'key'

Whether the text or key of the selected item is submitted as part of an HTML form. When allowsCustomValue is true, this option does not apply and the text is always submitted.

iconVariant"chevron" | "search"chevron
isDisabledboolean

Whether the input is disabled.

isInvalidboolean

Whether the input value is invalid.

isReadOnlyboolean

Whether the input can be selected but not changed by the user.

isRequiredboolean

Whether user input is required on the input before form submission.

itemsIterable<T>

The list of ComboBox items (controlled).

menuTriggerMenuTriggerAction'input'

The interaction required to display the ComboBox menu.

selectionMode"multiple" | "single"'single'

Whether single or multiple selection is enabled.

shouldFlipbooleantrue

Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

shouldFocusWrapboolean

Whether keyboard navigation is circular.

size"lg" | "md" | "sm"md

Controls height, padding, and typography of the input.

compactDeprecatedboolean

Use size instead. This prop is a no-op.

Combobox.Button

NameTypeDefault
childrenChildrenOrFunction<ButtonRenderProps>

The children of the component. A function may be provided to alter the children based on component state.

disableIconAnimationboolean
iconVariant"chevron" | "search"
isDisabledboolean

Whether the button is disabled.

isPendingboolean

Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.

Combobox.ClearButton

NameTypeDefault
childrenReactNode

The content or child elements nested within this component.

Combobox.Description

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
elementTypestring
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

isInvalidboolean
itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring

Combobox.Error

NameTypeDefault
childrenChildrenOrFunction<FieldErrorRenderProps>

The children of the component. A function may be provided to alter the children based on component state.

elementTypestring'span'

The HTML element type to render. Defaults to 'span'. Set to 'div' when using block-level children (e.g. <ul>) to avoid invalid HTML.

Combobox.Input

NameTypeDefault
aboutstring
acceptstring
accessKeystring
alignment"left" | "right"left

Alignment of the text inside the input

altstring
autoSavestring
capture"environment" | "user" | boolean
checkedboolean
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
disabledboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

heightstring | number
inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
liststring
multipleboolean
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
readOnlyboolean
relstring
requiredboolean
resourcestring
resultsnumber
revstring
securitystring
size"lg" | "md" | "sm""md"

Controls height, padding, and typography of the input.

srcstring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring
widthstring | number
compactDeprecatedboolean

Use size instead. This prop is a no-op.

Combobox.Item

NameTypeDefault
childrenChildrenOrFunction<ListBoxItemRenderProps>

The children of the component. A function may be provided to alter the children based on component state.

downloadstring | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN (opens in new tab).

hrefstring

A URL to link to. See MDN (opens in new tab).

hrefLangstring

Hints at the human language of the linked URL. SeeMDN (opens in new tab).

isDisabledboolean

Whether the item is disabled.

pingstring

A space-separated list of URLs to ping when the link is followed. See MDN (opens in new tab).

referrerPolicyHTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN (opens in new tab).

relstring

The relationship between the linked resource and the current page. See MDN (opens in new tab).

routerOptionsundefined

Options for the configured client side router.

targetHTMLAttributeAnchorTarget

The target window for the link. See MDN (opens in new tab).

textValuestring

A string representation of the item's contents, used for features like typeahead.

Combobox.Label

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
elementTypestring
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

htmlForstring
inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

isDisabledboolean

Whether the Label is on a disabled input or element.

isRequiredboolean

Whether the Label is on a required input or element.

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring

Combobox.LeadingIcon

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring

Combobox.List

NameTypeDefault
children((item: T) => ReactNode) | ReactNode

The contents of the collection.

dependenciesreadonly any[]

Values that should invalidate the item cache when using dynamic collections.

itemsIterable<T>

Item objects in the collection.

renderEmptyState((props: ListBoxRenderProps) => ReactNode)

Provides content to display when there are no items in the list.

shouldFocusOnHoverboolean

Whether options should be focused when the user hovers over them.

shouldFocusWrapboolean

Whether focus should wrap around when the end/start is reached.

shouldSelectOnPressUpboolean

Whether selection should occur on press up instead of press down.

Combobox.Popover

NameTypeDefault
children (required)ReactNode

The content rendered inside the popover.

arrowBoundaryOffsetnumber0

The minimum distance the arrow's edge should be from the edge of the overlay element.

arrowRefRefObject<Element | null>

A ref for the popover arrow element.

boundaryElementElementdocument.body

Element that that serves as the positioning boundary.

containerPaddingnumber12

The placement padding that should be applied between the element and its surrounding container.

crossOffsetnumber0

The additional offset applied along the cross axis between the element and its anchor element.

getTargetRect((target: Element) => DOMRect | null)target.getBoundingClientRect()

Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection.

isEnteringboolean

Whether the popover is currently performing an entry animation.

isExitingboolean

Whether the popover is currently performing an exit animation.

isKeyboardDismissDisabledbooleanfalse

Whether pressing the escape key to close the popover should be disabled.

Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.

isNonModalboolean

Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies.

Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.

maxHeightnumber

The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.

offsetnumber8

The additional offset applied along the main axis between the element and its anchor element.

placementPlacements

The placement of the element with respect to its anchor element.

scrollRefRefObject<Element | null>overlayRef

A ref for the scrollable region within the overlay.

shouldFlipbooleantrue

Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

shouldSkipAnimationboolean

Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays.

shouldUpdatePositionbooleantrue

Whether the overlay should update its position automatically.

triggerstring

The name of the component that triggered the popover. This is reflected on the element as the data-trigger attribute, and can be used to provide specific styles for the popover depending on which element triggered it.

triggerRefRefObject<Element | null>

The ref for the element which the popover positions itself with respect to.

When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.

Combobox.Section

NameTypeDefault
children((item: T) => ReactElement<unknown, string | JSXElementConstructor<any>>) | ReactNode

Static child items or a function to render children.

dependenciesreadonly any[]

Values that should invalidate the item cache when using dynamic collections.

itemsIterable<T>

Item objects in the section.

Combobox.SectionHeader

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring

Combobox.Value

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenChildrenOrFunction<ComboBoxValueRenderProps<T>>

The children of the component. A function may be provided to alter the children based on component state.

colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring