Select Fields

Select field components provide dropdown selection with support for single, multiple, and hierarchical data.

ProFormSelect

Dropdown select component with support for remote data loading.

Import

import { ProFormSelect } from '@ant-design/pro-components';

Usage

Basic
Multiple
Remote Data
With Search

<ProFormSelect
  name="status"
  label="Status"
  options={[
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
    { label: 'Pending', value: 'pending' }
  ]}
  placeholder="Please select status"
/>

<ProFormSelect
  name="tags"
  label="Tags"
  mode="multiple"
  options={[
    { label: 'Frontend', value: 'frontend' },
    { label: 'Backend', value: 'backend' },
    { label: 'DevOps', value: 'devops' }
  ]}
  placeholder="Select tags"
/>

<ProFormSelect
  name="userId"
  label="User"
  request={async () => {
    const response = await fetch('/api/users');
    const data = await response.json();
    return data.map(user => ({
      label: user.name,
      value: user.id
    }));
  }}
  placeholder="Select user"
/>

<ProFormSelect
  name="country"
  label="Country"
  showSearch
  options={countries}
  fieldProps={{
    filterOption: (input, option) =>
      (option?.label ?? '').toLowerCase().includes(input.toLowerCase())
  }}
  placeholder="Search and select country"
/>

Props

Extends ProFormText props and Ant Design Select props.

options

SelectOption[] | string[]

Options for the select. Can be:

Array of objects: { label: string, value: any, disabled?: boolean }
Array of strings: Will be used as both label and value

mode

'single' | 'multiple' | 'tags'

Selection mode:

single: Default, select single option
multiple: Allow selecting multiple options
tags: Allow creating new options by typing

showSearch

boolean

default:"false"

Whether to show search input for filtering options.

request

(params: any) => Promise<SelectOption[]>

Async function to load options from remote source. Called when component mounts.

params

Record<string, any>

Parameters passed to request function. When params change, request is triggered again.

valueEnum

Record<string, { text: string, status?: string }>

Enum mapping for options. Alternative to options prop:

valueEnum={{
  active: { text: 'Active', status: 'Success' },
  inactive: { text: 'Inactive', status: 'Default' }
}}

fieldProps.allowClear

boolean

Whether to show clear button when value is selected.

fieldProps.autoClearSearchValue

boolean

default:"true"

Whether to clear search input after selecting an option.

fieldProps.defaultActiveFirstOption

boolean

Whether to activate the first option by default when dropdown opens.

fieldProps.filterOption

boolean | ((input: string, option: SelectOption) => boolean)

Custom filter function for search. Return false to hide option.

fieldProps.labelInValue

boolean

default:"false"

Whether to return object instead of just value.

fieldProps.maxTagCount

number | 'responsive'

Maximum number of tags to show in multiple mode. Use ‘responsive’ for automatic calculation.

fieldProps.notFoundContent

ReactNode

Content displayed when no options match or data is empty.

fieldProps.optionFilterProp

string

default:"'value'"

Which property to filter when using search (e.g., ‘label’, ‘value’).

fieldProps.placeholder

string

Placeholder text shown when no value is selected.

fieldProps.searchValue

string

Controlled search value.

fieldProps.onSearch

(value: string) => void

Callback when search input changes.

fieldProps.onSelect

(value: any, option: SelectOption) => void

Callback when an option is selected.

fieldProps.onDeselect

(value: any, option: SelectOption) => void

Callback when an option is deselected (multiple mode).

fieldProps.onChange

(value: any, option: SelectOption | SelectOption[]) => void

Callback when selected value changes.

searchOnFocus

boolean

default:"false"

Whether to trigger search when input is focused.

resetAfterSelect

boolean

default:"false"

Whether to clear search value after selecting an option.

fetchDataOnSearch

boolean

default:"true"

Whether to call request when search keyword changes.

optionItemRender

(item: any) => ReactNode

Custom render function for each option item.

ProFormSelect.SearchSelect

Enhanced select with optimized search behavior for large datasets.

Import

import { ProFormSelect } from '@ant-design/pro-components';

Usage

