Ant Design

⌘ K

5.27.5

Cascader

Cascade selection box.

Importimport { Cascader } from "antd";

GitHub

components/cascader Issue Open issues

Docs

Edit this page

contributors

AutoComplete Checkbox

Ant Design

⌘ K

5.27.5

Cascader

Cascade selection box.

Importimport { Cascader } from "antd";

GitHub

components/cascader Issue Open issues

Docs

Edit this page

contributors

AutoComplete Checkbox

When To Use

When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.
When selecting from a large data set, with multi-stage classifications separated for easy selection.
Chooses cascade items in one float layer for better user experience.

Examples

API

Common props ref：Common props

jsx

<Cascader options={options} onChange={onChange} />

Property	Description	Type	Default	Version
allowClear	Show clear button	boolean \| { clearIcon?: ReactNode }	true	5.8.0: Support object type
autoClearSearchValue	Whether the current search will be cleared on selecting an item. Only applies when `multiple` is `true`	boolean	true	5.9.0
autoFocus	If get focus when component mounted	boolean	false
changeOnSelect	Change value on each selection if set to true, see above demo for details	boolean	false
className	The additional css class	string	-
classNames	Semantic DOM class	Record<SemanticDOM, string>	-	5.25.0
defaultOpen	Initial visible of cascader popup	boolean	-
defaultValue	Initial selected value	string[] \| number[]	[]
disabled	Whether disabled select	boolean	false
displayRender	The render function of displaying selected options	(label, selectedOptions) => ReactNode	label => label.join(`/`)	`multiple`: 4.18.0
tagRender	Custom render function for tags in `multiple` mode	(label: string, onClose: function, value: string) => ReactNode	-
~~popupClassName~~	The additional className of popup overlay, use `classNames.popup.root` instead	string	-	4.23.0
~~dropdownRender~~	Customize dropdown content, use `popupRender` instead	(menus: ReactNode) => ReactNode	-	4.4.0
popupRender	Customize dropdown content	(menus: ReactNode) => ReactNode	-
~~dropdownStyle~~	The style of dropdown menu, use `styles.popup.root` instead	CSSProperties	-
expandIcon	Customize the current item expand icon	ReactNode	-	4.4.0
expandTrigger	expand current item when click or hover, one of `click` `hover`	string	`click`
fieldNames	Custom field name for label and value and children	object	{ label: `label`, value: `value`, children: `children` }
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	function(triggerNode)	() => document.body
loadData	To load option lazily, and it cannot work with `showSearch`	(selectedOptions) => void	-
maxTagCount	Max tag count to show. `responsive` will cost render performance	number \| `responsive`	-	4.17.0
maxTagPlaceholder	Placeholder for not showing tags	ReactNode \| function(omittedValues)	-	4.17.0
maxTagTextLength	Max tag text length to show	number	-	4.17.0
notFoundContent	Specify content to show when no result matches	ReactNode	`Not Found`
open	Set visible of cascader popup	boolean	-	4.17.0
options	The data options of cascade	Option[]	-
placeholder	The input placeholder	string	-
placement	Use preset popup align config from builtinPlacements	`bottomLeft` `bottomRight` `topLeft` `topRight`	`bottomLeft`	4.17.0
prefix	The custom prefix	ReactNode	-	5.22.0
showSearch	Whether show search input in single mode	boolean \| Object	false
size	The input size	`large` \| `middle` \| `small`	-
status	Set validation status	'error' \| 'warning'	-	4.19.0
styles	Semantic DOM style	Record<SemanticDOM, CSSProperties>	-	5.25.0
suffixIcon	The custom suffix icon	ReactNode	-
value	The selected value	string[] \| number[]	-
variant	Variants of selector	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
onChange	Callback when finishing cascader select	(value, selectedOptions) => void	-
~~onDropdownVisibleChange~~	Callback when popup shown or hidden, use `onOpenChange` instead	(value) => void	-	4.17.0
onOpenChange	Callback when popup shown or hidden	(value) => void	-
multiple	Support multiple or not	boolean	-	4.17.0
removeIcon	The custom remove icon	ReactNode	-
showCheckedStrategy	The way show selected item in box. `SHOW_CHILD`: just show child treeNode. `Cascader.SHOW_PARENT`: just show parent treeNode (when all child treeNode under the parent treeNode are checked)	`Cascader.SHOW_PARENT` \| `Cascader.SHOW_CHILD`	`Cascader.SHOW_PARENT`	4.20.0
searchValue	Set search value, Need work with `showSearch`	string	-	4.17.0
onSearch	The callback function triggered when input changed	(search: string) => void	-	4.17.0
~~dropdownMenuColumnStyle~~	The style of the drop-down menu column, use `popupMenuColumnStyle` instead	CSSProperties	-
popupMenuColumnStyle	The style of the drop-down menu column	CSSProperties	-
loadingIcon	The appearance of lazy loading (now is useless)	ReactNode	-
optionRender	Customize the rendering dropdown options	(option: Option) => React.ReactNode	-	5.16.0

showSearch

