Importimport { Select } from "antd"; |
Docs |
contributors
<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 |
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 | |
| classNames | Customize class for each semantic structure inside the Select component. Supports object or function. | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | |
| 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 | |
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 |
Customize dropdown content, use popupRender instead | (originNode: ReactNode) => ReactNode | - | ||
| popupRender | Customize dropdown content | (originNode: ReactNode) => ReactNode | - | |
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) |
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 | ||
| 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 | - | |
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 | - | |
| The current input "search" text | string | - | ||
| showSearch | Whether select is searchable | boolean | Object | single: false, multiple: true | |
| size | Size of Select input | large | middle | small | middle | |
| status | Set validation status | 'error' | 'warning' | - | 4.19.0 |
| styles | Customize inline style for each semantic structure inside the Select component. Supports object or function. | Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties> | - | |
| 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 |
| onActive | Called when keyboard or mouse interaction occurs | function(value: string | number | LabeledValue) | - | |
| 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) | - | |
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 | - | |
| 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 .
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| autoClearSearchValue | Whether the current search will be cleared on selecting an item. Only applies when mode is set to multiple or tags | boolean | true | |
| 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 |
| 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 | |
| searchValue | The current input "search" text | string | - | |
| onSearch | Callback function that is fired when input changed | function(value: string) | - |
| 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 | 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 |
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.
tagRender will pop up a drop-down box when clicked to closeIf 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.
<SelecttagRender={(props) => {const { closable, label, onClose } = props;return (<span className="border">{label}{closable ? (<spanonMouseDown={(e) => e.stopPropagation()}onClick={onClose}className="cursor-pointer">❎</span>) : null}</span>);}}/>