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

NameDescriptionTypeDefault
model-value / v-modelbinding valuestring/number/object
optionsdata of the options, the key of value and label can be customize by CascaderProps.object
propsconfiguration options, see the following CascaderProps table.object
sizesize of inputenum
placeholderplaceholder of inputstring
disabledwhether Cascader is disabledboolean
clearablewhether selected value can be clearedboolean
show-all-levelswhether to display all levels of the selected value in the inputbooleantrue
collapse-tagswhether to collapse tags in multiple selection modeboolean
collapse-tags-tooltipwhether show all selected tags when mouse hover text of collapse-tags. To use this, collapse-tags must be truebooleanfalse
separatoroption label separatorstring' / '
filterablewhether the options can be searchedboolean
filter-methodcustomize search logic, the first parameter is node, the second is keyword, and need return a boolean value indicating whether it hits.Function
debouncedebounce delay when typing filter keyword, in millisecondsnumber300
before-filterhook 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 abortedFunction
popper-classcustom class name for Cascader's dropdownstring''
teleportedwhether cascader popup is teleportedbooleantrue
popper-append-to-body deprecatedwhether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to falsebooleantrue
tag-typetag typeenuminfo
validate-eventwhether to trigger form validationbooleantrue
max-collapse-tags 2.3.10The max tags number to be shown. To use this, collpase-tags must be truenumber1
empty-values 2.7.0empty values of component, see config-providerarray
value-on-clear 2.7.0clear return value, see config-providerstring / number / boolean / Function

Cascader Events

NameDescriptionType
changetriggers when the binding value changesFunction
expand-changetriggers when expand option changesFunction
blurtriggers when Cascader blursFunction
focustriggers when Cascader focusesFunction
clear 2.7.7triggers when the clear icon is clicked in a clearable SelectFunction
visible-changetriggers when the dropdown appears/disappearsFunction
remove-tagtriggers when remove tag in multiple selection modeFunction

Cascader Slots

NameDescriptionScope
defaultthe custom content of cascader node, which are current Node object and node data respectively.object
emptycontent when there is no matched options.

Cascader Exposes

NameDescriptionType
getCheckedNodesget an array of currently selected node,(leafOnly) whether only return the leaf checked nodes, default is falseFunction
cascaderPanelRefcascader panel refobject
togglePopperVisible 2.2.31toggle the visible type of popperFunction
contentRefcascader content refobject

CascaderPanel API

CascaderPanel Attributes

NameDescriptionTypeDefault
model-value / v-modelbinding valuestring/number/object
optionsdata of the options, the key of value and label can be customize by CascaderProps.object
propsconfiguration options, see the following CascaderProps table.object

CascaderPanel Events

NameDescriptionType
changetriggers when the binding value changesFunction
expand-changetriggers when expand option changesFunction
closeclose panel event, provided to Cascader to put away the panel judgment.Function

CascaderPanel Slots

NameDescriptionScope
defaultthe custom content of cascader node, which are current Node object and node data respectively.object

CascaderPanel Exposes

NameDescriptionType
getCheckedNodesget an array of currently selected node,(leafOnly) whether only return the leaf checked nodes, default is falseFunction
clearCheckedNodesclear checked nodesFunction

CascaderProps

AttributeDescriptionTypeDefault
expandTriggertrigger mode of expanding optionsenumclick
multiplewhether multiple selection is enabledbooleanfalse
checkStrictlywhether checked state of a node not affects its parent and child nodesbooleanfalse
emitPathwhen checked nodes change, whether to emit an array of node's path, if false, only emit the value of node.booleantrue
lazywhether to dynamic load child nodes, use with lazyload attributebooleanfalse
lazyLoadmethod for loading child nodes data, only works when lazy is trueFunction
valuespecify which key of node object is used as the node's valuestringvalue
labelspecify which key of node object is used as the node's labelstringlabel
childrenspecify which key of node object is used as the node's childrenstringchildren
disabledspecify which key of node object is used as the node's disabledstringdisabled
leafspecify which key of node object is used as the node's leaf fieldstringleaf
hoverThresholdhover threshold of expanding optionsnumber500

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

Source

ComponentDocs

Contributors