A select list enables users to select one or more items from a list. Use a select list when options are dynamic or variable.

Warning alert:Deprecated feature

This implementation has been deprecated in favor of a newer implementation, and is no longer getting maintained or enhanced. To learn more about the process, visit our about page.


Single select

To let users select a single item from a list, use a single select list.

A select list may use other properties for additional customization. Select each checkbox in the example below to visualize the following behavior:

  • To prevent a toggle click from opening a select list, use the isDisabled property.
  • To adjust the direction a select menu opens, use the direction property. The menu in the following example expands upwards. By default, select lists open upwards.
  • To add an icon to a select toggle, use the toggleIcon property.

With item descriptions

To give more context to a <SelectOption> in a list, use the description property.

With grouped items

To group related select options together, use 1 or more <SelectGroup> components and title each group using the label property.

Favoriting items

To allow users to favorite items in a select list, use the onFavorite callback. When users click the favorite button, the item is duplicated and placed in a separated group at the top of the menu. To change the name of the group use the favoritesLabel property.

Validated selections

To validate selections that users make, pass a validation state to the validated property. Validating selections can let users know if the selections they make would cause issues or errors.

The example below passes an "error" state when you choose “select a title”, a "warning" state when you choose "other", and a "success" state for any other item selected from the menu.

Styled placeholder text

To add a toggle label to a select, use the placeholderText property. The following example displays "Filter by status" in the toggle before a selection is made.

To fade the color of placeholderText to gray, use the hasPlaceholderStyle property.

Filter by status

Placeholder select options

To set a <SelectOption> as a placeholder, use the isPlaceholder property. The following example sets the "Filter by status" as a placeholder so that it is pre-selected.

Filter by status

You can add a footer to a <Select> list to hold actions that users can take on menu items.

With view more

To reduce the processing load for long select lists, replace overflow items with a "View more" link at the bottom of the select menu.

Adjust the number of items shown above the "View more" link with the numOptions property. The following example passes 3 items into this property.

Checkbox select

To let users select multiple list options via checkbox input, use a checkbox select. To create a checkbox select, pass variant={SelectVariant.checkbox} into the <Select> component.

By default, a badge is displayed in the menu toggle that indicates the number of items a user has selected.

Checkbox select with grouped items

You can use groups alongside checkbox input. The item count badge will display the number of items selected across all groups.

Checkbox select with custom badge

To change the default badge text for a checkbox select, use the customBadgeText property. The following example uses customBadgeText to display "all" in the badge once all menu items are selected.

Filter by status

Checkbox select without selected count

To remove the default item count badge, use the isCheckboxSelectionBadgeHidden property.

Checkbox select with item counts

To show users the number of items that a <SelectOption> would match, use the itemCount property. The numerical value you pass into itemCount is displayed to the right of each menu item.

You can combine a footer with checkbox input to allow users to apply an action to multiple items.

Checkbox select with view more

When a "view more" link is used alongside checkbox input, selections that users make prior to clicking "view more" are persisted after the click.

Filtering with placeholder text

To preload a filter search bar with placeholder text, use the inlineFilterPlaceholderText property. The following example preloads the search bar with "Filter by status".

Filter by status

Inline filtering

To allow users to filter select lists using text input, use the hasInlineFilter property. Filtering behavior can be further customized with other properties, as shown in the example below. Select each checkbox to visualize the following behavior:

  • To persist filter results on blur, use the isInputValuePersisted property.
  • To persist a filter that a user has searched, use the isInputFilterPersisted property.
  • To allow users to add new items to a select list, use the isCreatable property. When this property is applied and a user searches for an option that doesn't exist, they will be prompted to "create" the item.


Typeahead is a select variant that replaces the typical button toggle for opening the select menu with a text input and button toggle combo. As a user types in the text input, the select menu will provide suggestions by filtering the select options.

To make a typeahead, pass variant=typeahead into the <Select> component. To specify a label for the input field, use the typeAheadAriaLabel property.

A few additional customization options are shown in the example below. Select each checkbox to visualize the following behavior:

  • To place a created item at the top of a typeahead list use the isCreateOptionOnTop property.
  • To trigger a callback for newly created items, use the onCreateOption property.
  • To reset the typeahead value after a user makes a selection, use the shouldResetOnSelect property.

Grouped typeahead

Typeahead matches items with user input across groups.

Typeahead with custom filtering

You can add custom filtering to a select list to better fit needs that aren't covered by inline filtering. If you use custom filtering, use the onFilter property to trigger a callback with your custom filter implementation.

Multiple typeahead

To create a multiple typeahead select variant, pass variant={SelectVariant.typeaheadMulti} into the <Select> component. Multiple typeaheads let users select multiple items from a select list. Selected items appear as chips in the select toggle.

