Skip to content

Select

Props

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

Select.Root

NameTypeDefault
allowsEmptyCollectionboolean

Whether the select should be allowed to be open when the collection is empty.

childrenChildrenOrFunction<SelectRenderProps>

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

defaultOpenboolean

Sets the default open state of the menu.

disabledKeysIterable<Key>

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

isDisabledboolean

Whether the input is disabled.

isInvalidboolean

Whether the input value is invalid.

isOpenboolean

Sets the open state of the menu.

isRequiredboolean

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

selectionMode"multiple" | "single"'single'

Whether single or multiple selection is enabled.

shouldCloseOnSelectboolean

Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise.

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.

sizeListBoxSizemd

Controls trigger height, padding, and value typography.

compactDeprecatedboolean

Use size="md" instead. This prop is a no-op.

Select.Button

NameTypeDefault
childrenReactNode

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

disableIconAnimationbooleanfalse

Disables the icon animation when opening/closing the Select

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.

leadingIconReactNode

Icon element that renders at the start of the button, before the value. Typically used for contextual icons like time, location, or category indicators. Should be decorative only and not convey critical information.

sizeListBoxSize"md"

Controls trigger height, padding, and value typography.

compactDeprecatedboolean

Use size="md" instead. This prop is a no-op.

Select.ClearButton

NameTypeDefault
childrenReactNode

The content or child elements nested within this component.

Select.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

Select.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.

Select.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.

Select.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

Select.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

Select.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.

Select.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.

defaultOpenboolean

Whether the overlay is open by default (uncontrolled).

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.

isOpenboolean

Whether the overlay is open by default (controlled).

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.

Select.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.

Select.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

Select.Value

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenChildrenOrFunction<SelectValueRenderProps<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