Cascader

When a dataset has a clear hierarchical structure (e.g., administrative regions, department structures, product categories), use the cascader for step-by-step selection.

Basic Usage

A widely applicable basic single-select cascader.

Value: []

Basic Usage

Initial Value

By binding an initial array to v-model, you can pre-select nodes in the Cascader.

Zhejiang / Hangzhou / West Lake District

Zhejiang / Hangzhou / Binjiang DistrictJiangsu / Nanjing / Xuanwu District

Value (Single): [ "zhejiang", "hangzhou", "xihu" ]

Value (Multiple): [ [ "zhejiang", "hangzhou", "binjiang" ], [ "jiangsu", "nanjing", "xuanwu" ] ]

Initial Value

Disabled

You can disable the entire component or specify certain options as unselectable in the data.

Zhejiang / Hangzhou / West Lake District

Value: []

Disabled

Multiple Select with Collapsed Tags

Set multiple to enable multi-select; use collapse-tags to collapse displayed tags.

Value: []

Multiple Select

Select Any Level

With check-strictly enabled, users can select nodes at any level.

Value: []

Select Any Level

Return Mode (emit-path)

By default, the full path array is returned. Set emit-path="false" to return only the selected node's value.

Zhejiang / Hangzhou / West Lake District

Value: xihu

Non-Path Mode

Search Filter

Enable filterable for quick search suggestions. Supports matching any segment in the full path.

Value: []

Searchable

Custom Content

Use the #default slot to fully customize menu item rendering.

Custom Slot

Custom Fields

Use the props attribute to specify the field names in the option object, such as value, label, children, etc.

Value: []

Custom Fields

Large Data Optimization

Enable virtual for virtual scrolling. Handles tens of thousands of nodes with smooth interaction.

Virtual Scroll

Use in Nuxt

The Cascader component fully supports SSR rendering in Nuxt 3/4. Components are auto-imported in Nuxt projects.

Use in Nuxt

SSR Notes:

• ✅ Basic cascading level display fully supported
• ✅ Multiple select and collapsed tags supported
• ✅ Select any level (check-strictly) works in SSR
• ✅ Search filter auto-enables after client activation
• ✅ Virtual scroll supports initial render
• 💡 Dropdown menus render via Teleport, not interfering with server-generated HTML

SSR Safety

Cascader's recursive node system is deeply optimized for SSR, ensuring strong consistency between server and client-generated node IDs and structures, effectively preventing hydration conflicts.

API

Props

Prop	Description	Type	Default
model-value / v-model	Binding value	string | number | (string | number)[] | (string | number)[][]	—
options	Data source of options	CascaderOption[]	[]
props	Configuration options, see table below	object	—
placeholder	Input placeholder text	string	—
disabled	Whether disabled	boolean	false
clearable	Whether clearable	boolean	false
size	Size	'large' | 'default' | 'small'	'default'
filterable	Whether search filter is supported	boolean	false
filter-method	Custom filter method	(node: CascaderOption, keyword: string) => boolean	—
separator	Option path separator	string	' / '
show-all-levels	Whether to show full path labels	boolean	true
multiple	Whether multi-select is enabled	boolean	false
check-strictly	Whether to allow selecting any level node	boolean	false
expand-trigger	Sub-menu expand trigger	'click' | 'hover'	'click'
emit-path	Whether to return path array when selection changes	boolean	true
collapse-tags	Whether to collapse tags in multi-select	boolean	false
collapse-tags-tooltip	Whether to show tooltip for collapsed tags	boolean	false
max-collapse-tags	Max visible tags before collapsing	number	1
virtual	Whether to enable virtual scroll	boolean	false
virtual-item-height	Virtual scroll item height	number	34
popper-class	Dropdown custom class	string	—
teleported	Whether to mount dropdown to body	boolean	true
tag-type	Multi-select tag type	'success' | 'info' | 'warning' | 'danger' | ''	''
validate-event	Whether to trigger form validation on input	boolean	true

CascaderOption

Prop	Description	Type	Default
value	Option value	string | number	—
label	Option label	string	—
children	Child options array	CascaderOption[]	—
disabled	Whether disabled	boolean	false
leaf	Whether leaf node	boolean	—

Cascader Config (props)

Prop	Description	Type	Default
expandTrigger	Sub-menu expand trigger	'click' | 'hover'	'click'
multiple	Whether multi-select	boolean	false
checkStrictly	Whether to allow selecting any level	boolean	false
emitPath	Whether to return path array	boolean	true
value	Property name for option value	string	'value'
label	Property name for option label	string	'label'
children	Property name for child options	string	'children'
disabled	Property name for disabled state	string	'disabled'
leaf	Property name for leaf node	string	'leaf'

Events

Event Name	Description	Parameters
change	Triggered when selection changes	(value: any) => void
expand-change	Triggered when expanded node changes	(value: any[]) => void
visible-change	Triggered when dropdown shows/hides	(visible: boolean) => void
focus	Triggered on focus	(event: FocusEvent) => void
blur	Triggered on blur	(event: FocusEvent) => void
clear	Triggered when clear button is clicked	—

Slots

Slot Name	Description	Parameters
default	Custom node content	{ node: CascaderOption, data: CascaderOption }
empty	Content when no matching data	—

Expose

Name	Description	Type
focus	Focus the input	() => void
blur	Blur the input	() => void
getCheckedNodes	Get currently checked node objects	(leafOnly?: boolean) => CascaderOption[]
inputRef	Input DOM reference	HTMLInputElement

Theme Variables

Variable	Description	Default
--yh-cascader-height	Cascader height	32px
--yh-cascader-bg-color	Background color	var(--yh-fill-color-blank)
--yh-cascader-border-color	Border color	var(--yh-border-color)
--yh-cascader-border-color-hover	Hover border color	var(--yh-border-color-hover)
--yh-cascader-border-color-focus	Focus border color	var(--yh-color-primary)
--yh-cascader-text-color	Text color	var(--yh-text-color-regular)
--yh-cascader-placeholder-color	Placeholder color	var(--yh-text-color-placeholder)
--yh-cascader-node-height	Option node height	34px
--yh-cascader-node-bg-color-hover	Option hover background	var(--yh-fill-color-light)
--yh-cascader-node-bg-color-active	Option active background	var(--yh-fill-color-light)
--yh-cascader-node-text-color-active	Option active text color	var(--yh-color-primary)
--yh-cascader-menu-min-width	Menu min width	180px
--yh-cascader-menu-max-height	Menu max height	274px