Property	Description	Type	Default
filter	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	function(inputValue, path): boolean	-
limit	Set the count of filtered items	number \| false	50
matchInputWidth	Whether the width of list matches input, (how it looks)	boolean	true
render	Used to render filtered options	function(inputValue, path): ReactNode	-
sort	Used to sort filtered options	function(a, b, inputValue)	-

Option

typescript

interface Option {
  value: string | number;
  label?: React.ReactNode;
  disabled?: boolean;
  children?: Option[];
  // Determines if this is a leaf node(effective when `loadData` is specified).
  // `false` will force trade TreeNode as a parent node.
  // Show expand icon even if the current node has no children.
  isLeaf?: boolean;
}

Methods

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

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
controlItemWidth	Width of item	string \| number	111
controlWidth	Width of Cascader	string \| number	184
dropdownHeight	Height of dropdown	string \| number	180
menuPadding	Padding of menu item (single column)	Padding<string \| number> \| undefined	4
optionPadding	Padding of menu item	Padding<string \| number> \| undefined	5px 12px
optionSelectedBg	Background color of selected item	string	#e6f4ff
optionSelectedColor	Text color when option is selected	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	Font weight of selected item	FontWeight \| undefined	600

Global TokenHow to use?

When To Use

When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.
When selecting from a large data set, with multi-stage classifications separated for easy selection.
Chooses cascade items in one float layer for better user experience.

Examples

Basic

Cascade selection box for selecting province/city/district.

Custom trigger

Separate trigger button and result.

Disabled option

Disable option by specifying the disabled property in options.

Multiple

Select multiple options. Disable the checkbox by adding the disableCheckbox property and selecting a specific item. The style of the disable can be modified by the className.

Size

Cascade selection box of different sizes.

Search

Search and select options directly.

Now, Cascader[showSearch] doesn't support search on server, more info #5547

Custom Field Names

Custom field names.

Variants

Variants of Cascader, there are four variants: outlined filled borderless and underlined.

5.13.0

Panel

Used for inline view case.

>= 5.10.0

Default value

Specifies default value by an array.

Hover

Hover to expand sub menu, click to select option.

Change on select

Allows the selection of only parent options.

ShowCheckedStrategy

Shows a selected item in a box using showCheckedStrategy.

Custom render

For instance, add an external link after the selected value.

Load Options Lazily

Load options lazily with loadData.

Note: loadData cannot work with showSearch.

Prefix and Suffix

Use prefix to customize the prefix content, use suffixIcon to customize the selection box suffix icon, and use expandIcon to customize the current item expand icon.

5.22.0

Placement

You can manually specify the position of the popup via placement.

Status

Add status to Cascader with status, which could be error or warning.

API

Common props ref：Common props

jsx

<Cascader options={options} onChange={onChange} />

Property	Description	Type	Default	Version
allowClear	Show clear button	boolean \| { clearIcon?: ReactNode }	true	5.8.0: Support object type
autoClearSearchValue	Whether the current search will be cleared on selecting an item. Only applies when `multiple` is `true`	boolean	true	5.9.0
autoFocus	If get focus when component mounted	boolean	false
changeOnSelect	Change value on each selection if set to true, see above demo for details	boolean	false
className	The additional css class	string	-
classNames	Semantic DOM class	Record<SemanticDOM, string>	-	5.25.0
defaultOpen	Initial visible of cascader popup	boolean	-
defaultValue	Initial selected value	string[] \| number[]	[]
disabled	Whether disabled select	boolean	false
displayRender	The render function of displaying selected options	(label, selectedOptions) => ReactNode	label => label.join(`/`)	`multiple`: 4.18.0
tagRender	Custom render function for tags in `multiple` mode	(label: string, onClose: function, value: string) => ReactNode	-
~~popupClassName~~	The additional className of popup overlay, use `classNames.popup.root` instead	string	-	4.23.0
~~dropdownRender~~	Customize dropdown content, use `popupRender` instead	(menus: ReactNode) => ReactNode	-	4.4.0
popupRender	Customize dropdown content	(menus: ReactNode) => ReactNode	-
~~dropdownStyle~~	The style of dropdown menu, use `styles.popup.root` instead	CSSProperties	-
expandIcon	Customize the current item expand icon	ReactNode	-	4.4.0
expandTrigger	expand current item when click or hover, one of `click` `hover`	string	`click`
fieldNames	Custom field name for label and value and children	object	{ label: `label`, value: `value`, children: `children` }
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	function(triggerNode)	() => document.body
loadData	To load option lazily, and it cannot work with `showSearch`	(selectedOptions) => void	-
maxTagCount	Max tag count to show. `responsive` will cost render performance	number \| `responsive`	-	4.17.0
maxTagPlaceholder	Placeholder for not showing tags	ReactNode \| function(omittedValues)	-	4.17.0
maxTagTextLength	Max tag text length to show	number	-	4.17.0
notFoundContent	Specify content to show when no result matches	ReactNode	`Not Found`
open	Set visible of cascader popup	boolean	-	4.17.0
options	The data options of cascade	Option[]	-
placeholder	The input placeholder	string	-
placement	Use preset popup align config from builtinPlacements	`bottomLeft` `bottomRight` `topLeft` `topRight`	`bottomLeft`	4.17.0
prefix	The custom prefix	ReactNode	-	5.22.0
showSearch	Whether show search input in single mode	boolean \| Object	false
size	The input size	`large` \| `middle` \| `small`	-
status	Set validation status	'error' \| 'warning'	-	4.19.0
styles	Semantic DOM style	Record<SemanticDOM, CSSProperties>	-	5.25.0
suffixIcon	The custom suffix icon	ReactNode	-
value	The selected value	string[] \| number[]	-
variant	Variants of selector	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
onChange	Callback when finishing cascader select	(value, selectedOptions) => void	-
~~onDropdownVisibleChange~~	Callback when popup shown or hidden, use `onOpenChange` instead	(value) => void	-	4.17.0
onOpenChange	Callback when popup shown or hidden	(value) => void	-
multiple	Support multiple or not	boolean	-	4.17.0
removeIcon	The custom remove icon	ReactNode	-
showCheckedStrategy	The way show selected item in box. `SHOW_CHILD`: just show child treeNode. `Cascader.SHOW_PARENT`: just show parent treeNode (when all child treeNode under the parent treeNode are checked)	`Cascader.SHOW_PARENT` \| `Cascader.SHOW_CHILD`	`Cascader.SHOW_PARENT`	4.20.0
searchValue	Set search value, Need work with `showSearch`	string	-	4.17.0
onSearch	The callback function triggered when input changed	(search: string) => void	-	4.17.0
~~dropdownMenuColumnStyle~~	The style of the drop-down menu column, use `popupMenuColumnStyle` instead	CSSProperties	-
popupMenuColumnStyle	The style of the drop-down menu column	CSSProperties	-
loadingIcon	The appearance of lazy loading (now is useless)	ReactNode	-
optionRender	Customize the rendering dropdown options	(option: Option) => React.ReactNode	-	5.16.0

