N Select

n-select Component

The n-select component is a powerful dropdown selection component in Naive UI that supports single selection, multiple selection, searchable filtering, remote data loading, option grouping, and virtual scrolling for large datasets.

When to Use

Use n-select when you need to:

• Single Selection: Allow users to select one option from a dropdown list
• Multiple Selection: Enable users to select multiple options with tag display
• Searchable Dropdowns: Provide filtering capabilities for large option lists
• Remote Data Loading: Fetch options asynchronously from a server
• Grouped Options: Organize options into logical groups
• Tag Input: Create a tag input box for user-defined entries

Basic Usage

Single Select

<template>
  <n-select v-model:value="selectedValue" :options="options" />
</template>

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

const selectedValue = ref(null)
const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  { label: 'Option 3', value: '3' }
]
</script>

Multiple Select

<template>
  <n-select v-model:value="selectedValues" multiple :options="options" />
</template>

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

const selectedValues = ref([])
const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  { label: 'Option 3', value: '3' }
]
</script>

Filterable Select

<template>
  <n-select
    v-model:value="selectedValue"
    filterable
    placeholder="Search and select..."
    :options="options"
  />
</template>

Disabled State

<template>
  <n-select v-model:value="selectedValue" disabled :options="options" />
</template>

Different Sizes

<template>
  <n-space vertical>
    <n-select v-model:value="value" size="tiny" :options="options" />
    <n-select v-model:value="value" size="small" :options="options" />
    <n-select v-model:value="value" size="medium" :options="options" />
    <n-select v-model:value="value" size="large" :options="options" />
  </n-space>
</template>

API Reference

Props

Option Properties

SelectOption

SelectGroupOption

Events

Slots

Methods

Common Patterns

Remote Search

<template>
  <n-select
    v-model:value="selectedValue"
    filterable
    remote
    :options="options"
    :loading="loading"
    placeholder="Search..."
    @search="handleSearch"
  />
</template>

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

const selectedValue = ref(null)
const options = ref([])
const loading = ref(false)

const handleSearch = async (query) => {
  if (!query) return
  
  loading.value = true
  try {
    const response = await fetch(`/api/search?q=${query}`)
    const data = await response.json()
    options.value = data.map(item => ({
      label: item.name,
      value: item.id
    }))
  } finally {
    loading.value = false
  }
}
</script>

Group Options

<template>
  <n-select v-model:value="selectedValue" :options="groupedOptions" />
</template>

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

const selectedValue = ref(null)
const groupedOptions = [
  {
    type: 'group',
    label: 'Group A',
    key: 'group-a',
    children: [
      { label: 'Option 1', value: '1' },
      { label: 'Option 2', value: '2' }
    ]
  },
  {
    type: 'group',
    label: 'Group B',
    key: 'group-b',
    children: [
      { label: 'Option 3', value: '3' },
      { label: 'Option 4', value: '4' }
    ]
  }
]
</script>

Tag Input Mode

<template>
  <n-select
    v-model:value="tags"
    filterable
    multiple
    tag
    :show-arrow="false"
    :show="false"
    placeholder="Type and press enter to add tags"
  />
</template>

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

const tags = ref([])
</script>

Custom Field Names

<template>
  <n-select
    v-model:value="selectedValue"
    label-field="name"
    value-field="id"
    children-field="items"
    :options="customOptions"
  />
</template>

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

const selectedValue = ref(null)
const customOptions = [
  { name: 'Item 1', id: 1 },
  { name: 'Item 2', id: 2 }
]
</script>

Infinite Scroll Loading

<template>
  <n-select
    :options="options"
    :reset-menu-on-options-change="false"
    @scroll="handleScroll"
  />
</template>

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

const options = ref([])
const page = ref(1)

const loadMore = async () => {
  const newOptions = await fetchOptions(page.value)
  options.value = [...options.value, ...newOptions]
  page.value++
}

const handleScroll = (e) => {
  const { scrollTop, scrollHeight, clientHeight } = e.target
  if (scrollHeight - scrollTop <= clientHeight + 50) {
    loadMore()
  }
}

loadMore()
</script>

Custom Option Rendering

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

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

const renderLabel = (option, selected) => {
  return h('div', { style: { display: 'flex', alignItems: 'center' } }, [
    h('span', { style: { marginRight: '8px' } }, option.label),
    selected && h('span', { style: { color: 'green' } }, '✓')
  ])
}

const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' }
]
</script>

Best Practices

Performance

1. Use Virtual Scroll: For large datasets (100+ options), keep virtual-scroll enabled (default) for optimal performance.

2. Limit Options: When possible, limit the number of options displayed at once, especially for remote search scenarios.

3. Debounce Remote Search: Add debouncing to remote search handlers to reduce API calls:

<script setup>
import { ref } from 'vue'
import { useDebounceFn } from '@vueuse/core'

const handleSearch = useDebounceFn(async (query) => {
  // API call here
}, 300)
</script>

User Experience

1. Provide Clear Feedback: Use loading state during async operations to inform users that data is being fetched.

2. Use Meaningful Placeholders: Provide clear placeholder text that guides users on what to select or search.

3. Consider Max Tag Count: In multiple selection mode, use max-tag-count="responsive" or a specific number to prevent layout issues when many items are selected.

4. Enable Clearable: Allow users to easily clear their selection, especially for single-select scenarios.

Data Handling

1. Unique Values: Ensure each option has a unique value property to prevent unexpected behavior.

2. Handle Fallback Options: Decide whether to show fallback options for values without matching options. Set fallback-option="false" to automatically clear invalid values.

3. Custom Field Mapping: Use label-field, value-field, and children-field props when working with backend data that doesn't match the default field names.

Accessibility

1. Keyboard Navigation: Keep keyboard enabled (default) to allow users to navigate options using arrow keys.

2. Focus Management: Use the focus and blur methods for programmatic control when needed.

Form Integration

1. Validation Status: Use the status prop to show validation feedback (success, warning, error).

2. Disabled State: Use disabled prop to prevent selection when the field should be read-only.

3. Default Values: Set appropriate default-value for uncontrolled usage scenarios.