Cascader

Usage scenarios

Differences from TreeSelect component:

TreeSelect: The core value lies in target node. The structure is to facilitate users to quickly filter out target options. The final node is what the user wants. It is commonly used in file/folder selection, organizational structure, permission allocation and other scenarios.
Cascader: The core selection value lies in the path. What the user selects is not an isolated point, but a complete path from root to leaf, which is often used in scenarios such as geographical location and product classification.

Demos

How to import

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';
</script>

Basic Usage

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

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader placeholder="请选择所在地区" style="width: 300px" {treeData} />

Multiple

Set multiple to make multiple selections.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    // Cascader has no defaultValue: bind a state seeded with the initial selection
    let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader bind:value multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />

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. The label is text only, and search still matches the label text when you customize the node content with the label snippet. To match other text, store it in another field in treeData and specify the field 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.

filterLeafOnly=false:

Label 为自定义节点，指定其他属性进行搜索

Code

<script lang="ts">
    import { IconMapPinStroked } from '@fibrae/semi-icons-svelte';
    import { Cascader, TypographyTitle } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];

    // The label snippet adds a decorative icon in the columns; labelText holds the text that search matches
    const labelNodeTreeData = [
        {
            label: '浙江省',
            labelText: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    labelText: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', labelText: '西湖区', value: 'xihu' },
                        { label: '萧山区', labelText: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', labelText: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    labelText: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', labelText: '海曙区', value: 'haishu' },
                        { label: '江北区', labelText: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<div>
    <Cascader filterTreeNode placeholder="默认对label值进行搜索" style="width: 300px" {treeData} />
    <br />
    <br />
    <Cascader filterTreeNode placeholder="对value值进行搜索" style="width: 300px" {treeData} treeNodeFilterProp="value" />
    <br />
    <br />
    <TypographyTitle heading={6}>filterLeafOnly=false:</TypographyTitle>
    <Cascader filterLeafOnly={false} filterTreeNode placeholder="filterLeafOnly=false" style="width: 300px" {treeData} />
    <br />
    <br />
    <TypographyTitle heading={6}>Label 为自定义节点，指定其他属性进行搜索</TypographyTitle>
    <Cascader displayProp="labelText" filterTreeNode placeholder="Search for labelText" style="width: 300px" treeData={labelNodeTreeData} treeNodeFilterProp="labelText">
        {#snippet label({ item })}
            <span style="display: inline-flex; align-items: center; column-gap: 4px">
                <IconMapPinStroked />
                {item.label}
            </span>
        {/snippet}
    </Cascader>
</div>

Searchable Multiple Selection

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.

海曙区

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'haishu']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader bind:value filterTreeNode multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />

Filtered data can be sorted using filterSorter.

Code

<script lang="ts">
    import { Cascader, type CascaderProps } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: 'Product',
            value: 'Product',
            children: [
                { label: 'Semi-Material', value: 'Semi-Material' },
                { label: 'Semi-DSM', value: 'Semi-DSM' },
                { label: 'Semi', value: 'Semi' },
                { label: 'Semi-C2D', value: 'Semi-C2D' },
                { label: 'Semi-D2C', value: 'Semi-D2C' },
            ],
        },
    ];

    // The sorter receives the two result paths, so compare their last nodes
    const filterSorter: CascaderProps['filterSorter'] = (first, second, inputValue) => {
        const firstData = first[first.length - 1];
        const lastData = second[second.length - 1];
        if (firstData.label === inputValue) {
            return -1;
        } else if (lastData.label === inputValue) {
            return 1;
        } else {
            return firstData.label < lastData.label ? -1 : 1;
        }
    };
</script>

<div>
    <Cascader {filterSorter} filterTreeNode placeholder="输入 s 查看排序效果" style="width: 300px" {treeData} />
</div>

If you want to customize the rendering options after the search, you can use the filterItem snippet to achieve custom rendering of the entire line. The snippet parameter has the type CascaderFilterItemSnippetProps:

interface CascaderFilterItemSnippetProps {
    props: CascaderFilterItemDomProps; // The id, role, aria-selected, class and click handler of the option, spread it on the root element of the snippet
    inputValue: string; // Search bar search content
    disabled: boolean; // Whether to disable
    data: CascaderData[]; // Search result data, the nodes on this path
    selected: boolean; // Selected state when single selection
    checkStatus: {
        // Checked state when multiple selection
        checked: boolean;
        halfChecked: boolean;
    };
    onCheck: (event: CheckboxEvent) => void; // Check the option in multiple selection, bind it to the onChange of Checkbox
}

Spread props on the root element (such as <li {...props}>), and clicking the row selects it in single selection. When virtualizeInSearch is on, props.style is the positioning style of the row; join your own style to it instead of overriding it.

The example is as follows

鼠标 hover 到选项可查看被省略文本完整内容

Code

<script lang="ts">
    import { Cascader, Checkbox, TypographyText, type CascaderData, type TypographyEllipsis } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: 'Semi',
            value: 'Semi',
            children: [
                {
                    label: 'Semi-Material Semi-Material Semi-Material Semi-Material',
                    value: 'Semi-Material',
                },
                {
                    label: 'Semi-DSM Semi-DSM Semi-DSM Semi-DSM',
                    value: 'Semi-DSM',
                },
                {
                    label: 'Semi Design Semi Design Semi Design Semi Design',
                    value: 'Semi',
                },
                {
                    label: 'Semi-C2D Semi-C2D Semi-C2D Semi-C2D Semi-C2D',
                    value: 'Semi-C2D',
                },
                {
                    label: 'Semi-D2C Semi-D2C Semi-D2C Semi-D2C Semi-D2C ',
                    value: 'Semi-D2C',
                },
            ],
        },
    ];
    const ellipsis: TypographyEllipsis = { showTooltip: { opts: { style: 'word-break: break-all' } } };
    const pathLabel = (data: CascaderData[]) => data.map((item) => item.label).join(' / ');
</script>

