logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.25.0
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
    • Splitter
      5.21.0
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
    • Tabs
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

Select

A dropdown menu for displaying choices.
Importimport { Select } from "antd";
Sourcecomponents/select
Docs
Edit this pageChangelog

Resources

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

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

PropertyDescriptionTypeDefaultVersion
allowClearCustomize clear iconboolean | { clearIcon?: ReactNode }false5.8.0: Support object type
autoClearSearchValueWhether the current search will be cleared on selecting an item. Only applies when mode is set to multiple or tagsbooleantrue
autoFocusGet focus by defaultbooleanfalse
defaultActiveFirstOptionWhether active first option by defaultbooleantrue
defaultOpenInitial open state of dropdownboolean-
defaultValueInitial selected optionstring | string[] |
number | number[] |
LabeledValue | LabeledValue[]
-
disabledWhether disabled selectbooleanfalse
popupClassNameThe className of dropdown menu, use classNames.popup.root insteadstring-4.23.0
popupMatchSelectWidthDetermine 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 scrollboolean | numbertrue5.5.0
dropdownRenderCustomize dropdown content, use popupRender instead(originNode: ReactNode) => ReactNode-
popupRenderCustomize dropdown content(originNode: ReactNode) => ReactNode-
dropdownStyleThe style of dropdown menu, use styles.popup.root insteadCSSProperties-
fieldNamesCustomize node label, value, options,groupLabel field nameobject{ label: label, value: value, options: options, groupLabel: label }4.17.0 (groupLabel added in 5.6.0)
filterOptionIf 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 excludedboolean | function(inputValue, option)true
filterSortSort function for search options sorting, see Array.sort's compareFunction(optionA: Option, optionB: Option, info: { searchValue: string }) => number-searchValue: 5.19.0
getPopupContainerParent 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. Examplefunction(triggerNode)() => document.body
labelInValueWhether to embed label in value, turn the format of value from string to { value: string, label: ReactNode }booleanfalse
listHeightConfig popup heightnumber256
loadingIndicate loading statebooleanfalse
maxCountThe max number of items can be selected, only applies when mode is multiple or tagsnumber-5.13.0
maxTagCountMax tag count to show. responsive will cost render performancenumber | responsive-responsive: 4.10
maxTagPlaceholderPlaceholder for not showing tagsReactNode | function(omittedValues)-
maxTagTextLengthMax tag text length to shownumber-
menuItemSelectedIconThe custom menuItemSelected icon with multiple optionsReactNode-
modeSet mode of Selectmultiple | tags-
notFoundContentSpecify content to show when no result matchesReactNodeNot Found
openControlled open state of dropdownboolean-
optionFilterPropWhich prop value of option will be used for filter if filterOption is true. If options is set, it should be set to labelstringvalue
optionLabelPropWhich prop value of option will render as content of select. Examplestringchildren
optionsSelect options. Will get better perf than jsx definition{ label, value }[]-
optionRenderCustomize the rendering dropdown options(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode-5.11.0
placeholderPlaceholder of selectReactNode-
placementThe position where the selection box pops upbottomLeft bottomRight topLeft topRightbottomLeft
prefixThe custom prefixReactNode-5.22.0
removeIconThe custom remove iconReactNode-
searchValueThe current input "search" textstring-
showSearchWhether select is searchablebooleansingle: false, multiple: true
sizeSize of Select inputlarge | middle | smallmiddle
statusSet validation status'error' | 'warning'-4.19.0
suffixIconThe 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 bypassReactNode<DownOutlined />
tagRenderCustomize tag render, only applies when mode is set to multiple or tags(props) => ReactNode-
labelRenderCustomize selected label render (LabelInValueType definition see LabelInValueType)(props: LabelInValueType) => ReactNode-5.15.0
tokenSeparatorsSeparator used to tokenize, only applies when mode="tags"string[]-
valueCurrent selected option (considered as a immutable array)string | string[] |
number | number[] |
LabeledValue | LabeledValue[]
-
variantVariants of selectoroutlined | borderless | filled | underlinedoutlined5.13.0 | underlined: 5.24.0
virtualDisable virtual scroll when set to falsebooleantrue4.1.0
onBlurCalled when blurfunction-
onChangeCalled when select an option or input value changefunction(value, option:Option | Array<Option>)-
onClearCalled when clearfunction-4.6.0
onDeselectCalled when an option is deselected, param is the selected option's value. Only called for multiple or tags, effective in multiple or tags mode onlyfunction(value: string | number | LabeledValue)-
onDropdownVisibleChangeCalled when dropdown open, use onOpenChange instead(open: boolean) => void-
onOpenChangeCalled when dropdown open(open: boolean) => void-
onFocusCalled when focus(event: FocusEvent) => void-
onInputKeyDownCalled when key pressed(event: KeyboardEvent) => void-
onPopupScrollCalled when dropdown scrolls(event: UIEvent) => void-
onSearchCallback function that is fired when input changedfunction(value: string)-
onSelectCalled when an option is selected, the params are option's value (or key) and option instancefunction(value: string | number | LabeledValue, option: Option)-
classNamesSemantic DOM classRecord<SemanticDOM, string>-5.25.0
stylesSemantic DOM styleRecord<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

NameDescriptionVersion
blur()Remove focus
focus()Get focus

Option props

PropertyDescriptionTypeDefaultVersion
classNameThe additional class to optionstring-
disabledDisable this optionbooleanfalse
titletitle attribute of Select Optionstring-
valueDefault to filter with this propertystring | number-

OptGroup props

PropertyDescriptionTypeDefaultVersion
keyGroup keystring-
labelGroup labelReact.ReactNode-
classNameThe additional class to optionstring-
titletitle attribute of Select Optionstring-

Semantic DOM

Design Token

Component TokenHow to use?
Token NameDescriptionTypeDefault Value
activeBorderColorActive border colorstring#1677ff
activeOutlineColorActive outline colorstringrgba(5,145,255,0.1)
clearBgBackground color of clear buttonstring#ffffff
hoverBorderColorHover border colorstring#4096ff
multipleItemBgBackground color of multiple tagstringrgba(0,0,0,0.06)
multipleItemBorderColorBorder color of multiple tagstringtransparent
multipleItemBorderColorDisabledBorder color of multiple tag when disabledstringtransparent
multipleItemColorDisabledText color of multiple tag when disabledstringrgba(0,0,0,0.25)
multipleItemHeightHeight of multiple tagnumber24
multipleItemHeightLGHeight of multiple tag with large sizenumber32
multipleItemHeightSMHeight of multiple tag with small sizenumber16
multipleSelectorBgDisabledBackground color of multiple selector when disabledstringrgba(0,0,0,0.04)
optionActiveBgBackground color when option is activestringrgba(0,0,0,0.04)
optionFontSizeFont size of optionnumber14
optionHeightHeight of optionnumber32
optionLineHeightLine height of optionundefined | LineHeight<string | number>1.5714285714285714
optionPaddingPadding of optionundefined | Padding<string | number>5px 12px
optionSelectedBgBackground color when option is selectedstring#e6f4ff
optionSelectedColorText color when option is selectedstringrgba(0,0,0,0.88)
optionSelectedFontWeightFont weight when option is selectedundefined | FontWeight600
selectorBgBackground color of selectorstring#ffffff
showArrowPaddingInlineEndInline end padding of arrownumber18
singleItemHeightLGHeight of single selected item with large sizenumber40
zIndexPopupz-index of dropdownnumber1050
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.

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

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.

Basic Usage

Basic Usage.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom Search

Customize search using filterOption.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Sizes

The height of the input field for the select defaults to 32px. If size is set to large, the height will be 40px, and if set to small, 24px.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Search with sort

Search the options with sorting.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Option Group

Using OptGroup to group the options.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Search Box

Search with remote data.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Automatic tokenization

Try to copy Lucy,Jack and paste to the input. Only available in tags and multiple mode.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Prefix and Suffix

Custom prefix and suffixIcon.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.22.0
Hide Already Selected

Hide already selected options in the dropdown.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom Tag Render

Allows for custom rendering of tags.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Responsive maxTagCount

Auto collapse to tag with responsive case. Not recommend use in large form case since responsive calculation has a perf cost.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Status

Add status to Select with status, which could be error or warning.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Max Count

You can set the maxCount prop to control the max number of items can be selected. When the limit is exceeded, the options will become disabled.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
Select with search field

Search the options while expanded.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
multiple selection

Multiple selection, selecting from existing items.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom dropdown options

Use optionRender to customize the rendering dropdown options

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Tags

Allow user to select tags from list or input custom tag.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
coordinate

Coordinating the selection of provinces and cities is a common use case and demonstrates how selection can be coordinated. Cascader component is strongly recommended in this case.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Get value of selected item

As a default behavior, the onChange callback can only get the value of the selected item. The labelInValue prop can be used to get the label property of the selected item.

The label of the selected item will be packed as an object for passing to the onChange callback.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Search and Select Users

A complete multiple select sample with remote search, debounce fetch, ajax callback order flow, and loading state.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom dropdown

Customize the dropdown menu via dropdownRender. If you want to close the dropdown after clicking the custom content, you need to control open prop, here is an codesandbox.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Variants

Variants of Select, there are four variants: outlined filled borderless and underlined.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
Custom Selected Label Render

Allows custom rendering of the currently selected label, which can be used for value backfill but the corresponding option is missing and does not want to directly render the value.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Big Data

Select use virtual scroll which get better performance, turn off it by setting virtual={false}.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Placement

You can manually specify the position of the popup via placement.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Lucy
Lucy
Lucy
Lucy
Select a person


a1
a10
c12
 
a10
c12
 
Search to Select
lucy
input search text
 
User
Lucy
Lucy
Lucy

User
Lucy
 
Lucy
 
Lucy
 
 
Inserted are removed
gold
cyan
 
+ 4 ...
 
 
Select Item...
Hover Me
 
Ava Swift
 
1 / 3
Select a person
a10
c12
 
a10
c12
 
China
 
 
Tags Mode
Zhejiang
Hangzhou
Lucy (101)
 
Select users
custom dropdown render
Outlined
Lucy
 
Filled
Lucy
 
Borderless
Lucy
 
Underlined
Lucy
 
No option match

100000 Items

a10
c12
 


HangZhou #310000
aojunhao123
  • root
    5.25.0
    Root element
  • popup.root
    5.25.0
    Popup element