N Auto Complete

n-auto-complete Component

The n-auto-complete component is an input field with autocomplete functionality that provides search hints and likely options as users type. It supports grouped options, custom input elements, and various selection behaviors.

When to Use

Use n-auto-complete when you need to:

• Provide search hints or suggestions based on user input
• Create email input fields with domain suggestions
• Build search inputs with autocomplete options
• Offer likely options while users are typing
• Create custom input elements with autocomplete (e.g., textarea)
• Implement append-mode autocomplete for continuous input

Basic Usage

Basic Autocomplete

<template>
  <n-auto-complete
    v-model:value="value"
    :input-props="{
      autocomplete: 'disabled',
    }"
    :options="options"
    placeholder="Email"
    clearable
  />
</template>

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

const value = ref('')

const options = computed(() => {
  return ['@gmail.com', '@outlook.com', '@yahoo.com'].map(suffix => ({
    label: value.value.split('@')[0] + suffix,
    value: value.value.split('@')[0] + suffix
  }))
})
</script>

Different Sizes

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

Grouped Options

<template>
  <n-auto-complete
    v-model:value="value"
    :options="options"
    placeholder="Search..."
  />
</template>

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

const value = ref('')

const options = [
  {
    type: 'group',
    label: 'Cities',
    key: 'cities',
    children: [
      { label: 'Beijing', value: 'beijing' },
      { label: 'Shanghai', value: 'shanghai' }
    ]
  },
  {
    type: 'group',
    label: 'Countries',
    key: 'countries',
    children: [
      { label: 'China', value: 'china' },
      { label: 'USA', value: 'usa' }
    ]
  }
]
</script>

API Reference

Props

AutoCompleteOption Properties

AutoCompleteGroupOption Properties

Events

Slots

Methods

Common Patterns

Custom Input Element (Textarea)

<template>
  <n-auto-complete v-model:value="value" :options="options">
    <template #default="{ handleInput, handleBlur, handleFocus, value: slotValue }">
      <n-input
        type="textarea"
        :value="slotValue"
        placeholder="Email"
        @input="handleInput"
        @focus="handleFocus"
        @blur="handleBlur"
      />
    </template>
  </n-auto-complete>
</template>

Conditional Menu Display

<template>
  <n-auto-complete
    v-model:value="value"
    :options="options"
    placeholder="Input 'a' to show menu"
    :get-show="getShow"
  />
</template>

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

const value = ref('')

const getShow = (value) => {
  return value.includes('a')
}
</script>

Append Mode

<template>
  <n-space vertical>
    <n-auto-complete
      v-model:value="value"
      :options="options"
      :append="false"
      placeholder="Select and overwrite"
    />
    <n-auto-complete
      v-model:value="appendValue"
      :options="appendOptions"
      :append="true"
      :get-show="getShow"
      placeholder="Select and append"
    />
  </n-space>
</template>

Custom Label Rendering

<template>
  <n-auto-complete
    v-model:value="value"
    :options="options"
    placeholder="Email"
    :render-label="renderLabel"
  />
</template>

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

const renderLabel = (option) => {
  return h('span', { style: { color: '#18a058' } }, option.label)
}
</script>

Validation Status

<template>
  <n-space vertical>
    <n-auto-complete status="warning" placeholder="Warning status" />
    <n-auto-complete status="error" placeholder="Error status" />
  </n-space>
</template>

Async Options with Loading

<template>
  <n-auto-complete
    v-model:value="value"
    :options="options"
    :loading="loading"
    placeholder="Search..."
    @input="handleInput"
  />
</template>

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

const value = ref('')
const options = ref([])
const loading = ref(false)

const handleInput = async (val) => {
  if (!val) {
    options.value = []
    return
  }
  loading.value = true
  const results = await fetchSuggestions(val)
  options.value = results
  loading.value = false
}
</script>

Best Practices

1. Use input-props to disable browser autocomplete: Set autocomplete: 'disabled' in input-props to prevent browser autocomplete from interfering.

2. Choose appropriate selection behavior: Use blur-after-select for single-selection scenarios, or clear-after-select when you want users to make another selection.

3. Use get-show for conditional display: Control when the dropdown appears based on input content for better UX.

4. Leverage append mode for continuous input: When users need to add multiple items, use append: true to append instead of replace.

5. Implement debouncing for async options: When fetching options asynchronously, debounce the input handler to reduce API calls.

6. Use render-label for custom styling: Customize option appearance while maintaining consistent behavior.

7. Handle empty states gracefully: Use the empty slot to provide helpful feedback when no options match.

8. Consider keyboard navigation: The component supports keyboard navigation by default - ensure your custom implementations maintain this accessibility.