Cascader

A Neo-Brutalist styled cascading dropdown selection component. It displays multi-level hierarchical options in grid-cascaded panels, supporting path binding (single/multiple select), parent-child relation control, and complete keyboard interactions.

Preview

Preview

基础单选

请选择

当前值: 空

多选模式

多选模式

当前值: 空

父子节点独立选择 (checkStrictly)

可选择任意一级

当前值: 空

Installation

pnpm dlx brutx-vue@latest add cascader

Usage

Basic Usage

<script setup>
import { ref } from 'vue'
import { Cascader } from 'brutx-ui-vue'

const options = [
    {
        value: 'us',
        label: 'USA',
        children: [
            {
                value: 'ny',
                label: 'New York',
                children: [
                    { value: 'man', label: 'Manhattan' },
                    { value: 'qns', label: 'Queens' },
                ]
            },
            {
                value: 'ca',
                label: 'California',
            }
        ]
    },
    {
        value: 'cn',
        label: 'China',
        children: [
            { value: 'bj', label: 'Beijing' },
            { value: 'sh', label: 'Shanghai' },
        ]
    }
]

const selected = ref([])
</script>

<template>
    <Cascader
        v-model="selected"
        :options="options"
        placeholder="Select region"
        clearable
    />
</template>

Multiple Selection

Set the multiple attribute to enable multi-select. The v-model bound value will be a two-dimensional array representing the selected full path arrays. By default, checking a parent node checks all its descendant leaf nodes.

<script setup>
import { ref } from 'vue'
import { Cascader } from 'brutx-ui-vue'

const selected = ref([]) // e.g. [['us', 'ny', 'man'], ['cn', 'bj']]
</script>

<template>
    <Cascader
        v-model="selected"
        :options="options"
        multiple
        placeholder="Select multiple regions"
    />
</template>

Check Strictly (Any level selection)

By default, only leaf nodes can be selected. Set checkStrictly to true to allow selecting nodes of any level (parent nodes can be bound as paths).

<template>
    <Cascader
        v-model="selected"
        :options="options"
        check-strictly
        placeholder="Select any level"
    />
</template>

API Reference

Cascader — Props

Name	Type	Default	Description
options Required	CascaderOption<unknown>[]	—	The nested option tree for cascading selection; each option uses value and label and may include children.
Details Declared type CascaderOption<unknown>[] Referenced types CascaderOption Type definition — CascaderOption export interface CascaderOption<T = unknown> { value: CascaderValue label: string children?: CascaderOption<T>[] disabled?: boolean data?: T } Default value details Not declared — Source Cascader.vue:17 packages/ui/src/components/cascader/Cascader.vue
modelValue	CascaderValue[] | CascaderValue[][] | undefined	[] Factory evaluated per instance	The selected paths, bound with v-model. Single mode uses one CascaderValue path; multiple mode uses an array of paths.
Details Declared type CascaderValue[] | CascaderValue[][] | undefined Referenced types CascaderValue Type definition — CascaderValue export type CascaderValue = string | number Default value details Declaration () => [] Source: packages/ui/src/components/cascader/Cascader.vue Resolved value [] Source Cascader.vue:19 packages/ui/src/components/cascader/Cascader.vue
open	boolean | undefined	undefined	The controlled open state of the dropdown panel, synchronized with v-model:open.
Details Declared type boolean | undefined Literal values false true Default value details Declaration undefined Source: packages/ui/src/components/cascader/Cascader.vue Resolved value undefined Source Cascader.vue:21 packages/ui/src/components/cascader/Cascader.vue
multiple	boolean | undefined	false	Allows selecting multiple option paths; modelValue is an array of paths when enabled.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/cascader/Cascader.vue Resolved value false Source Cascader.vue:23 packages/ui/src/components/cascader/Cascader.vue
clearable	boolean | undefined	false	Shows a clear action for removing the selected paths.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/cascader/Cascader.vue Resolved value false Source Cascader.vue:25 packages/ui/src/components/cascader/Cascader.vue
checkStrictly	boolean | undefined	false	Allows parent nodes with children to be selected without requiring a leaf node.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/cascader/Cascader.vue Resolved value false Source Cascader.vue:27 packages/ui/src/components/cascader/Cascader.vue
separator	string | undefined	" / "	Sets the separator displayed between labels in a path on the trigger.
Details Declared type string | undefined Default value details Declaration ' / ' Source: packages/ui/src/components/cascader/Cascader.vue Resolved value " / " Source Cascader.vue:29 packages/ui/src/components/cascader/Cascader.vue
maxDisplay	number | undefined	2	In multiple mode, the maximum number of paths shown directly in the trigger; remaining paths are collapsed into a summary.
Details Declared type number | undefined Default value details Declaration 2 Source: packages/ui/src/components/cascader/Cascader.vue Resolved value 2 Source Cascader.vue:31 packages/ui/src/components/cascader/Cascader.vue
size	"default" | "lg" | "sm" | undefined	"default"	Sets the trigger button size variant.
Details Declared type "default" | "lg" | "sm" | undefined Literal values "default" "lg" "sm" Default value details Declaration 'default' Source: packages/ui/src/components/cascader/Cascader.vue Resolved value "default" Source Cascader.vue:33 packages/ui/src/components/cascader/Cascader.vue
placeholder	string | undefined	undefined	Text shown in the trigger when no path is selected.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/cascader/Cascader.vue Resolved value undefined Source Cascader.vue:35 packages/ui/src/components/cascader/Cascader.vue
disabled	boolean | undefined	false	Disables user interaction with the select trigger and dropdown panel.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/cascader/Cascader.vue Resolved value false Source Cascader.vue:37 packages/ui/src/components/cascader/Cascader.vue
dropdownClass	string | undefined	undefined	CSS classes added to the cascader dropdown panel.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/cascader/Cascader.vue Resolved value undefined Source Cascader.vue:39 packages/ui/src/components/cascader/Cascader.vue
class	string | undefined	undefined	CSS classes added to the select trigger button.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/cascader/Cascader.vue Resolved value undefined Source Cascader.vue:41 packages/ui/src/components/cascader/Cascader.vue
ariaLabel	string | undefined	undefined	Sets the accessible label for the select trigger.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/cascader/Cascader.vue Resolved value undefined Source Cascader.vue:43 packages/ui/src/components/cascader/Cascader.vue

