Preview Updated 2026-05-10

Cascader

Column-by-column expanding picker for hierarchical options — path-based selection, common for region / department / category filters.

Basic usage

options is a tree; clicking a leaf node selects the entire path. v-model / value is a string[] — the sequence of values from root to the selected node.

背景

选中：(无)

src/App.vue

<script setup lang="ts">
import { ref } from 'vue';
import { CfCascader, type CascaderOption } from '@chufix-design/vue';

const options: CascaderOption[] = [
  {
    value: 'cn',
    label: '中国',
    children: [
      {
        value: 'sh',
        label: '上海',
        children: [
          { value: 'pudong', label: '浦东新区' },
          { value: 'huangpu', label: '黄浦区' },
        ],
      },
      {
        value: 'bj',
        label: '北京',
        children: [
          { value: 'haidian', label: '海淀区' },
          { value: 'chaoyang', label: '朝阳区' },
        ],
      },
    ],
  },
  {
    value: 'us',
    label: '美国',
    children: [
      { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
    ],
  },
];

const value = ref<string[]>([]);
</script>
<template>
  <div style="display: flex; flex-direction: column; gap: 8px; align-items: flex-start;">
    <CfCascader v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3);">选中：<code>{{ value.join(' / ') || '(无)' }}</code></span>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CfCascader } from '@chufix-design/vue';

const options= [
  {
    value: 'cn',
    label: '中国',
    children: [
      {
        value: 'sh',
        label: '上海',
        children: [
          { value: 'pudong', label: '浦东新区' },
          { value: 'huangpu', label: '黄浦区' },
        ],
      },
      {
        value: 'bj',
        label: '北京',
        children: [
          { value: 'haidian', label: '海淀区' },
          { value: 'chaoyang', label: '朝阳区' },
        ],
      },
    ],
  },
  {
    value: 'us',
    label: '美国',
    children: [
      { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
    ],
  },
];

const value = ref<string[]>([]);
</script>
<template>
  <div style="display: flex; flex-direction: column; gap: 8px; align-items: flex-start;">
    <CfCascader v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3);">选中：<code>{{ value.join(' / ') || '(无)' }}</code></span>
  </div>
</template>

import { useState } from 'react';
import { CfCascader } from '@chufix-design/react';

export default function Demo() {
  const [value, setValue] = useState(ref<string[]>([]));
  return (
    <>
      <CfCascader value={value} onChange={setValue} options={options} clearable />
    </>
  );
}

API

Prop	Type	Default	Description
`options`	`CascaderOption[]`	`—`	Cascading option tree
`value` / `modelValue`	`string[]`	`—`	Controlled selected path
`defaultValue`	`string[]`	`[]`	Uncontrolled initial value
`placeholder`	`string`	`'Please select'`	Placeholder when nothing is selected
`separator`	`string`	`' / '`	Path separator shown in the trigger
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Trigger size
`disabled`	`boolean`	`false`	Disabled
`clearable`	`boolean`	`false`	Show a clear button

CascaderOption

Field	Type	Description
`value`	`string`	Unique value
`label`	`string`	Display text
`disabled`	`boolean`	Disable this option
`children`	`CascaderOption[]`	Next-level options; omit to mark as a leaf

Events: onChange(path: string[]) — fires when the selected path changes.