N Tree Select

n-tree-select Component

The n-tree-select component combines the functionality of a select dropdown with a tree structure, allowing users to select values from hierarchical data. It's ideal for scenarios like organization charts, file system navigation, category selection, and any nested data structure.

When to Use

Use n-tree-select when you need to:

• Hierarchical Selection: Select values from nested/hierarchical data structures
• Category Selection: Choose categories from a multi-level category tree
• Organization Picker: Select departments or teams from an organizational hierarchy
• File/Folder Selection: Navigate and select files from a folder structure
• Multi-Level Filtering: Filter and select from nested option groups

Basic Usage

Basic Tree Select

<template>
  <n-tree-select
    :options="options"
    default-value="Drive My Car"
    @update:value="handleUpdateValue"
  />
</template>

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

const options = [
  {
    label: 'Rubber Soul',
    key: 'Rubber Soul',
    children: [
      { label: 'Drive My Car', key: 'Drive My Car' },
      { label: 'Norwegian Wood', key: 'Norwegian Wood' }
    ]
  },
  {
    label: 'Let It Be',
    key: 'Let It Be',
    children: [
      { label: 'Dig It', key: 'Dig It' },
      { label: 'Let It Be', key: 'Let It Be' }
    ]
  }
]

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

Multiple Selection

<template>
  <n-tree-select
    multiple
    :options="options"
    :default-value="['Norwegian Wood']"
    @update:value="handleUpdateValue"
  />
</template>

Checkable with Cascade

<template>
  <n-tree-select
    multiple
    cascade
    checkable
    :options="options"
    :default-value="['Norwegian Wood']"
  />
</template>

Filterable

<template>
  <n-space vertical>
    <n-tree-select
      filterable
      :options="options"
      default-value="Drive My Car"
      clearable
    />
    <n-tree-select
      multiple
      checkable
      filterable
      :clear-filter-after-select="false"
      :options="options"
      :default-value="['Norwegian Wood']"
      clearable
    />
  </n-space>
</template>

Show Line

<template>
  <n-tree-select
    show-line
    default-expand-all
    :options="options"
    default-value="Drive My Car"
  />
</template>

API Reference

Props

TreeSelectOption Properties

Events

Slots

Methods

Common Patterns

Async Loading

<template>
  <n-tree-select
    v-model:value="value"
    multiple
    checkable
    :options="options"
    :cascade="cascade"
    :check-strategy="checkStrategy"
    :show-path="showPath"
    :allow-checking-not-loaded="cascade"
    :on-load="handleLoad"
  />
</template>

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

const value = ref([])
const options = ref([
  {
    label: 'Root',
    key: 'root',
    children: [
      { label: 'Loading...', key: 'child1', isLeaf: false }
    ]
  }
])

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

Custom Field Names

<template>
  <n-tree-select
    :options="options"
    default-value="Drive My Car"
    label-field="whateverLabel"
    key-field="whateverKey"
    children-field="whateverChildren"
  />
</template>

<script setup>
const options = [
  {
    whateverLabel: 'Album',
    whateverKey: 'album',
    whateverChildren: [
      { whateverLabel: 'Song 1', whateverKey: 'song1' }
    ]
  }
]
</script>

Check Strategy Demo

<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-tree-select
      multiple
      cascade
      checkable
      :check-strategy="checkStrategy"
      :options="options"
      :default-value="['Dig It', 'go']"
    />
  </n-space>
</template>

File Picker Simulation

<template>
  <n-tree-select
    block-line
    :options="fileOptions"
    :override-default-node-click-behavior="override"
  />
</template>

<script setup>
const override = ({ option }) => {
  if (option.isFolder) {
    return 'toggleExpand'
  }
  return 'toggleSelect'
}

const fileOptions = [
  {
    label: 'Documents',
    key: 'docs',
    isFolder: true,
    children: [
      { label: 'report.pdf', key: 'report', isFolder: false }
    ]
  }
]
</script>

Validation Status

<template>
  <n-space vertical>
    <n-tree-select status="warning" placeholder="Warning state" />
    <n-tree-select status="error" placeholder="Error state" />
  </n-space>
</template>

Custom Rendering

<template>
  <n-tree-select
    :options="options"
    :render-label="renderLabel"
    :render-prefix="renderPrefix"
  />
</template>

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

const renderLabel = ({ option, checked, selected }) => {
  return h('span', { style: { fontWeight: selected ? 'bold' : 'normal' } }, option.label)
}

const renderPrefix = ({ option }) => {
  return h('span', option.children ? '📁' : '📄')
}

const options = [
  {
    label: 'Folder',
    key: 'folder',
    children: [
      { label: 'File', key: 'file' }
    ]
  }
]
</script>

Best Practices

Performance

1. Virtual Scroll: Keep virtual-scroll enabled (default) for large tree structures.

2. Lazy Loading: Use async loading with on-load for deeply nested trees to improve initial load time.

3. Limit Expanded Nodes: Avoid default-expand-all for very large trees; use default-expanded-keys instead.

User Experience

1. Check Strategy: Choose appropriate check-strategy:

   • 'all': Show all selected nodes (default)
   • 'parent': Show only parent when all children selected
   • 'child': Show only leaf nodes

2. Show Path: Enable show-path for deep hierarchies to help users understand the selection context.

3. Filterable: Enable filterable for trees with many nodes to help users find options quickly.

4. Clearable: Enable clearable to allow users to easily reset their selection.

Data Handling

1. Unique Keys: Ensure each option has a unique key property.

2. isLeaf Property: Set isLeaf: false for nodes that will have children loaded asynchronously.

3. Custom Field Names: Use key-field, label-field, and children-field when your data doesn't match the default structure.

4. Cascade Selection: Be careful with cascade and allow-checking-not-loaded when using async loading, as values may be incomplete.

Form Integration

1. Validation Status: Use the status prop to show validation feedback.

2. Disabled State: Use disabled to prevent selection in read-only scenarios.

3. Loading State: Show loading state during async operations.