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

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.