<div>
    <p>鼠标 hover 到选项可查看被省略文本完整内容</p>
    <br />
    <Cascader filterTreeNode placeholder="单选，输入 s 自定义搜索选项渲染结果" style="width: 320px" {treeData}>
        {#snippet filterItem({ props, data, selected })}
            <li {...props} style="justify-content: flex-start">
                <TypographyText {ellipsis} style={`width: 270px; ${selected ? 'color: var(--semi-color-primary)' : ''}`}>
                    {pathLabel(data)}
                </TypographyText>
            </li>
        {/snippet}
    </Cascader>
    <br />
    <Cascader filterTreeNode multiple placeholder="多选，输入 s 自定义搜索选项渲染结果" style="width: 320px; margin-top: 20px" {treeData}>
        {#snippet filterItem({ props, data, checkStatus, onCheck })}
            <li {...props} aria-label={pathLabel(data)} style="justify-content: flex-start">
                <Checkbox checked={checkStatus.checked} indeterminate={checkStatus.halfChecked} onChange={onCheck} tabindex={-1}>
                    <TypographyText {ellipsis} style="width: 250px">
                        {pathLabel(data)}
                    </TypographyText>
                </Checkbox>
            </li>
        {/snippet}
    </Cascader>
</div>

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 is an object containing the following values:

height: Option list height in px (number), default 180, the same as the dropdown height
width: Option list width value
itemSize: The height of each row of Option

Code

<script lang="ts">
    import { Cascader, Checkbox, TypographyText, type TypographyEllipsis } from '@fibrae/semi-ui-svelte';

    const treeData = ['通用', '场景'].map((label, m) => ({
        label,
        value: m,
        children: Array.from({ length: 100 }, (_item, n) => ({
            value: `${m}-${n}`,
            label: `${m}-${n} 第二级`,
            children: Array.from({ length: 20 }, (_item, o) => ({
                value: `${m}-${n}-${o}`,
                label: `${m}-${n}-${o} 第三级详细内容`,
            })),
        })),
    }));

    const virtualize = {
        // Height = default panel 180px minus 2 * 8px padding
        height: 172,
        width: 320,
        itemSize: 36,
    };
    const ellipsis: TypographyEllipsis = { showTooltip: { opts: { style: 'word-break: break-all' } } };
</script>

<Cascader filterTreeNode multiple placeholder="输入 通用 or 场景 进行搜索" style="width: 320px" {treeData} virtualizeInSearch={virtualize}>
    {#snippet filterItem({ props, data, onCheck, checkStatus })}
        <div {...props} style={`${props.style ?? ''}; justify-content: start; padding: 8px 16px 8px 12px; box-sizing: border-box`}>
            <Checkbox checked={checkStatus.checked} indeterminate={checkStatus.halfChecked} onChange={onCheck} style="margin-right: 8px" />
            <TypographyText {ellipsis} style="max-width: 260px">
                {data.map((item) => item.label).join(' | ')}
            </TypographyText>
        </div>
    {/snippet}
</Cascader>

Limit Tags Displayed

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.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([
        ['zhejiang', 'ningbo', 'haishu'],
        ['zhejiang', 'hangzhou', 'xihu'],
    ]);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
    const restTagsPopoverProps = { position: 'top' } as const;
</script>

<Cascader bind:value maxTagCount={1} multiple placeholder="请选择所在地区" {restTagsPopoverProps} showRestTagsPopover style="width: 300px" {treeData} />

Limit Tags Number

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.

Code

<script lang="ts">
    import { Cascader, Toast, type CascaderEntity, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([['zhejiang', 'ningbo', 'haishu']]);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];

    const onExceed = (checked: CascaderEntity[]) => {
        Toast.warning('exceed max');
        console.log(checked);
    };
</script>

<Cascader bind:value max={1} multiple {onExceed} placeholder="请选择所在地区" style="width: 300px" {treeData} />

Change on Select

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

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<div>
    <Cascader changeOnSelect placeholder="选择即改变" style="width: 300px" {treeData} />
    <br />
    <br />
    <Cascader changeOnSelect filterTreeNode placeholder="可搜索的选择即改变" style="width: 300px" {treeData} />
</div>

Custom Display Property

Set displayProp to select which property in the data you would like to display. By default, label is displayed.

单选

多选

Code

<script lang="ts">
    import { Cascader, TypographyTitle, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let single = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
    let multiple = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<TypographyTitle heading={6}>单选</TypographyTitle>
<Cascader bind:value={single} displayProp="value" placeholder="回填时显示数据的value值" style="width: 300px" {treeData} />
<br />
<br />
<TypographyTitle heading={6}>多选</TypographyTitle>
<Cascader bind:value={multiple} displayProp="value" multiple placeholder="回填时显示数据的value值" style="width: 300px" {treeData} />

displayRender is split into two snippets.

When single selection (multiple is false), use the display snippet to set the displayed content. Its parameter is { labels, path }, where labels holds the displayProp of each node on the path and path holds the nodes on the path (the raw values when the value is not in treeData, as in the parameter of onChange with onChangeWithObject); empty snippet content shows the placeholder.

When multiple selection (multiple is true), use the tag snippet to replace each tag. Its parameter is { entity, index, disabled, onClose }, where entity is the relevant data of the node and onClose unchecks the node; bind it to your own Tag when you need a close button. It works in searchable multiple selection too. The type of entity is CascaderEntity, as follows:

interface Entity {
    children?: Entity[]; // children list
    data: CascaderData; // treedata
    ind: number; // index
    key: string; // key
    level: number; // node level
    parent?: Entity; // parent data
    parentKey?: string; // parent key
    path: string[]; // key path
    pos: string; // position of the node in treeData, such as '0-0-1'
    valuePath: string[]; // value path
}

The label of a data item is text only. To render custom content in an option of the columns, use the label snippet with the parameter { item }, where item is the data of the node; the search results, the selection and the tags still show the text of the node.

单选

多选

Code

<script lang="ts">
    import { Cascader, Tag, TypographyTitle, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let single = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);
    let multiple = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<TypographyTitle heading={6}>单选</TypographyTitle>
<Cascader bind:value={single} placeholder="自定义回填时显示数据的格式" style="width: 300px" {treeData}>
    {#snippet display({ labels })}
        已选择：{labels.join(' -> ')}
    {/snippet}
</Cascader>
<br />
<br />
<TypographyTitle heading={6}>多选</TypographyTitle>
<Cascader bind:value={multiple} multiple placeholder="自定义回填时显示数据的格式" style="width: 300px" {treeData}>
    {#snippet tag({ entity })}
        <Tag color="white" style="margin-right: 4px">{entity.data.label}</Tag>
    {/snippet}
</Cascader>

Custom Separator

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.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>(['zhejiang', 'ningbo', 'jiangbei']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader bind:value filterTreeNode separator=" > " style="width: 300px" {treeData} />

Disabled

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>(['zhejiang', 'hangzhou', 'xihu']);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
            ],
        },
    ];
</script>

<div>
    <Cascader disabled placeholder="请选择所在地区" style="width: 300px" {treeData} />
    <br />
    <br />
    <Cascader bind:value disabled filterTreeNode placeholder="请选择所在地区" style="width: 300px" {treeData} />
</div>

Disable Strictly

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 "宁波市" is strictly disabled. Therefore, when we change the selected state of its parent node "浙江省", it will not affect the selected state of the node "宁波市".

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    disabled: true,
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader disableStrictly multiple placeholder="请选择所在地区" style="width: 300px" {treeData} />

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

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader placeholder="请选择所在地区" showNext="hover" style="width: 300px" {treeData} />

Click to Select

In multiple mode, clicking on non-leaf nodes does not trigger selection by default. You can use clickToSelect to enable selecting any node on click.

This API is especially useful when combined with showNext="hover": hovering expands the submenu, while clicking selects the current node.

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [{ label: '海曙区', value: 'haishu' }],
                },
            ],
        },
    ];
