Select
Select
Importimport { Select } from 'antd'; |
<select> element.Common props ref：Common props
| Property | Description | Type | Default | Version | Global Config |
|---|---|---|---|---|---|
| allowClear | Customize clear icon | boolean | { clearIcon?: ReactNode } | false | 5.8.0: Support object type | 6.4.0 |
Whether the current search will be cleared on selecting an item. Only applies when mode is set to multiple or tags | boolean | true | × | ||
Whether has border style, please use variant instead | boolean | true | - | × | |
| classNames | Customize class for each semantic structure inside the Select component. Supports object or function. | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | 5.25.0 | |
| 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, please use classNames.popup.root instead | string | - | - | × | |
Determine whether the popup menu and the select input are the same width, please use popupMatchSelectWidth instead | boolean | number | true | - | × | |
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 | - | 5.25.0 | × |
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 | × | |
| loadingIcon | Customize the loading icon | ReactNode | <LoadingOutlined spin /> | 6.4.0 | 6.4.0 |
| 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 | <CheckOutlined /> | 6.4.0 | |
| 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 | - | × | |
Deprecated, see showSearch.optionFilterProp | × | ||||
| 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 | <CloseOutlined /> | 6.4.0 | |
| The current input "search" text | string | - | × | ||
Whether to show the arrow icon, please use suffixIcon={null} instead | boolean | true | - | × | |
| showSearch | Whether select is searchable | boolean | Object | single: false, multiple: true | Object: 6.0.0 | 6.4.0 |
| size | Size of Select input | large | medium | small | medium | × | |
| 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> | - | 5.25.0 | |
| suffixIcon | The custom suffix icon. Custom icons will not respond to clicks to open, because the replaced icon may be designed for other interactions. You can use pointer-events: none style to bypass | ReactNode | <DownOutlined /> | 6.4.0 | |
| 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" or mode="multiple" | string[] | ((input: string) => string[]) | - | function: 6.5.0 | × |
| 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 | 5.19.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. When a string[] is provided, multiple fields are searched using OR matching. | string | string[] | value | string[]: 6.1.0 |
| searchValue | The current input "search" text | string | - | |
| onSearch | Callback function that is fired when input changed | function(value: string) | - | |
| searchIcon | Customize the search icon | ReactNode | <SearchOutlined /> | 6.4.0 |
| 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 |
| Token Name | Description | Type | Default Value |
|---|---|---|---|
| colorBgBase | Used to derive the base variable of the background color gradient. In v5, we added a layer of background color derivation algorithm to produce map token of background color. But PLEASE DO NOT USE this Seed Token directly in the code! | string | #fff |
| colorBgContainer | Container background color, e.g: default button, input box, etc. Be sure not to confuse this with `colorBgElevated`. | string | #ffffff |
| colorBgContainerDisabled | Control the background color of container in disabled state. | string | rgba(0,0,0,0.04) |
| colorBgElevated | Container background color of the popup layer, in dark mode the color value of this token will be a little brighter than `colorBgContainer`. E.g: modal, pop-up, menu, etc. | string | #ffffff |
| colorBorder | Default border color, used to separate different elements, such as: form separator, card separator, etc. | string | #d9d9d9 |
| colorBorderDisabled | Control the border color of the element in the disabled state. | string | #d9d9d9 |
| colorError | Used to represent the visual elements of the operation failure, such as the error Button, error Result component, etc. | string | #ff4d4f |
| colorErrorAffix | Control the color of form control prefix/suffix in error state. | string | #ff4d4f |
| colorErrorBg | The background color of the error state. | string | #fff2f0 |
| colorErrorBgHover | The hover state background color of the error state. | string | #fff1f0 |
| colorErrorBorderHover | The hover state border color of the error state. | string | #ffa39e |
| colorErrorOutline | Control the outline color of input component in error state. | string | rgba(255,38,5,0.06) |
| colorErrorText | The default state of the text in the error color. | string | #ff4d4f |
| colorFillSecondary | The second level of fill color can outline the shape of the element more clearly, such as Rate, Skeleton, etc. It can also be used as the Hover state of the third level of fill color, such as Table, etc. | string | rgba(0,0,0,0.06) |
| colorFillTertiary | The third level of fill color is used to outline the shape of the element, such as Slider, Segmented, etc. If there is no emphasis requirement, it is recommended to use the third level of fill color as the default fill color. | string | rgba(0,0,0,0.04) |
| colorIcon | Weak action. Such as `allowClear` or Alert close button | string | rgba(0,0,0,0.45) |
| colorIconHover | Weak action hover color. Such as `allowClear` or Alert close button | string | rgba(0,0,0,0.88) |
| colorPrimary | Brand color is one of the most direct visual elements to reflect the characteristics and communication of the product. After you have selected the brand color, we will automatically generate a complete color palette and assign it effective design semantics. | string | #1677ff |
| colorSplit | Used as the color of separator, this color is the same as colorBorderSecondary but with transparency. | string | rgba(5,5,5,0.06) |
| colorText | Default text color which comply with W3C standards, and this color is also the darkest neutral color. | string | rgba(0,0,0,0.88) |
| colorTextDescription | Control the font color of text description. | string | rgba(0,0,0,0.45) |
| colorTextDisabled | Control the color of text in disabled state. | string | rgba(0,0,0,0.25) |
| colorTextPlaceholder | Control the color of placeholder text. | string | rgba(0,0,0,0.25) |
| colorTextQuaternary | The fourth level of text color is the lightest text color, such as form input prompt text, disabled color text, etc. | string | rgba(0,0,0,0.25) |
| colorWarning | Used to represent the warning map token, such as Notification, Alert, etc. Alert or Control component(like Input) will use these map tokens. | string | #faad14 |
| colorWarningAffix | Control the color of form control prefix/suffix in warning state. | string | #faad14 |
| colorWarningBg | The background color of the warning state. | string | #fffbe6 |
| colorWarningBgHover | The hover state background color of the warning state. | string | #fff1b8 |
| colorWarningHover | The hover state of the warning color. | string | #ffd666 |
| colorWarningOutline | Control the outline color of input component in warning state. | string | rgba(255,215,5,0.1) |
| borderRadius | Border radius of base components | number | 6 |
| borderRadiusLG | LG size border radius, used in some large border radius components, such as Card, Modal and other components. | number | 8 |
| borderRadiusSM | SM size border radius, used in small size components, such as Button, Input, Select and other input components in small size | number | 4 |
| borderRadiusXS | XS size border radius, used in some small border radius components, such as Segmented, Arrow and other components with small border radius. | number | 2 |
| boxShadowSecondary | Control the secondary box shadow style of an element. | string | 0 6px 16px 0 rgba(0,0,0,0.08), 0 3px 6px -4px rgba(0,0,0,0.12), 0 9px 28px 8px rgba(0,0,0,0.05) |
| controlHeight | The height of the basic controls such as buttons and input boxes in Ant Design | number | 32 |
| controlHeightLG | LG component height | number | 40 |
| controlHeightSM | SM component height | number | 24 |
| controlItemBgActiveHover | Control the background color of control component item when hovering and active. | string | #bae0ff |
| controlOutlineWidth | Control the outline width of input component. | number | 2 |
| controlPaddingHorizontal | Control the horizontal padding of an element. | number | 12 |
| fontFamily | The font family of Ant Design prioritizes the default interface font of the system, and provides a set of alternative font libraries that are suitable for screen display to maintain the readability and readability of the font under different platforms and browsers, reflecting the friendly, stable and professional characteristics. | string | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji' |
| fontSize | The most widely used font size in the design system, from which the text gradient will be derived. | number | 14 |
| fontSizeIcon | Control the font size of operation icon in Select, Cascader, etc. Normally same as fontSizeSM. | number | 12 |
| fontSizeLG | Large font size | number | 16 |
| fontSizeSM | Small font size | number | 12 |
| lineHeight | Line height of text. | number | 1.5714285714285714 |
| lineHeightLG | Line height of large text. | number | 1.5 |
| lineType | Border style of base components | string | solid |
| lineWidth | Border width of base components | number | 1 |
| marginXS | Control the margin of an element, with a small size. | number | 8 |
| motionDurationMid | Motion speed, medium speed. Used for medium element animation interaction. | string | 0.2s |
| motionDurationSlow | Motion speed, slow speed. Used for large element animation interaction. | string | 0.3s |
| motionEaseInOut | Preset motion curve. | string | |
| motionEaseInOutCirc | Preset motion curve. | string | |
| motionEaseInQuint | Preset motion curve. | string | |
| motionEaseOutCirc | Preset motion curve. | string | |
| motionEaseOutQuint | Preset motion curve. | string | |
| paddingSM | Control the small padding of the element. | number | 12 |
| paddingXS | Control the extra small padding of the element. | number | 8 |
| paddingXXS | Control the extra extra small padding of the element. | number | 4 |
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.
popupRender?Select will close when it lose focus. You can prevent event to handle this:
<SelectpopupRender={() => (<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 tag open the dropdown?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.
<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>);}}/>