Select

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

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

Select.Option

Select.OptGroup

Select Reference Type

LabeledValue

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

OptionInfo

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

AvailableVirtualListProps

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

InputValueChangeReason

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

ObjectValueType

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

VirtualListProps