Input · Cascader
Used to select an option under a multi-level classification.


How to import

Basic Usage

Basic usage, only leaf nodes can be selected by default.


version: >= 1.28.0
Set multiple to make multiple selections.


Use filterTreeNode to support search input. By default it searches the value property of the data. You can use treeNodeFilterProp to set another property to search or pass in a function to filterTreeNode to customize search behavior.

Searchable Multiple Selection

version: >= 1.28.0
When multiple selection and search are supported at the same time, in this scenario, you can delete the corresponding selected item by pressing the BackSpace key.

Limit Tags Displayed

version: >= 1.28.0
When multiple selections, you can use maxTagCount to limit the number of tags displayed, and the excess will be displayed as +N.
You can use showRestTagsPopover to set whether hover +N displays Popover after maxTagCount is exceeded, the default is false. And, you can also configure Popover in the restTagsPopoverProps property.

Limit Tags Number

version: >= 1.28.0
In a multi-selection scene, use max to limit the number of multi-selection selections. After max is exceeded, the onExceed callback will be triggered.

Change on Select

In the case of single selection, you can also set changeOnSelect to allow the parent option to be selected.

Custom Display Property

Set displayProp to select which property in the data you would like to display. By default, label is displayed.
The return format can be set by setting displayRender.
When single selection (multiple=false), displayRender((labelPath: string[]) => ReactNode), where labelPath is a path array composed of labels.
When multiple selection (multiple=true), displayRender((item: Entity, index: number) => ReactNode), where item is the relevant data of the node.

Custom Separator

Version: >=2.2.0
You can use separator to set the separator, including: the separator of the content displayed in the dropdown during search and displayed in the Trigger during single selection.


Disable Strictly

version: >= 1.32.0
You can use disableStrictly to enable strict disabling. After enabling strict disabling, when the node is disabled, the selected state cannot be changed through the relationship between the child or the parent.
Take the following demo as an example, the node "Music" is strictly disabled. Therefore, when we change the selected state of its parent node "Impressionism", it will not affect the selected state of the node "Music".

the Way of Expand Menu

version: >= 1.29.0
You can use showNext to set the time to expand the Dropdown submenu, optional: click (default), hover.

Additional items

We have reserved slots at the top and bottom of the cascade selector. You can set them through bottomSlot or topSlot.

Controlled Component

You can use value along with onChange property if you want to use Cascader as a controlled component.

Auto Merge Value

In the multi-selection (multiple=true) scenario, when we select the ancestor node, if we want the value not to include its corresponding descendant nodes, we can set it by autoMergeValue, and the default is true. When autoMergeValue and leafOnly are turned on at the same time, the latter has a higher priority.

Leaf Only

version: >=2.2.0
In multiple selection, you can set the value to include only leaf nodes by turning on leafOnly, that is, the displayed Tag and onChange parameter values only include value.

Dynamic Update of Data

Deep & long list

When your data structure level is particularly deep, the Cascader drop-down menu may be at the top of the screen. At this time, we recommend setting overflow -x: auto and a suitable width for the drop-down menu (it is recommended to use a width of N+0.5 columns, the most Expand to display half a column to give users a visual cue that they can scroll in the horizontal direction)

Load Async Data

You could use loadData to load data asynchronously. v>=1.8.0
Could not be used together with searching

Custom Trigger

If the default trigger style cannot meet your needs, you can use triggerRender to customize the display of the select box
The parameters of triggerRender are as follows

API reference


