Input · Select
Select
The user can select one or more options from a set of options through the Select selector and present the final selection result
Demos
How to import
Basic Usage
Each Option tag must declare the
value
attribute, and the Option children
content will be rendered to the drop-down listPass Option as an array
You can pass an array of objects directly through
optionList
. Each object must contain the value / label attribute.Multi-choice
Since v2.28, the selector will have its own maxHeight 270, and the content can be viewed by scrolling vertically after it exceeds.
Configuration
multiple
properties that can support multi-selectionConfiguration
maxTagCount
. You can limit the number of options displayed, and the excess will be displayed in the form of + NConfigure
ellipsisTrigger
(>= v2.28.0) to do adaptive processing on the overflow part of the tag. When the width is insufficient, the last tag content will be truncated. After enabling this function, there will be a certain performance loss, and it is not recommended to use it in large form scenariosConfigure
expandRestTagsOnClick
(>= v2.28.0) to display all remaining tags by clicking when maxTagCount
is setUse
showRestTagsPopover
(>= v2.22.0) to set whether hover +N displays Popover after exceeding maxTagCount
, the default is false
. Also, popovers can be configured in the restTagsPopoverProps
propertyConfiguration
max
Properties can limit the maximum number of options and cannot be selected beyond the maximum limit, while triggeringOn Exceed
callbackWith Group
Grouping Option with
OptGroup
(Only supports the declaration of children through jsx, and does not support pass in through optionList)Different sizes
Size: small / default / large
Different validate status
validateStatus: default / warning / error
Configure Prefix, Suffix, Clear Button
- You can pass the selection box prefix through
prefix
, the selection box suffix throughsuffix
, for text or React Node
The left and right padding is automatically brought when the content passed in by prefix and reactix is text or Icon. If it is a custom ReactNode, the left and right padding is 0. - Whether to show the clear button is displayed by
showClear
- Whether to show the right drop-down arrow is displayed by
showArrow
Select with inset label
By setting
When the incoming type is ReactNode, you need to handle the padding between the label and the text.
insetLabel
, you can set a label for Select, you can pass in string or ReactNodeWhen the incoming type is ReactNode, you need to handle the padding between the label and the text.
Additional items
We have reserved two slots at the bottom of the pop-up layer, which you can use when you need to add a custom node to the pop-up layer.
Use
Use
innerTopSlot
or outerTopSlot
to pass the custom node, which will be rendered at the top of the pop-up layer. UseinnerBottomSlot
or outerBottomSlot
instead at the bottom.innerTopSlot
andinnerBottomSlot
will be rendered inside the Option ListouterTopSlot
andouterBottomSlot
will be rendered to level with the option List
Using outerTopSlot to insert content
Controlled component
When
value
is passed, Select is a controlled component, and the value selected is entirely determined by value
.Linkage Select
If it is a complex linkage with a hierarchical relationship, it is recommended to use Cascader components directly
Search
You can turn on the search capability by setting
The default search strategy will include comparison of the input value with the label value of option
filter
to true.The default search strategy will include comparison of the input value with the label value of option
By default, the search keywords will be cleared automatically after multiple selection is selected. If you want to keep it, you can turn off the default behavior by setting
autoClearSearchValue
to false (provided after v2.3)Search position
The default search input is displayed on the Select Trigger. You can specify different positions through
If you want to customize the placeholder of the Input search box in the dropdown, you can control it through
If the
If the
searchPosition
, and you can choose dropdown
or trigger
. Available after v2.61.0
If you want to customize the placeholder of the Input search box in the dropdown, you can control it through
searchPlaceholder
If the
searchPosition
is trigger
, when showClear=true
, clicking the clear button of the input will clear the selected items and the search text in the input at the same timeIf the
searchPosition
is dropdown
, when showClear=true
, clicking the clear button of the trigger will clear the selected items, clicking the clear button in the dropdown input will clear search text Remote search
A multi-select example with remote search, request debounce, loading status.
- Use
filter
turn on the search capability. - Use
remote
to disabled local filter - Dynamic Update
optionList
afteronSearch
callback - Update
loading
when fetching data / finish - Use controlled value attribute
Custom search strategy
By default, the user's search input will be compared with the option's label value as a string include.
You can set
You can set
filter
as a custom function to customize your filter strategy.Custom selection rendering
By default, the content of
But you can customize the rendering of the selection box through the
option.label
or option.children
will be backfilled into the selection box when the option is selected.But you can customize the rendering of the selection box through the
renderSelectedItem
function- Select:
renderSelectedItem(optionNode: object) => content: ReactNode
- Multiple Select:
renderSelectedItem(optionNode: object, { index: number, onClose: function }) => { isRenderInTag: boolean, content: ReactNode }
- When
isRenderInTag
is true, content will automatically wrapped inTag
rendering (with background color and close button) - When
isRenderInTag
is false, it renders the returned content directly
- When
Custom pop-up layer style
You can control the style of the pop-up layer through
For example, when you customize the width of the pop-up layer, you can pass the width through
dropdownClassName
, dropdownStyle
For example, when you customize the width of the pop-up layer, you can pass the width through
drowndownStyle
Dynamic Modification Options
If you need to update Options dynamically, you should use controlled value
Get all attribute of selected option
By default, through
If you need to take other attributes of the selected option, you can use
At this time, the argument of
Note that when onChange With Object is set to true,
onChange
uou can only get value attribute of selected option.If you need to take other attributes of the selected option, you can use
onChangeWithObject
PropertiesAt this time, the argument of
onChange
will be object, containing various attributes of selected option, eg: onChange({ value, label, ...rest })
Note that when onChange With Object is set to true,
defaultValue
/Value
it should also be object and must have value
keyCreate entries
You can create and select entries that do not exist in the options by setting
allowCreate=true
You can customize the content display when creating the label through renderCreateItem (by returning ReactNode, note that you need to customize the style) In addition, can be used with the defaultActiveFirstOption
property to automatically select the first item. When you enter directly and press Enter, you can immediately create an OptionVirtualize
Turn on list virtualization when passing in
virtualize
to optimize performance when there are a large number of Option nodes virtualize is an object containing the following values:- height: Option list height value, default 270 (before v2.20.8 was 300)
- width: Option list width value, default 100%
- itemSize: The height of each line of Option, must be passed
Custom Trigger
If the default layout style of the selection box does not meet your needs, you can use
triggerRender
to customize the display of the selection boxThe parameters of triggerRender are as follows
The following is a more complex example: Reusing the drag-and-sort capability of TagInput and adding sorting to Select through triggerRender.
Custom Option Render
- Simple customization: Pass the label property of Option or children into ReactNode, you can control the rendering of the candidates, and the content will automatically bring styles such as padding, background color, etc.
- Complete customization: By passing in
renderOptionItem
, you can completely take over the rendering of the candidates in the list, and get the relevant state values from the callback input parameters. Achieve a higher degree of freedom of structural rendering
Notice:- The style passed in by props needs to be consumed on wrapper dom, otherwise it will not be able to be used normally in virtualization scenarios
- The styles of selected, focused, disabled, etc. state need to be added by yourself, and you can get the relative boolean value from props
onMouseEnter
、className
needs to be bound on the wrapper dom, otherwise the display will be problematic when the upper and lower keyboards are operated- If your custom item is Select.Option, you need to pass renderProps.onClick transparently to the onSelect prop of Option
API reference
Select Props
Properties | Instructions | Type | Default | version |
---|---|---|---|---|
allowCreate | Whether to allow the user to create new entries. Needs to be used with filter . When allowCreate is enabled, it will no longer respond to updates to children or optionList | boolean | false | |
arrowIcon | Customize the right drop-down arrow Icon, when the showClear switch is turned on and there is currently a selected value, hover will give priority to the clear icon | ReactNode | ||
autoAdjustOverflow | Whether the pop-up layer automatically adjusts the direction when it is obscured (only vertical direction is supported for the time being, and the inserted parent is body) | boolean | true | |
autoClearSearchValue | After selecting the option, whether to automatically clear the search keywords, it will take effect when mutilple and filter are both enabled | boolean | true | 2.3.0 |
autoFocus | Whether automatically focus when component mount | boolean | false | |
borderless | borderless mode >=2.33.0 | boolean | ||
className | The CSS class name of the wrapper element | string | ||
clearIcon | Can be used to customize the clear button, valid when showClear is true | ReactNode | 2.25.0 | |
clickToHide | When expanded, click on the selection box to automatically put away the drop-down list | boolean | false | |
defaultValue | Originally selected value when component mount | string|number|array | ||
defaultOpen | Whether show dropdown when component mounted | boolean | false | |
defaultActiveFirstOption | Whether to highlight the first option by default (press Enter to select directly) | boolean | true | |
disabled | Whether disabled component | boolean | false | |
dropdownClassName | ClassName of the pop-up layer | string | ||
dropdownMatchSelectWidth | Is the minimum width of the drop-down menu equal to Select | boolean | true | |
dropdownMargin | Popup layer calculates the size of the safe area when the current direction overflows, used in scenes covered by fixed elements, more detail refer to issue#549, same as Tooltip margin | object|number | 2.25.0 | |
dropdownStyle | The inline style of the pop-up layer | object | ||
emptyContent | Content displayed when there is no result. When set to null, the drop-down list will not be displayed | string | ReactNode | |
ellipsisTrigger | When maxTagCount exists and is multi-select, whether to perform adaptive processing on the overflow part of the tag(When the width is insufficient, the last tag content is truncated). After enabling this function, there will be a certain performance loss, and it is not recommended to use it in large form scenarios | boolean | false | 2.28.0 |
expandRestTagsOnClick | When maxTagCount exists and is multi-selected, select whether to expand redundant Tags when the panel is open | boolean | false | 2.28.0 |
filter | Whether searchable or not, the default is false. When true is passed, it means turn on search ability, default filtering policy is whether the label matches search inputWhen the input type is function, the function arguments are searchInput, option. It should return true when the option meets the filtering conditions, otherwise it returns false. | false | boolean|function | |
getPopupContainer | Specifies the parent DOM, and the popup layer will be rendered to the DOM, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position. | function(): HTMLElement | () => document.body | |
inputProps | When filter is true, the additional configuration parameters of the input, please refer to the Input component for specific configurable properties (note: please do not pass in value , ref , onChange , onFocus , otherwise it will override Select related callbacks and affect component behavior) | object | 2.2.0 | |
innerTopSlot | Render at the top of the pop-up layer, custom slot inside the optionList | ReactNode | ||
innerBottomSlot | Render at the bottom of the pop-up layer, custom slot inside the optionList | ReactNode | ||
insetLabel | Same to prefix , just an alias | ReactNode | ||
loading | Does the drop-down list show the loading animation | boolean | false | |
max | Maximum number of choices, effective only in multi-selection mode | number | ||
maxTagCount | In multi-selection mode, when the option is beyond maxTag Count, the subsequent option is rendered in the form of + N | number | ||
maxHeight | Maximum height of optionList in the pop-up layer | string | number | 270 | |
multiple | Whether allow multiple selection | boolean | false | |
outerBottomSlot | Rendered at the bottom of the popup layer, custom slot level with optionList | ReactNode | ||
outerTopSlot | Rendered at the top of the pop-up layer, custom slot level with optionList | ReactNode | ||
optionList | You can pass Option through this property, make sure that each element in the array has label , value properties | Array ([{value, label}]) | ||
placeholder | placeholder | ReactNode | ||
position | Pop-up layer position, refer to Popover·API reference·position | string | 'bottomLeft' | |
prefix | An input helper rendered before | ReactNode | ||
preventScroll | Indicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the user | boolean | ||
remote | Whether to turn on remote search, when remote is true, the input content will not be locally filtered and matched | boolean | false | |
renderCreateItem | When allowCreate is true, you can customize the rendering of the creation label | function(inputValue: string) | InputValue => 'Create' + InputValue | |
renderSelectedItem | Customize the rendering of selected tabs in the selection box | function(option) | ||
restTagsPopoverProps | The configuration properties of the Popover | PopoverProps | {} | 2.22.0 |
size | Size, optional value default / small / large | |||
searchPosition | When the filter is turned on, the search box is in the trigger by default. You can set it to 'dropdown' to put the search box at the top of the popup list. | string | 'trigger' | 2.61.0 |
showArrow | Whether to show arrow icon | boolean | true | |
showClear | Whether to show the clear button | boolean | false | |
showRestTagsPopover | When the number of tags exceeds maxTagCount and hover reaches +N, whether to display the remaining content through Popover | boolean | false | 2.22.0 |
spacing | Spacing between popup layer and trigger | number | 4 | |
stopPropagation | Whether to prevent click events on the popup layer from bubbling | boolean | true | |
style | Inline Style | object | ||
suffix | An input helper rendered after | ReactNode | ||
triggerRender | Custom DOM of trigger | function | ||
virtualize | List virtualization, used to optimize performance in the case of a large number of nodes, composed of height, width, and itemSize | object | ||
validateStatus | Verification result, optional warning , error , default (only affect the style background color) | string | 'default' | |
value | The currently selected value is passed as a controlled component, used in conjunction with onchange | string|number|array | ||
zIndex | Popup layer z-index | number | 1030 | |
onBlur | Callback when blur | function(event) | ||
onChange | Callback function when selected option | function (value) | ||
onChangeWithObject | Whether to use the other properties of the selected option as a callback. When set to true, the entry type of onchange changes from string to object: {value, label,...rest} | boolean | false | |
onClear | Callback when click clear icon | function | ||
onCreate | Allow Create is true and provides after the callback when creating the standby option | function | ||
onDeselect | Callback when selected cancel | function (value, option) | ||
onDropdownVisibleChange | A callback when the drop-down menu expands / collapsed | function(visible: boolean) | ||
onExceed | Callback invoked when the number of attempts to select exceeds the max limit, effective only at multi-selection | function | ||
onFocus | Callback when focus select | function(event) | ||
onSearch | The callback function when the content of the input box changes. The second parameter is available after v2.31 | function(sugInput: string, e: ReactEvent) | ||
onSelect | Callback when selected | function (value, option) |
Option Props
The label of different Option must be unique . Value allows repetition
Properties | Instructions | Type | Default |
---|---|---|---|
className | The CSS class name of the wrapper element | string | |
disabled | Disabled | boolean | false |
label | Text displayed. Prioritize the label when rendering, take the child, value if not, and downgrade in turn | string|ReactNode | |
showTick | Whether to show the Icon of tick when option selected | boolean | true |
style | Inline Style | object | |
value | Property value | string|number |
OptGroup Props
Properties | Instructions | Type |
---|---|---|
className | The CSS class name | string |
label | Text displayed. | ReactNode |
style | Inline Style | object |
Methods
Some internal methods provided by Select can be accessed through ref:
Method | Instructions | Version |
---|---|---|
close | Manually close dropdown list | |
clearInput | Manually clear value of input | |
deselectAll | Manually clear selected options | |
focus | Manually focus select | |
open | Manually open dropdown list | |
selectAll | Manually select all options | |
search(value: string, event: event) | You can call this method through ref to search, and the search value will be set to Input | v2.35.0 |
Accessibility
ARIA
- The role of the Select trigger is combobox, the role of the popup layer is listbox, and the role of the option is option
- Select trigger has aria-haspopup, aria-expanded, and aria-controls properties, indicating the relationship between trigger and popup layer
- When multiple selections are made, listbox aria-multiselectable is true, indicating that multiple selections are currently available
- aria-selected is true when Option is selected; aria-disabled is true when Option is disabled
- The attribute aria-activedescendant ensures that the currently selected option is recognized when the narration is spoken(for more information, please refer to Managing Focus in Composites Using aria-activedescendant)
Keyboard and Focus
Select without Filter:
- After Select is focused, keyboard users can open the dropdown menu with the
Up Arrow
orDown Arrow
orEnter
keys and automatically focus on the first option in the dropdown menu (defaultActiveFirstOption
defaults to true) - When the dropdown menu is open:
- Use
Esc
key orTab
key to close the menu - Use
Up Arrow
orDown Arrow
to toggle options - The focused option can be selected with the Enter key and the panel is collapsed
- Use
- When the focus is on the dropdown menu and the user uses an
innerBottomSlot
orouterBottomSlot
attribute with a custom slot with an interactive element:- You can use the
Tab
key to switch to these interactive elements - When the focus is on the first interactive element of the custom slot, use
Shift
+Tab
to return the focus to the Select box
- You can use the
Select with Filter function:
- When Select is focused, keyboard users can open dropdown menus with
Up Arrow
orDown Arrow
orEnter
keys. At this point, the focus is still on the Select box, the user can enter content, and can also use theup arrow
ordown arrow
to switch options - When the dropdown menu is open: the keyboard interaction is the same as Select without the Filter function
- When the focus is on the Select box, and the user uses an
innerBottomSlot
orouterBottomSlot
property with a custom slot with an interactive element:- You can use the
Tab
key to switch to these interactive elements - When the focus is on the first interactive element of the custom slot, use
Shift
+Tab
to return the focus to the Select box
- You can use the
Content Guidelines
- Selector trigger
- Describe in 1-3 words the input that the user needs to make
- Use statement writing conventions (first letter uppercase, rest lowercase)
- Avoid punctuation and prepositions ("the", "an", "a")
- Labels need to be independent statements. Don't let the label be the first half of the statement and the option the second half of the statement.
- Use descriptive sentences, not indicative ones. Help text is available under the select box if the option needs more explanation.
- Selector options
- If there is no default option, use "Select" as placeholder copy
- Options should be in alphabetical order or other logical order to make it easier for users to find options
- Use statement writing conventions (first letter uppercase, rest lowercase), avoid commas and semicolons at the end of sentences
- Clearly articulate the purpose of the choice indicated by the option
Design Tokens
FAQ
- Searchable Select, using remote data to dynamically update the
optionList
, why sometimes there is no data before the asynchronous request is completed??
Please check whetherremote={true}
is set. If remote is not set, the input value of the input box will be compared with the current optionList by default. If there is no match, no data will be displayed.
You can turn off matching filtering on the current local data by setting remote to true. - Use jsx to declare Option, label is the content after i18n, fail to re-render after switching locale When the children jsx method declares Options, because it is ReactNode, it is impossible to use deepEqual to compare whether the content is updated (excessive performance consumption), so the key of children ReactNode will be collected. When the key is unchanged, it is considered that Options have not occurred. Changes will not go through the process of re-collecting data. You can also use locale as part of the Option key.
The problem can also be solved by usingoptionList
to pass in. Because the key is relatively limited for the object form, isEqual is used inside Select to determine whether there is a change - Use jsx to declare Option, and fail to re-render after dynamically switching the disabled attribute
The reason is the same as above, you can set a different key value for Option again, or use optionList to declare candidate options - Will Select automatically limit the width of the drop-down menu?
MinWidth will be given, but width will not be written dead. If necessary, you can add it yourself through dropdownStyle. - After setting allowCreate, dynamically updating optionList or children does not take effectallowCreate is mainly used for locally created scenarios. When this item is turned on, it is equivalent to forcibly taking over optionList/children, and will no longer respond to external updates to these two types of values. Otherwise, how the currently created options are combined with the latest props.optionList, and whether the strategy is overwritten or merged depends largely on the business scenario logic, and it is inappropriate to force presets by the component layer.
- Why Semi's Select requires that the label must be unique, but not the value?Unique label and repeated value are more common in daily use. For example, a selector that selects the company id based on the app name, value is the company id corresponding to the app, and label is the name of the app. We don't recommend showing the user a duplicate label option, but if you're sure you need to, you can bypass this restriction when you pass a ReactNode type to the label.
- Why is the blur event not fired after a radio selection option?Before V2.17.0, after Select radio is selected, the blur event of Select will be triggered. After V2.17.0, Select has added A11y support, which will not trigger Select's blur event. In single-selection selection, the Select floating layer is closed, and the focus is still on the trigger (at this time, the Select floating layer can be opened again by pressing the Enter key) No matter single selection or multiple selection, press Esc, only the Select floating layer is closed, and the trigger keeps the focus (the Select floating layer can be opened again by pressing the Enter key at this time)