N Cascader

n-cascader Component

The n-cascader component is used to display and select tree-structured data. It supports single and multiple selection modes, async data loading, filtering, and various check strategies for flexible selection behavior.

When to Use

Use n-cascader when you need to:

• Select from hierarchical data (e.g., region selection, category selection)
• Build multi-level navigation or selection interfaces
• Support both single and multiple selection in tree structures
• Load data asynchronously as users navigate
• Filter through large hierarchical datasets
• Display selected values as paths or individual items

Basic Usage

Single Selection

<template>
  <n-cascader
    v-model:value="value"
    placeholder="Select option"
    :options="options"
    check-strategy="child"
    @update:value="handleUpdateValue"
  />
</template>

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

const value = ref(null)

const options = [
  {
    label: 'Asia',
    value: 'asia',
    children: [
      {
        label: 'China',
        value: 'china',
        children: [
          { label: 'Beijing', value: 'beijing' },
          { label: 'Shanghai', value: 'shanghai' }
        ]
      }
    ]
  }
]

const handleUpdateValue = (value) => {
  console.log(value)
}
</script>

Multiple Selection

<template>
  <n-cascader
    v-model:value="value"
    multiple
    placeholder="Select options"
    clearable
    :options="options"
    cascade
    check-strategy="all"
    @update:value="handleUpdateValue"
  />
</template>

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

const value = ref([])
const options = []
</script>

Different Sizes

<template>
  <n-space vertical>
    <n-cascader
      v-model:value="value"
      placeholder="Small"
      :options="options"
      size="small"
    />
    <n-cascader
      v-model:value="value"
      placeholder="Medium (default)"
      :options="options"
      size="medium"
    />
    <n-cascader
      v-model:value="value"
      placeholder="Large"
      :options="options"
      size="large"
    />
  </n-space>
</template>

API Reference

Props

CascaderOption Properties

Events

Slots

Methods

Common Patterns

Async Loading

<template>
  <n-cascader
    v-model:value="value"
    placeholder="Select option"
    :options="options"
    remote
    :on-load="handleLoad"
  />
</template>

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

const value = ref(null)
const options = ref([
  {
    label: 'Root',
    value: 'root'
  }
])

const handleLoad = async (option) => {
  const children = await fetchChildren(option.value)
  option.children = children
}
</script>

Check Strategies

<template>
  <n-space vertical>
    <n-radio-group v-model:value="checkStrategy">
      <n-radio-button value="all">All</n-radio-button>
      <n-radio-button value="parent">Parent</n-radio-button>
      <n-radio-button value="child">Child</n-radio-button>
    </n-radio-group>

    <n-cascader
      multiple
      cascade
      :check-strategy="checkStrategy"
      :options="options"
    />
  </n-space>
</template>

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

const checkStrategy = ref('all')
</script>

Custom Field Names

<template>
  <n-cascader
    :options="options"
    label-field="name"
    value-field="id"
    children-field="items"
  />
</template>

<script setup>
const options = [
  {
    name: 'Category',
    id: 'cat1',
    items: [
      { name: 'Sub Category', id: 'sub1' }
    ]
  }
]
</script>

Filterable with Hover Trigger

<template>
  <n-cascader
    v-model:value="value"
    placeholder="Select option"
    :options="options"
    :expand-trigger="'hover'"
    :filterable="true"
  />
</template>

Custom Label Rendering

<template>
  <n-cascader
    v-model:value="value"
    :options="options"
    :render-label="renderLabel"
  />
</template>

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

const renderLabel = (option) => {
  return h('span', { style: { fontWeight: 'bold' } }, option.label)
}
</script>

Large Data Handling

<template>
  <n-cascader
    v-model:value="value"
    placeholder="Select from large dataset"
    :options="options"
    :virtual-scroll="true"
    :filterable="true"
  />
</template>

Using Methods via Ref

<template>
  <n-space item-style="display: flex; align-item: center;">
    <n-button @click="handleClick">Focus then blur in 1 second</n-button>
    <n-cascader ref="cascaderRef" style="width: 200px" />
  </n-space>
</template>

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

const cascaderRef = ref(null)

const handleClick = () => {
  cascaderRef.value?.focus()
  setTimeout(() => {
    cascaderRef.value?.blur()
  }, 1000)
}
</script>

Best Practices

1. Choose appropriate check-strategy: Use 'child' when you only want leaf nodes selected, 'parent' for cleaner display when all children are selected, and 'all' for full flexibility.

2. Use cascade wisely: Enable cascade when parent-child selection should be linked. Disable it for independent selection behavior.

3. Implement async loading for large datasets: Use remote and on-load for lazy loading to improve initial render performance.

4. Enable virtual-scroll for large data: Keep virtual-scroll: true (default) for smooth scrolling with thousands of options.

5. Customize field names for backend data: Use label-field, value-field, and children-field to match your API response structure without data transformation.

6. Use show-path for clarity: Keep show-path: true to show the full selection path, helping users understand their selection context.

7. Handle disabled nodes carefully: When using allow-checking-not-loaded, be aware of consistency between frontend and backend checking logic.

8. Use max-tag-count: 'responsive': For multiple selection with many items, this keeps the display clean and responsive.