Cascader

Used for hierarchical selection of tree-structured data, supporting both static data and asynchronous loading modes.

Tip

For province-city-district scenarios, you can directly use useCascaderAreaData from @vant/area-data as the data source.

Component Type

Basic Usage

<wd-cascader v-model="value" v-model:visible="show" :options="options" @confirm="handleConfirm" />

Initial Options

<wd-cascader v-model="value" v-model:visible="show" :options="options" @confirm="handleConfirm" />

Custom Fields

<wd-cascader
  v-model="value"
  v-model:visible="show"
  :options="customOptions"
  value-key="id"
  text-key="name"
  children-key="items"
  @confirm="handleConfirm"
/>

Component State

Disabled Options

<wd-cascader v-model="value" v-model:visible="show" :options="optionsWithDisabled" @confirm="handleConfirm" />

Option Tips

<wd-cascader v-model="value" v-model:visible="show" :options="optionsWithTip" @confirm="handleConfirm" />

Before Confirm Validation

before-confirm supports returning boolean or Promise<boolean>.

<wd-cascader
  v-model="value"
  v-model:visible="show"
  :options="options"
  :before-confirm="beforeConfirm"
  @confirm="handleConfirm"
/>

const beforeConfirm = async (value, selectedOptions) => {
  if (String(value) === '120000') return false
  return true
}

Component Style

Display Formatting

const handleConfirm = ({ selectedOptions }) => {
  displayValue.value = `${selectedOptions[selectedOptions.length - 2].text}-${selectedOptions[selectedOptions.length - 1].text}`
}

Set Title

<wd-cascader v-model="value" v-model:visible="show" title="Select Address" :options="options" @confirm="handleConfirm" />

Special Style

Asynchronous Loading

After passing lazy-load, it enters asynchronous mode: when option = null, it loads root nodes; resolve([]) indicates the current node is a leaf node.

<wd-cascader v-model="value" v-model:visible="show" :lazy-load="lazyLoad" @confirm="handleConfirm" />

const lazyLoad = (option, tabIndex, resolve) => {
  fetchChildren(option ? String(option.value) : null).then(resolve)
}

Asynchronous Loading (No Initial Value)

<wd-cascader v-model="value" v-model:visible="show" :lazy-load="lazyLoad" @confirm="handleConfirm" />

Any Level Selectable

After enabling check-strictly, clicking a node only updates the current path, and submission is done through the confirm button in the top right corner.

<wd-cascader v-model="value" v-model:visible="show" :options="options" check-strictly @confirm="handleConfirm" />

Attributes

Parameter	Description	Type	Default Value
v-model	Selected item. Static mode is leaf node value; asynchronous mode can pass path array for display	string | number | (string | number)[]	-
visible / v-model:visible	Whether to show popup	boolean	false
options	Hierarchical option data (tree structure)	CascaderOption[]	[]
title	Popup title	string	-
before-confirm	Validation function before confirm, parameters are (value, selectedOptions), returns boolean or Promise<boolean>	CascaderBeforeConfirm	-
check-strictly	Whether to enable any level selectable	boolean	false
confirm-text	Confirm button text in strict mode	string	''
value-key	Option value field name	string	value
text-key	Option text field name	string	text
children-key	Child node field name	string	children
tip-key	Tip text field name	string	tip
is-leaf-key	Leaf node identifier field name, when value is true, clicking confirms	string	isLeaf
lazy-load	Asynchronous loading callback, parameters are (option, tabIndex, resolve)	CascaderLazyLoad	-
close-on-click-modal	Whether to close when clicking mask	boolean	true
z-index	Popup z-index	number	15
safe-area-inset-bottom	Whether popup panel sets bottom safe distance (iPhone X type devices)	boolean	true
line-width	Bottom line width, supports number or string with unit	number | string	-
line-height	Bottom line height, supports number or string with unit	number | string	-
line-theme	Bottom line position style, supports normal / text / underline / dot	string	normal
root-portal	Whether to render outside document flow (H5: teleport, App: renderjs, Mini Program: root-portal)	boolean	false
custom-class	Root node custom class name	string	''
custom-style	Root node custom style	string	''

CascaderOption Data Structure

Key	Description	Type
value	Option value	string | number
text	Option text	string
children	Child options	CascaderOption[]
disabled	Whether disabled	boolean
tip	Tip text	string
isLeaf	Whether it is a leaf node (asynchronous mode)	boolean

Events

Event Name	Description	Parameters
confirm	Triggered when confirming selection	Static mode: { value, selectedOptions }, value is leaf value; Asynchronous mode: { value, selectedOptions }, value is path array
close	Triggered when popup closes	-

Methods

Method Name	Description	Parameters
open	Open cascader popup	-
close	Close cascader popup	-

主题定制

CSS 变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 全局配置。

名称	默认值	描述
--wot-cascader-bg	$filled-oppo	级联选择器弹层背景色
--wot-cascader-list-height	calc(336 * #{$n-1})	选项列表高度
--wot-cascader-list-item-color	$text-main	选项文字颜色
--wot-cascader-list-item-opacity-disabled	$opacity-disabled	选项禁用态透明度
--wot-cascader-list-item-font-size	$typography-body-size-extra-large	选项文字字号
--wot-cascader-list-item-line-height	$typography-body-line--height-size-extra-large	选项文字行高
--wot-cascader-list-item-padding	$padding-extra-loose $padding-loose	选项内边距
--wot-cascader-list-item-color-checked	$primary-6	选项选中态文字颜色
--wot-cascader-list-item-font-weight-checked	$font-weight-medium	选项选中态文字字重
--wot-cascader-list-tip-color	$text-secondary	选项提示文字颜色
--wot-cascader-list-tip-font-size	$typography-label-size-main	选项提示文字字号
--wot-cascader-list-tip-line-height	$typography-label-line--height-size-main	选项提示文字行高
--wot-cascader-list-tip-margin-top	$spacing-ultra-tight	选项提示顶部外边距
--wot-cascader-list-checked-icon-size	$n-20	选中图标尺寸
--wot-cascader-list-checked-icon-spacing	$spacing-tight	选中图标与文字间距
--wot-cascader-action-right	$spacing-loose	关闭图标右侧偏移
--wot-cascader-confirm-color	$primary-6	checkStrictly模式确认按钮颜色
--wot-cascader-confirm-opacity-disabled	$opacity-disabled	checkStrictly模式确认按钮禁用透明度
--wot-cascader-confirm-font-size	$typography-body-size-large	checkStrictly模式确认按钮字号
--wot-cascader-confirm-line-height	$typography-body-line--height-size-large	checkStrictly模式确认按钮行高
--wot-cascader-confirm-font-weight	$font-weight-regular	checkStrictly模式确认按钮字重
--wot-cascader-loading-opacity	$opacity-disabled	loading 状态下选项区透明度
--wot-cascader-loading-icon-size	$n-48	loading 图标尺寸

Source Code

Documentation

• Component