When many items are selected, you can hide overflowing items under a "more" button. The following example hides items after more than 3 are selected. To show hidden items, select the “more” button. Click "show less" to hide extra items again.

Multiple typeahead with custom chips

To customize the appearance of chips, use the chipGroupProps property. The numChips property allows you to control the number of items shown, while the expandedText and collapsedText properties allow you to control the labels of the expansion and collapse chips.

Multiple typeahead with chip group

To customize chips even more, render a <ChipGroup> component and pass it into the chipGroupComponent property of the <Select> component.

Multiple typeahead with custom objects

A <SelectOption> can have an object passed into the value property in order to store additional data beyond just a string value. The object passed in must have a toString function that returns a string to display in the SelectMenu.

Plain multiple typeahead

To plainly style a typeahead, use the isPlain property.

Custom menu content

To add custom menu content, use the customContent property.

Appending document body vs parent

Avoid passing in document.body to the menuAppendTo property. Doing so can cause accessibility issues because this prevents users from being able to enter the contents of the select options via assistive technologies (like keyboards or screen readers). Instead, pass in parent to achieve the same result without sacrificing accessibility.

The following example demonstrates both methods. When the dropdown is opened, both select variants manage focus the same way, but behave differently when the tab key is pressed after an option is selected.

  • For the document.body variant, the focus will be placed at the end of the page, since that is where the dropdown content is appended to in the DOM (rather than focus being placed on the second Select variant as one might expect).
  • For the parent variant, however, the focus will be placed on the next tab-able element (the "Toggle JS code" button for the code editor in this case).



onTogglerequired(event: React.MouseEvent | React.ChangeEvent | React.KeyboardEvent | Event, isExpanded: boolean) => voidCallback for toggle button behavior
aria-describedbystring''Id of div for the select aria-labelledby
aria-invalidbooleanfalseFlag indicating if the select is an invalid state
aria-labelstring''Adds accessible text to Select
aria-labelledbystring''Id of label for the Select aria-labelledby
childrenReact.ReactElement[][]Content rendered inside the Select. Must be React.ReactElement<SelectGroupProps>[]
chipGroupComponentReact.ReactNodenullOptional props to render custom chip group in the typeaheadmulti variant
chipGroupPropsOmit<ChipGroupProps, 'children' | 'ref'>Optional props to pass to the chip group in the typeaheadmulti variant
classNamestring''Classes applied to the root of the Select
clearSelectionsAriaLabelstring'Clear all'Label for clear selection button of type ahead select variants
createTextstring'Create'Text displayed in typeahead select to prompt the user to create an item
customBadgeTextstring | numbernullCustom text for select badge
customContentReact.ReactNodenullCustom content to render in the select menu. If this prop is defined, the variant prop will be ignored and the select will render with a single select toggle
direction'up' | 'down'SelectDirection.downFlag specifying which direction the Select menu expands
favoritesstring[][]ID list of favorited select items
favoritesLabelstring'Favorites'Label for the favorites group
footerReact.ReactNodeContent rendered in the footer of the select menu
hasInlineFilterbooleanfalseFlag indicating if select should have an inline text input for filtering
hasPlaceholderStylebooleanfalseFlag indicating if placeholder styles should be applied
inlineFilterPlaceholderTextstringnullPlaceholder text for inline filter
inputAutoCompletestring'off'Value for the typeahead and inline filtering input autocomplete attribute. When targeting Chrome this property should be a random string.
inputIdPrefixstring''Prefix for the id of the input in the checkbox select variant
isCheckboxSelectionBadgeHiddenbooleanFlag indicating if selection badge should be hidden for checkbox variant,default false
isCreatablebooleanfalseFlag to indicate if the typeahead select allows new items
isCreateOptionOnTopbooleanfalseFlag to indicate if create option should be at top of typeahead
isCreateSelectOptionObjectbooleanfalseFlag indicating if the creatable option should set its value as a SelectOptionObject
isDisabledbooleanfalseFlag to indicate if select is disabled
isFlipEnabledbooleantrueFlag for indicating that the select menu should automatically flip vertically when it reaches the boundary. This prop can only be used when the select component is not appended inline, e.g. `menuAppendTo="parent"`
isGroupedbooleanfalseFlag to indicate if select options are grouped
isInputFilterPersistedbooleanfalseFlag for retaining filter results on blur from keyboard-entered typeahead text
isInputValuePersistedbooleanfalseFlag for retaining keyboard-entered value in typeahead text field when focus leaves input away
isOpenbooleanfalseFlag to indicate if select is open
isPlainbooleanfalseDisplay the toggle with no border or background
loadingVariant'spinner' | SelectViewMoreObjectLoading variant to display either the spinner or the view more text button
maxHeightstring | numberMax height of the select container as a number of px or string percentage
menuAppendToHTMLElement | (() => HTMLElement) | 'inline' | 'parent''inline'The container to append the menu to. Defaults to 'inline'. If your menu is being cut off you can append it to an element higher up the DOM tree. Some examples: menuAppendTo="parent" menuAppendTo={() => document.body} menuAppendTo={document.getElementById('target')}
noResultsFoundTextstring'No results found'Text to display in typeahead select when no results are found
onBlur(event?: any) => voidCallback for toggle blur
onClear(event: React.MouseEvent) => void() => undefined as voidCallback for typeahead clear button
onCreateOption(newOptionValue: string) => void() => undefined as voidOptional callback for newly created options
onFavorite(itemId: string, isFavorite: boolean) => voidEnables favorites. Callback called when a select options's favorite button is clicked
onFilter(e: React.ChangeEvent<HTMLInputElement> | null, value: string) => React.ReactElement[] | undefinednullOptional callback for custom filtering
onSelect( event: React.MouseEvent | React.ChangeEvent, value: string | SelectOptionObject, isPlaceholder?: boolean ) => voidCallback for selection behavior
onTypeaheadInputChanged(value: string) => voidnullOptional event handler called each time the value in the typeahead input changes.
ouiaIdnumber | stringValue to overwrite the randomly generated data-ouia-component-id.
ouiaSafebooleantrueSet the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.
placeholderTextstring | React.ReactNode''Title text of Select
positionSelectPosition | 'right' | 'left'SelectPosition.leftIndicates where menu will be aligned horizontally
removeSelectionAriaLabelstring'Remove'Label for remove chip button of multiple type ahead select variant
selectionsstring | SelectOptionObject | (string | SelectOptionObject)[][]Array of selected items for multi select variants.
shouldResetOnSelectbooleantrueFlag indicating the typeahead input value should reset upon selection
toggleAriaLabelstring'Options menu'Label for toggle of type ahead select variants
toggleIconReact.ReactElementnullIcon element to render inside the select toggle
toggleIdstringnullId for select toggle element
toggleIndicatorReact.ReactElementnullCustom icon for the dropdown replacing the CaretDownIcon
toggleRefReact.Ref<HTMLButtonElement> | React.Ref<HTMLDivElement>Ref for the select toggle element
typeAheadAriaDescribedbystring''Id of div for input field of type ahead select variants
typeAheadAriaLabelstring''Label for input field of type ahead select variants
validated'success' | 'warning' | 'error' | 'default''default'Value to indicate if the select is modified to show that validation state. If set to success, select will be modified to indicate valid state. If set to error, select will be modified to indicate error state. If set to warning, select will be modified to indicate warning state.
variant'single' | 'checkbox' | 'typeahead' | 'typeaheadmulti'SelectVariant.singleVariant of rendered Select
widthstring | number''Width of the select container as a number of px or string percentage
zIndexnumber9999z-index of the select menu when menuAppendTo is not inline.


