Cascader

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

Basic usage

There are two ways to expand child option items.

:::demo Assigning the options attribute to an array of options renders a Cascader. The props.expandTrigger attribute defines how child options are expanded.

cascader/basic

:::

Disabled option

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

:::demo In this example, the first item in options array has a disabled: true field, so it is disabled. By default, Cascader checks the disabled field in each option object; if you are using another field name to indicate whether an option is disabled, you can assign it in the props.disabled attribute (see the API table below for details). And of course, field name value, label and children can also be customized in the same way.

cascader/option-disabling

:::

Clearable

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

:::demo

cascader/clearable

:::

Custom Clear Icon ^(2.11.0)

You can customize the clear icon by setting the clear-icon attribute

:::demo

cascader/clear-icon

:::

Display only the last level

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

:::demo The show-all-levels attribute defines if all levels are displayed. If it is false, only the last level is displayed.

cascader/last-level

:::

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>

:::demo When using multiple selection, all selected tags will display by default. You can set collapse-tags = true to fold selected tags. You can set max-collapse-tags to show max tags number, default 1. You can check them when mouse hover collapse text by using collapse-tags-tooltip attribute.

cascader/multiple-selection

:::

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.

:::demo Set props.checkStrictly = true to make checked state of a node not affects its parent nodes and child nodes, and then you can select any level of options.

cascader/any-level

:::

Dynamic loading

Dynamic load its child nodes when checked a node.

:::demo Set lazy = true to use dynamic loading, and you have to specify how to load the data source by lazyload. There are two parameters of lazyload,the first parameter node is the node currently clicked, and the resolve is a callback that indicate loading is finished which must invoke. To display the status of node more accurately, you can add a leaf field (can be modified by props.leaf) to indicate whether it is a leaf node. Otherwise, it will be inferred by if has any child nodes.

cascader/dynamic-loading

:::

Filterable

Search and select options with a keyword.

:::demo Adding filterable to el-cascader enables filtering. Cascader will match nodes whose label or parent's label (according to show-all-levels) includes input keyword. Of course, you can customize search logic by filter-method which accepts a function, the first parameter is node, the second is keyword, and need return a boolean value indicating whether it hits.

cascader/filterable

:::

Custom option content

You can customize the content of cascader node.

:::demo You can customize the content of cascader node by scoped slot. You'll have access to node and data in the scope, standing for the Node object and node data of the current node respectively.

cascader/custom-content

:::

Custom suggestion item ^(2.9.5)

You can customize the filter suggestion item by suggestion-item slot. You'll have access to item in the scope, standing for the suggestion item.

:::demo

cascader/custom-suggestion-item

:::

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.

:::demo Just like el-cascader, you can set alternative options by options, and enable other features by props, see the API form below for details.

cascader/panel

:::

Custom Tag ^(2.10.3)

You can customize tags.

:::demo Insert customized tags into the slot of el-cascader. collapse-tags, collapse-tags-tooltip, max-collapse-tags will not work.

cascader/custom-tag

:::

Show Checked Strategy ^(2.10.5)

Control how selected values are displayed in multiple selection mode.

:::demo In multiple selection mode, you can use show-checked-strategy to control how selected values are displayed. The default strategy is child, which shows all selected child nodes. The parent strategy only shows parent nodes when all their children are selected.

cascader/show-checked-strategy

:::

Click to Check Node ^(2.10.5)

Only using multiple or checkStrictly attributes.

You can add checkOnClickNode to be able to click on the node in addition with the prefix icon.
Toggle the visibility of the prefix with showPrefix. :::tip Add checkOnClickLeaf to check only the leaf node (last children), enabled by default. :::

:::demo

cascader/check-on-click-node

:::

Custom Header & Footer ^(2.10.5)

You can customize both the header and footer of the dropdown using slots.

:::demo Use slot to customize the content.

cascader/custom-header-footer

:::

Cascader API

Cascader Attributes

Cascader Events

Cascader Slots

Cascader Exposes

CascaderPanel API

CascaderPanel Attributes

CascaderPanel Events

CascaderPanel Slots

CascaderPanel Exposes

CascaderProps

Type 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, reject: () => void) => 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(): void
  emit(): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode