• Guides

    Get startedComponent definitionDesigning custom elementsDevelopment best practices

  • Styles

    ColorsTypographySpacingShadowsRadii

  • Components

    AvatarButtonCheckboxColorPickerDropdownFormFieldIconIconButtonIllustrationIndicatorLinkListLogoMenuModalNotificationBarPillRadioSelectSkeletonSwitchTabsTextTextareaTextButtonTextInputTypeaheadToastTooltip

    Loaders

    LoaderLogoLoaderEllipsesLoaderWaveformLoader

    Layout

    AlignArrangeBackdropContainerErrorContainerPopoverSpacerSplit

  • Icons

    Icon set

  • Illustrations

    Illustration set

  • Patterns

    Disabled stylesErrorsFormsDiscoveryPlan upgradeSettings

  • Utilities

    CSS utilitiesCSS variablesResponsive

  • Playground

    Layout recipesShowcase

Select

UsageGuidelines

Placeholder

Selected option

Deselection

Use allowsDeselect to add a deselection option. When a selected item is hovered over, its check mark will change to an 'X', indicating the user can click to deselect. The onChange callback will receive null when an item is deselected.

With icon

Accepts icon or image URL/Data URLs.

See the Icon set.

Disabled

Disabled option

Hidden and disabled option

This option is hidden and disabled. It can be used to show the selected option when it's not available in the list.

When an option is hidden, it will be visually removed from the list, but it will still be available in the DOM. And can still be selected through input controls (keyboard, mouse, touch, etc.) and screen readers.

Combined with the isDisabled prop, the option will be inaccessible from input controls (keyboard, mouse, touch, etc.) and hidden visually as well as from screen readers.

With divider

Use to visually separate items without needing labels.
Good for: Simple visual breaks, especially in action menus.

With group

Use when items fall into clear, labeled categories that help users navigate. Good for: Large lists with meaningful, named categories.

Menu can be positoned on the left or right side relative to the trigger. Wrap the <Select> component so it doesn’t take up full width and set menuMinWidth accordingly.

For selects with many options that make it difficult to find the intended value, a search input can be added. By default, the option values are filtered on the inputted value using a loose includes pattern.

Client-side

With string options

With ReactElement options

For options that implement a ReactElement as the title of the options property, the element properties must be joined with React.PropsWithChildren or have the children property. Furthermore, the searchable value of the element must be included as a child of the element to ensure its value can be parsed.

The search.onSearch callback enables server-side/backend search functionality. When a function is passed in, it:

  • Disables client-side filtering (above)
  • Invokes the callback whenever the search input changes with the current search value
  • Calls the callback with an empty string upon dropdown close to reset results
  • Requires your component to update the options prop based on search results

Container

Specify where it's going to be rendered in the DOM, this is especially useful when working with Shadow DOM.

<Select
  container={() => document.querySelector("#renderContainer")}
  options={[{ value: 'bahamas', title: 'Bahamas' }]}
/>

onChange callback

onOuterClick callback

onOpenChange callback

Callback that provides the isOpen value when dropdown opens or closes.

Custom trigger

Use a custom button to trigger the menu. Make sure the trigger element is a button.

With TextButton
With placeholder
With icons and selected option
Display custom trigger based on selected value

With error

Props

name
type
default
menuZIndex
number
1100
menuMaxHeight
string | number
34
triggerOffset
number
0
menuPosition
'left' | 'right' | 'topRight' | 'topLeft'
'left'
errorMessage
string
"Oops, that didn't work."
allowsDeselect
boolean
false
onChange
(selectedOption: OptionsObject) => void
isDisabled
boolean
placeholder
React.ReactNode
selectedOptionValue
string | null
menuMaxWidth
string | number
menuMinWidth
string | number
ariaMenuName
string
options
OptionsObject[] | GroupedOptionsObject[]
container
HTMLElement
onOuterClick
() => void
onOpenChange
(isOpen: boolean) => void
trigger
(triggerContent, buttonProps) => void
hasError
boolean
search
{ searchPlaceholder: string; searchType?: 'contains' | 'startsWith'; /** * Optional callback for backend search. When provided, client-side filtering is disabled * and this callback is called whenever the search input changes. * Use this to fetch search results from your backend API. */ onSearch?: (searchValue: string) => void; }