showSearch

Property	Description	Type	Default
filter	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	function(inputValue, path): boolean	-
limit	Set the count of filtered items	number \| false	50
matchInputWidth	Whether the width of list matches input, (how it looks)	boolean	true
render	Used to render filtered options	function(inputValue, path): ReactNode	-
sort	Used to sort filtered options	function(a, b, inputValue)	-

Option

typescript

interface Option {
  value: string | number;
  label?: React.ReactNode;
  disabled?: boolean;
  children?: Option[];
  // Determines if this is a leaf node(effective when `loadData` is specified).
  // `false` will force trade TreeNode as a parent node.
  // Show expand icon even if the current node has no children.
  isLeaf?: boolean;
}

Methods

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

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
controlItemWidth	Width of item	string \| number	111
controlWidth	Width of Cascader	string \| number	184
dropdownHeight	Height of dropdown	string \| number	180
menuPadding	Padding of menu item (single column)	Padding<string \| number> \| undefined	4
optionPadding	Padding of menu item	Padding<string \| number> \| undefined	5px 12px
optionSelectedBg	Background color of selected item	string	#e6f4ff
optionSelectedColor	Text color when option is selected	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	Font weight of selected item	FontWeight \| undefined	600

Global TokenHow to use?

Basic

Cascade selection box for selecting province/city/district.

Custom trigger

Separate trigger button and result.

Disabled option

Disable option by specifying the disabled property in options.

Multiple

Select multiple options. Disable the checkbox by adding the disableCheckbox property and selecting a specific item. The style of the disable can be modified by the className.

Size

Cascade selection box of different sizes.

Search

Search and select options directly.

Now, Cascader[showSearch] doesn't support search on server, more info #5547

Custom Field Names

Custom field names.

Variants

Variants of Cascader, there are four variants: outlined filled borderless and underlined.

5.13.0

Panel

Used for inline view case.

>= 5.10.0

Default value

Specifies default value by an array.

Hover

Hover to expand sub menu, click to select option.

Change on select

Allows the selection of only parent options.

ShowCheckedStrategy

Shows a selected item in a box using showCheckedStrategy.

Custom render

For instance, add an external link after the selected value.

Load Options Lazily

Load options lazily with loadData.

Note: loadData cannot work with showSearch.

Prefix and Suffix

Use prefix to customize the prefix content, use suffixIcon to customize the selection box suffix icon, and use expandIcon to customize the current item expand icon.

5.22.0

Placement

You can manually specify the position of the popup via placement.

Status

Add status to Cascader with status, which could be error or warning.

Please select

Unselect Change city

Please select

No data

Zhejiang / Hangzhou / West Lake

Zhejiang / Hangzhou / West Lake (752100)

Please select

topLefttopRightbottomLeftbottomRight

Please select

Error

Warning multiple

contributors / aojunhao123

root
5.25.0
Root element
popup.root
5.25.0
Popup element

Cascader

Cascader

When To Use

Examples

API

showSearch

Option

Methods

Semantic DOM

Design Token

When To Use

Examples

API

showSearch

Option

Methods

Semantic DOM

Design Token

root

popup.root