Select

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 is recommended when there are fewer total options (less than 5).
• You probably need AutoComplete 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

Select props

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

Select Methods

Option props

OptGroup props

Semantic DOM

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.

Declaration source: vendor/components/select/style/token.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?

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?

You can control it by open prop: codesandbox.

I don't want dropdown close when click inside popupRender?

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

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

Why sometimes customize Option cause scroll break?

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:

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

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

Why a11y test report missing aria- props?

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?

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.

<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

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

Install and reproduce an example

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.