Select components

Q: What sizes are available for the select?

The select supports three sizes: "sm", "md", and "lg". The default size is "md". Set size on Select and every Select.Item in its popover picks it up through context.

Q: How do I control the selected value?

Select passes its remaining props to React Aria's Select, so use value and onChange for a controlled select or defaultValue for an uncontrolled one. The value is the id of the selected Select.Item. The older selectedKey and onSelectionChange props still work but are deprecated in React Aria.

Q: How do I disable the select or a single option?

Set isDisabled on Select to disable the whole field, which also dims the trigger with opacity-50. To disable one option, pass isDisabled to that Select.Item and it is skipped by the keyboard and can't be selected.

Q: How do I add search to the select?

Use Select.ComboBox instead of Select. It takes the same items, label, hint and size props, opens its list as soon as the input is focused, and defaults its placeholder to "Search". It also shows a ⌘K hint on the right by default, which is only a visual label with no shortcut wired up, so pass shortcut={false} to hide it.

Q: How do I add icons, avatars, or status dots to options?

Pass icon (a component or an element) or avatarUrl to Select.Item. If both are set, the avatar wins. For a status dot, pass an element such as <Dot className="size-2.5 text-fg-success-secondary" /> as the icon, as the Dot leading example does. The selected option's icon or avatar also appears in the trigger, and the icon prop on Select sets a fallback icon for the trigger.

Q: Can I select multiple options?

Not with Select, which is single-selection only. For selections shown as removable tags, use TagSelect from tag-select.tsx as in the Tags example: it takes a selectedItems list created with useListData from react-stately. For a dropdown with checkboxes, use the multi-select component.

Q: How do I add a label, hint, or tooltip?

Pass label, hint, and tooltip to Select. The tooltip adds a help icon next to the label. Setting isRequired adds an asterisk to the label, which hideRequiredIndicator removes, and isInvalid switches the hint text to the error style.

FREE

Free and open-source React select components built for modern applications and websites. These select components are built using React Aria and styled with Tailwind CSS.

Select example

Preview

Code

Team member*This is a hint text to help user.

Installation

You can add this select component using our CLI or manually:

CLI

Manual

npx untitledui@latest add select

Code

Search*

This is a hint text to help user.

API reference

Import the parts and assemble them:

import { Select } from "@/components/base/select/select";
 
<Select items={items}>
    {(item) => renderItem(item)}
</Select>
 
<Select.ComboBox items={items}>
    {(item) => renderItem(item)}
</Select.ComboBox>

ComboBox

Import ComboBox from @/components/base/select/combobox. Renders React Aria’s ComboBox — all of its props are supported.

ComboBox props
Prop	Type	Default	Description
`children`* (required)	`ReactNode \| ((item: SelectItemType) => ReactNode)`	—	The dropdown contents: either `Select.Item` elements, or a render function called with each entry of `items`.
`shortcut`	`boolean`	`true`	Whether to pin a ⌘K key hint to the right edge of the input. It is hidden below the medium breakpoint.
`items`	`SelectItemType[]`	—	The options to render in the dropdown. When `children` is a function it is called once per item to render it.
`popoverClassName`	`string`	—	Additional classes merged onto the dropdown popover, which is sized to match the input.
`shortcutClassName`	`string`	—	Additional classes merged onto the ⌘K hint container, useful for adjusting its fade and spacing.
`icon`	`FC \| ReactNode`	—	Leading icon component displayed before the input.
`hint`	`string`	—	Helper text displayed below the input.
`label`	`string`	—	Field label displayed above the input.
`tooltip`	`string`	—	Tooltip text for the help icon next to the label.
`size`	`"sm""md""lg"`	`"md"`	The size of the component.
`placeholder`	`string`	`"Search"`	Placeholder text when no value is selected.
`hideRequiredIndicator`	`boolean`	—	Whether to hide the required indicator from the label.

Props from React Aria (42)

