Van Cascader

Vant Cascader Component

Cascader component for multi-level data selection, typically used for province-city selection.

When to Invoke

Invoke this skill when:

• User needs to select hierarchical data (e.g., provinces and cities)
• User wants to implement multi-level selection
• User needs to load options asynchronously
• User wants to customize field names
• User asks about cascading selection patterns

Features

• Multi-level Selection: Support for unlimited levels
• Async Options: Load options dynamically
• Custom Field Names: Customize text, value, and children fields
• Custom Styling: Active color customization
• Swipeable: Gesture support for navigation
• Custom Content: Slots for custom rendering

API Reference

Props

Data Structure of CascaderOption

Events

Slots

Usage Examples

Basic Usage

<template>
  <van-field
    v-model="fieldValue"
    is-link
    readonly
    label="Area"
    placeholder="Select Area"
    @click="show = true"
  />
  <van-popup v-model="show" round position="bottom">
    <van-cascader
      v-model="cascaderValue"
      title="Select Area"
      :options="options"
      @close="show = false"
      @finish="onFinish"
    />
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'

const show = ref(false)
const fieldValue = ref('')
const cascaderValue = ref('')

const options = [
  {
    text: 'Zhejiang',
    value: '330000',
    children: [{ text: 'Hangzhou', value: '330100' }],
  },
  {
    text: 'Jiangsu',
    value: '320000',
    children: [{ text: 'Nanjing', value: '320100' }],
  },
]

const selectedOptions }) => {
  show.value = false
  fieldValue.value = selectedOptions.map((option) => option.text).join('/')
}
</script>

Custom Color

<template>
  <van-cascader
    v-model="cascaderValue"
    title="Select Area"
    :options="options"
    active-color="#ee0a24"
    @close="show = false"
    @finish="onFinish"
  />
</template>

Async Options

<template>
  <van-field
    v-model="fieldValue"
    is-link
    readonly
    label="Area"
    placeholder="Select Area"
    @click="show = true"
  />
  <van-popup v-model="show" round position="bottom">
    <van-cascader
      v-model="cascaderValue"
      title="Select Area"
      :options="options"
      @close="show = false"
      @change="onChange"
      @finish="onFinish"
    />
  </van-popup>
</template>

<script setup>
import { ref } from 'vue'
import { closeToast, showLoadingToast } from 'vant'

const show = ref(false)
const fieldValue = ref('')
const cascaderValue = ref('')

const options = ref([
  {
    text: 'Zhejiang',
    value: '330000',
    children: [],
  },
])

const value }) => {
  if (
    value === options.value[0].value &&
    options.value[0].children.length === 0
  ) {
    showLoadingToast('Loading...')
    setTimeout(() => {
      options.value[0].children = [
        { text: 'Hangzhou', value: '330100' },
        { text: 'Ningbo', value: '330200' },
      ]
      closeToast()
    }, 1000)
  }
}

const selectedOptions }) => {
  show.value = false
  fieldValue.value = selectedOptions.map((option) => option.text).join('/')
}
</script>

Custom Field Names

<template>
  <van-cascader
    v-model="code"
    title="Select Area"
    :options="options"
    :field-names="fieldNames"
  />
</template>

<script setup>
import { ref } from 'vue'

const code = ref('')

const fieldNames = {
  text: 'name',
  value: 'code',
  children: 'items',
}

const options = [
  {
    name: 'Zhejiang',
    code: '330000',
    items: [{ name: 'Hangzhou', code: '330100' }],
  },
  {
    name: 'Jiangsu',
    code: '320000',
    items: [{ name: 'Nanjing', code: '320100' }],
  },
]
</script>

Custom Content

<template>
  <van-cascader v-model="code" title="Select Area" :options="options">
    <template #options-top="{ tabIndex }">
      <div class="current-level">Current level is {{ tabIndex + 1 }}</div>
    </template>
  </van-cascader>
</template>

<style>
.current-level {
  font-size: 14px;
  padding: 16px 16px 0;
  color: var(--van-gray-6);
}
</style>

Best Practices

1. Async Loading: Show loading indicator when fetching async data to improve user experience.

2. Field Names: Use field-names prop when your data structure doesn't match the default field names.

3. Performance: For large datasets, consider loading options asynchronously instead of loading all at once.

4. Error Handling: Handle async loading errors gracefully and provide feedback to users.

5. Default Values: Set appropriate default values to improve user experience.

6. Mobile Optimization: The component is optimized for mobile, ensure proper touch interactions.