Input · Cascader
Cascader
Used to select an option under a multi-level classification.
Demos
How to import
Basic Usage
Basic usage, only leaf nodes can be selected by default.
Multiple
version: >= 1.28.0
Set
multiple
to make multiple selections.Searchable
Use
filterTreeNode
to support search input. By default, the
label
value is searched (using the includes method of the string for matching, case-insensitive). You can specify other attribute values through treeNodeFilterProp
to search. For example, If label
is ReactNode, you can use other fields in treeData to store plain text, and specify the field for search through treeNodeFilterProp
.The default search results will only display the paths of leaf nodes. If you want to display more results, you can set
filterLeafOnly
to false
.Searchable Multiple Selection
When multiple selection and search are supported at the same time (version: >= 1.28.0), in this scenario, you can delete the corresponding selected item by pressing the BackSpace key.
Filtered data can be sorted using
filterSorter
, filterSorter
is available since v2.28.0.If you want to customize the rendering options after the search, you can use
filterRender
to achieve custom rendering of the entire line. The filterRender
is available since v2.28.0, parameters are as follows:The example is as follows
If there are a lot of options in the search results, you can optimize performance by setting virtualizeInSearch to enable the virtualization of the search result panel. virtualizeInSearch has been available since v2.44.0. virtualizeInSearch is an object containing the following values:
- height: Option list height value
- width: Option list width value
- itemSize: The height of each row of Option
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.Disabled
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.
Checked RelationShip
Version: >= 2.71.0
In multiple,
checkRelation
can be used to set the type of node selection relationship, optional: 'related' (default), 'unRelated'. When the selection relationship is 'unRelated', it means that selections between nodes do not affect each other.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
Could not be used together with searching
loadData
to load data asynchronously.
v>=1.8.0Could 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 boxThe parameters of triggerRender are as follows
API reference
Cascader
Properties | Instructions | type | Default | version |
---|---|---|---|---|
arrowIcon | Customize 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 icon | ReactNode | - | 1.15.0 |
autoAdjustOverflow | Whether to automatically adjust the expansion direction of the dropdown for automatic adjustment of the expansion direction during edge occlusion | boolean | true | - |
autoMergeValue | Auto 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 switching | boolean | true | 1.28.0 |
borderless | borderless mode >=2.33.0 | boolean | ||
bottomSlot | bottom slot | ReactNode | - | 1.27.0 |
changeOnSelect | Toggle whether non-leaf nodes are selectable | boolean | false | - |
checkRelation | In multiple, the relationship between the checked states of the nodes, optional: 'related'、'unRelated'. | string | 'related' | v2.71.0 |
className | ClassName | string | - | - |
clearIcon | Can be used to customize the clear button, valid when showClear is true | ReactNode | - | 2.25.0 |
defaultOpen | Set whether to open the dropDown by default | boolean | false | - |
defaultValue | Default selected value | string|number|CascaderData|(string|number|CascaderData)[] | - | - |
disabled | Makes the element disabled | boolean | false | - |
displayProp | Set the attribute value displayed by the backfill option displayed | string | label | - |
displayRender | Set the backfill format value | (selected: string[] | Entity, idx?: number) => ReactNode | selected => selected.join ('/') | - |
dropdownClassName | ClassName property for the drop-down menu | string | - | - |
dropdownMargin | Popup layer calculates the size of the safe area when the current direction overflows, used in scenes covered by fixed elements, more detail refer to issue#549, same as Tooltip margin | object|number | - | 2.25.0 |
dropdownStyle | Inline style of drop-down menu | object | - | - |
expandIcon | customize expand icon | ReactNode | - | 2.68.0 |
emptyContent | Content displayed when the search has no result | ReactNode | No result | - |
filterLeafOnly | Whether the search results only show the path of leaf nodes | boolean | true | 1.26.0 |
filterRender | Used to render filtered options | (props: FilterRenderProps) => ReactNode; | - | 2.28.0 |
filterSorter | Sort the filtered options | (first: CascaderData, second: CascaderData, inputValue: string) => number | - | 2.28.0 |
filterTreeNode | Set filter, the value of treeNodeFilterProp is used for searching, data parameter provided since v2.28.0 | ((inputValue: string, treeNodeString: string, data?: CascaderData) => boolean) | boolean | false | - |
getPopupContainer | Specify the parent DOM, the drop-down box will be rendered into the DOM, the customization needs to set position: relative This will change the DOM tree position, but not the view's rendering position. | () => HTMLElement | () => document.body | - |
insetLabel | Prefix alias, used mainly in Form | ReactNode | - | 0.28.0 |
leafOnly | When 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 switching | boolean | false | 2.2.0 |
loadData | Load data asynchronously and the return value should be a promise | (selectOptions: CascaderData[]) => Promise< void > | - | 1.8.0 |
max | In the case of multiple selections, the number of multiple selections is limited, and the onExceed callback will be triggered when max is exceeded | number | - | 1.28.0 |
maxTagCount | When multiple selections, the maximum number of labels to be displayed will be displayed in the form of +N after exceeding | number | - | 1.28.0 |
motion | Set the pop-up animation of the dropdown box | boolean | true | - |
mouseEnterDelay | After the mouse is moved in, the time to delay the display of the dropdown box, in milliseconds | number | 50 | - |
mouseLeaveDelay | After the mouse is moved out, the time to hide the display of the dropdown box, in milliseconds | number | 50 | - |
multiple | Set multiple | boolean | false | 1.28.0 |
placeholder | Placeholder | string | - | - |
prefix | Prefix label | ReactNode | - | 0.28.0 |
preventScroll | Indicates 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 user | boolean | - | 2.15.0 |
restTagsPopoverProps | The configuration properties of the Popover | PopoverProps | {} | 1.28.0 |
searchPlaceholder | Placeholder for search input | string | - | - |
searchPosition | Set the position of the search box, trigger or custom | string | trigger | 2.54.0 |
separator | Custom separator, including: the separator of the content displayed in the dropdown during search and displayed in the Trigger during single selection | string | / | 2.2.0 |
showClear | Toggle whether to show clear button | boolean | false | 0.35.0 |
showNext | Set the way to expand the Dropdown submenu, one of: click 、hover | string | click | 1.29.0 |
showRestTagsPopover | When the number of tags exceeds maxTagCount and hover reaches +N, whether to display the remaining content through Popover | boolean | false | 1.28.0 |
size | Selectbox size, one of large , small , default | string | default | - |
stopPropagation | Whether to prevent the click event on the dropdown box from bubbling | boolean | true | - |
disableStrictly | Set 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 parent | boolean | false | 1.32.0 |
style | Inline style | CSSProperties | - | - |
suffix | Suffix label | ReactNode | - | 0.28.0 |
topSlot | top slot | ReactNode | - | 1.27.0 |
treeData | Render data. Refer to CascaderData for detailed formatting. | CascaderData[] | [] | - |
treeNodeFilterProp | When searching, the input item filters the corresponding CascaderData property. | string | label | - |
triggerRender | Method to create a custom trigger | (props: TriggerRenderProps) => ReactNode | - | 0.34.0 |
value | Selected value (controlled mode) | string|number|CascaderData|(string|number|CascaderData)[][] | - | - |
validateStatus | The validation status of the trigger only affects the display style. Optional: default、error、warning | string | default | - |
virtualizeInSearch | Search result list virtualization, used when there are a large number of tree nodes, composed of height, width,itemSize | Object | - | - |
zIndex | zIndex for dropdown menu | number | 1030 | - |
enableLeafClick | Multiple mode, click the leaf option enable trigger check | boolean | false | 2.2.0 |
onBlur | Out of focus Cascader's callback | (e: MouseEvent) => void | - | - |
onChange | Callback function when the tree node is selected | (value: string|number|CascaderData|(string|number|CascaderData)[]) => void | - | - |
onClear | When showClear is true, click the clear button to trigger the callback | () => void | - | 1.29.0 |
onChangeWithObject | Toggle whether to return all properties in an option as a return value. When set to true, return value looks like CascaderData. For controlled mode, you need to pass CascaderData to value correspondingly. DefaultValue similarly. | boolean | false | 1.16.0 |
onDropdownVisibleChange | Callback function when dropdown menu visibility changes | (visible: boolean) => void | - | 0.35.0 |
onExceed | When multiple selections are made, the callback triggered after max is exceeded | (checkedItem: Entity[]) => void | - | 1.28.0 |
onFocus | Focus on Cascader's callback | (e: MouseEvent) => void | - | - |
onListScroll | Callback function when panel list scroll | (e: React.Event, panel: { panelIndex: number; activeNode: CascaderData; } ) => void | - | 1.15.0 |
onLoad | Callback function when a node is loaded | (newLoadedKeys: Set< string >, data: CascaderData) => void | - | 1.8.0 |
onSearch | Callback function when the values for search input changes | (value: string) => void | - | - |
onSelect | Callback function when selected | (value: string | number | (string | number)[]) => void | - | - |
CascaderData
Properties | Instructions | type | Default |
---|---|---|---|
children | children node | CascaderData[] | - |
disabled | Disabled status >=0.35.0 | boolean | - |
isLeaf | leaf node | boolean | - |
label | Text to be displayed (required) | ReactNode | - |
loading | loading | boolean | - |
value | Value property (required) | string|number | - |
Methods
Some internal methods provided by Select can be accessed through ref:
Method | Instructions | Version |
---|---|---|
close | Manually close dropdown list | v2.30.0 |
open | Manually open dropdown list | v2.30.0 |
focus | Manually focus | v2.34.0 |
blur | Manually blur | v2.34.0 |
search(value: string) | To manually trigger the search, you need to set filterTreeNode to enable search, and searchPosition to custom to customize the display search box. | v2.54.0 |
Accessibility
ARIA
- 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