Cascader - Ant Design

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

<code src="./demo/basic.tsx">Basic</code> <code src="./demo/default-value.tsx">Default value</code> <code src="./demo/custom-trigger.tsx">Custom trigger</code> <code src="./demo/hover.tsx">Hover</code> <code src="./demo/disabled-option.tsx">Disabled option</code> <code src="./demo/change-on-select.tsx">Change on select</code> <code src="./demo/multiple.tsx">Multiple</code> <code src="./demo/showCheckedStrategy.tsx">ShowCheckedStrategy</code> <code src="./demo/size.tsx">Size</code> <code src="./demo/custom-render.tsx">Custom render</code> <code src="./demo/search.tsx">Search</code> <code src="./demo/lazy.tsx">Load Options Lazily</code> <code src="./demo/fields-name.tsx">Custom Field Names</code> <code src="./demo/suffix.tsx" version="5.22.0">Prefix and Suffix</code> <code src="./demo/custom-dropdown.tsx">Custom dropdown</code> <code src="./demo/placement.tsx">Placement</code> <code src="./demo/variant.tsx" version="5.13.0">Variants</code> <code src="./demo/status.tsx">Status</code> <code src="./demo/style-class.tsx" version="6.0.0">Custom semantic dom styling</code> <code src="./demo/panel.tsx" version=">= 5.10.0">Panel</code> <code src="./demo/ellipsis-debug.tsx" debug>Menu item ellipsis</code> <code src="./demo/render-panel.tsx" debug>_InternalPanelDoNotUseOrYouWillBeFired</code> <code src="./demo/component-token.tsx" debug>Component Token</code>

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
~~bordered~~	Whether has border style, please use `variant` instead	boolean	true	-
changeOnSelect	Change value on each selection if set to true, see above demo for details	boolean	false
className	The additional css class	string	-
classNames	Customize class for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
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
~~dropdownClassName~~	The additional className of popup overlay, please use `classNames.popup.root` instead	string	-	-
~~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	-
loadingIcon	Customize the loading icon	ReactNode	-
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
~~showArrow~~	Whether to show the arrow icon, please use `suffixIcon={null}` instead	boolean	true	-
showSearch	Whether show search input in single mode	boolean \| Object	false
size	The input size	`large` \| `medium` \| `small`	`medium`
status	Set validation status	'error' \| 'warning'	-	4.19.0
styles	Customize inline style for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-
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	-
~~onPopupVisibleChange~~	Callback when popup shown or hidden, please use `onOpenChange` instead	(value) => void	-	-
multiple	Support multiple or not	boolean	-	4.17.0
removeIcon	The custom remove icon	ReactNode	-
showCheckedStrategy	The way to show selected items in the box (only effective when `multiple` is `true`). `Cascader.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 `styles.popup.listItem` instead	CSSProperties	-
~~popupMenuColumnStyle~~	The style of the drop-down menu column, use `styles.popup.listItem` instead	CSSProperties	-
optionRender	Customize the rendering dropdown options	(option: Option) => React.ReactNode	-	5.16.0

showSearch

Property	Description	Type	Default	Version
autoClearSearchValue	Whether the current search will be cleared on selecting an item. Only applies when `multiple` is `true`	boolean	true	5.9.0
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)	-
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

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