Skip to content
Apps Platform

Select

The Select component provides a dropdown listbox interface, consisting of multiple SelectItem components. This component enables users to select an option or perform an action. Each SelectItem within the Select component represents an individual list item, ensuring consistent adherence to the defined menu style.

Usage Guide

The Select component allows users to choose an option from a dropdown list. Below is an example of its basic usage:

<Select>
  <SelectItem id="one">Item One</SelectItem>
  <SelectItem id="two">Item Two</SelectItem>
  <SelectItem id="three">Item Three</SelectItem>
</Select>

Filterable Select

The Select component can also be made filterable by setting the filterable prop to true. This allows users to search through the options.

<Select filterable>
  <SelectItem id="one">Item One</SelectItem>
  <SelectItem id="two">Item Two</SelectItem>
  <SelectItem id="three">Item Three</SelectItem>
</Select>

Props

Select Props

interface SelectProps
className ? string

Optional class name to apply to the Select.

filterable ? boolean

If true, the select is filterable.

children (item: { [key: string]: string | number; }) => ReactNode

The options to be displayed in the select.

label ? string

The label for the select.

hideLabel ? boolean

Hide the label visually.

Defaults to false
popoverProps ? PopoverProps

Optional props to pass to the popover.

onSelectionChange (key: string | number | null) => void

Callback function that is called when the selection changes.

renderEmptyState ? (props: ListBoxRenderProps) => ReactNode

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

validationBehavior ? "native" | "aria"

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'
items ? Iterable

The list of ComboBox items (controlled).

isReadOnly ? boolean

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

isDisabled ? boolean

Whether the input is disabled.

autoComplete ? string

Describes the type of autocomplete functionality the input should provide if any. See MDN.

name ? string

The name of the input, used when submitting an HTML form. The name of the input element, used when submitting an HTML form. See MDN.

form ? string

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.

selectionMode ? "single"

Whether single or multiple selection is enabled.

Defaults to 'single'
selectedKey ? Key | null

The currently selected key in the collection (controlled). @deprecated

defaultSelectedKey ? Key

The initial selected key in the collection (uncontrolled). @deprecated

isOpen ? boolean

Sets the open state of the menu.

defaultOpen ? boolean

Sets the default open state of the menu.

onOpenChange ? ((isOpen: boolean) => void) & ((isOpen: boolean, menuTrigger?: MenuTriggerAction)

Method that is called when the open state of the menu changes. Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.

disabledKeys ? Iterable

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

value ? Key | null

The current value (controlled).

defaultValue ? Key | null

The default value (uncontrolled).

onChange ? (value: Key | null) => void

Handler that is called when the value changes.

isRequired ? boolean

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

isInvalid ? boolean

Whether the input value is invalid.

validate ? ((value: Key) => true | ValidationError | null) & ((value: ComboBoxValidationValue)

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

placeholder ? string

Temporary text that occupies the select when it is empty.

Defaults to 'Select an item' (localized)
autoFocus ? boolean

Whether the element should receive focus on render.

onFocus ? ((e: FocusEvent) => void) & ((e: FocusEvent Element>)

Handler that is called when the element receives focus.

onBlur ? ((e: FocusEvent) => void) & ((e: FocusEvent Element>)

Handler that is called when the element loses focus.

onFocusChange ? (isFocused: boolean) => void

Handler that is called when the element's focus status changes.

onKeyDown ? (e: KeyboardEvent) => void

Handler that is called when a key is pressed.

onKeyUp ? (e: KeyboardEvent) => void

Handler that is called when a key is released.

id ? string

The element's unique identifier. See MDN.

excludeFromTabOrder ? boolean

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

shouldFocusWrap ? boolean

Whether keyboard navigation is circular.

defaultItems ? Iterable

The list of ComboBox items (uncontrolled).

inputValue ? string

The value of the ComboBox input (controlled).

defaultInputValue ? string

The default value of the ComboBox input (uncontrolled).

onInputChange ? (value: string) => void

Handler that is called when the ComboBox input value changes.

allowsCustomValue ? boolean

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

menuTrigger ? MenuTriggerAction

The interaction required to display the ComboBox menu.

Defaults to 'input'
style ? (StyleOrFunction & StyleOrFunction) =>

The inline style for the element. A function may be provided to compute the style based on component state.

slot ? string | null

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.

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

The filter function used to determine if a option should be included in the combo box list.

formValue ? "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.

Defaults to 'key'
allowsEmptyCollection ? boolean

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

SelectItem Props

interface SelectItemProps
id ? Key

The unique id of the item.

value ? object

The object value that this item represents. When using dynamic collections, this is set automatically.

textValue ? string

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

isDisabled ? boolean

Whether the item is disabled.

onAction ? () => void

Handler that is called when a user performs an action on the item. The exact user event depends on the collection's selectionBehavior prop and the interaction modality.

children ? ChildrenOrFunction

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

className ? ClassNameOrFunction

The CSS className for the element. A function may be provided to compute the class based on component state.

style ? (StyleOrFunction & StyleOrFunction) =>

The inline style for the element. A function may be provided to compute the style based on component state.

href ? string

A URL to link to. See MDN.

hrefLang ? string

Hints at the human language of the linked URL. SeeMDN.

target ? HTMLAttributeAnchorTarget

The target window for the link. See MDN.

rel ? string

The relationship between the linked resource and the current page. See MDN.

download ? string | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping ? string

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy ? HTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN.

routerOptions ? undefined

Options for the configured client side router.

onHoverStart ? (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd ? (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

onHoverChange ? (isHovering: boolean) => void

Handler that is called when the hover state changes.

onPress ? (e: PressEvent) => void

Handler that is called when the press is released over the target.

onPressStart ? (e: PressEvent) => void

Handler that is called when a press interaction starts.

onPressEnd ? (e: PressEvent) => void

Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.

onPressChange ? (isPressed: boolean) => void

Handler that is called when the press state changes.

onPressUp ? (e: PressEvent) => void

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

onClick ? (e: MouseEvent) => void

Not recommended – use onPress instead. onClick is an alias for onPress provided for compatibility with other libraries. onPress provides additional event details for non-mouse interactions.