Cascader — Events

Name	Signature or type	Description
@update:modelValue	[value: CascaderValue[] | CascaderValue[][]]	Emits the updated path value when selection changes, for synchronizing the controlled value with v-model.
Details Declared type [value: CascaderValue[] | CascaderValue[][]] Referenced types CascaderValue Type definition — CascaderValue export type CascaderValue = string | number Source Cascader.vue packages/ui/src/components/cascader/Cascader.vue
@update:open	[value: boolean]	Emits the new boolean when the dropdown open state changes and can be used with v-model:open.
Details Declared type [value: boolean] Literal values false true Source Cascader.vue packages/ui/src/components/cascader/Cascader.vue
@change	[value: CascaderValue[] | CascaderValue[][]]	Emits the selected single path or set of paths when the user changes the selection.
Details Declared type [value: CascaderValue[] | CascaderValue[][]] Referenced types CascaderValue Type definition — CascaderValue export type CascaderValue = string | number Source Cascader.vue packages/ui/src/components/cascader/Cascader.vue
@open-change	[open: boolean]	Emits the current open state when the dropdown panel opens or closes.
Details Declared type [open: boolean] Literal values false true Source Cascader.vue packages/ui/src/components/cascader/Cascader.vue

Data Types

type CascaderValue = string | number

interface CascaderOption<T = unknown> {
    value: CascaderValue
    label: string
    children?: CascaderOption<T>[]
    disabled?: boolean
    data?: T
}

CascaderOption supports a generic for the business data type: in CascaderOption<MyData>[] the data field gets type inference; it defaults to unknown to stay permissive.

Exported Types

import type { CascaderOption, CascaderValue } from 'brutx-ui-vue'

Accessibility

• Keyboard Interaction:
  • ArrowDown / ArrowUp: Move focus up and down within the active column, skipping disabled options
  • ArrowRight: Expand the focused option's sub-column and focus the first item
  • ArrowLeft: Collapse the active sub-column, returning to parent option column
  • Enter / Space: Select option, or toggle Checkbox state in multi-select mode
  • Escape: Close dropdown panel
• ARIA Attributes: The trigger has role="combobox", aria-expanded and aria-disabled indicators. Option items have role="menuitem"
• Focus Management: Upon opening, focus moves to the last selected value's option item; with no selected value no item is highlighted (aria-activedescendant stays undefined) until keyboard navigation begins, avoiding misreporting the first option while focus is still on the trigger
• Reduced Motion: Transition animations support prefers-reduced-motion settings and automatically downgrade (if applicable)