</script>

<Cascader clickToSelect multiple placeholder="请选择所在地区" showNext="hover" style="width: 300px" {treeData} />

Additional items

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

Code

<script lang="ts">
    import { Cascader, TypographyText } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader placeholder="请选择所在地区" style="width: 300px" {treeData}>
    {#snippet bottomSlot()}
        <div style="height: 36px; display: flex; padding: 0 32px; align-items: center; cursor: pointer; border-top: 1px solid var(--semi-color-border)">
            <TypographyText>找不到相关选项？</TypographyText>
            <TypographyText link>去新建</TypographyText>
        </div>
    {/snippet}
</Cascader>

Controlled Component

Bind value with bind:value to use Cascader as a controlled component; onChange is still called. The Svelte Cascader has no defaultValue: to start with a selection, bind a $state that holds it, and leave value unbound for an uncontrolled Cascader; bind:value={get, set} makes it fully controlled.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([]);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader bind:value placeholder="请选择所在地区" style="width: 300px" {treeData} />

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.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([]);

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader autoMergeValue={false} bind:value multiple placeholder="autoMergeValue 为 false" style="width: 300px" {treeData} />

Leaf Only

In multiple selection, you can set the value to include only leaf nodes by turning on leafOnly, that is, the displayed Tag and the value of bind:value and onChange only include leaf nodes.

Code

<script lang="ts">
    import { Cascader, type CascaderChangeValue, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([]);

    const onChange = (v: CascaderChangeValue) => {
        console.log(v);
    };

    const treeData = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader bind:value leafOnly multiple {onChange} placeholder="开启 leafOnly" style="width: 300px" {treeData} />

Checked RelationShip

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.

Code

<script lang="ts">
    import { Cascader, type CascaderValue } from '@fibrae/semi-ui-svelte';

    let value = $state<CascaderValue>([['Asia'], ['Asia', 'China', 'Beijing']]);

    const treeData = [
        {
            label: '亚洲',
            value: 'Asia',
            children: [
                {
                    label: '中国',
                    value: 'China',
                    children: [
                        { label: '北京', value: 'Beijing' },
                        { label: '上海', value: 'Shanghai' },
                    ],
                },
            ],
        },
        {
            label: '北美洲',
            value: 'North America',
        },
    ];
</script>

<Cascader bind:value checkRelation="unRelated" multiple style="width: 300px" {treeData} />

Dynamic Update of Data

treeData can be replaced as a whole or changed in place in $state data (such as push, or assigning children); both are noticed and recalculated, and a new array with equal content keeps the expanded and selected state.

Code

<script lang="ts">
    import { Button, Cascader, type CascaderData } from '@fibrae/semi-ui-svelte';

    let treeData = $state<CascaderData[]>([]);

    const add = () => {
        const itemLength = Math.floor(Math.random() * 3) + 1;
        treeData = Array.from({ length: itemLength }, (_, i) => {
            const length = Math.floor(Math.random() * 3);
            const children = Array.from({ length }, (_, ci) => ({
                key: `${i}-${ci}`,
                label: `Item-${i}-${ci}`,
                value: `${i}-${ci}`,
            }));
            return {
                key: `${i}`,
                label: `Item-${i}`,
                value: `${i}`,
                children,
            };
        });
    };
</script>

<Cascader placeholder="请选择" style="width: 300px" {treeData} />
<br />
<br />
<Button onclick={add}>动态改变数据</Button>

Load Async Data

You could use loadData to load data asynchronously.

Could not be used together with searching

Code

<script lang="ts">
    import { Cascader, type CascaderData } from '@fibrae/semi-ui-svelte';

    let treeData = $state<CascaderData[]>([
        { label: 'Node1', value: '0-0' },
        { label: 'Node2', value: '0-1' },
        { label: 'Node3', value: '0-2', isLeaf: true },
    ]);

    const updateTreeData = (list: CascaderData[], value: CascaderData['value'], children: CascaderData[]): CascaderData[] =>
        list.map((node) => {
            if (node.value === value) {
                return { ...node, children };
            }
            if (node.children) {
                return { ...node, children: updateTreeData(node.children, value, children) };
            }
            return node;
        });

    const loadData = (selectedOpt: CascaderData[]) => {
        const targetOpt = selectedOpt[selectedOpt.length - 1];
        const { label, value } = targetOpt;
        return new Promise<void>((resolve) => {
            if (targetOpt.children) {
                resolve();
                return;
            }

            setTimeout(() => {
                treeData = updateTreeData(treeData, value, [
                    {
                        label: `${label} - 1`,
                        value: `${label}-1`,
                        isLeaf: selectedOpt.length > 1,
                    },
                    {
                        label: `${label} - 2`,
                        value: `${label}-2`,
                        isLeaf: selectedOpt.length > 1,
                    },
                ]);
                resolve();
            }, 1000);
        });
    };
</script>

<Cascader {loadData} placeholder="Please select" style="width: 300px" {treeData} />

Remote Search

Cascader supports remote search. With remote enabled, search input no longer goes through local filtering; only the onSearch callback is called, and you are responsible for fetching treeData asynchronously based on the input. This mirrors Select's remote behavior.

Code

<script lang="ts">
    import { debounce } from 'es-toolkit';
    import { Cascader, Spin, type CascaderData } from '@fibrae/semi-ui-svelte';

    const fetchByKeyword = (keyword: string) =>
        new Promise<CascaderData[]>((resolve) => {
            const delay = 200 + Math.floor(Math.random() * 800);
            setTimeout(() => {
                if (!keyword) {
                    resolve([]);
                    return;
                }
                resolve([
                    { label: `${keyword} - 选项 A`, value: `${keyword}-a` },
                    { label: `${keyword} - 选项 B`, value: `${keyword}-b` },
                    { label: `${keyword} - 选项 C`, value: `${keyword}-c` },
                ]);
            }, delay);
        });

    let treeData = $state<CascaderData[]>([]);
    let loading = $state(false);

    let latestToken = 0;
    const onSearch = debounce((input: string) => {
        if (!input) {
            treeData = [];
            loading = false;
            return;
        }
        latestToken += 1;
        const token = latestToken;
        loading = true;
        void fetchByKeyword(input).then((next) => {
            // Drop stale results that arrive after a newer request
            if (token !== latestToken) {
                return;
            }
            treeData = next;
            loading = false;
        });
    }, 300);
</script>

<Spin spinning={loading}>
    <Cascader filterTreeNode onChange={(v) => console.log('selected:', v)} {onSearch} placeholder="输入关键词远程搜索" remote style="width: 300px" {treeData} />
</Spin>

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)

Code

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    const treeData = [
        {
            label: 'A',
            value: 'A',
            children: [
                {
                    label: 'B',
                    value: 'B',
                    children: [
                        {
                            label: 'C',
                            value: 'C',
                            children: [
                                {
                                    label: 'D',
                                    value: 'D',
                                    children: [
                                        {
                                            label: 'E',
                                            value: 'E',
                                            children: [{ label: 'F', value: 'F' }],
                                        },
                                    ],
                                },
                            ],
                        },
                    ],
                },
            ],
        },
    ];
</script>

<Cascader dropdownClassName="components-cascader-demo" placeholder="请选择所在地区" style="width: 300px" {treeData} />

.components-cascader-demo {
    .semi-cascader-option-lists {
        max-width: 510px;
        overflow-x: auto;
    }
}

Custom Trigger

If the default trigger style cannot meet your needs, you can use the trigger snippet to customize the display of the select box.

The snippet parameter of trigger has the type CascaderTriggerSnippetProps, as follows:

interface CascaderTriggerSnippetProps {
    /**
     * The hierarchical position of the selected node in treeData,
     *  as in the following example, when "浙江省-杭州市-萧山区" is
     *  selected, the value here is '0-0-1'; a Set<string> in multiple mode
     */
    value: string | Set<string> | undefined;
    /* The search text while open; while a searchable single Cascader is closed, the display text of the selected path */
    inputValue: string;
    /* Placeholder of Cascader */
    placeholder?: string;
    /* Whether to disable Cascader */
    disabled: boolean;
    /**
     * The function used to update the value of the input box. You
     *  should call this function when the value of the Input component
     *  customized by trigger is updated to synchronize the
     *  state with Cascader, you need to set the filterTreeNode parameter
     *  to non-false when use it
     */
    onSearch: (inputValue: string) => void;
    /* Function to clear the value; pass the click event when it is bound to a control inside the trigger, so the click does not open the dropdown */
    onClear: (event?: MouseEvent) => void;
    /* Used to delete a single item, the input parameter is the hierarchical
     * position of the node in treeData (the same format as value)
     */
    onRemove: (pos: string) => void;
}

Code

<script lang="ts">
    import { IconChevronDown, IconClose } from '@fibrae/semi-icons-svelte';
    import { Button, ButtonGroup, Cascader, Tag, TagInput, type CascaderData } from '@fibrae/semi-ui-svelte';

    const treeData: CascaderData[] = [
        {
            label: '浙江省',
            value: 'zhejiang',
            children: [
                {
                    label: '杭州市',
                    value: 'hangzhou',
                    children: [
                        { label: '西湖区', value: 'xihu' },
                        { label: '萧山区', value: 'xiaoshan' },
                        { label: '临安区', value: 'linan' },
                    ],
                },
                {
                    label: '宁波市',
                    value: 'ningbo',
                    children: [
                        { label: '海曙区', value: 'haishu' },
                        { label: '江北区', value: 'jiangbei' },
                    ],
                },
            ],
        },
    ];

    const getLabelFromValue = (value: string) => {
        const [first, ...rest] = value.split('-').map((item) => Number(item));
        let node: CascaderData | undefined = treeData[first];
        rest.forEach((item) => {
            node = node?.children?.[item];
        });
        return node?.label;
    };
</script>

{#snippet chevron()}
    <IconChevronDown />
{/snippet}

{#snippet close()}
    <IconClose />
{/snippet}

<Cascader placeholder="Custom Trigger" {treeData}>
    {#snippet trigger({ value, placeholder, onClear })}
        <!-- The clear button is a sibling of the trigger button: buttons cannot nest -->
        <ButtonGroup theme="light">
            <Button icon={chevron} iconPosition="right">
                {value ? getLabelFromValue(value as string) : placeholder}
            </Button>
            {#if value}
                <Button
                    aria-label="清除"
                    icon={close}
                    onclick={(event) => {
                        event.stopPropagation();
                        onClear(event);
                    }}
                />
            {/if}
        </ButtonGroup>
    {/snippet}
</Cascader>
<br />
<Cascader filterTreeNode multiple placeholder="Custom Trigger" style="width: 300px" {treeData}>
    {#snippet trigger({ value, onSearch, onRemove })}
        <TagInput onInputChange={onSearch} value={Array.from(value as Set<string>)}>
            {#snippet tag({ value: pos })}
                <Tag
                    closable
                    onClose={(event) => {
                        event.preventDefault();
                        onRemove(pos);
                    }}
                    style="margin-left: 2px"
                    tagKey={pos}
                >
                    {getLabelFromValue(pos)}
                </Tag>
            {/snippet}
        </TagInput>
    {/snippet}
</Cascader>

API reference

Props

Property	Description	Type	Default
arrowIcon	Custom dropdown arrow on the right; null hides the arrow. Hovering shows the clear button first when it is visible.	`Snippet \| null`	-
autoAdjustOverflow	Whether the dropdown flips its direction when an edge covers it.	`boolean`	-
autoMergeValue	In multiple mode, the value leaves out the descendants of a selected parent. Changes after mount are not followed; leafOnly takes precedence when both are on.	`boolean`	`true`
borderless	Whether to use the borderless style.	`boolean`	`false`
bottomSlot	Extra content at the bottom of the dropdown.	`Snippet`	-
changeOnSelect	Whether a non-leaf node can be selected in single mode.	`boolean`	`false`
checkRelation	In multiple mode, how the checked states of the nodes relate: related links parents and children, unRelated keeps them independent.	`'related' \| 'unRelated'`	`"related"`
clearIcon	Custom icon of the clear button, effective when showClear is true; empty content keeps the default icon.	`Snippet`	-
clickToSelect	In multiple mode, clicking any node selects it. Often used with showNext set to hover: hovering expands the submenu and clicking selects the node.	`boolean`	`false`
defaultOpen	Whether the dropdown is open on mount.	`boolean`	`false`
disabled	Whether the Cascader is disabled. A disabled Cascader cannot be reached with Tab.	`boolean`	-
disableStrictly	Whether to disable strictly. A disabled node then does not change when its parent or children are checked or unchecked.	`boolean`	`false`
display	The selected path shown in single mode, with `{ labels, path }`: `labels` holds the displayProp of each node and `path` the nodes, or the raw values when the value is not in treeData. Empty content shows the placeholder.	`Type`	-
displayProp	The node field shown in the trigger and the tags, label by default.	`string`	`"label"`
dropdownClassName	Class of the dropdown.	`string`	-
dropdownStyle	Style of the dropdown, as a CSS string.	`string`	-
emptyContent	Content shown when there is no data to pick or the search has no result. The default text from the locale shows when it is not given, and null hides the empty state.	`Snippet \| null`	-
enableLeafClick	In multiple mode, whether clicking the option of a leaf node checks it.	`boolean`	`false`
expandIcon	Custom expand icon; empty content keeps the default icon.	`Snippet`	-
filterItem	Replaces a row of the search results, with `{ props, inputValue, disabled, data, checkStatus, selected, onCheck }`; spread `props` on the root element of the row.	`Type`	-
filterLeafOnly	Whether the search results only show the paths of leaf nodes.	`boolean`	`true`
filterSorter	Sorts the filtered results; it receives the two result paths (the node arrays from the root to the matched node) and the input.	`Type`	-
filterTreeNode	Whether search is on. True matches the input against the field named by treeNodeFilterProp, case-insensitively; a custom match function can be given instead.	`Type`	`false`
insetLabel	A label inside the select box; it is not rendered when prefix is also given.	`Snippet`	-
insetLabelId	The id of the insetLabel content, used to name the combobox; the component generates one when the insetLabel snippet is used and this is not given.	`string`	-
keyMaps	Custom field names for value, label, children, disabled and isLeaf in a node.	`CascaderKeyMapProps`	-
label	Content of an option in the columns, with `{ item }`; the search results, the selection and the tags still show the text of the node.	`Type`	-
leafOnly	In multiple mode, the value and the tags shown only include leaf nodes. Changes after mount are not followed.	`boolean`	`false`
loadData	Loads data asynchronously. It receives the path from the root to the current node and must return a Promise; after a rejection the node leaves the loading state and can be expanded again. Cannot be used with search.	`Type`	-
max	In multiple mode, the most paths that can be selected; exceeding it calls onExceed.	`number`	-
maxTagCount	In multiple mode, the most tags shown; the rest appear as +N.	`number`	-
motion	Whether the dropdown animates.	`boolean`	`true`
multiple	Whether several paths can be selected. It has no global default.	`boolean`	`false`
onBlur	Called when the dropdown closes: a MouseEvent for a click outside, a KeyboardEvent for Esc, undefined when the close method closes it. It is not a DOM blur event.	`Type`	-
onChange	Called when the selection changes. In single mode the selected path, in multiple mode an array of the selected paths; node data with onChangeWithObject.	`Type`	-
onChangeWithObject	Whether onChange carries the data of each node instead of its value. A bound value must then be node data too, with a value. This is a boolean attribute, not a callback.	`boolean`	`false`
onClear	Called when the clear button clears the selection.	`Type`	-
onDropdownVisibleChange	Called when the dropdown opens or closes, with whether it is open.	`Type`	-
onExceed	Called in multiple mode when the selection goes past max, with the Entity array of the checked nodes.	`Type`	-
onFocus	Called when a click or a key opens the dropdown, with that MouseEvent or KeyboardEvent. It is not a DOM focus event and Tabbing in or out does not call it.	`Type`	-
onKeyDown	Called once per key press before the Cascader handles it; calling preventDefault there does not stop the Cascader. Except for a key on the clear button or a control inside a custom trigger, it is reported in the capture phase on the trigger, so stopPropagation there keeps the key from the search input and skips the trigger's handling of it (opening the dropdown, closing it on Esc); the options still take it.	`Type`	-
onListScroll	Called when a column of the tree scrolls, with the scroll event and the column. Scrolling the search results does not call it.	`Type`	-
onLoad	Called when a node has loaded, with the set of loaded keys and the node data.	`Type`	-
onSearch	Called when the search input changes, with the text.	`Type`	-
onSelect	Called when a node is selected, with the value of the node. In multiple mode, one checked node gives its value and more give an array.	`Type`	-
placeholder	Placeholder of the select box.	`string`	-
position	Direction of the dropdown, bottomLeft by default and bottomRight in RTL.	`Position`	-
prefix	Prefix content.	`Snippet`	-
preventScroll	Whether focusing inside the component stops the browser scrolling the document to show the focused element.	`boolean`	-
remote	Whether to search remotely. Input is then not filtered locally and only calls onSearch, and the caller updates treeData asynchronously.	`boolean`	`false`
restTagsPopoverProps	Configuration of the Popover of the remaining tags, such as position and trigger. See Popover.	`Type`	-
searchPlaceholder	Placeholder of the search input; placeholder is used when it is not given.	`string`	-
searchPosition	Where the search input is: trigger puts it in the trigger, custom leaves it to the caller.	`'trigger' \| 'custom'`	`"trigger"`
separator	The separator of a path in the search results and in the trigger in single mode.	`string`	`" / "`
showClear	Whether to show the clear button.	`boolean`	`false`
showNext	When the submenu expands: on click or on hover.	`'click' \| 'hover'`	`"click"`
showRestTagsPopover	Whether hovering +N shows the remaining tags in a Popover once maxTagCount is exceeded.	`boolean`	`false`
size	Size of the select box.	`CascaderSize`	-
stopPropagation	Whether clicks on the dropdown stop bubbling.	`boolean \| string`	`true`
suffix	Suffix content.	`Snippet`	-
tag	Replaces each tag in multiple mode, with `{ entity, index, disabled, onClose }`; `onClose` unchecks the node.	`Type`	-
topSlot	Extra content at the top of the dropdown.	`Snippet`	-
treeData	Node data. The label is text only, use the label snippet for node content. Changes made in place to $state data are noticed, and a new array with equal content keeps the expanded and selected state.	`CascaderData[]`	`[]`
treeNodeFilterProp	The node field matched against the search input, label by default.	`string`	`"label"`
trigger	Replaces the content of the trigger, with `{ value, inputValue, placeholder, disabled, onSearch, onClear, onRemove }`.	`Type`	-
validateStatus	Validation status of the trigger; it only affects the style.	`ValidateStatus`	-
value	The selected entry, bound with bind:value. Leave it out for an uncontrolled Cascader; to start with a selection, bind a $state that holds it. `bind:value={get, set}` makes it fully controlled. In single mode it is a node or a path, in multiple mode it can also be an array of paths.	`CascaderValue`	-
virtualizeInSearch	Virtual list configuration of the search results, made of height, width and itemSize, for large result sets; height defaults to 180, the same as the dropdown height.	`CascaderVirtualize`	-

Methods

Method	Description	Type
blur	Blurs the trigger or the search input.	`Type`
close	Closes the dropdown.	`Type`
focus	Focuses the trigger or the search input.	`Type`
open	Opens the dropdown.	`Type`
search	Searches as if the keyword were typed; filterTreeNode must be set to turn search on.	`Type`

Cascader puts class, style and undeclared native attributes on the root element (the trigger), and aria-label, aria-labelledby, aria-describedby, aria-errormessage, aria-invalid and aria-required on the current combobox (see ARIA). onChange, onSelect, onFocus, onBlur and onKeyDown are component callbacks and hide the native events of the same name on the root element; onFocus and onBlur are called when the dropdown opens and closes, they are not DOM focus events. style and dropdownStyle are CSS strings.

CascaderData

Properties	Instructions	type	Default
children	children node	CascaderData[]	-
disabled	Disabled status	boolean	-
isLeaf	leaf node	boolean	-
label	Text to be displayed (required), use the `label` snippet for custom content	string\|number	-
loading	loading	boolean	-
value	Value property (required)	string\|number	-

Methods

Cascader exposes open(), close(), focus(), blur() and search(value) through export function; call them on the instance from bind:this. search searches as if the value were typed; set filterTreeNode to enable search, and searchPosition to custom to customize the display search box.

<script lang="ts">
    import { Cascader } from '@fibrae/semi-ui-svelte';

    let cascader = $state<Cascader>();
</script>

<Cascader bind:this={cascader} {treeData} />
<button onclick={() => cascader?.open()}>Open</button>

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;

These aria-* attributes fall on the current combobox: the root element (the trigger) without search, the search input with search, and the tag input in multiple mode when the search input is in the trigger;

The combobox takes its name from, in order: aria-labelledby, aria-label, the rendered insetLabel (the combobox's aria-labelledby points at it, with an id the component generates when insetLabelId is not given; with a prefix the insetLabel is not rendered and does not name it), and otherwise "Cascader" from the locale. The tree or the search-result listbox in the dropdown uses the same name source;
Following the ARIA 1.2 combobox pattern, exactly one element is the combobox at any time; its aria-controls points at the list in the dropdown, and the dropdown has the combobox's name. Without search the trigger is a select-only combobox and the selected path is its value; with search the input itself is the combobox, with aria-autocomplete="list", and the trigger has no role and no Tab stop. In single mode the input appears only while searching, so the trigger is the combobox otherwise; the input is empty until the user types, so the selected path is linked to it as its description with aria-describedby; picking a result returns focus to the trigger;
The columns together are one role="tree": options are treeitems with aria-level (their column), aria-setsize, aria-posinset and aria-disabled, and aria-expanded on options that can expand; a single-choice Cascader uses aria-selected, a multi-choice one uses aria-checked (mixed when half checked);

Search results are a role="listbox" of options, with aria-selected for selected, or checked in a multi-choice Cascader. The props of filterItem carry the id, role="option" and aria-selected of the option, and must be spread on the root element of the snippet;

The tick and the checkbox in front of an option only picture its state: they are hidden from screen readers and take no focus.

Keyboard Interaction

Cascader follows the WAI-ARIA Combobox pattern: focus always stays on the trigger or the search input, aria-activedescendant points at the current option, and the current option shows the focus ring. There is no current option when the dropdown opens.

While the dropdown is closed: ArrowDown, ArrowUp and Enter open it; without search, Space also opens it, and Home and End open it and move to the first or last option of the first column. With search, Space, Home and End edit the text
Enter: with a current option, act like a click on it, or check and uncheck it in a multi-choice Cascader; disabled options do not respond
ArrowDown, ArrowUp: move to the next or previous option in the current option's column (or in the search results); the first ArrowDown moves to the first option of the first column; Home, End: move to the first or last option of that column
ArrowRight: expand the current option, showing its column; once expanded, move to the first option of that column (swapped with ArrowLeft in RTL)
ArrowLeft: collapse the expanded current option; otherwise move to the parent option in the previous column
Space: with a current option, the same as Enter (it types a space in the search input)
Typing characters: while the dropdown is open, move to the next option after the current one, across the shown columns, whose label starts with the typed text, leaving the columns as they are; characters typed in quick succession form one search string. In the search input the characters are typed as text; a closed dropdown ignores them
Esc: close the dropdown

While focus is in the search input and text is typed, only ArrowDown, ArrowUp and Enter move and select; the other keys edit the text. The arrow keys only move the current option: unlike hovering, they do not expand the next column or trigger loadData, which loads when ArrowRight expands.

With showClear, a selected value or search text, and no disabled, the trigger renders a clear button. It is a native button named "Clear selection" from the locale, shown on hover, while the dropdown is open, or while focus is inside the Cascader. From the trigger or the search input, Tab moves to the clear button; Enter or Space clears, as a mouse click does, and the focus goes back to the trigger or the search input. In multiple mode Backspace in the search input also removes tags.

Content Guidelines

Selector options
- If there is no default option, use "Select" as the placeholder text
- Arrange options in alphabetical order or another logical order, so that users can find them more easily
- Write in sentence case (capitalize the first letter, lowercase the rest) and avoid ending with commas or semicolons
- Clearly express the purpose of the choice that each option represents

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$transition_duration-cascader_option-bg	var(--semi-transition_duration-none)
$transition_function-cascader_option-bg	var(--semi-transition_function-easeIn)
$transition_delay-cascader_option-bg	var(--semi-transition_delay-none)
$radius-cascader	var(--semi-border-radius-small)	级联选择触发器圆角
$radius-cascader_option_empty	var(--semi-border-radius-medium)	级联选择菜单空状态圆角
$color-cascader_default-border-default	transparent	级联选择触发器描边颜色 - 默认
$color-cascader_default-border-hover	transparent	级联选择触发器描边颜色 - 悬浮
$color-cascader_default-border-focus	var(--semi-color-focus-border)	级联选择触发器描边颜色 - 选中
$color-cascader_default-bg-default	var(--semi-color-fill-0)	级联选择触发器背景颜色 - 默认
$color-cascader_default-bg-hover	var(--semi-color-fill-1)	级联选择触发器背景颜色 - 悬浮
$color-cascader_default-bg-active	var(--semi-color-fill-2)	级联选择触发器背景颜色 - 按下
$color-cascader_option_list-border-default	var(--semi-color-fill-0)	级联选择各级菜单分割线颜色
$color-cascader_option_main-text-default	var(--semi-color-text-0)	级联选择菜单项文字颜色
$color-cascader_option-bg-hover	var(--semi-color-fill-0)	级联选择菜单项背景颜色 - 悬浮
$color-cascader_option-bg-active	var(--semi-color-fill-1)	级联选择菜单项背景颜色 - 按下
$color-cascader_option-bg-selected	var(--semi-color-primary-light-default)	级联选择菜单项背景颜色 - 命中
$color-cascader_option_disabled-text-default	var(--semi-color-disabled-text)	级联选择菜单项文字颜色 - 禁用
$color-cascader_option_disabled-bg-hover	transparent	级联选择菜禁用单项背景颜色 - 悬浮
$color-cascader_option_disabled-bg-active	transparent	级联选择菜禁用单项背景颜色 - 按下
$color-cascader_tag_disabled-bg-default	transparent	级联选择菜禁用Tag背景颜色
$color-cascader_warning-bg-default	var(--semi-color-warning-light-default)	级联选择触发器警告背景颜色
$color-cascader_warning-border-default	var(--semi-color-warning-light-default)	级联选择触发器警告描边颜色
$color-cascader_warning-bg-hover	var(--semi-color-warning-light-hover)	级联选择触发器警告背景颜色 - 悬浮
$color-cascader_warning-border-hover	var(--semi-color-warning-light-hover)	级联选择触发器警告描边颜色 - 悬浮
$color-cascader_warning-bg-focus	var(--semi-color-warning-light-default)	级联选择触发器警告背景颜色 - 选中
$color-cascader_warning-border-focus	var(--semi-color-warning)	级联选择触发器警告描边颜色 - 选中
$color-cascader_warning-bg-active	var(--semi-color-warning-light-active)	级联选择触发器警告背景颜色 - 按下
$color-cascader_warning-border-active	var(--semi-color-warning-light-active)	级联选择触发器警告描边颜色 - 按下
$color-cascader_danger-bg-default	var(--semi-color-danger-light-default)	级联选择触发器危险背景颜色
$color-cascader_danger-border-default	var(--semi-color-danger-light-default)	级联选择触发器危险描边颜色
$color-cascader_danger-bg-hover	var(--semi-color-danger-light-hover)	级联选择触发器危险背景颜色 - 悬浮
$color-cascader_danger-border-hover	var(--semi-color-danger-light-hover)	级联选择触发器危险描边颜色 - 悬浮
$color-cascader_danger-bg-focus	var(--semi-color-danger-light-default)	级联选择触发器危险背景颜色 - 选中
$color-cascader_danger-border-focus	var(--semi-color-danger)	级联选择触发器危险描边颜色 - 选中
$color-cascader_danger-bg-active	var(--semi-color-danger-light-active)	级联选择触发器危险背景颜色 - 按下
$color-cascader_danger-border-active	var(--semi-color-danger-light-active)	级联选择触发器危险描边颜色 - 按下
$color-cascader_prefix_suffix_text-default	var(--semi-color-text-2)	级联选择前后缀文字颜色
$spacing-cascader_selection-paddingLeft	12px	级联选择触发器左侧内边距 - 默认
$spacing-cascader_selection-paddingRight	12px	级联选择触发器右侧内边距 - 默认
$spacing-cascader_small_selection-paddingLeft	12px	级联选择触发器左侧内边距 - 小尺寸
$spacing-cascader_small_selection-paddingRight	12px	级联选择触发器右侧内边距 - 小尺寸
$spacing-cascader_large_selection-paddingLeft	12px	级联选择触发器左侧内边距 - 大尺寸
$spacing-cascader_large_selection-paddingRight	12px	级联选择触发器右侧内边距 - 大尺寸
$spacing-cascader_selection_multiple-paddingLeft	$spacing-extra-tight	级联选择触发器多选时左侧内边距 - 默认
$spacing-cascader_selection_multiple-paddingRight	$spacing-extra-tight	级联选择触发器多选时右侧内边距 - 默认
$spacing-cascader_small_selection_multiple-paddingLeft	$spacing-extra-tight	级联选择触发器多选时左侧内边距 - 小尺寸
$spacing-cascader_small_selection_multiple-paddingRight	$spacing-extra-tight	级联选择触发器多选时左侧内边距 - 小尺寸
$spacing-cascader_large_selection_multiple-paddingLeft	$spacing-extra-tight	级联选择触发器多选时左侧内边距 - 大尺寸
$spacing-cascader_large_selection_multiple-paddingRight	$spacing-extra-tight	级联选择触发器多选时左侧内边距 - 大尺寸
$spacing-cascader_selection_tag-marginLeft	$spacing-none	级联选择触发器多选时标签的水平左外边距
$spacing-cascader_selection_tag-marginRight	$spacing-super-tight	级联选择触发器多选时标签的水平右外边距
$spacing-cascader_selection_tag-marginY	1px	级联选择触发器多选时标签的垂直外边距
$spacing-cascader_selection_tagInput-marginLeft	-$spacing-extra-tight	级联选择触发器多选搜索时 TagInput 的左外边距
$spacing-cascader_selection_input-marginLeft	$spacing-extra-tight	级联选择触发器多选搜索时输入框的左外边距
$spacing-cascader_selection_n-marginRight	$spacing-extra-tight	超出 maxTagCount 后，+n 的右外边距
$spacing-cascader_option-icon-marginLeft	8px	级联选择菜单项图标左侧外边距
$color-cascader_selection_n-text-default	var(--semi-color-text-0)	超出 maxTagCount 后，+n 的文字默认颜色
$color-cascader_selection_n-text-disabled	var(--semi-color-disabled-text)	超出 maxTagCount 后，+n 的文字disabled颜色
$color-cascader_selection_text_inactive	var(--semi-color-text-2)	级联选择单选inpu输入框和text并存时，text颜色
$color-cascader_selection-text-default	var(--semi-color-text-0)	级联选择选中项文字颜色
$color-cascader_placeholder-text-default	var(--semi-color-text-2)	级联选择未选中项文字颜色
$color-cascader-icon-default	var(--semi-color-text-2)	级联选择触发器图标颜色 - 默认
$color-cascader-icon-hover	var(--semi-color-primary-hover)	级联选择触发器图标颜色 - 悬浮
$color-cascader-icon-active	var(--semi-color-primary-active)	级联选择触发器图标颜色 - 按下
$color-cascader_option-icon-default	$color-cascader-icon-default	级联选择菜单项图标颜色
$color-cascader_input_disabled-bg-default	var(--semi-color-disabled-fill)	级联选择禁用态背景颜色
$color-cascader_input_disabled-bg-hover	var(--semi-color-disabled-fill)	级联选择禁用态背景颜色 - 悬浮
$color-cascader_input_disabled-text-default	var(--semi-color-disabled-text)	级联选择禁用态文字颜色
$color-cascader_input_disabled-icon-default	var(--semi-color-disabled-text)	级联选择禁用态图标颜色
$color-cascader_search-border-default	var(--semi-color-fill-0)	级联选择搜索描边颜色
$color-cascader_option_empty-text-default	var(--semi-color-disabled-text)	级联选择空状态文字颜色
$color-cascader_input-bg-default	transparent	级联选择输入框背景颜色
$color-cascader_input-border-default	none	级联选择输入框描边颜色
$color-cascader_select_highlight	var(--semi-color-primary)	级联选择器搜索命中后文字高亮的颜色
$font-cascader_select-fontWeight	$font-weight-bold	级联选择菜单项字重 - 选中
$font-cascader-fontWeight	$font-weight-regular	级联选择菜单项字重 - 未选中
$font-cascader_selection_n-fontSize	$font-size-small	超出 maxTagCount 后，+n 的文字尺寸
$font-cascader_prefix_suffix_fontWeight	$font-weight-bold	级联选择 prefix/suffix 文字字重
$width-cascader-border	1px	级联选择触发器描边宽度
$width-cascader_option_list-border	1px	级联选择各级菜单分割线宽度
$width-cascader	80px	级联选择触发器最小宽度
$height-cascader_default	$height-control-default	级联选择触发器高度 - 默认
$height-cascader_small	$height-control-small	级联选择触发器高度 - 小尺寸
$height-cascader_large	$height-control-large	级联选择触发器高度 - 大尺寸
$width-cascader_hover-border	$width-cascader-border	级联选择触发器描边宽度 - 悬浮
$width-cascader_focus-border	$border-thickness-control-focus	级联选择触发器描边宽度 - 选中态
$width-cascader_search-border	1px	级联选择触搜索描边宽度
$width-cascader-icon	32px	级联选择触发器图标尺寸
$width-cascader-option-icon	16px	级联选择菜单项图标尺寸
$width-cascader_option	150px	级联选择各级菜单宽度
$height-cascader_option_list	180px	级联选择菜单高度
$height-cascader_selection_tagInput_wrapper_small	22px	级联选择多选搜索时搜索框最小高度 - 小尺寸
$height-cascader_selection_tagInput_wrapper_default	30px	级联选择多选搜索时搜索框最小高度 - 默认尺寸
$height-cascader_selection_tagInput_wrapper_large	38px	级联选择多选搜索时搜索框最小高度 - 大尺寸
$height-cascader_selection_wrapper_small	22px	级联选择单选搜索时搜索框高度 - 小尺寸
$height-cascader_selection_wrapper	30px	级联选择单选搜索时搜索框高度 - 默认尺寸
$height-cascader_selection_wrapper_large	38px	级联选择单选搜索时搜索框高度 - 大尺寸
$spacing-cascader_text-marginX	$spacing-base-tight	级联选择 prefix/suffix 文字水平内间距
$spacing-cascader_icon-marginX	$spacing-tight	级联选择 prefix/suffix 图标水平内间距
$spacing-cascader_label_checkbox-marginRight	$spacing-tight	级联选择 checkbox 的右间距
$spacing-cascader_selection_n-paddingX	$spacing-tight	级联选择 +N 的水平间距
$spacing-cascader_flatten_list-paddingRight	64px	级联选择搜索结果菜单右侧内边距
$spacing-cascader_empty_icon-marginRight	8px	级联选择搜索结果菜单
$spacing-cacader_option_list-paddingY	4px	级联选择下拉菜单列表垂直内边距
$spacing-cacader_option_list-paddingX	0px	级联选择下拉菜单列表水平内边距
$spacing-cascader_search-paddingX	12px	级联选择搜索水平内边距
$spacing-cascader_search-paddingY	8px	级联选择搜索垂直内边距
$spacing-cascader_option_empty-paddingY	8px	级联选择空结果垂直内边距
$spacing-cascader_option_empty-paddingX	12px	级联选择空结果水平内边距
$spacing-cascader_option-paddingTop	8px	级联选择菜单项顶部内边距
$spacing-cascader_option-paddingBottom	8px	级联选择菜单项底部内边距
$spacing-cascader_option-paddingLeft	12px	级联选择菜单项左侧内边距
$spacing-cascader_option-paddingRight	16px	级联选择菜单项右侧内边距

Usage scenarios

Demos

How to import

Basic Usage

Multiple

Searchable

filterLeafOnly=false:

Label 为自定义节点，指定其他属性进行搜索

Searchable Multiple Selection

Limit Tags Displayed

Limit Tags Number

Change on Select

Custom Display Property

单选

多选

单选

多选

Custom Separator

Disabled

Disable Strictly

the Way of Expand Menu

Click to Select

Additional items

Controlled Component

Auto Merge Value

Leaf Only

Checked RelationShip

Dynamic Update of Data

Load Async Data

Remote Search

Deep & long list

Custom Trigger

API reference

Cascader

CascaderData

Methods

Accessibility

ARIA

Keyboard Interaction

Content Guidelines

Design Tokens