Select

When To Use

A dropdown menu for displaying choices - an elegant alternative to the native <select> element.
Utilizing Radio is recommended when there are fewer total options (less than 5).
You probably need AutoComplete if you're looking for an input box that can be typed or selected.

Usage upgrade 5.11.0+

Upgrade Tip

After version 5.11.0, we provide a simpler usage <Select options={[...]} /> with better performance and potential of writing simpler code style in your applications. Meanwhile, we deprecated the old usage in browser console, we will remove it in antd 6.0.

jsx

// works when >=5.11.0, recommended ✅
return <Select options={[{ value: 'sample', label: <span>sample</span> }]} />;

// works when <5.11.0, deprecated when >=5.11.0 🙅🏻‍♀️
return (
  <Select onChange={onChange}>
    <Select.Option value="sample">Sample</Select.Option>
  </Select>
);

Examples

API

Common props ref：Common props

Select props

Property	Description	Type	Default	Version
allowClear	Customize clear icon	boolean \| { clearIcon?: ReactNode }	false	5.8.0: Support object type
autoClearSearchValue	Whether the current search will be cleared on selecting an item. Only applies when `mode` is set to `multiple` or `tags`	boolean	true
autoFocus	Get focus by default	boolean	false
defaultActiveFirstOption	Whether active first option by default	boolean	true
defaultOpen	Initial open state of dropdown	boolean	-
defaultValue	Initial selected option	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
disabled	Whether disabled select	boolean	false
~~popupClassName~~	The className of dropdown menu, use `classNames.popup.root` instead	string	-	4.23.0
popupMatchSelectWidth	Determine whether the popup menu and the select input are the same width. Default set `min-width` same as input. Will ignore when value less than select width. `false` will disable virtual scroll	boolean \| number	true	5.5.0
~~dropdownRender~~	Customize dropdown content, use `popupRender` instead	(originNode: ReactNode) => ReactNode	-
popupRender	Customize dropdown content	(originNode: ReactNode) => ReactNode	-
~~dropdownStyle~~	The style of dropdown menu, use `styles.popup.root` instead	CSSProperties	-
fieldNames	Customize node label, value, options，groupLabel field name	object	{ label: `label`, value: `value`, options: `options`, groupLabel: `label` }	4.17.0 (`groupLabel` added in 5.6.0)
filterOption	If true, filter options by input, if function, filter options against it. The function will receive two arguments, `inputValue` and `option`, if the function returns `true`, the option will be included in the filtered set; Otherwise, it will be excluded	boolean \| function(inputValue, option)	true
filterSort	Sort function for search options sorting, see Array.sort's compareFunction	(optionA: Option, optionB: Option, info: { searchValue: string }) => number	-	`searchValue`: 5.19.0
getPopupContainer	Parent Node which the selector should be rendered to. Default to `body`. When position issues happen, try to modify it into scrollable content and position it relative. Example	function(triggerNode)	() => document.body
labelInValue	Whether to embed label in value, turn the format of value from `string` to { value: string, label: ReactNode }	boolean	false
listHeight	Config popup height	number	256
loading	Indicate loading state	boolean	false
maxCount	The max number of items can be selected, only applies when `mode` is `multiple` or `tags`	number	-	5.13.0
maxTagCount	Max tag count to show. `responsive` will cost render performance	number \| `responsive`	-	responsive: 4.10
maxTagPlaceholder	Placeholder for not showing tags	ReactNode \| function(omittedValues)	-
maxTagTextLength	Max tag text length to show	number	-
menuItemSelectedIcon	The custom menuItemSelected icon with multiple options	ReactNode	-
mode	Set mode of Select	`multiple` \| `tags`	-
notFoundContent	Specify content to show when no result matches	ReactNode	`Not Found`
open	Controlled open state of dropdown	boolean	-
optionFilterProp	Which prop value of option will be used for filter if filterOption is true. If `options` is set, it should be set to `label`	string	`value`
optionLabelProp	Which prop value of option will render as content of select. Example	string	`children`
options	Select options. Will get better perf than jsx definition	{ label, value }[]	-
optionRender	Customize the rendering dropdown options	(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode	-	5.11.0
placeholder	Placeholder of select	ReactNode	-
placement	The position where the selection box pops up	`bottomLeft` `bottomRight` `topLeft` `topRight`	bottomLeft
prefix	The custom prefix	ReactNode	-	5.22.0
removeIcon	The custom remove icon	ReactNode	-
searchValue	The current input "search" text	string	-
showSearch	Whether select is searchable	boolean	single: false, multiple: true
size	Size of Select input	`large` \| `middle` \| `small`	`middle`
status	Set validation status	'error' \| 'warning'	-	4.19.0
suffixIcon	The custom suffix icon. Customize icon will not response click open to avoid icon designed to do other interactive. You can use `pointer-events: none` style to bypass	ReactNode	`<DownOutlined />`
tagRender	Customize tag render, only applies when `mode` is set to `multiple` or `tags`	(props) => ReactNode	-
labelRender	Customize selected label render (LabelInValueType definition see LabelInValueType)	(props: LabelInValueType) => ReactNode	-	5.15.0
tokenSeparators	Separator used to tokenize, only applies when `mode="tags"`	string[]	-
value	Current selected option (considered as a immutable array)	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
variant	Variants of selector	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
virtual	Disable virtual scroll when set to false	boolean	true	4.1.0
onBlur	Called when blur	function	-
onChange	Called when select an option or input value change	function(value, option:Option \| Array<Option>)	-
onClear	Called when clear	function	-	4.6.0
onDeselect	Called when an option is deselected, param is the selected option's value. Only called for `multiple` or `tags`, effective in multiple or tags mode only	function(value: string \| number \| LabeledValue)	-
~~onDropdownVisibleChange~~	Called when dropdown open, use `onOpenChange` instead	(open: boolean) => void	-
onOpenChange	Called when dropdown open	(open: boolean) => void	-
onFocus	Called when focus	(event: FocusEvent) => void	-
onInputKeyDown	Called when key pressed	(event: KeyboardEvent) => void	-
onPopupScroll	Called when dropdown scrolls	(event: UIEvent) => void	-
onSearch	Callback function that is fired when input changed	function(value: string)	-
onSelect	Called when an option is selected, the params are option's value (or key) and option instance	function(value: string \| number \| LabeledValue, option: Option)	-
classNames	Semantic DOM class	Record<SemanticDOM, string>	-	5.25.0
styles	Semantic DOM style	Record<SemanticDOM, CSSProperties>	-	5.25.0

Note, if you find that the drop-down menu scrolls with the page, or you need to trigger Select in other popup layers, please try to use getPopupContainer={triggerNode => triggerNode.parentElement} to fix the drop-down popup rendering node in the parent element of the trigger .

Select Methods

Name	Description	Version
blur()	Remove focus
focus()	Get focus

Option props

Property	Description	Type	Default
className	The additional class to option	string	-
disabled	Disable this option	boolean	false
title	`title` attribute of Select Option	string	-
value	Default to filter with this property	string \| number	-

OptGroup props

Property	Description	Type	Default
key	Group key	string	-
label	Group label	React.ReactNode	-
className	The additional class to option	string	-
title	`title` attribute of Select Option	string	-

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
activeBorderColor	Active border color	string	#1677ff
activeOutlineColor	Active outline color	string	rgba(5,145,255,0.1)
clearBg	Background color of clear button	string	#ffffff
hoverBorderColor	Hover border color	string	#4096ff
multipleItemBg	Background color of multiple tag	string	rgba(0,0,0,0.06)
multipleItemBorderColor	Border color of multiple tag	string	transparent
multipleItemBorderColorDisabled	Border color of multiple tag when disabled	string	transparent
multipleItemColorDisabled	Text color of multiple tag when disabled	string	rgba(0,0,0,0.25)
multipleItemHeight	Height of multiple tag	number	24
multipleItemHeightLG	Height of multiple tag with large size	number	32
multipleItemHeightSM	Height of multiple tag with small size	number	16
multipleSelectorBgDisabled	Background color of multiple selector when disabled	string	rgba(0,0,0,0.04)
optionActiveBg	Background color when option is active	string	rgba(0,0,0,0.04)
optionFontSize	Font size of option	number	14
optionHeight	Height of option	number	32
optionLineHeight	Line height of option	LineHeight<string \| number> \| undefined	1.5714285714285714
optionPadding	Padding of option	Padding<string \| number> \| undefined	5px 12px
optionSelectedBg	Background color when option is selected	string	#e6f4ff
optionSelectedColor	Text color when option is selected	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	Font weight when option is selected	FontWeight \| undefined	600
selectorBg	Background color of selector	string	#ffffff
showArrowPaddingInlineEnd	Inline end padding of arrow	number	18
singleItemHeightLG	Height of single selected item with large size	number	40
zIndexPopup	z-index of dropdown	number	1050

Global TokenHow to use?

FAQ

Why sometime search will show 2 same option when in `tags` mode?

It's caused by option with different label and value. You can use optionFilterProp="label" to change filter logic instead.

You can control it by open prop: codesandbox.

I don't want dropdown close when click inside `dropdownRender`?

Select will close when it lose focus. You can prevent event to handle this:

tsx

<Select
  dropdownRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>

Why sometime customize Option cause scroll break?

Virtual scroll internal set item height as 24px. You need to adjust listItemHeight when your option height is less and listHeight config list container height:

tsx

<Select listItemHeight={10} listHeight={250} />

Note: listItemHeight and listHeight are internal props. Please only modify when necessary.

Why a11y test report missing `aria-` props?

Select only create a11y auxiliary node when operating on. Please open Select and retry. For aria-label & aria-labelledby miss warning, please add related prop to Select with your own requirement.

Default virtual scrolling will create a mock element to simulate an accessible binding. If a screen reader needs to fully access the entire list, you can set virtual={false} to disable virtual scrolling and the accessibility option will be bound to the actual element.

Custom tags generated using `tagRender` will pop up a drop-down box when clicked to close

If you don't want a drop-down menu to appear automatically after clicking on an element (such as a close icon), you can prevent the MouseDown event from propagating on it.

tsx

<Select
  tagRender={(props) => {
    const { closable, label, onClose } = props;
    return (
      <span className="border">
        {label}
        {closable ? (
          <span
            onMouseDown={(e) => e.stopPropagation()}
            onClick={onClose}
            className="cursor-pointer"
          >
            ❎
          </span>
        ) : null}
      </span>
    );
  }}
/>

When To Use

Usage upgrade 5.11.0+

Examples

API

Select props

Select Methods

Option props

OptGroup props

Semantic DOM

Design Token

FAQ

Why sometime search will show 2 same option when in tags mode?

When I click elements in dropdownRender, the select dropdown will not be closed?

I don't want dropdown close when click inside dropdownRender?

Why sometime customize Option cause scroll break?

Why a11y test report missing aria- props?

Custom tags generated using tagRender will pop up a drop-down box when clicked to close

100000 Items

root

popup.root

Why sometime search will show 2 same option when in `tags` mode?

I don't want dropdown close when click inside `dropdownRender`?

Why a11y test report missing `aria-` props?

Custom tags generated using `tagRender` will pop up a drop-down box when clicked to close