ComboBox inherited props
Prop	Type	Default	Description
`onBlur`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.
`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.
`name`	`string`	—	The name of the input element, used when submitting an HTML form.
`allowsCustomValue`	`boolean`	—	Whether the ComboBox allows a non-item matching input value to be set.
`allowsEmptyCollection`	`boolean`	—	Whether the combo box allows the menu to be open when the collection is empty.
`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.
`defaultInputValue`	`string`	—	The default value of the ComboBox input (uncontrolled).
`defaultItems`	`Iterable<SelectItemType>`	—	The list of ComboBox items (uncontrolled).
`defaultSelectedKey`	`Key \| null`	—	Deprecated.The initial selected key in the collection (uncontrolled).
`defaultValue`	`Key \| null`	—	The default value (uncontrolled).
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`formValue`	`"text""key"`	`"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.
`id`	`string`	—	The element's unique identifier.
`inputValue`	`string`	—	The value of the ComboBox input (controlled).
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`menuTrigger`	`"focus""input""manual"`	`"focus"`	The interaction required to display the ComboBox menu.
`onChange`	`((value: Key \| null) => void)`	—	Handler that is called when the value changes.
`onInputChange`	`((value: string) => void)`	—	Handler that is called when the ComboBox input value changes.
`onOpenChange`	`((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void)`	—	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.
`onSelectionChange`	`((key: Key \| null) => void)`	—	Deprecated.Handler that is called when the selection changes.
`selectedKey`	`Key \| null`	—	Deprecated.The currently selected key in the collection (controlled).
`selectionMode`	`"single"`	`"single"`	Whether single or multiple selection is enabled.
`shouldFocusWrap`	`boolean`	—	Whether keyboard navigation is circular.
`validate`	`((value: ComboBoxValidationValue<"single">) => ValidationError \| true \| null \| undefined)`	—	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.
`validationBehavior`	`"native""aria"`	`"native"`	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.
`value`	`Key \| null`	—	The current value (controlled).
`style`	`StyleOrFunction<ComboBoxRenderProps>`	—	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.
`className`	`ClassNameOrFunction<ComboBoxRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", ComboBoxRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

MultiSelect

Import MultiSelect from @/components/base/select/multi-select. Renders a <div> element.

MultiSelect props
Prop	Type	Default	Description
`children`* (required)	`ReactNode \| ((item: SelectItemType) => ReactNode)`	—	The children to render for each item.
`items`	`SelectItemType[]`	—	The items to display in the listbox.
`selectedKeys`	`Selection`	—	The currently selected keys (controlled).
`defaultSelectedKeys`	`Selection`	—	The initial selected keys (uncontrolled).
`onSelectionChange`	`((keys: Selection) => void)`	—	Handler that is called when the selection changes.
`isDisabled`	`boolean`	—	Whether the select is disabled.
`isRequired`	`boolean`	—	Whether the select is required.
`isInvalid`	`boolean`	—	Whether the select is in an invalid state.
`popoverClassName`	`string`	—	Additional class name for the popover.
`className`	`string`	—	Additional class name for the root element.
`onReset`	`(() => void)`	—	Handler that is called when the reset button is clicked.
`onSelectAll`	`(() => void)`	—	Handler that is called when the select all button is clicked.
`showFooter`	`boolean`	`true`	Whether to show the footer with reset and select all buttons.
`showSearch`	`boolean`	`true`	Whether to show the search input in the popover.
`emptyStateTitle`	`string`	—	The title to display when no items match the search.
`emptyStateDescription`	`string`	—	The description to display when no items match the search.
`selectedCountFormatter`	`((count: number) => ReactNode)`	—	Custom formatter for the selected count text in the trigger.
`supportingText`	`ReactNode`	—	Supporting text displayed next to the selected count in the trigger.
`icon`	`FC \| ReactNode`	—	Leading icon rendered in the trigger, before the placeholder / selected count. Matches `Select`'s `icon`.
`hint`	`string`	—	Helper text displayed below the input.
`label`	`string`	—	Field label displayed above the input.
`tooltip`	`string`	—	Tooltip text for the help icon next to the label.
`size`	`"sm""md""lg"`	`"md"`	The size of the component.
`placeholder`	`string`	`"Select"`	Placeholder text when no value is selected.
`hideRequiredIndicator`	`boolean`	—	Whether to hide the required indicator from the label.

MultiSelect.EmptyState

Import MultiSelect from @/components/base/select/multi-select and use it as MultiSelect.EmptyState. Renders a <div> element.

MultiSelect.EmptyState props
Prop	Type	Default	Description
`title`	`string`	`"No results found"`	The title to display.
`description`	`string`	`"Please try a different search term."`	The description to display.
`onClearSearch`	`(() => void)`	—	Handler that is called when the clear search button is clicked.
`className`	`string`	—	Additional class name.

MultiSelect.Footer

Import MultiSelect from @/components/base/select/multi-select and use it as MultiSelect.Footer. Renders a <div> element.

MultiSelect.Footer props
Prop	Type	Default	Description
`size`	`"sm""md""lg"`	`"sm"`	The size of the footer buttons.
`onReset`	`(() => void)`	—	Handler that is called when the reset button is clicked.
`onSelectAll`	`(() => void)`	—	Handler that is called when the select all button is clicked.
`className`	`string`	—	Additional class name.

NativeSelect

Import NativeSelect from @/components/base/select/select-native. Renders a <div> element.

NativeSelect props
Prop	Type	Default	Description
`options`* (required)	`{ label: string; value: string; disabled?: boolean; }[]`	—	The options to render. Each entry becomes an `option` element showing `label` and submitting `value`.
`label`	`string`	—	Text rendered in a label above the select and linked to it by a generated id.
`hint`	`string`	—	Helper text rendered below the select and referenced by its `aria-describedby`.
`selectClassName`	`string`	—	Additional classes merged onto the native select element. Use `className` to style the wrapper around it instead.
`size`	`"sm""md""lg"`	`"md"`	Controls the select's padding, text size, and the size of the chevron. Ignored when the select sits inside an `InputGroup`, which imposes its own sizing.

Also accepts all standard React DOM event handlers, all standard select attributes, all standard HTML attributes, all aria-* attributes.

Popover

Import Popover from @/components/base/select/popover. Renders React Aria’s Popover — all of its props are supported.

Popover props
Prop	Type	Default	Description
`size`* (required)	`"sm""md""lg"`	—	Caps how tall the popover can grow before its list starts scrolling: 14rem for `sm`, 16rem for `md`, and 20rem for `lg`.

Props from react-aria (35)

Popover inherited props
Prop	Type	Default	Description
`arrowBoundaryOffset`	`number`	`0`	The minimum distance the arrow's edge should be from the edge of the overlay element.
`arrowRef`	`RefObject<Element \| null>`	—	A ref for the popover arrow element.
`boundaryElement`	`Element`	`document.body`	Element that that serves as the positioning boundary.
`containerPadding`	`number`	`0`	The placement padding that should be applied between the element and its surrounding container.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`getTargetRect`	`((target: Element) => DOMRect \| null \| undefined)`	`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.
`isEntering`	`boolean`	—	Whether the popover is currently performing an entry animation.
`isExiting`	`boolean`	—	Whether the popover is currently performing an exit animation.
`isKeyboardDismissDisabled`	`boolean`	`false`	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.
`isNonModal`	`boolean`	—	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.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`maxHeight`	`number`	—	The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
`offset`	`number`	`4`	The additional offset applied along the main axis between the element and its anchor element.
`onBlurWithin`	`((e: FocusEvent) => void)`	—	Handler that is called when the target element and all descendants lose focus.
`onFocusWithin`	`((e: FocusEvent) => void)`	—	Handler that is called when the target element or a descendant receives focus.
`onFocusWithinChange`	`((isFocusWithin: boolean) => void)`	—	Handler that is called when the the focus within state changes.
`onOpenChange`	`((isOpen: boolean) => void)`	—	Handler that is called when the overlay's open state changes.
`placement`	`"bottom""bottom left""bottom right""bottom start""bottom end""top""top left""top right""top start""top end""left""left top""left bottom""start"` +8 moreShow fewer `"start top""start bottom""right""right top""right bottom""end""end top""end bottom"`	`"bottom"`	The placement of the element with respect to its anchor element.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	A ref for the scrollable region within the overlay.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	—	When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
`shouldFlip`	`boolean`	`true`	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.
`shouldSkipAnimation`	`boolean`	—	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.
`shouldUpdatePosition`	`boolean`	`true`	Whether the overlay should update its position automatically.
`trigger`	`string`	—	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.
`triggerRef`	`RefObject<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.
`style`	`StyleOrFunction<PopoverRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<PopoverRenderProps>`	—	The children of the component. A function may be provided to alter the children 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.
`className`	`ClassNameOrFunction<PopoverRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", PopoverRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

Select

Renders React Aria’s Select — all of its props are supported.

Select props
Prop	Type	Default	Description
`children`* (required)	`ReactNode \| ((item: SelectItemType) => ReactNode)`	—	The dropdown contents: either `Select.Item` elements, or a render function called with each entry of `items`.
`items`	`SelectItemType[]`	—	The options to render in the dropdown. When `children` is a function it is called once per item to render it.
`popoverClassName`	`string`	—	Additional classes merged onto the dropdown popover.
`icon`	`FC \| ReactNode`	—	Leading icon shown in the trigger, used as a fallback when the selected item has no icon of its own. Accepts a component reference or a rendered element.
`hint`	`string`	—	Helper text displayed below the input.
`label`	`string`	—	Field label displayed above the input.
`tooltip`	`string`	—	Tooltip text for the help icon next to the label.
`size`	`"sm""md""lg"`	`"md"`	The size of the component.
`hideRequiredIndicator`	`boolean`	—	Whether to hide the required indicator from the label.

Props from React Aria (38)

Select inherited props
Prop	Type	Default	Description
`onBlur`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.
`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.
`allowsEmptyCollection`	`boolean`	—	Whether the select should be allowed to be open when the collection is empty.
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`defaultSelectedKey`	`Key \| null`	—	Deprecated.The initial selected key in the collection (uncontrolled).
`defaultValue`	`Key \| null`	—	The default value (uncontrolled).
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`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.
`id`	`string`	—	The element's unique identifier.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isOpen`	`boolean`	—	Sets the open state of the menu.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`name`	`string`	—	The name of the input, used when submitting an HTML form.
`onChange`	`((value: Key \| null) => void)`	—	Handler that is called when the value changes.
`onOpenChange`	`((isOpen: boolean) => void)`	—	Method that is called when the open state of the menu changes.
`onSelectionChange`	`((key: Key \| null) => void)`	—	Deprecated.Handler that is called when the selection changes.
`placeholder`	`string`	`"Select"`	Temporary text that occupies the select when it is empty.
`selectedKey`	`Key \| null`	—	Deprecated.The currently selected key in the collection (controlled).
`selectionMode`	`"single"`	`"single"`	Whether single or multiple selection is enabled.
`shouldCloseOnSelect`	`boolean`	—	Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise.
`validate`	`((value: Key) => ValidationError \| true \| null \| undefined)`	—	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.
`validationBehavior`	`"native""aria"`	`"native"`	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.
`value`	`Key \| null`	—	The current value (controlled).
`style`	`StyleOrFunction<SelectRenderProps>`	—	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.
`className`	`ClassNameOrFunction<SelectRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", SelectRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

TagSelect

Import TagSelect from @/components/base/select/tag-select. Renders React Aria’s ComboBox — all of its props are supported.

TagSelect props
Prop	Type	Default	Description
`selectedItems`* (required)	`ListData<SelectItemType>`	—	The list state holding the selected items, typically created with `useListData`. The component appends to it on selection and removes from it when a tag is dismissed.
`children`* (required)	`ReactNode \| ((item: SelectItemType) => ReactNode)`	—	The listbox content: either the options themselves or a render function called with each filtered item.
`hint`	`string`	—	Helper text rendered below the input. It switches to the error style when the field is invalid.
`label`	`string`	—	The label rendered above the input. Nothing is rendered when it is omitted.
`tooltip`	`string`	—	Text for the help tooltip shown next to the label. Only rendered when `label` is set.
`size`	`"sm""md""lg"`	`"sm"`	Controls the height, padding, and text size of the input, the selected tags, and the popover.
`placeholder`	`string`	`"Search"`	The placeholder text shown in the search input.
`shortcut`	`boolean`	—	Whether to show the ⌘K hint at the end of the input on medium screens and up.
`items`	`SelectItemType[]`	—	The full set of options offered in the dropdown. They are filtered as the user types, and already selected items are hidden from the list.
`popoverClassName`	`string`	—	Additional CSS classes merged onto the dropdown popover.
`shortcutClassName`	`string`	—	Additional CSS classes merged onto the container of the ⌘K hint.
`icon`	`IconComponentType \| null`	`SearchLg`	The icon component rendered at the start of the input. Pass `null` to render no icon.
`onItemCleared`	`((key: Key) => void)`	—	Fires with the key of an item after its tag has been removed from the selection.
`onItemInserted`	`((key: Key) => void)`	—	Fires with the key of an item after it has been added to the selection.
`valueFormatter`	`((item: SelectItemType) => string)`	—	Returns the text to display on the tag for a selected item. Without it the item's `label` is used.

Props from React Aria (42)

TagSelect inherited props
Prop	Type	Default	Description
`onBlur`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.
`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.
`name`	`string`	—	The name of the input element, used when submitting an HTML form.
`allowsCustomValue`	`boolean`	—	Whether the ComboBox allows a non-item matching input value to be set.
`allowsEmptyCollection`	`boolean`	—	Whether the combo box allows the menu to be open when the collection is empty.
`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.
`defaultInputValue`	`string`	—	The default value of the ComboBox input (uncontrolled).
`defaultItems`	`Iterable<SelectItemType>`	—	The list of ComboBox items (uncontrolled).
`defaultSelectedKey`	`Key \| null`	—	Deprecated.The initial selected key in the collection (uncontrolled).
`defaultValue`	`Key \| null`	—	The default value (uncontrolled).
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`formValue`	`"text""key"`	`"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.
`id`	`string`	—	The element's unique identifier.
`inputValue`	`string`	—	The value of the ComboBox input (controlled).
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`menuTrigger`	`"focus""input""manual"`	`"focus"`	The interaction required to display the ComboBox menu.
`onChange`	`((value: Key \| null) => void)`	—	Handler that is called when the value changes.
`onInputChange`	`((value: string) => void)`	—	Handler that is called when the ComboBox input value changes.
`onOpenChange`	`((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void)`	—	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.
`onSelectionChange`	`((key: Key \| null) => void)`	—	Deprecated.Handler that is called when the selection changes.
`selectedKey`	`Key \| null`	—	Deprecated.The currently selected key in the collection (controlled).
`selectionMode`	`"single"`	`"single"`	Whether single or multiple selection is enabled.
`shouldFocusWrap`	`boolean`	—	Whether keyboard navigation is circular.
`validate`	`((value: ComboBoxValidationValue<"single">) => ValidationError \| true \| null \| undefined)`	—	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.
`validationBehavior`	`"native""aria"`	`"native"`	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.
`value`	`Key \| null`	—	The current value (controlled).
`style`	`StyleOrFunction<ComboBoxRenderProps>`	—	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.
`className`	`ClassNameOrFunction<ComboBoxRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", ComboBoxRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

TagSelect.Item

Import SelectItem from @/components/base/select/select-item. Renders React Aria’s ListBoxItem — all of its props are supported.

TagSelect.Item props
Prop	Type	Default	Description
`id`* (required)	`string \| number`	—	Unique identifier for the item.
`selectionIndicator`	`"checkmark""checkbox""none"`	`"checkmark"`	The selection indicator to be displayed on the item.
`selectionIndicatorAlign`	`"left""right"`	`"right"`	The alignment of the selection indicator.
`label`	`string`	—	The primary display text.
`avatarUrl`	`string`	—	Avatar image URL.
`supportingText`	`string`	—	Secondary text displayed alongside the label.
`icon`	`FC \| ReactNode`	—	Leading icon component or element.

Props from React Aria (31)

TagSelect.Item inherited props
Prop	Type	Default	Description
`onClick`	`((e: MouseEvent<FocusableElement>) => 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.
`onPress`	`((e: PressEvent) => void)`	—	Handler that is called when the press is released over the target.
`onPressChange`	`((isPressed: boolean) => void)`	—	Handler that is called when the press state changes.
`onPressEnd`	`((e: PressEvent) => void)`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressStart`	`((e: PressEvent) => void)`	—	Handler that is called when a press interaction starts.
`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.
`onHoverChange`	`((isHovering: boolean) => void)`	—	Handler that is called when the hover state changes.
`onHoverEnd`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction ends.
`onHoverStart`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction starts.
`onBlur`	`((e: FocusEvent<HTMLDivElement, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<HTMLDivElement, Element>) => void)`	—	Handler that is called when the element receives 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.
`download`	`string \| boolean`	—	Causes the browser to download the linked URL. A string may be provided to suggest a file name.
`href`	`string`	—	A URL to link to.
`hrefLang`	`string`	—	Hints at the human language of the linked URL.
`ping`	`string`	—	A space-separated list of URLs to ping when the link is followed.
`referrerPolicy`	`"""no-referrer""no-referrer-when-downgrade""origin""origin-when-cross-origin""same-origin""strict-origin""strict-origin-when-cross-origin""unsafe-url"`	—	How much of the referrer to send when following the link.
`rel`	`string`	—	The relationship between the linked resource and the current page.
`routerOptions`	`RouterOptions`	—	Options for the configured client side router.
`target`	`HTMLAttributeAnchorTarget`	—	The target window for the link.
`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.
`textValue`	`string`	—	A string representation of the item's contents, used for features like typeahead.
`value`	`SelectItemType`	—	The object value that this item represents. When using dynamic collections, this is set automatically.
`style`	`StyleOrFunction<ListBoxItemRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<ListBoxItemRenderProps>`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`ClassNameOrFunction<ListBoxItemRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| JSX.IntrinsicElements[Fallback], renderProps: T) => ReactElement`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Note: You can check if `'href' in props` in order to tell whether to render an `<a>` element.Requirements: You must render the expected element type (e.g. if `<a>` is expected, you cannot render a `<button>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-label`	`string`	—	An accessibility label for this item.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

TagSelectBase

Import TagSelectBase from @/components/base/select/tag-select. Renders React Aria’s ComboBox — all of its props are supported.

TagSelectBase props
Prop	Type	Default	Description
`selectedItems`* (required)	`ListData<SelectItemType>`	—	The list state holding the selected items, typically created with `useListData`. The component appends to it on selection and removes from it when a tag is dismissed.
`children`* (required)	`ReactNode \| ((item: SelectItemType) => ReactNode)`	—	The listbox content: either the options themselves or a render function called with each filtered item.
`hint`	`string`	—	Helper text rendered below the input. It switches to the error style when the field is invalid.
`label`	`string`	—	The label rendered above the input. Nothing is rendered when it is omitted.
`tooltip`	`string`	—	Text for the help tooltip shown next to the label. Only rendered when `label` is set.
`size`	`"sm""md""lg"`	`"sm"`	Controls the height, padding, and text size of the input, the selected tags, and the popover.
`placeholder`	`string`	`"Search"`	The placeholder text shown in the search input.
`shortcut`	`boolean`	—	Whether to show the ⌘K hint at the end of the input on medium screens and up.
`items`	`SelectItemType[]`	—	The full set of options offered in the dropdown. They are filtered as the user types, and already selected items are hidden from the list.
`popoverClassName`	`string`	—	Additional CSS classes merged onto the dropdown popover.
`shortcutClassName`	`string`	—	Additional CSS classes merged onto the container of the ⌘K hint.
`icon`	`IconComponentType \| null`	`SearchLg`	The icon component rendered at the start of the input. Pass `null` to render no icon.
`onItemCleared`	`((key: Key) => void)`	—	Fires with the key of an item after its tag has been removed from the selection.
`onItemInserted`	`((key: Key) => void)`	—	Fires with the key of an item after it has been added to the selection.
`valueFormatter`	`((item: SelectItemType) => string)`	—	Returns the text to display on the tag for a selected item. Without it the item's `label` is used.

Props from React Aria (42)

TagSelectBase inherited props
Prop	Type	Default	Description
`onBlur`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<HTMLInputElement, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`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.
`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.
`name`	`string`	—	The name of the input element, used when submitting an HTML form.
`allowsCustomValue`	`boolean`	—	Whether the ComboBox allows a non-item matching input value to be set.
`allowsEmptyCollection`	`boolean`	—	Whether the combo box allows the menu to be open when the collection is empty.
`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.
`defaultInputValue`	`string`	—	The default value of the ComboBox input (uncontrolled).
`defaultItems`	`Iterable<SelectItemType>`	—	The list of ComboBox items (uncontrolled).
`defaultSelectedKey`	`Key \| null`	—	Deprecated.The initial selected key in the collection (uncontrolled).
`defaultValue`	`Key \| null`	—	The default value (uncontrolled).
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`formValue`	`"text""key"`	`"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.
`id`	`string`	—	The element's unique identifier.
`inputValue`	`string`	—	The value of the ComboBox input (controlled).
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`menuTrigger`	`"focus""input""manual"`	`"focus"`	The interaction required to display the ComboBox menu.
`onChange`	`((value: Key \| null) => void)`	—	Handler that is called when the value changes.
`onInputChange`	`((value: string) => void)`	—	Handler that is called when the ComboBox input value changes.
`onOpenChange`	`((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void)`	—	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.
`onSelectionChange`	`((key: Key \| null) => void)`	—	Deprecated.Handler that is called when the selection changes.
`selectedKey`	`Key \| null`	—	Deprecated.The currently selected key in the collection (controlled).
`selectionMode`	`"single"`	`"single"`	Whether single or multiple selection is enabled.
`shouldFocusWrap`	`boolean`	—	Whether keyboard navigation is circular.
`validate`	`((value: ComboBoxValidationValue<"single">) => ValidationError \| true \| null \| undefined)`	—	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.
`validationBehavior`	`"native""aria"`	`"native"`	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.
`value`	`Key \| null`	—	The current value (controlled).
`style`	`StyleOrFunction<ComboBoxRenderProps>`	—	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.
`className`	`ClassNameOrFunction<ComboBoxRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", ComboBoxRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

TagSelectTagsValue

Import TagSelectTagsValue from @/components/base/select/tag-select. Renders React Aria’s Group — all of its props are supported.

TagSelectTagsValue props
Prop	Type	Default	Description
`size`	`"sm""md""lg"`	`"sm"`	Controls the height, padding, and text size of the input group, as well as how compact the selected tags are.
`shortcut`	`boolean`	—	Whether to show the ⌘K hint at the end of the input on medium screens and up. It also reserves a minimum width for the text input.
`isDisabled`	`boolean`	—	Whether the tags are disabled. This value is not forwarded to the DOM — the group's own disabled styling comes from the enclosing combo box state.
`placeholder`	`string`	—	The placeholder text shown in the search input.
`shortcutClassName`	`string`	—	Additional CSS classes merged onto the container of the ⌘K hint.
`icon`	`IconComponentType \| null`	`SearchLg`	The icon component rendered at the start of the input group. Pass `null` to render no icon.
`onFocus`	`FocusEventHandler`	—	Fires when focus enters the group. `TagSelect` uses it to re-measure the trigger width before the popover opens.
`onPointerEnter`	`PointerEventHandler`	—	Fires when the pointer enters the group. `TagSelect` uses it to re-measure the trigger width before the popover opens.

Props from React Aria Components (15)

TagSelectTagsValue inherited props
Prop	Type	Default	Description
`onHoverChange`	`((isHovering: boolean) => void)`	—	Handler that is called when the hover state changes.
`onHoverEnd`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction ends.
`onHoverStart`	`((e: HoverEvent) => void)`	—	Handler that is called when a hover interaction starts.
`isInvalid`	`boolean`	—	Whether the group is invalid.
`isReadOnly`	`boolean`	—	Whether the group is read only.
`style`	`StyleOrFunction<GroupRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<GroupRenderProps>`	—	The children of the component. A function may be provided to alter the children 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.
`className`	`ClassNameOrFunction<GroupRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", GroupRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`role`	`"group""region""presentation"`	`"group"`	An accessibility role for the group. By default, this is set to `'group'`. Use `'region'` when the contents of the group is important enough to be included in the page table of contents. Use `'presentation'` if the group is visual only and does not represent a semantic grouping of controls.

Also accepts all standard HTML attributes, all standard React DOM event handlers, all aria-* attributes.

FAQs

Please refer to our frequently asked questions page for more.

The select supports three sizes: "sm", "md", and "lg". The default size is "md". Set size on Select and every Select.Item in its popover picks it up through context.

Select passes its remaining props to React Aria's Select, so use value and onChange for a controlled select or defaultValue for an uncontrolled one. The value is the id of the selected Select.Item. The older selectedKey and onSelectionChange props still work but are deprecated in React Aria.

Set isDisabled on Select to disable the whole field, which also dims the trigger with opacity-50. To disable one option, pass isDisabled to that Select.Item and it is skipped by the keyboard and can't be selected.

Use Select.ComboBox instead of Select. It takes the same items, label, hint and size props, opens its list as soon as the input is focused, and defaults its placeholder to "Search". It also shows a ⌘K hint on the right by default, which is only a visual label with no shortcut wired up, so pass shortcut={false} to hide it.

Pass icon (a component or an element) or avatarUrl to Select.Item. If both are set, the avatar wins. For a status dot, pass an element such as <Dot className="size-2.5 text-fg-success-secondary" /> as the icon, as the Dot leading example does. The selected option's icon or avatar also appears in the trigger, and the icon prop on Select sets a fallback icon for the trigger.

Not with Select, which is single-selection only. For selections shown as removable tags, use TagSelect from tag-select.tsx as in the Tags example: it takes a selectedItems list created with useListData from react-stately. For a dropdown with checkboxes, use the multi-select component.

Pass label, hint, and tooltip to Select. The tooltip adds a help icon next to the label. Setting isRequired adds an asterisk to the label, which hideRequiredIndicator removes, and isInvalid switches the hint text to the error style.

Rating badge and stars Multi-select