Vue Suggestion List Input

Common errors

• [Vue warn]: Unknown custom element: <vue-suggestion> - did you register the component correctly? For recursive components, make sure to provide the 'name' option.

  cause The `VueSuggestion` component has not been registered with Vue, either globally via `Vue.use()` or locally within a parent component's `components` option.
  fix To register globally: `import VueSuggestion from 'vue-suggestion'; Vue.use(VueSuggestion);`. To register locally: `import { VueSuggestion } from 'vue-suggestion'; export default { components: { VueSuggestion } };`

• TypeError: Cannot read properties of undefined (reading 'name')

  cause The `setLabel` prop or the `itemTemplate` expects a specific property (e.g., `name`) on the `item` object, but the `items` array contains objects with a different structure or `item` is undefined.
  fix Verify that the `items` array elements have the properties expected by `setLabel` and your `itemTemplate`. Adjust `setLabel` and `itemTemplate` to match the actual data structure of your `items`.

• Suggestion list appears empty or doesn't update when typing.

  cause The `inputChange` event handler is not correctly updating the component's `items` data property, or the filtering logic within `inputChange` is incorrect, resulting in an empty or unfiltered `items` array.
  fix Ensure that within your `@changed` event handler, `this.items` is actively updated with the filtered results based on the input `text`. Double-check your filtering logic or data fetching mechanism.

Warnings

• breaking Version 2.0.0 was a complete rewrite of the codebase, changing the build tool from Rollup to Vue CLI and reorganizing component props (e.g., `inputOptions`, `suggestionOptions`). Existing v1.x implementations will require significant refactoring.
  Fix: Refer to the official documentation for v2.0.0+ to understand the new API and prop structure. Migrate prop usage from individual props to the new organized `inputOptions` and `suggestionOptions` objects.
• breaking Version 1.0.0 transitioned the build tool from PoiJS to Vue CLI. While less impactful for direct users, internal build processes or highly customized integrations based on pre-1.0.0 build artifacts might be affected.
  Fix: Update build configurations if they were tightly coupled to the previous build system. For most users, this change will be transparent.
• gotcha The `vue-suggestion` library is primarily built for Vue 2. Using it in a Vue 3 project will likely lead to incompatibility issues and may require a compatibility layer (`@vue/compat`) or manual adaptation, as Vue 3 introduces breaking changes to the reactivity system and component lifecycle.
  Fix: For Vue 3 projects, consider using a Vue 3 native autocomplete component or migrating with `@vue/compat`. This library is not officially Vue 3 compatible out of the box.
• gotcha The component provides basic markup but relies heavily on custom CSS for styling the input, suggestion list, and active item states. Without custom styles, the component's appearance will be minimal and may not integrate well with the application's design.
  Fix: Implement custom CSS for the `.vue-suggestion` and its child classes (`.vs__list`, `.vs__list-item`, `.vs__item-active`) to match your application's design system. Refer to the provided CSS examples in the documentation.
• gotcha The component does not perform data filtering itself. The responsibility of filtering the `items` array based on user input lies with the consumer, typically within the `@changed` event handler. If the `items` prop is not updated correctly, the suggestion list will not show relevant results.
  Fix: Ensure that the `inputChange` method (or similar handler for the `@changed` event) correctly filters the `items` data property, or fetches new data, based on the provided `text` argument.

Install

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

Imports

• VueSuggestion
  wrong:

  import { VueSuggestion } from 'vue-suggestion'; Vue.use(VueSuggestion);

  correct:

  import VueSuggestion from 'vue-suggestion'; Vue.use(VueSuggestion);

  For global component registration, `VueSuggestion` is a default export intended for `Vue.use()`.
• VueSuggestion
  wrong:

  import VueSuggestion from 'vue-suggestion';

  correct:

  import { VueSuggestion } from 'vue-suggestion';

  For local component registration, `VueSuggestion` is a named export. It should be imported directly and added to the `components` option.
• itemTemplate
  wrong:

  import { itemTemplate } from './item-template.vue';

  correct:

  import itemTemplate from './item-template.vue';

  Custom item templates are typically single-file Vue components, which are imported as default exports.

Quickstart

This quickstart demonstrates how to set up `vue-suggestion` with global plugin registration, local data filtering, a custom label function, and a custom item template. It shows how to handle input changes and item selections to update the component's state.

import Vue from 'vue';
import VueSuggestion from 'vue-suggestion';
import itemTemplate from './item-template.vue';

Vue.use(VueSuggestion);

new Vue({
  el: '#app',
  template: `
    <div id="app">
      <vue-suggestion
        :items="items"
        v-model="selectedItem"
        :setLabel="setLabel"
        :itemTemplate="itemTemplate"
        @changed="inputChange"
        @selected="itemSelected"
      >
      </vue-suggestion>
      <p>Selected Item: {{ selectedItem.name || 'None' }}</p>
    </div>
  `,
  components: {
    // No need to list VueSuggestion here if globally registered via Vue.use()
  },
  data() {
    return {
      selectedItem: {},
      items: [
        { id: 1, name: 'Golden Retriever' },
        { id: 2, name: 'Cat' },
        { id: 3, name: 'Squirrel' },
        { id: 4, name: 'Dolphin' },
        { id: 5, name: 'Elephant' },
      ],
      itemTemplate,
    };
  },
  methods: {
    itemSelected(item) {
      this.selectedItem = item;
      console.log('Selected:', item);
    },
    setLabel(item) {
      return item.name;
    },
    inputChange(text) {
      console.log('Input changed:', text);
      // Simulate asynchronous search or filter local data
      this.items = [
        { id: 1, name: 'Golden Retriever' },
        { id: 2, name: 'Cat' },
        { id: 3, name: 'Squirrel' },
        { id: 4, name: 'Dolphin' },
        { id: 5, name: 'Elephant' },
      ].filter((item) => item.name.toLowerCase().includes(text.toLowerCase()));
    },
  },
});