Cascader

If the options have a clear hierarchical structure, Cascader can be used to view and select them.

TIP

This component requires the <client-only></client-only> wrap when used in SSR (eg: Nuxt) and SSG (eg: VitePress).

Basic usage

There are two ways to expand child option items.

Disabled option

Disable an option by setting a disabled field in the option object.

Clearable

Set clearable attribute for el-cascader and a clear icon will appear when selected and hovered

Display only the last level

The input can display only the last level instead of all levels.

Multiple Selection

Add :props="props" in tag and set data props = { multiple: true } to use multiple selection.

Do:

<template>
  <el-cascader :props="props" />
</template>
<script lang="ts" setup>
  const props = { multiple: true }
</script>

Don't do:

<template>
  <!--  Object literal binging here is invalid syntax for cascader  -->
  <el-cascader :props="{ multiple: true }" />
</template>

Select any level of options

In single selection, only the leaf nodes can be checked, and in multiple selection, check parent nodes will lead to leaf nodes be checked eventually. When enable this feature, it can make parent and child nodes unlinked and you can select any level of options.

Dynamic loading

Dynamic load its child nodes when checked a node.

Filterable

Search and select options with a keyword.

Custom option content

You can customize the content of cascader node.

Cascader panel

CascaderPanel is the core component of Cascader which has various of features such as single selection, multiple selection, dynamic loading and so on.

Cascader API

Cascader Attributes

Name	Description	Type	Default
model-value / v-model	binding value	`string`/`number`/`object`	—
options	data of the options, the key of `value` and `label` can be customize by `CascaderProps`.	`object`	—
props	configuration options, see the following `CascaderProps` table.	`object`	—
size	size of input	`enum`	—
placeholder	placeholder of input	`string`	—
disabled	whether Cascader is disabled	`boolean`	—
clearable	whether selected value can be cleared	`boolean`	—
show-all-levels	whether to display all levels of the selected value in the input	`boolean`	true
collapse-tags	whether to collapse tags in multiple selection mode	`boolean`	—
collapse-tags-tooltip	whether show all selected tags when mouse hover text of collapse-tags. To use this, `collapse-tags` must be true	`boolean`	false
separator	option label separator	`string`	' / '
filterable	whether the options can be searched	`boolean`	—
filter-method	customize search logic, the first parameter is `node`, the second is `keyword`, and need return a boolean value indicating whether it hits.	`Function`	—
debounce	debounce delay when typing filter keyword, in milliseconds	`number`	300
before-filter	hook function before filtering with the value to be filtered as its parameter. If `false` is returned or a `Promise` is returned and then is rejected, filtering will be aborted	`Function`	—
popper-class	custom class name for Cascader's dropdown	`string`	''
teleported	whether cascader popup is teleported	`boolean`	true
popper-append-to-body deprecated	whether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to false	`boolean`	true
tag-type	tag type	`enum`	info
validate-event	whether to trigger form validation	`boolean`	true
max-collapse-tags 2.3.10	The max tags number to be shown. To use this, `collpase-tags` must be true	`number`	1
empty-values 2.7.0	empty values of component, see config-provider	`array`	—
value-on-clear 2.7.0	clear return value, see config-provider	`string` / `number` / `boolean` / `Function`	—

Cascader Events

Name	Description	Type
change	triggers when the binding value changes	`Function`
expand-change	triggers when expand option changes	`Function`
blur	triggers when Cascader blurs	`Function`
focus	triggers when Cascader focuses	`Function`
visible-change	triggers when the dropdown appears/disappears	`Function`
remove-tag	triggers when remove tag in multiple selection mode	`Function`

Cascader Slots

Name	Description	Scope
default	the custom content of cascader node, which are current Node object and node data respectively.	`object`
empty	content when there is no matched options.	—

Cascader Exposes

Name	Description	Type
getCheckedNodes	get an array of currently selected node,(leafOnly) whether only return the leaf checked nodes, default is `false`	`Function`
cascaderPanelRef	cascader panel ref	`object`
togglePopperVisible 2.2.31	toggle the visible type of popper	`Function`
contentRef	cascader content ref	`object`

