logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.20.6
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tabs
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

Cascader

Cascade selection box.
Importimport{ Cascader }from"antd";
Sourcecomponents/cascader
DocsEdit this page

Resources

Ant Design Charts
Ant Design Pro
Ant Design Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
ahooks-React Hooks Library
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

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

<Cascader options={options} onChange={onChange} />
PropertyDescriptionTypeDefaultVersion
allowClearShow clear buttonboolean | { clearIcon?: ReactNode }true5.8.0: Support object type
autoClearSearchValueWhether the current search will be cleared on selecting an item. Only applies when multiple is truebooleantrue5.9.0
autoFocusIf get focus when component mountedbooleanfalse
changeOnSelectChange value on each selection if set to true, see above demo for detailsbooleanfalse
classNameThe additional css classstring-
defaultValueInitial selected valuestring[] | number[][]
disabledWhether disabled selectbooleanfalse
displayRenderThe render function of displaying selected options(label, selectedOptions) => ReactNodelabel => label.join(/)multiple: 4.18.0
tagRenderCustom render function for tags in multiple mode(label: string, onClose: function, value: string) => ReactNode-
popupClassNameThe additional className of popup overlaystring-4.23.0
dropdownRenderCustomize dropdown content(menus: ReactNode) => ReactNode-4.4.0
expandIconCustomize the current item expand iconReactNode-4.4.0
expandTriggerexpand current item when click or hover, one of click hoverstringclick
fieldNamesCustom field name for label and value and childrenobject{ label: label, value: value, children: children }
getPopupContainerParent 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. examplefunction(triggerNode)() => document.body
loadDataTo load option lazily, and it cannot work with showSearch(selectedOptions) => void-
maxTagCountMax tag count to show. responsive will cost render performancenumber | responsive-4.17.0
maxTagPlaceholderPlaceholder for not showing tagsReactNode | function(omittedValues)-4.17.0
maxTagTextLengthMax tag text length to shownumber-4.17.0
notFoundContentSpecify content to show when no result matchesstringNot Found
openSet visible of cascader popupboolean-4.17.0
optionsThe data options of cascadeOption[]-
placeholderThe input placeholderstring-
placementUse preset popup align config from builtinPlacementsbottomLeft bottomRight topLeft topRightbottomLeft4.17.0
showSearchWhether show search input in single modeboolean | Objectfalse
sizeThe input sizelarge | middle | small-
statusSet validation status'error' | 'warning'-4.19.0
styleThe additional styleCSSProperties-
suffixIconThe custom suffix iconReactNode-
valueThe selected valuestring[] | number[]-
variantVariants of selectoroutlined | borderless | filledoutlined5.13.0
onChangeCallback when finishing cascader select(value, selectedOptions) => void-
onDropdownVisibleChangeCallback when popup shown or hidden(value) => void-4.17.0
multipleSupport multiple or notboolean-4.17.0
removeIconThe custom remove iconReactNode-
showCheckedStrategyThe 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_CHILDCascader.SHOW_PARENT4.20.0
searchValueSet search value, Need work with showSearchstring-4.17.0
onSearchThe callback function triggered when input changed(search: string) => void-4.17.0
dropdownMenuColumnStyleThe style of the drop-down menu columnCSSProperties-
loadingIconThe appearance of lazy loading (now is useless)ReactNode-
optionRenderCustomize the rendering dropdown options(option: Option) => React.ReactNode-5.16.0

showSearch

PropertyDescriptionTypeDefaultVersion
filterThe 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 excludedfunction(inputValue, path): boolean-
limitSet the count of filtered itemsnumber | false50
matchInputWidthWhether the width of list matches input, (how it looks)booleantrue
renderUsed to render filtered optionsfunction(inputValue, path): ReactNode-
sortUsed to sort filtered optionsfunction(a, b, inputValue)-

Option

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

NameDescriptionVersion
blur()Remove focus
focus()Get focus

Design Token

Component TokenHow to use?

Token NameDescriptionTypeDefault Value
controlItemWidthWidth of itemstring | number111
controlWidthWidth of Cascaderstring | number184
dropdownHeightHeight of dropdownstring | number180
menuPaddingPadding of menu item (single column)undefined | Padding<string | number>4
optionPaddingPadding of menu itemundefined | Padding<string | number>5px 12px
optionSelectedBgBackground color of selected itemstring#e6f4ff
optionSelectedFontWeightFont weight of selected itemundefined | FontWeight600

Global TokenHow to use?

Basic

Cascade selection box for selecting province/city/district.

codepen icon
External Link Icon
expand codeexpand code
Custom trigger

Separate trigger button and result.

codepen icon
External Link Icon
expand codeexpand code
Disabled option

Disable option by specifying the disabled property in options.

codepen icon
External Link Icon
expand codeexpand code
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.

codepen icon
External Link Icon
expand codeexpand code
Size

Cascade selection box of different sizes.

codepen icon
External Link Icon
expand codeexpand code
Search

Search and select options directly.

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

codepen icon
External Link Icon
expand codeexpand code
Custom Field Names

Custom field names.

codepen icon
External Link Icon
expand codeexpand code
Placement

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

codepen icon
External Link Icon
expand codeexpand code
Panel

Used for inline view case.

codepen icon
External Link Icon
expand codeexpand code
>= 5.10.0
Default value

Specifies default value by an array.

codepen icon
External Link Icon
expand codeexpand code
Hover

Hover to expand sub menu, click to select option.

codepen icon
External Link Icon
expand codeexpand code
Change on select

Allows the selection of only parent options.

codepen icon
External Link Icon
expand codeexpand code
ShowCheckedStrategy

Shows a selected item in a box using showCheckedStrategy.

codepen icon
External Link Icon
expand codeexpand code
Custom render

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

codepen icon
External Link Icon
expand codeexpand code
Load Options Lazily

Load options lazily with loadData.

Note: loadData cannot work with showSearch.

codepen icon
External Link Icon
expand codeexpand code
Custom dropdown

Customize the dropdown menu via dropdownRender.

codepen icon
External Link Icon
expand codeexpand code
Status

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

codepen icon
External Link Icon
expand codeexpand code
Please select
Unselect Change city
 






Please select
Please select


Please select
  • Zhejiang
  • Jiangsu
  • Zhejiang
  • Jiangsu
Simple Empty
No data
Zhejiang / Hangzhou / West Lake
+ 2 ...
 


+ 0 ...
 
Zhejiang / Hangzhou / West Lake (752100)
Please select
Error
 
Warning multiple