Vue Autosuggest Component

Common errors

• Error: Cannot read properties of null (reading 'data')

  cause The `suggestions` prop was provided with a structure where `data` within a suggestion object was `null`, e.g., `suggestions: [{ data: null }]`.
  fix Ensure that the `data` property of all suggestion objects is an array, even if empty, and not `null`. Upgrade to `vue-autosuggest@2.0.4` or higher to handle this gracefully.

• Input props (e.g., placeholder, id) are not updating when their values change.

  cause The `inputProps` object passed to the component was not reactive in older versions, preventing dynamic updates to the underlying input element's attributes.
  fix Update to `vue-autosuggest@2.0.3` or a newer version to enable reactivity for `inputProps`.

• Section slots disappear or render incorrectly, especially after data updates.

  cause In versions prior to 2.1.1, the `v-for` key used for rendering section slots might not have been unique, leading to incorrect re-rendering behavior.
  fix Upgrade to `vue-autosuggest@2.1.1` or a newer version, which includes a fix that ensures unique keys for section slots.

• ARIA warnings in the console about `aria-labelledby` referencing non-existent elements or `role='combobox'` being misplaced.

  cause Inconsistencies with the WAI-ARIA specification, particularly regarding attribute placement and element referencing, in versions prior to 2.1.2.
  fix Update to `vue-autosuggest@2.1.2` or later. These versions include fixes for ARIA attribute conformance, ensuring correct accessibility implementation.

Warnings

• breaking Version 2.0.0 introduced significant breaking changes, including built-in `v-model` support, which replaced the `initialValue` prop. Several old events (`onInputChange`, `onClick`, `onBlur`, `onFocus`, `onSelected`) were deprecated and removed in favor of more intuitive native `<input />` events and new custom events.
  Fix: Migrate to `v-model` for input binding. Replace deprecated event listeners with `@input`, `@focus`, `@blur`, `@selected` (for item selection), `@opened`, and `@closed` (for suggestion list visibility).
• gotcha Versions 2.2.0 and 2.1.2 implemented WAI-ARIA compliance updates, which involved moving `role="combobox"` and `aria-controls` attributes from the input to a surrounding wrapper. If your styling or JavaScript relied on the precise location of these attributes, it might be affected.
  Fix: Review custom CSS or JS that targets WAI-ARIA attributes (`role="combobox"`, `aria-controls`) and adjust selectors to account for their new positions on wrapper elements. Rely on provided CSS classes for styling instead.
• gotcha In versions prior to 2.0.4, providing `suggestions` data containing `null` values (e.g., `suggestions: [{data: null}]`) could lead to cryptic runtime errors.
  Fix: Ensure that the `data` array within each suggestion object is never `null`. Filter out `null` data entries before passing them to the `suggestions` prop, or update to `v2.0.4` or newer.
• gotcha In versions prior to 2.0.3, the `inputProps` were not reactive, meaning changes to the `inputProps` object after initial rendering would not be reflected in the component's input element.
  Fix: Update to `v2.0.3` or newer to ensure `inputProps` reactivity. If updating is not an option, consider using a `key` prop on the `vue-autosuggest` component to force re-render when `inputProps` change.
• gotcha In versions prior to 2.0.1, the `autocomplete="off"` attribute set by default might be unset on subsequent re-renders, potentially causing browser autocomplete features to interfere with the autosuggest.
  Fix: Update to `v2.0.1` or newer. If you cannot update, explicitly set `inputProps.autocomplete = 'off'` to enforce the behavior.

Install

• npm install vue-autosuggest npm
• yarn add vue-autosuggest yarn
• pnpm add vue-autosuggest pnpm

Imports

• VueAutosuggest (local)
  wrong:

  import VueAutosuggest from 'vue-autosuggest';

  correct:

  import { VueAutosuggest } from 'vue-autosuggest';

  Use named import for local component registration in Vue components.
• VueAutosuggest (global)
  wrong:

  const VueAutosuggest = require('vue-autosuggest');

  correct:

  import VueAutosuggest from 'vue-autosuggest';
  Vue.use(VueAutosuggest);

  For global registration via `Vue.use()`, the default export is typically used. CommonJS `require()` is not supported for modern Vue component usage.
• VueAutosuggest (types)

  import type { VueAutosuggest } from 'vue-autosuggest';

  While not explicitly documented, for TypeScript users, importing the type can be useful for strict checking, although the component itself is designed for Vue 2.

Quickstart

This quickstart initializes a Vue app with the VueAutosuggest component, demonstrating basic setup with static suggestions, input handling, and selection. It showcases both global registration and local component usage patterns.

import Vue from 'vue';
import { VueAutosuggest } from 'vue-autosuggest';

Vue.use(VueAutosuggest); // Register globally, or import locally into a component

new Vue({
  el: '#app',
  components: {
    VueAutosuggest
  },
  data() {
    return {
      query: '',
      selectedItem: null,
      suggestionsData: [{
        data: ['Frodo', 'Samwise', 'Gandalf', 'Galadriel', 'Faramir', 'Éowyn']
      }]
    };
  },
  methods: {
    onInputChange(input) {
      this.query = input;
      console.log('Input changed:', input);
      // In a real application, you would typically fetch suggestions from an API here
      // and update this.suggestionsData based on the input.
    },
    selectHandler(selected) {
      this.selectedItem = selected.item;
      console.log('Item selected:', selected.item);
    },
    clickHandler(event) {
      console.log('Input clicked:', event);
    },
  },
  template: `
    <div class="app-container">
      <h3>Vue Autosuggest Example</h3>
      <vue-autosuggest
          :suggestions="suggestionsData"
          :input-props="{id:'autosuggest__input', placeholder:'Search characters...'}"
          @input="onInputChange"
          @selected="selectHandler"
          @click="clickHandler"
      >
        <template slot-scope="{suggestion}">
          <span class="my-suggestion-item">{{suggestion.item}}</span>
        </template>
      </vue-autosuggest>
      <p v-if="selectedItem" style="margin-top: 15px;">Selected: <strong>{{ selectedItem }}</strong></p>
      <p style="margin-top: 10px;">Current input: <em>{{ query }}</em></p>
    </div>
  `
});