# Select

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

A dropdown menu for displaying choices.


## When To Use

- A dropdown menu for displaying choices - an elegant alternative to the native `<select>` element.
- Utilizing [Radio](/components/radio/) is recommended when there are fewer total options (less than 5).
- You probably need [AutoComplete](/components/auto-complete/) if you're looking for an input box that can be typed or selected.

## Examples


- Basic Usage · `basic`
- Select with search field · `search`
- Custom Search · `search-filter-option`
- Multi field search · `search-multi-field`
- multiple selection · `multiple`
- Sizes · `size`
- Custom dropdown options · `option-render`
- Search with sort · `search-sort`
- Tags · `tags`
- Option Group · `optgroup`
- coordinate · `coordinate`
- Get value of selected item · `label-in-value`
- Automatic tokenization · `automatic-tokenization`
- Custom tokenization · `custom-tokenization`
- Search and Select Users · `select-users`
- Prefix and Suffix · `suffix`
- Custom dropdown · `custom-dropdown-menu`
- Hide Already Selected · `hide-selected`
- Variants · `variant`


- Custom Tag Render · `custom-tag-render`
- Custom Selected Label Render · `custom-label-render`
- Responsive maxTagCount · `responsive`
- Big Data · `big-data`
- Status · `status`
- Placement · `placement`






- Max Count · `maxCount`
- Custom semantic dom styling · `style-class`

## API