<ProFormSelect.SearchSelect
  name="products"
  label="Products"
  mode="multiple"
  request={async ({ keyWords }) => {
    const response = await fetch(`/api/products?search=${keyWords}`);
    const data = await response.json();
    return data.map(product => ({
      label: product.name,
      value: product.id
    }));
  }}
  placeholder="Search products"
  fieldProps={{
    labelInValue: true
  }}
/>

Props

Extends ProFormSelect props with enhanced search features:

Defaults to showSearch={true}
Defaults to labelInValue={true}
Optimized for remote search scenarios
Auto-clears search value after selection
No suffix icon by default

ProFormTreeSelect

Tree structure select component for hierarchical data.

Import

import { ProFormTreeSelect } from '@ant-design/pro-components';

Usage

Basic
Multiple
Remote Data

<ProFormTreeSelect
  name="department"
  label="Department"
  fieldProps={{
    treeData: [
      {
        title: 'Engineering',
        value: 'eng',
        children: [
          { title: 'Frontend', value: 'eng-fe' },
          { title: 'Backend', value: 'eng-be' }
        ]
      },
      {
        title: 'Marketing',
        value: 'mkt',
        children: [
          { title: 'Content', value: 'mkt-content' },
          { title: 'Social', value: 'mkt-social' }
        ]
      }
    ]
  }}
  placeholder="Select department"
/>

<ProFormTreeSelect
  name="permissions"
  label="Permissions"
  fieldProps={{
    treeData: permissionsTree,
    multiple: true,
    treeCheckable: true,
    showCheckedStrategy: 'SHOW_PARENT'
  }}
  placeholder="Select permissions"
/>

<ProFormTreeSelect
  name="category"
  label="Category"
  request={async () => {
    const response = await fetch('/api/categories/tree');
    return response.json();
  }}
  placeholder="Select category"
/>

Props

Extends ProFormText props and Ant Design TreeSelect props.

fieldProps.treeData

TreeNode[]

Tree data structure. Each node:

interface TreeNode {
  title: string;
  value: string | number;
  children?: TreeNode[];
  disabled?: boolean;
  selectable?: boolean;
  checkable?: boolean;
}

request

(params: any) => Promise<TreeNode[]>

Async function to load tree data from remote source.

params

Record<string, any>

Parameters passed to request function.

fieldProps.multiple

boolean

default:"false"

Whether to allow selecting multiple nodes.

fieldProps.treeCheckable

boolean

default:"false"

Whether to show checkbox on each tree node.

fieldProps.showCheckedStrategy

'SHOW_ALL' | 'SHOW_PARENT' | 'SHOW_CHILD'

Strategy for displaying selected nodes:

SHOW_ALL: Show all checked nodes
SHOW_PARENT: Show only parent nodes when all children are checked
SHOW_CHILD: Show only child nodes

fieldProps.treeDefaultExpandAll

boolean

default:"false"

Whether to expand all tree nodes by default.

fieldProps.treeDefaultExpandedKeys

(string | number)[]

Array of keys for nodes to expand by default.

fieldProps.treeNodeFilterProp

string

default:"'title'"

Which property to filter when searching.

fieldProps.showSearch

boolean

default:"false"

Whether to show search input.

fieldProps.treeNodeLabelProp

string

default:"'title'"

Which property to use as label for selected value display.

fieldProps.allowClear

boolean

Whether to show clear button.

fieldProps.onChange

(value: any, label: string[], extra: any) => void

Callback when selected value changes.

fetchDataOnSearch

boolean

default:"true"

Whether to call request when search keyword changes.

ProFormCascader

Cascading select component for multi-level related data.

Import

import { ProFormCascader } from '@ant-design/pro-components';

Usage

Basic
Remote Data
Dynamic Load

<ProFormCascader
  name="location"
  label="Location"
  fieldProps={{
    options: [
      {
        value: 'usa',
        label: 'United States',
        children: [
          {
            value: 'ca',
            label: 'California',
            children: [
              { value: 'sf', label: 'San Francisco' },
              { value: 'la', label: 'Los Angeles' }
            ]
          },
          {
            value: 'ny',
            label: 'New York',
            children: [
              { value: 'nyc', label: 'New York City' }
            ]
          }
        ]
      }
    ]
  }}
  placeholder="Select location"
