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

• Simple Suggestions
• Complex Suggestions w/ Custom Slot
• Custom Input

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

<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.

<VueCompleter
  :suggestions="suggestions"
  @selectionChange="onSelectionChange"
  v-model="query"
>
  <template v-slot:input="{ inputListeners, inputAttrs }">
    <b-form-input
      v-on="inputListeners"
      v-bind="inputAttrs"
      ...
  </template>
</VueCompleter>

Events

Event	Description
selectionChange	Fired when the suggestion selection has been changed. i.e. A user manually makes a selection from the list. This event is also fired once on input if a selection has been previously.

Classes & Styling

VueCompleter does not provide ANY styles out of the box. See the examples for ideas.

Selectors will be prepended with the value provided in the namespace prop. For example, a namespace of "employeelist" will result in employeelist-autocomplete__container.

Class	Description
autocomplete__container	Top level container
autocomplete__input	The input element
autocomplete__suggestion-results-container	Suggestion list container
autocomplete__suggestion-results-list	Suggestion list
autocomplete__suggestion-results-item	Suggestion list item
autocomplete__suggestion-results-item--highlighted	Currently highlighted suggestion list item
autocomplete__suggestion-query-match	Matched input within the rendered suggestion list item

Additional Information

Any additional events or attributes are inherited directly by the native input element.

VueCompleter supports the use of v-model. Note: when a selection is made, in addition to the selectionChange event an input event is also fired to update the value of v-model using the appropriate suggestion value.