Common props ref：[Common props](#jguang-common-props)

### Select props

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| allowClear | Customize clear icon | boolean \| { clearIcon?: ReactNode } | false | 5.8.0: Support object type | 6.4.0 |
| ~~autoClearSearchValue~~ | Whether the current search will be cleared on selecting an item. Only applies when `mode` is set to `multiple` or `tags` | boolean | true |  | × |
| ~~bordered~~ | 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](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), 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\[] \| <br />number \| number\[] \| <br />LabeledValue \| LabeledValue\[] | - |  | × |
| disabled | Whether disabled select | boolean | false |  | × |
| ~~dropdownClassName~~ | The className of dropdown menu, please use `classNames.popup.root` instead | string | - | - | × |
| ~~dropdownMatchSelectWidth~~ | Determine whether the popup menu and the select input are the same width, please use `popupMatchSelectWidth` instead | boolean \| number | true | - | × |
| ~~popupClassName~~ | 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 | × |
| ~~dropdownRender~~ | Customize dropdown content, use `popupRender` instead | (originNode: ReactElement) => ReactNode | - |  | × |
| popupRender | Customize dropdown content | (originNode: ReactElement) => ReactNode | - | 5.25.0 | × |
| ~~dropdownStyle~~ | 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) | × |
| ~~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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://codesandbox.io/s/4j168r7jw0) | 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 | `No data` |  | × |
| open | Controlled open state of dropdown | boolean | - |  | × |
| ~~optionFilterProp~~ | Deprecated, see `showSearch.optionFilterProp` |  |  |  | × |
| optionLabelProp | Which prop value of option will render as content of select. [Example](https://codesandbox.io/s/antd-reproduction-template-tk678) | 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 |
| ~~searchValue~~ | The current input "search" text | string | - |  | × |
| ~~showArrow~~ | Whether to show the arrow icon, please use `suffixIcon={null}` instead | boolean | true | - | × |
| showSearch | Whether select is searchable | boolean \| [Object](#showsearch) | 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](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), 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](https://github.com/react-component/select/blob/b39c28aa2a94e7754ebc570f200ab5fd33bd31e7/src/Select.tsx#L70)) | (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\[] \| <br />number \| number\[] \| <br />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&lt;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) | - |  | × |
| ~~onDropdownVisibleChange~~ | 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 | - |  | × |
| ~~onSearch~~ | 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 .

### showSearch

| 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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. <br/> If `options` is set, it should be set to `label`. <br/> 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 |

### Select Methods

| Name    | Description  | Version |
| ------- | ------------ | ------- |
| blur()  | Remove focus |         |
| focus() | Get focus    |         |

### Option props

| 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 | -       |         |

### OptGroup props

| 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          | -       |         |

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root element with relative positioning, inline-flex layout, cursor styles, transitions, border and other basic selector container styles | — |
| `prefix` | Prefix element with layout and styling for prefix content | — |
| `content` | Multiple selection container with layout, spacing, and wrapping styles for selected items | — |
| `placeholder` | Placeholder element with font styles and colors for placeholder text | — |
| `clear` | Clear button element with layout, styling and interactive effects for clear button | — |
| `input` | Input element with search input styling, cursor control, font inheritance and other search-related styles. Remove border styles | — |
| `suffix` | Suffix element with layout and styling for suffix content like clear button, arrow icon, etc. | — |
| `popup.root` | Popup element with popup layer positioning, z-index, background, border, box-shadow and other popup container styles | — |
| `popup.list` | Popup list element with option list layout, scrolling, max-height and other list container styles | — |
| `popup.listItem` | Popup item element with option item padding, hover effects, selected states, disabled states and other option interactive styles | — |
| `item` | Multiple selection item element with border, background, padding, and margin styles (multiple) | — |
| `itemContent` | Multiple selection item content area with text ellipsis styles (multiple) | — |
| `itemRemove` | Multiple selection item remove button with font-related styles (multiple) | — |

Semantic description source: `vendor/.dumi/theme/common/SelectSemanticTemplate.tsx`

## Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

| Token | Type | Native description |
| --- | --- | --- |
| `zIndexPopup` | `number` | z-index of dropdown |
| `optionSelectedColor` | `string` | Text color when option is selected |
| `optionSelectedFontWeight` | `CSSProperties['fontWeight']` | Font weight when option is selected |
| `optionSelectedBg` | `string` | Background color when option is selected |
| `optionActiveBg` | `string` | Background color when option is active |
| `optionPadding` | `CSSProperties['padding']` | Padding of option |
| `optionFontSize` | `number` | Font size of option |
| `optionLineHeight` | `CSSProperties['lineHeight']` | Line height of option |
| `optionHeight` | `number` | Height of option |
| `selectorBg` | `string` | Background color of selector |
| `clearBg` | `string` | Background color of clear button |
| `singleItemHeightLG` | `number` | Height of single selected item with large size |
| `showArrowPaddingInlineEnd` | `number` | Inline end padding of arrow |
| `hoverBorderColor` | `string` | Hover border color |
| `activeBorderColor` | `string` | Active border color |
| `activeOutlineColor` | `string` | Active outline color |

Declaration source: `vendor/components/select/style/token.ts`

```ts
import type { CSSProperties } from 'react';

import type { FullToken, GetDefaultToken } from '../../theme/internal';

export interface MultipleSelectorToken {
  /**
   * @desc 多选标签背景色
   * @descEN Background color of multiple tag
   */
  multipleItemBg: string;
  /**
   * @desc 多选标签边框色
   * @descEN Border color of multiple tag
   */
  multipleItemBorderColor: string;
  /**
   * @desc 多选标签高度
   * @descEN Height of multiple tag
   */
  multipleItemHeight: number;
  /**
   * @desc 小号多选标签高度
   * @descEN Height of multiple tag with small size
   */
  multipleItemHeightSM: number;
  /**
   * @desc 大号多选标签高度
   * @descEN Height of multiple tag with large size
   */
  multipleItemHeightLG: number;
  /**
   * @desc 多选框禁用背景
   * @descEN Background color of multiple selector when disabled
   */
  multipleSelectorBgDisabled: string;
  /**
   * @desc 多选标签禁用文本颜色
   * @descEN Text color of multiple tag when disabled
   */
  multipleItemColorDisabled: string;
  /**
   * @desc 多选标签禁用边框色
   * @descEN Border color of multiple tag when disabled
   */
  multipleItemBorderColorDisabled: string;
  /**
   * @internal
   */
}

export interface ComponentToken extends MultipleSelectorToken {
  /**
   * @desc 下拉菜单 z-index
   * @descEN z-index of dropdown
   */
  zIndexPopup: number;
  /**
   * @desc 选项选中时文本颜色
   * @descEN Text color when option is selected
   */
  optionSelectedColor: string;
  /**
   * @desc 选项选中时文本字重
   * @descEN Font weight when option is selected
   */
  optionSelectedFontWeight: CSSProperties['fontWeight'];
  /**
   * @desc 选项选中时背景色
   * @descEN Background color when option is selected
   */
  optionSelectedBg: string;
  /**
   * @desc 选项激活态时背景色
   * @descEN Background color when option is active
   */
  optionActiveBg: string;
  /**
   * @desc 选项内间距
   * @descEN Padding of option
   */
  optionPadding: CSSProperties['padding'];
  /**
   * @desc 选项字体大小
   * @descEN Font size of option
   */
  optionFontSize: number;
  /**
   * @desc 选项行高
   * @descEN Line height of option
   */
  optionLineHeight: CSSProperties['lineHeight'];
  /**
   * @desc 选项高度
   * @descEN Height of option
   */
  optionHeight: number;
  /**
   * @desc 选框背景色
   * @descEN Background color of selector
   */
  selectorBg: string;
  /**
   * @desc 清空按钮背景色
   * @descEN Background color of clear button
   */
  clearBg: string;
  /**
   * @desc 单选大号回填项高度
   * @descEN Height of single selected item with large size
   */
  singleItemHeightLG: number;
  /**
   * @desc 箭头的行末内边距
   * @descEN Inline end padding of arrow
   */
  showArrowPaddingInlineEnd: number;
  /**
   * @desc 悬浮态边框色
   * @descEN Hover border color
   */
  hoverBorderColor: string;
  /**
   * @desc 激活态边框色
   * @descEN Active border color
   */
  activeBorderColor: string;
  /**
   * @desc 激活态 outline 颜色
   * @descEN Active outline color
   */
  activeOutlineColor: string;
}

export interface SelectorToken {
  selectAffixPadding: number | string;
  inputPaddingHorizontalBase: number | string;
  multipleSelectItemHeight: number;
  selectHeight: number;
}

export interface SelectToken extends FullToken<'Select'>, SelectorToken {
  rootPrefixCls: string;

  /** @private Used for internal calculation */
  INTERNAL_FIXED_ITEM_MARGIN: number;
}
```

## FAQ

### Why sometimes search will show 2 same option when in `tags` mode? {#faq-tags-mode-duplicate}

It's caused by option with different `label` and `value`. You can use `optionFilterProp="label"` to change filter logic instead.

### When I click elements in popupRender, the select dropdown will not be closed? {#faq-popup-not-close}

You can control it by `open` prop: [codesandbox](https://codesandbox.io/s/ji-ben-shi-yong-antd-4-21-7-forked-gnp4cy?file=/demo.js).

### I don't want dropdown close when click inside `popupRender`? {#faq-popup-keep-open}

Select will close when it lose focus. You can prevent event to handle this:

```tsx
<Select
  popupRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>
```

### Why sometimes customize Option cause scroll break? {#faq-custom-option-scroll}

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:

```tsx
<Select listItemHeight={10} listHeight={250} />
```

Note: `listItemHeight` and `listHeight` are internal props. Please only modify when necessary.

### Why a11y test report missing `aria-` props? {#faq-aria-attribute}

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.

### Why does clicking close on a custom `tagRender` tag open the dropdown? {#faq-tagrender-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.

```tsx
<Select
  tagRender={(props) => {
    const { closable, label, onClose } = props;
    return (
      <span className="border">
        {label}
        {closable ? (
          <span
            onMouseDown={(e) => e.stopPropagation()}
            onClick={onClose}
            className="cursor-pointer"
          >
            ❎
          </span>
        ) : null}
      </span>
    );
  }}
/>
```


## Shared native props {#jguang-common-props}


> Tips: The following generic properties apply to most antd components; those not supported are described separately.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

## Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

- `vendor/components/select/index.tsx`
- `vendor/components/select/style/select-input.ts`
- `vendor/components/select/style/token.ts`
- `vendor/components/select/useIcons.tsx`
- `vendor/components/select/usePopupRender.tsx`

## Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

---

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