arrowIconCustomize the right drop-down arrow Icon, when the showClear switch is turned on and there is currently a selected value, hover will give priority to the clear iconReactNode1.15.0
autoAdjustOverflowWhether to automatically adjust the expansion direction of the dropdown for automatic adjustment of the expansion direction during edge occlusionbooleantrue-
autoMergeValueAuto merge value. Specifically, after opening, when a parent node is selected, the value will not include the descendants of the node. Does not support dynamic switchingbooleantrue1.28.0
bottomSlotbottom slotReactNode-1.27.0
changeOnSelectToggle whether non-leaf nodes are selectablebooleanfalse-
defaultOpenSet whether to open the dropDown by defaultbooleanfalse-
defaultValueDefault selected valuestring|number|TreeNode|(string|number|TreeNode)[]--
disabledMakes the element disabledbooleanfalse-
displayPropSet the attribute value displayed by the backfill option displayedstringlabel-
displayRenderSet the backfill format value(selected: string[] | Entity, idx?: number) => ReactNodeselected => selected.join ('/')-
dropdownClassNameClassName property for the drop-down menustring--
dropdownStyleInline style of drop-down menuobject--
emptyContentContent displayed when the search has no resultReactNodeNo result-
filterLeafOnlyWhether the search results only show the path of leaf nodesbooleantrue1.26.0
filterTreeNodeSet filter, the value of treeNodeFilterProp is used for searching((inputValue: string, treeNodeString: string) => boolean) | booleanfalse-
getPopupContainerSpecify the parent DOM, the drop-down box will be rendered into the DOM, the customization needs to set position: relative() => HTMLElement() => document.body-
insetLabelPrefix alias, used mainly in FormReactNode-0.28.0
leafOnlyWhen multiple selections, the set value only includes leaf nodes, that is, the displayed Tag and onChange value parameters only include leaf nodes. Does not support dynamic switchingbooleanfalse2.2.0
loadDataLoad data asynchronously and the return value should be a promise(selectOptions: TreeNode[]) => Promise< void >-1.8.0
maxIn the case of multiple selections, the number of multiple selections is limited, and the onExceed callback will be triggered when max is exceedednumber-1.28.0
maxTagCountWhen multiple selections, the maximum number of labels to be displayed will be displayed in the form of +N after exceedingnumber-1.28.0
motionSet the pop-up animation of the dropdown boxboolean|objecttrue-
mouseEnterDelayAfter the mouse is moved in, the time to delay the display of the dropdown box, in millisecondsnumber50-
mouseLeaveDelayAfter the mouse is moved out, the time to hide the display of the dropdown box, in millisecondsnumber50-
multipleSet multiplebooleanfalse1.28.0
prefixPrefix labelReactNode-0.28.0
preventScrollIndicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the userboolean
restTagsPopoverPropsThe configuration properties of the PopoverPopoverProps{}1.28.0
searchPlaceholderPlaceholder for search inputstring--
separatorCustom separator, including: the separator of the content displayed in the dropdown during search and displayed in the Trigger during single selectionstring' / '2.2.0
showClearToggle whether to show clear buttonbooleanfalse0.35.0
showNextSet the way to expand the Dropdown submenu, one of: clickhoverstringclick1.29.0
showRestTagsPopoverWhen the number of tags exceeds maxTagCount and hover reaches +N, whether to display the remaining content through Popoverbooleanfalse1.28.0
sizeSelectbox size, one of large, small, defaultstringdefault-
stopPropagationWhether to prevent the click event on the dropdown box from bubblingbooleantrue-
disableStrictlySet whether to enable strict prohibition. After opening, when the node is disabled, the selected state cannot be changed through the relationship between the child or the parentbooleanfalse1.32.0
styleInline styleCSSProperties--
suffixSuffix labelReactNode-0.28.0
topSlottop slotReactNode-1.27.0
treeDataRender data. Refer to TreeNode for detailed formatting.TreeNode[]\ []-
treeNodeFilterPropWhen searching, the input item filters the corresponding treeNode property.stringlabel-
triggerRenderMethod to create a custom trigger(triggerRenderData: object) => ReactNode-0.34.0
valueSelected value (controlled mode)string|number|TreeNode|(string|number|TreeNode)[][]--
validateStatusThe validation status of the trigger only affects the display style. Optional: default、error、warningstringdefault-
zIndexzIndex for dropdown menunumber1030-
enableLeafClickMultiple mode, click the leaf option enable trigger checkbooleanfalse2.2.0
onBlurOut of focus Cascader's callback(e: MouseEvent) => void--
onChangeCallback function when the tree node is selected(value: string|number|TreeNode|(string|number|TreeNode)[]) => void--
onClearWhen showClear is true, click the clear button to trigger the callback() => void-1.29.0
onChangeWithObjectToggle whether to return all properties in an option as a return value. When set to true, return value looks like TreeNode. For controlled mode, you need to pass TreeNode to value correspondingly. DefaultValue similarly.booleanfalse1.16.0
onDropdownVisibleChangeCallback function when dropdown menu visibility changes(visible: boolean) => void-0.35.0
onExceedWhen multiple selections are made, the callback triggered after max is exceeded(checkedItem: Entity[]) => void-1.28.0
onFocusFocus on Cascader's callback(e: MouseEvent) => void--
onListScrollCallback function when panel list scroll(e: React.Event, panel: { panelIndex: number; activeNode: TreeNode; } ) => void-1.15.0
onLoadCallback function when a node is loaded(newLoadedKeys: Set< string >, data: TreeNode) => void-1.8.0
onSearchCallback function when the values for search input changes(value: string) => void--
onSelectCallback function when selectedfunction(selected: string)--


childrenchildren nodeTreeNode[]-
disabledDisabled status >=0.35.0boolean-
isLeafleaf nodeboolean-
labelText to be displayed (required)ReactNode-
valueValue property (required)string|number-



  • Cascader supports importing aria-label, aria-describedby, aria-errormessage, aria-invalid, aria-labelledby, aria-required to indicate the relevant information of the Cascader;
  • Cascader supports selecting options, clearing options, and expanding drop-down box by pressing the Enter key

Design Tokens

© 2021 - 2022 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED