Select
Select
A dropdown menu for displaying choices.
Importimport{ Select }from"antd"; |
Sourcecomponents/select |
- Components Overview
- General
- Layout
- Navigation
- Data Entry
- Data Display
- Feedback
- Other
Importimport{ Select }from"antd"; |
Sourcecomponents/select |
<select> element.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.
// 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>);
Common props ref：Common 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 | 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 | (originNode: ReactNode) => ReactNode | - | |
| dropdownStyle | The style of dropdown menu | 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 | outlined | 5.13.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 | (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) | - |
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 .
| Name | Description | Version |
|---|---|---|
| blur() | Remove focus | |
| focus() | Get focus |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| 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 | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| key | Group key | string | - | |
| label | Group label | React.ReactNode | - | |
| className | The additional class to option | string | - | |
| title | title attribute of Select Option | string | - |
| 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 | undefined | LineHeight<string | number> | 1.5714285714285714 |
| optionPadding | Padding of option | undefined | Padding<string | number> | 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 | undefined | FontWeight | 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 |
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.
dropdownRender?Select will close when it lose focus. You can prevent event to handle this:
<SelectdropdownRender={() => (<divonMouseDown={(e) => {e.preventDefault();e.stopPropagation();}}>Some Content</div>)}/>
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:
<Select listItemHeight={10} listHeight={250} />
Note: listItemHeight and listHeight are internal props. Please only modify when necessary.
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.
Shift the popup if not enough space after flip.
Basic Usage.
Customize search using filterOption.
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.
Search the options with sorting.
Using OptGroup to group the options.
Search with remote data.
Try to copy Lucy,Jack and paste to the input. Only available in tags and multiple mode.
Custom prefix and suffixIcon.
Hide already selected options in the dropdown.
There are outlined filled and borderless, totally three variants to choose from.
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.
Select use virtual scroll which get better performance, turn off it by setting virtual={false}.
You can manually specify the position of the popup via placement.
Debug Usage.
Options label Centered.
Component Token
Search the options while expanded.
Multiple selection, selecting from existing items.
Use optionRender to customize the rendering dropdown options
Allow user to select tags from list or input custom tag.
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.
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.
A complete multiple select sample with remote search, debounce fetch, ajax callback order flow, and loading state.
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.
There are three variants to choose from, namely: outlined filled and borderless.
Allows for custom rendering of tags.
Auto collapse to tag with responsive case. Not recommend use in large form case since responsive calculation has a perf cost.
Add status to Select with status, which could be error or warning.
You can manually specify the position of the popup via placement.
Debug usage. Do not use in your production.
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.
