Cascader

TxCascader selects a path from nested options. Single mode stores one path array, while multiple mode stores an array of path arrays. Search is local to the loaded option tree; async children are loaded through load when a non-leaf node without children is expanded.

Basic Usage

Cascader

Demo will load when visible.

<script setup lang="ts">
import { ref } from 'vue'

const value1 = ref<any>(undefined)
const value2 = ref<any>([])

const options = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          { value: 'xihu', label: 'West Lake', leaf: true },
          { value: 'binjiang', label: 'Binjiang', leaf: true },
        ],
      },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      {
        value: 'nanjing',
        label: 'Nanjing',
        children: [
          { value: 'zhonghuamen', label: 'Zhong Hua Men', leaf: true },
        ],
      },
    ],
  },
]
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; width: 520px;">
    <div style="display: flex; gap: 12px; align-items: center;">
      <TxCascader v-model="value1" :options="options" placeholder="Single" />
      <TxCascader v-model="value2" :options="options" multiple placeholder="Multiple" />
    </div>

    <div style="color: var(--tx-text-color-secondary); font-size: 12px;">
      single: {{ value1 }}
    </div>
    <div style="color: var(--tx-text-color-secondary); font-size: 12px;">
      multiple: {{ value2 }}
    </div>
  </div>
</template>

Notes

Single-select modelValue is a path array; multi-select is an array of path arrays.
expandTrigger controls click/hover expansion (in hover mode, clicking non-leaf nodes will not expand).
Async load only triggers when a node has no children and is not marked leaf.

API

TxCascader Props

Prop	Type	Default	Description
`modelValue`	`CascaderValue`	-	Selected value. Single mode uses one path array; multiple mode uses an array of path arrays.
`options`	`CascaderNode[]`	`[]`	Root option tree rendered by the cascader columns.
`multiple`	`boolean`	`false`	Enables selecting multiple leaf paths and renders selected paths as tags.
`disabled`	`boolean`	`false`	Disables the trigger, clear button, node selection, and keyboard open behavior.
`placeholder`	`string`	`'请选择'`	Placeholder text shown when no path is selected.
`searchable`	`boolean`	`true`	Shows a local search input that filters loaded leaf paths by formatted label.
`clearable`	`boolean`	`true`	Shows the clear button when a value is selected and the component is enabled.
`placement`	`PopoverPlacement`	`'bottom-start'`	Placement forwarded to the underlying `TxPopover`.
`dropdownOffset`	`number`	`6`	Offset forwarded to the underlying `TxPopover`.
`dropdownWidth`	`number`	`360`	Width forwarded to the underlying `TxPopover`.
`dropdownMaxWidth`	`number`	`520`	Maximum width forwarded to the underlying `TxPopover`.
`dropdownMaxHeight`	`number`	`340`	Maximum panel height in px.
`expandTrigger`	`'click' \| 'hover' \| 'both'`	`'both'`	Controls how non-leaf nodes expand; `hover` ignores click expansion for branch nodes.
`load`	`(node, level) => Promise<CascaderNode[]>`	-	Lazily loads children for a non-leaf node that does not already provide `children`.

CascaderNode

Field	Type	Description
`value`	`string \| number`	Stable node key used to build selected paths.
`label`	`string`	Text rendered in columns, selected tags, and local search results.
`disabled`	`boolean`	Prevents expanding or selecting this node.
`leaf`	`boolean`	Marks the node as selectable and prevents lazy loading.
`children`	`CascaderNode[]`	Child nodes rendered in the next column when this branch is active.

CascaderValue

Single select: CascaderPath (Array<string | number>)
Multi select: CascaderPath[]

Events

Event	Params	Description
`update:modelValue`	`(v)`	Emitted with the next `CascaderValue` whenever selection or clear changes the value.
`change`	`(v)`	Mirrors value changes for consumers that do not use `v-model`.
`open`	-	Emitted after the dropdown opens.
`close`	-	Emitted after the dropdown closes.

Expose

Name	Type	Description
`open()`	`() => void`	Opens the dropdown.
`close()`	`() => void`	Closes the dropdown.
`toggle()`	`() => void`	Toggles the dropdown open state.
`focus()`	`() => void`	Focuses the trigger element.
`blur()`	`() => void`	Blurs the trigger element.
`clear()`	`() => void`	Clears to `undefined` in single mode or `[]` in multiple mode.
`setValue(v)`	`(v) => void`	Emits `update:modelValue` and `change` with the supplied value.
`getValue()`	`() => any`	Returns the current `modelValue` prop.