A Vue Autocomplete component with accessibility and simplicity in mind.

Related tags

Autocomplete javascript autocomplete vue accessibility typeahead autosuggest
Overview

Build Status

VueCompleter

A Vue Autocomplete component with accessibility and simplicity in mind.

Installation

npm install vue-completer

or

yarn add vue-completer

Usage

"> 
<template>
    <VueCompleter
      :limit="5"
      :suggestions="suggestions"
      @selectionChange="onSelectionChange"
      v-model="query"
    ></VueCompleter>
</template>

<script>
  import VueCompleter from 'vue-completer';

  export default {
    ...
    components: {
        VueCompleter
    }
    ...
  };
</script>

Examples

Props

Property Description Type Required Default
suggestions An array of suggestions to be rendered. This can be as simple as an array of string values or deeply nested objects. Array Yes
getSuggestionValue Used to determine the value to be rendered in the suggestion list. *Required for non-string suggestions. i.e. an array of suggestion objects. Function No*
limit The number of suggestions to render. Number No 5
highlightCycle Used to stop at the top & bottom suggestions when using the up & down arrow keys. Boolean No true
selectOnBlur Used to automatically select the highlighted suggestion on blur. Boolean No True
highlightFirstSuggestion Used to automatically highlight the first suggestion when the suggestion list is rendered. Boolean No True
suggestionsOnFocus Used to display the suggestion list on initial focus. Boolean No True
namespace CSS namespace to use for class & id selectors. String No

suggestions

The supplied suggestions array can be as simple as an array of strings or more complex as in an array of objects. When using objects, use the getSuggestionValue prop to tell VueCompleter how to render the suggestions.

Simple:

dataset: [
  'Jacob',
  'Joanne',
  'John',
  'Jonathon',
  'Logan',
  'Thomas',
  'Tim',
  'Tom',
],

Complex:

dataset: [
  {
    code: '93473',
    value: 'Jacob',
    position: {
      title: 'Director',
      department: 'Engineering',
    },
  },
  {
    code: '23674',
    value: 'Janet',
    position: {
      title: 'Senior Software Engineer',
      department: 'Engineering',
    },
  },
  {
    code: '68684',
    value: 'James',
    position: {
      title: 'Software Engineer',
      department: 'Engineering',
    },
  },
]

getSuggestionValue

When using a more complex suggestion, like an object, VueCompleter needs to know how to render suggestions. For example, using the complex example above:

"> 
<template>
    <VueCompleter
      :suggestions="suggestions"
      :getSuggestionValue="getSuggestionValue"
      @selectionChange="onSelectionChange"
      v-model="query"
    ></VueCompleter>
</template>

<script>
export default {
  ...
  methods: {
    getSuggestionValue(suggestion) {
      return suggestion.value;
    },
  }
}
</script>

Slots

For more control over the rendered suggestions, the suggestion default scoped slot is available. This allows the use of any markup or component you want.

"> 
<VueCompleter
  :suggestions="suggestions"
  @selectionChange="onSelectionChange"
  v-model="query"
>
  <template v-slot="{ suggestion }">
    <EmployeeSuggestion :suggestion="suggestion" />
  </template>
</VueCompleter>

EmployeeSuggestion.vue

{{ props.suggestion.value }}
{{ props.suggestion.position.title }}
{{ props.suggestion.position.department }}
"> 
<template functional>
  <div class="employee-suggestion">
    <div class="employee-suggestion--left">
      <div class="employee-name">
        {{ props.suggestion.value }}
      </div>
      <div class="employee-title">{{ props.suggestion.position.title }}</div>
    </div>
    <div class="employee-suggestion--right">
      <div class="employee-department">
        {{ props.suggestion.position.department }}
      </div>
    </div>
  </div>
</template>

<script>
export default {
  props: ['suggestion'],
};
</script>

Additionally, you can use the input named slot for providing your own custom input element. This can be useful when working with UI frameworks such as Bootstrap.