Demos

How to import

import { Select } from '@douyinfe/semi-ui';
const Option = Select.Option;

Basic Usage

Pass Option as an array

Multi-choice

With Group

Different sizes

Different validate status

Configure Prefix, Suffix, Clear Button

• You can pass the selection box prefix through prefix, the selection box suffix through suffix, 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

Additional items

• innerTopSlot and innerBottomSlot will be rendered inside the Option List
• outerTopSlot and outerBottomSlot will be rendered to level with the option List

Controlled component

Linkage Select

Search

Search position

Remote search

• Use filter turn on the search capability.
• Use remote to disabled local filter
• Dynamic Update optionList after onSearch callback
• Update loading when fetching data / finish
• Use controlled value attribute

Custom search strategy

Custom selection rendering

• 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 in Tag rendering (with background color and close button)
  • When isRenderInTag is false, it renders the returned content directly

Custom pop-up layer style

Dynamic Modification Options

Get all attribute of selected option

Create entries

Virtualize

• 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

interface TriggerRenderProps {
  value: array<object> // All currently selected options
  inputValue: string; // The input value of the current input box
  onSearch: (inputValue: string) => void; // The function used to update the value of the input box. You should call this function when the value of the Input component you customize in triggerRender is updated to synchronize the state to the Select internal. props.filter needs to be true, support after v2.32
  onClear: () => void; // Function to clear the value
  onRemove: (option: object) => void; // support after v2.32
  disabled: boolean; // Whether to disable Select
  placeholder: string; // Select placeholder
  componentProps: //All props passed to Select by users
}

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:
  1. 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
  2. The styles of selected, focused, disabled, etc. state need to be added by yourself, and you can get the relative boolean value from props
  3. onMouseEnter、className needs to be bound on the wrapper dom, otherwise the display will be problematic when the upper and lower keyboards are operated
  4. If your custom item is Select.Option, you need to pass renderProps.onClick transparently to the onSelect prop of Option

.components-select-demo-renderOptionItem {
    .custom-option-render {
        display: flex;
        font-size: 14px;
        line-height: 20px;
        word-break: break-all;
        padding-left: 12px;
        padding-right: 12px;
        padding-top: 8px;
        padding-bottom: 8px;
        color: var(--semi-color-text-0);
        position: relative;
        display: flex;
        align-items: center;
        cursor: pointer;
        box-sizing: border-box;
        .option-right {
            margin-left: 8px;
            display: inline-flex;
            align-items: center;
        }
        &:active {
            background-color: var(--semi-color-fill-1);
        }
        &-focused {
            background-color: var(--semi-color-fill-0);
        }
        &-selected {
            //font-weight: 700;
        }
        &-disabled {
            color: var(--semi-color-disabled-text);
            cursor: not-allowed;
        }
        &:first-of-type {
            margin-top: 4px;
        }
        &:last-of-type {
            margin-bottom: 4px;
        }
    }
}

API reference

Select Props

Option Props

The label of different Option must be unique . Value allows repetition

OptGroup Props

Methods

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

• After Select is focused, keyboard users can open the dropdown menu with the Up Arrow or Down Arrow or Enter 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 or Tab key to close the menu
  • Use Up Arrow or Down Arrow to toggle options
  • The focused option can be selected with the Enter key and the panel is collapsed
• When the focus is on the dropdown menu and the user uses an innerBottomSlot or outerBottomSlot 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

• When Select is focused, keyboard users can open dropdown menus with Up Arrow or Down Arrow or Enter keys. At this point, the focus is still on the Select box, the user can enter content, and can also use the up arrow or down 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 or outerBottomSlot 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

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 whether remote={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 using optionList 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 effect
  allowCreate 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?

  First of all, we must need a unique identifier to make a selection judgment. For almost all UI libraries, when using Select.Option, the minimum requirements will only require the two values of label and value to be passed in, instead of requiring a separate key (too cumbersome). Semi continues this setting.
  So why is label instead of value in semi's select?
  The label of the option is what the user perceives. From an interactive point of view, if there are two options that are exactly the same on the display, to the user’s perception, they look the same and cannot be distinguished, but the selected effects are different (for example, one value is 0, the other As 1), it is unreasonable. (Users' first reaction is often repeated, and there may be a bug)
  

  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)