ariaIsFavoriteLabelstringAria label text for favoritable button when favorited
ariaIsNotFavoriteLabelstringAria label text for favoritable button when not favorited
childrenReact.ReactNodeOptional alternate display for the option
classNamestring''Additional classes added to the Select Option
componentReact.ReactNode'button'Indicates which component will be used as select item
descriptionReact.ReactNodeDescription of the item for single and both typeahead select variants
idstringID of the item. Required for tracking favorites
inputIdstring''Id of the checkbox input
isDisabledbooleanfalseFlag indicating if the option is disabled
isFocusedbooleanFlag forcing the focused state
isNoResultsOptionbooleanfalseFlag indicating if the option acts as a "no results" indicator
isPlaceholderbooleanfalseFlag indicating if the option acts as a placeholder
itemCountnumberNumber of items matching the option
onClick(event: React.MouseEvent | React.ChangeEvent) => void() => {}Optional callback for click event
valuestring | SelectOptionObject''The value for the option, can be a string or select option object


childrenReact.ReactNode[]Checkboxes within group. Must be React.ReactElement<SelectOptionProps>[]
classNamestring''Additional classes added to the CheckboxSelectGroup control
labelstring''Group label
titleIdstring''ID for title label


toStringrequiredstringFunction returns a string to represent the select option object
compareTobooleanFunction returns a true if the passed in select option is equal to this select option object, false otherwise


onClickrequired(event: React.MouseEvent | React.ChangeEvent) => voidCallback for when the view more button is clicked
textrequiredstringView more text

CSS variables

Expand or collapse columnSelectorVariableValue
calc(100% - 1.5rem)
1px solid transparent
0 0.25rem 0.5rem 0rem rgba(3, 3, 3, 0.12), 0 0 0.25rem 0 rgba(3, 3, 3, 0.06)
calc(100% + 0.25rem)
calc(-100% - 0.25rem)