CascaderPanel API

CascaderPanel Attributes

Name	Description	Type	Default
model-value / v-model	binding value	`string`/`number`/`object`	—
options	data of the options, the key of `value` and `label` can be customize by `CascaderProps`.	`object`	—
props	configuration options, see the following `CascaderProps` table.	`object`	—

CascaderPanel Events

Name	Description	Type
change	triggers when the binding value changes	`Function`
expand-change	triggers when expand option changes	`Function`
close	close panel event, provided to Cascader to put away the panel judgment.	`Function`

CascaderPanel Slots

Name	Description	Scope
default	the custom content of cascader node, which are current Node object and node data respectively.	`object`

CascaderPanel Exposes

Name	Description	Type
getCheckedNodes	get an array of currently selected node,(leafOnly) whether only return the leaf checked nodes, default is `false`	`Function`
clearCheckedNodes	clear checked nodes	`Function`

CascaderProps

Attribute	Description	Type	Default
expandTrigger	trigger mode of expanding options	`enum`	click
multiple	whether multiple selection is enabled	`boolean`	false
checkStrictly	whether checked state of a node not affects its parent and child nodes	`boolean`	false
emitPath	when checked nodes change, whether to emit an array of node's path, if false, only emit the value of node.	`boolean`	true
lazy	whether to dynamic load child nodes, use with `lazyload` attribute	`boolean`	false
lazyLoad	method for loading child nodes data, only works when `lazy` is true	`Function`	—
value	specify which key of node object is used as the node's value	`string`	value
label	specify which key of node object is used as the node's label	`string`	label
children	specify which key of node object is used as the node's children	`string`	children
disabled	specify which key of node object is used as the node's disabled	`string`	disabled
leaf	specify which key of node object is used as the node's leaf field	`string`	leaf
hoverThreshold	hover threshold of expanding options	`number`	500

Type Declarations

Show declarations

type CascaderNodeValue = string | number
type CascaderNodePathValue = CascaderNodeValue[]
type CascaderValue =
  | CascaderNodeValue
  | CascaderNodePathValue
  | (CascaderNodeValue | CascaderNodePathValue)[]

type Resolve = (data: any) => void

type ExpandTrigger = 'click' | 'hover'

type LazyLoad = (node: Node, resolve: Resolve) => void

type isDisabled = (data: CascaderOption, node: Node) => boolean

type isLeaf = (data: CascaderOption, node: Node) => boolean

interface CascaderOption extends Record<string, unknown> {
  label?: string
  value?: CascaderNodeValue
  children?: CascaderOption[]
  disabled?: boolean
  leaf?: boolean
}

interface CascaderProps {
  expandTrigger?: ExpandTrigger
  multiple?: boolean
  checkStrictly?: boolean
  emitPath?: boolean
  lazy?: boolean
  lazyLoad?: LazyLoad
  value?: string
  label?: string
  children?: string
  disabled?: string | isDisabled
  leaf?: string | isLeaf
  hoverThreshold?: number
}

class Node {
  readonly uid: number
  readonly level: number
  readonly value: CascaderNodeValue
  readonly label: string
  readonly pathNodes: Node[]
  readonly pathValues: CascaderNodePathValue
  readonly pathLabels: string[]

  childrenData: ChildrenData
  children: Node[]
  text: string
  loaded: boolean
  /**
   * Is it checked
   *
   * @default false
   */
  checked: boolean
  /**
   * Used to indicate the intermediate state of unchecked and fully checked child nodes
   *
   * @default false
   */
  indeterminate: boolean
  /**
   * Loading Status
   *
   * @default false
   */
  loading: boolean

  // getter
  isDisabled: boolean
  isLeaf: boolean
  valueByOption: CascaderNodeValue | CascaderNodePathValue

  // method
  appendChild(childData: CascaderOption): Node
  calcText(allLevels: boolean, separator: string): string
  broadcast(event: string, ...args: unknown[]): void
  emit(event: string, ...args: unknown[]): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode