# Select

- Page: https://jiguang132.com/resources/arco-design/docs/select
- Resource: Arco Design (https://jiguang132.com/resources/arco-design.md)
- All guides: https://jiguang132.com/resources/arco-design/docs.md

When users need to select one or more from a group of similar data, they can use Select to click and select the corresponding item.

## Install

```bash
npm install @arco-design/web-react@2.66.18
```

Import `@arco-design/web-react/dist/css/arco.css` at the entry and set the locale with `ConfigProvider`. React 19 projects must also import `@arco-design/web-react/es/_util/react-19-adapter` first, or imperative APIs such as Message and Modal cannot render.

## Examples

- **Basic**: Basic usage of Select.
- **Allow Clear**: With built-in clear button.
- **Multiple Mode**: Specify `mode=multiple` to use multiple selection. Set the maximum number of tags displayed through `maxTagCount`, and customize the rendering method of tags through the `renderTag` property to achieve more complex customization.
- **Front Label**: Specify `addBefore` to add elements before the select box. (`2.41.0`)
- **Allow-Create**: Specify `allowCreate` as `true` to create entries that do not exist in the options. Format user creations via `allowCreate.formatter`.
- **Search**: Specify `showSearch=true` to search for the expanded options, and cooperate with `filterOption` to customize the search. When the search box is focused, the entered content will be cleared by default, however the content can be retained by specifying `showSearch={ retainInputValue: true }`.
- **Search Users**: Through the combination of `showSearch`, `filterOption` and `onSearch`, you can search user from origin and select them.
- **Custom Popup Width**: This example shows that the pop-up box can automatically adjust the width according to the content, and the minimum width is the width of the input box. The `triggerProps.autoAlignPopupWidth` property is to keep the width of popup box consistent with the input box. The `triggerProps.autoAlignPopupMinWidth` property is to keep the minimum width of the popup box consistent with the input box. They can be freely combined.
- **Size**: Use `size` to select the size of Select (`mini`, `small`, `default`, `large`), the height corresponds to `24px`, `28px`, `32px`, `36px`.
- **Custom Selection Render**: Use `renderFormat` to customize the content what will be rendered in select box. **Note: In scenarios such as remote loading of option data, the corresponding option in value may not exist at some point. It is necessary to determine if the option does not exist, return the value as the displayed content.**
- **With Group**: Use `Select.Group` to group the drop-down menu options.
- **Specify Options**: Specify optional options by passing in `options`.
- **Load Data While Scrolling**: When loading dynamically, you can monitor scroll events through `onPopupScroll`.
- **Automatic Tokenization**: Set `tokenSeparators` to use automatic word segmentation. Try copying `Beijing,Shanghai,Shenzhen|Nanjing/Xi'an|Hangzhou` into the input box. Only available in `multiple` mode.
- **Custom Trigger**: Set `triggerElement` to customize the node that triggers the drop-down box. When the trigger element is customized, the shortcut key operation will not be available due to the invalidation of the internally bound keyboard processing functions, and additional processing needs to be performed through the `hotkeyHandler`.
- **Customize Dropdown**: Use `dropdownRender` to freely customize the drop-down menu.
- **Borderless**: Use `bordered = false` to use Select without borders.
- **Custom Tag Render**: Use `renderTag` to customize Tags will be rendered in select box.
- **Coordinate**: Coordinating the selection of provinces and cities is a common use case.
- **Hide Selected Items**: Hide selected items in the drop-down menu.
- **Big Data**: `Select` uses virtual-scrolling to ensure performance even in large amounts of data. **When `triggerProps.autoAlignPopupWidth = false` and `Option.label` is a non-text type, virtual scrolling will be automatically closed because the maximum width of the option cannot be obtained when the option list is first rendered.**
- **Draggable**: In multiple mode, specify the `dragToSort` property to allow sort the entered values by dragging.
- **Auto Width**: The width adaptation of `Select` can be set through the `autoWidth` property
- **Max tag count**: The maximum number of tags for `Select` can be set through the `maxTagCount` property. When `maxTagCount=responsive` is used, the number of tags will be dynamically displayed based on the container size. Because it will monitor the size changes of all tags and containers, it is not recommended to use it when there are many options, as there may be performance issues.

Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.

## API

### Select

|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|allowClear|Whether allow to clear selected options|boolean |`-`|-|
|animation|Whether to add animation for internal label changes|boolean |`true`|2.15.0|
|bordered|Whether to render border|boolean |`true`|-|
|defaultActiveFirstOption|Whether to highlight the first option by default|boolean |`true`|-|
|defaultPopupVisible|Whether to show dropdown by default.|boolean |`-`|2.14.0|
|disabled|Whether is disabled|boolean |`-`|-|
|dragToSort|Weather it is possible to sort tags by drag|boolean |`-`|2.27.0|
|error|Whether the textarea is error.(Deprecated, removed in the next major version, use status='error' instead)|boolean |`-`|-|
|labelInValue|Whether to embed label in value, turn the format of value from string to `{ value: string, label: ReactNode }`|boolean |`-`|-|
|loading|Whether is in loading|boolean |`-`|-|
|popupVisible|Whether to show dropdown.|boolean |`-`|2.6.0|
|unmountOnExit|Whether to destroy the DOM when hiding|boolean |`true`|-|
|inputValue|To set input value|string |`-`|-|
|placeholder|Placeholder of element|string |`-`|-|
|allowCreate|Whether to allow new options to be created by input.|\| boolean\| {formatter: (inputValue: string, creating: boolean) => [SelectProps](select#select)['options'][number];} |`-`|2.13.0, `{ formatter }` in 2.54.0|
|autoWidth|auto width. minWidth defaults to 0, maxWidth defaults to 100%|\| boolean\| { minWidth?: CSSProperties['minWidth']; maxWidth?: CSSProperties['maxWidth'] } |`-`|2.54.0|
|maxTagCount|The maximum number of `tags` is displayed, only valid in `multiple` and `label` mode. Setting the number of `responsive` responsive display tags is not recommended when there are many options, as there may be performance issues.|\| number\| 'responsive'\| {count: number \| 'responsive';render?: (invisibleTagCount: number) => ReactNode;} |`-`|Object type in 2.37.0. `responsive ` in `2.62.0`|
|mode|Set mode of Select(**`tags` recommends using `mode: multiple; allowCreate: true` instead, this mode will be removed in the next major version**)|'multiple' \| 'tags' |`-`|-|
|size|Height of element, `24px` `28px` `32px` `36px`|'mini' \| 'small' \| 'default' \| 'large' |`-`|-|
|status|Status|'error' \| 'warning' |`-`|2.45.0|
|trigger|The trigger mode which executes the dropdown action.|[TriggerProps](trigger#trigger)['trigger'] |`click`|-|
|addBefore|The label text displayed before (on the left side of) the select field|ReactNode |`-`|2.41.0|
|clearIcon|Configure the icon of the clear button when `allowClear`.|ReactNode |`-`|2.26.0|
|notFoundContent|Specify content to show when no result matches.|ReactNode |`-`|-|
|prefix|Customize select suffix|ReactNode |`-`|2.11.0|
|suffixIcon|Customize select suffix icon|ReactNode |`-`|-|
|arrowIcon|Customize select arrow icon.|ReactNode \| null |`-`|-|
|className|Additional css class|string \| string[] |`-`|-|
|defaultValue|To set default value|string \| string[] \| number \| number[] \| [LabeledValue](#labeledvalue) \| [LabeledValue](#labeledvalue)[] |`-`|-|
|dropdownMenuClassName|The className of dropdown menu.|string \| string[] |`-`|-|
|dropdownMenuStyle|The style of dropdown menu.|CSSProperties |`-`|-|
|options|Select options|(\| string\| number\| { label: ReactNode \| string; value: string \| number; disabled?: boolean; extra?: any })[] |`-`|`extra` in 2.2.0|
|removeIcon|Customize the delete icon of tags selected in `multiple` and `label` mode.|ReactNode \| null |`-`|-|
|showSearch|Whether single mode Select is searchable. `{ retainInputValue: true }` to retain the existing content when the search box is focused,`{ retainInputValueWhileSelect: true }` to retain the existing content when multiple selection is selected.|boolean \| { retainInputValue?: boolean; retainInputValueWhileSelect?: boolean } |`-`|-|
|style|Additional style|CSSProperties |`-`|-|
|tokenSeparators|Separator used to tokenize on `multiple` mode.|string[] |`-`|-|
|triggerProps|Pass all `Trigger` component properties|Partial<[TriggerProps](trigger#trigger)> |`-`|-|
|value|To set value|string \| string[] \| number \| number[] \| [LabeledValue](#labeledvalue) \| [LabeledValue](#labeledvalue)[] |`-`|-|
|virtualListProps|Pass properties used by VirtualList.|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.1.0|
|dropdownRender|Customize dropdown content|(menu: ReactNode) => ReactNode |`-`|-|
|filterOption|If it's true, filter options by input value. If it's a function, filter options base on the function.|boolean \| ((inputValue: string, option: ReactElement) => boolean) |`true`|-|
|getPopupContainer|To set the container of the dropdown.|(node: HTMLElement) => Element |`-`|-|
|onBlur|Callback when lose focus|(e) => void |`-`|-|
|onChange|Callback when select an option or input value change.|(value, option: [OptionInfo](#optioninfo) \| [OptionInfo](#optioninfo)[]) => void |`-`|-|
|onClear|Called when clear|(visible: boolean) => void |`-`|-|
|onClick|Callback when the mouse clicks on the drop-down box|(e) => void |`-`|-|
|onDeselect|Called when an option is deselected. Only called for `multiple` mode.|(value: string \| number \| [LabeledValue](#labeledvalue), option: [OptionInfo](#optioninfo)) => void |`-`|-|
|onFocus|Callback when get focus|(e) => void |`-`|-|
|onInputValueChange|Callback when the value of input is changed.|(value: string, reason: [InputValueChangeReason](#inputvaluechangereason)) => void |`-`|2.3.0|
|onKeyDown|Callback when keyboard pressed|(e) => void |`-`|2.40.0|
|onPaste|Callback when the you paste text in input box.|(e) => void |`-`|2.9.0|
|onPopupScroll|Callback when dropdown scrolls.|(elem) => void |`-`|-|
|onSearch|Callback when input changed|(value: string, reason: [InputValueChangeReason](#inputvaluechangereason)) => void |`-`|-|
|onSelect|Called when an option is selected. Only called for `multiple` mode.|(value: string \| number \| [LabeledValue](#labeledvalue), option: [OptionInfo](#optioninfo)) => void |`-`|2.52.0|
|onVisibleChange|Callback when visibility of dropdown is changed.|(visible: boolean) => void |`-`|-|
|renderFormat|Customize the content that will be displayed in the Select.If the `Option` corresponding to `value` does not exist, the first parameter will be `null`|(option: [OptionInfo](#optioninfo) \| null, value: string \| number \| [LabeledValue](#labeledvalue)) => ReactNode |`-`|-|
|renderTag|Custom tag rendering, `props` is the current tag attribute, `index` is the order of the current tag, `values` is the value of all tags|(props: {value: any;label: ReactNode;closable: boolean;onClose: (event) => void;},index: number,values: [ObjectValueType](#objectvaluetype)[]) => ReactNode |`-`|index、values added in 2.15.0|
|triggerElement|The trigger element which executes the dropdown action.|\| ReactNode\| ((params: { value: any; option: [OptionInfo](#optioninfo) \| [OptionInfo](#optioninfo)[] }) => ReactNode) |`-`|`() => ReactNode` in 2.31.0|

### Select.Option

|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|disabled|Whether the option is disabled|boolean |`-`|-|
|className|Additional css class|string \| string[] |`-`|-|
|extra|Any data you want to pass to Option.|any |`-`|2.2.0|
|style|Additional style|CSSProperties |`-`|-|
|value|Value of this Option|string \| number  **(Required)**|`-`|-|

### Select.OptGroup

|Property|Description|Type|DefaultValue|
|---|---|---|---|
|label|Name of Group|ReactNode |`-`|
|className|Additional css class|string \| string[] |`-`|
|style|Additional style|CSSProperties |`-`|

### Select Reference Type

|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|activeOptionValue|The value of active option|[OptionProps](select#selectoption)['value']  **(Required)**|`-`|-|
|getOptionInfoByValue|Get the option info by its value|(value: [OptionProps](select#selectoption)['value']) => [OptionInfo](#optioninfo)  **(Required)**|`-`|-|
|scrollIntoView|Scroll the drop-down list to the specified option|(value: [OptionProps](select#selectoption)['value'], options?: ScrollIntoViewOptions) => void  **(Required)**|`-`|2.46.0|
|dom|DOM|HTMLDivElement  **(Required)**|`-`|-|
|blur|Blur Select|() => void  **(Required)**|`-`|-|
|focus|Focus Select|() => void  **(Required)**|`-`|-|
|getOptionInfoList|Get the list of option info|() => [OptionInfo](#optioninfo)[]  **(Required)**|`-`|-|
|hotkeyHandler|Processor of mouse shortcut operation|(event: KeyboardEvent) => void  **(Required)**|`-`|-|

### LabeledValue

```js
export type LabeledValue = {
  value: string | number;
  label: ReactNode;
};
```

### OptionInfo

```js
export interface OptionInfo extends PropsWithChildren<OptionProps> {
  child?: ReactElement;
  _valid: boolean;
  _index: number;
  _origin: "children" | "options" | "userCreatedOptions" | "userCreatingOption";
}
```

### AvailableVirtualListProps

```js
export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;
```

### InputValueChangeReason

```js
// 造成输入框值改变的原因：用户输入、选中选项、选项下拉框收起、触发自动分词
export type InputValueChangeReason =
  | "manual"
  | "optionChecked"
  | "optionListHide"
  | "tokenSeparator";
```

### ObjectValueType

```js
export type ObjectValueType = {
  value?: any;
  label?: ReactNode;
  closable?: boolean;
};
```

### VirtualListProps

|Property|Description|Type|Default|
|---|:---:|:---:|---:|
|height|Viewable area height (`2.11.0` starts to support `string` type such as `80%`)|`number`| 200 |
|threshold|The threshold of the number of elements that automatically enable virtual scrolling, pass in `null` to disable virtual scrolling.|`number` \| `null`| 100 |
|isStaticItemHeight|Whether it is a static element of the same height|`boolean`|true|

---

Index of all JGuang resources: https://jiguang132.com/llms.txt