/>

<ProFormCascader
  name="category"
  label="Category"
  request={async () => {
    const response = await fetch('/api/categories/cascader');
    return response.json();
  }}
  placeholder="Select category"
/>

<ProFormCascader
  name="region"
  label="Region"
  fieldProps={{
    options: initialOptions,
    loadData: async (selectedOptions) => {
      const targetOption = selectedOptions[selectedOptions.length - 1];
      targetOption.loading = true;
      
      const response = await fetch(`/api/regions/${targetOption.value}/children`);
      const children = await response.json();
      
      targetOption.loading = false;
      targetOption.children = children;
    }
  }}
/>

Props

Extends ProFormText props and Ant Design Cascader props.

fieldProps.options

CascaderOption[]

Cascading options data. Each option:

interface CascaderOption {
  value: string | number;
  label: string;
  children?: CascaderOption[];
  disabled?: boolean;
  loading?: boolean;
  isLeaf?: boolean;
}

request

(params: any) => Promise<CascaderOption[]>

Async function to load options from remote source.

params

Record<string, any>

Parameters passed to request function.

fieldProps.changeOnSelect

boolean

default:"false"

Whether to change value on each selection in the cascade path.

fieldProps.displayRender

(label: string[], selectedOptions: CascaderOption[]) => ReactNode

Custom render function for displaying selected value.

fieldProps.expandTrigger

'click' | 'hover'

default:"'click'"

How to trigger expanding of next level options.

fieldProps.fieldNames

{ label: string, value: string, children: string }

Custom field names for options:

fieldNames={{ label: 'name', value: 'code', children: 'items' }}

fieldProps.loadData

(selectedOptions: CascaderOption[]) => void

Function to load options dynamically. Called when expanding a node.

fieldProps.showSearch

boolean | ShowSearchType

Whether to show search input. Can be boolean or search configuration:

showSearch={{
  filter: (inputValue, path) => 
    path.some(option => option.label.includes(inputValue)),
  limit: 50,
  matchInputWidth: true,
  render: (inputValue, path) => path.map(o => o.label).join(' / ')
}}

fieldProps.allowClear

boolean

Whether to show clear button.

fieldProps.placeholder

string

Placeholder text when no value is selected.

fieldProps.onChange

(value: any[], selectedOptions: CascaderOption[]) => void

Callback when selected value changes.

Common Features

Show Remote Data Loading

All select components support loading options from remote sources using the request prop:

<ProFormSelect
  request={async (params) => {
    const response = await fetch('/api/options', {
      method: 'POST',
      body: JSON.stringify(params)
    });
    return response.json();
  }}
  params={{ type: 'active' }} // Triggers request when changed
/>

The request function is called:

On component mount
When params prop changes
When search keyword changes (if fetchDataOnSearch={true})

Show Value Enum

Use valueEnum for simple option mapping with status indicators:

<ProFormSelect
  valueEnum={{
    open: { text: 'Open', status: 'Processing' },
    closed: { text: 'Closed', status: 'Success' },
    cancelled: { text: 'Cancelled', status: 'Error' }
  }}
/>

Show Popup Container

Show Read-only Mode

In read-only mode, selected values display as badges or text instead of dropdowns:

<ProFormSelect
  readonly
  name="status"
  valueEnum={{ active: { text: 'Active', status: 'Success' } }}
/>

Components API

Form Fields API

Utilities

ProFormSelect

Import

Usage

Props

ProFormSelect.SearchSelect

Import

Usage

Props

ProFormTreeSelect

Import

Usage

Props

ProFormCascader

Import

Usage

Props

Common Features

Build docs developers (and LLMs) love

Components API

Form Fields API

Utilities

​ProFormSelect

​Import

​Usage

​Props

​ProFormSelect.SearchSelect

​Import

​Usage

​Props

​ProFormTreeSelect

​Import

​Usage

​Props

​ProFormCascader

​Import

​Usage

​Props

​Common Features

Build docs developers (and LLMs) love

ProFormSelect

Import

Usage

Props

ProFormSelect.SearchSelect

Import

Usage

Props

ProFormTreeSelect

Import

Usage

Props

ProFormCascader

Import

Usage

Props

Common Features