{"id":12588,"library":"vue-suggestion","title":"Vue Suggestion List Input","description":"vue-suggestion is a Vue 2 component library designed to provide a flexible and customizable suggestion list input, commonly known as an autocomplete field. It simplifies the process of displaying a filtered list of items to users as they type, abstracting away the UI logic for suggestion display and selection. The current stable version is 2.1.0. Releases appear to follow an ad-hoc cadence, with significant rewrites occurring in major versions like v2.0.0. Its key differentiators include support for customizable item templates using Vue components, allowing developers to define exactly how each suggestion in the list is rendered. It also provides a clear API for handling input changes and item selections through events and props.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/iamstevendao/vue-suggestion","tags":["javascript","vue","suggestion","vue-suggestion","suggestion-vue","v-suggestion"],"install":[{"cmd":"npm install vue-suggestion","lang":"bash","label":"npm"},{"cmd":"yarn add vue-suggestion","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-suggestion","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For global component registration, `VueSuggestion` is a default export intended for `Vue.use()`.","wrong":"import { VueSuggestion } from 'vue-suggestion'; Vue.use(VueSuggestion);","symbol":"VueSuggestion","correct":"import VueSuggestion from 'vue-suggestion'; Vue.use(VueSuggestion);"},{"note":"For local component registration, `VueSuggestion` is a named export. It should be imported directly and added to the `components` option.","wrong":"import VueSuggestion from 'vue-suggestion';","symbol":"VueSuggestion","correct":"import { VueSuggestion } from 'vue-suggestion';"},{"note":"Custom item templates are typically single-file Vue components, which are imported as default exports.","wrong":"import { itemTemplate } from './item-template.vue';","symbol":"itemTemplate","correct":"import itemTemplate from './item-template.vue';"}],"quickstart":{"code":"import Vue from 'vue';\nimport VueSuggestion from 'vue-suggestion';\nimport itemTemplate from './item-template.vue';\n\nVue.use(VueSuggestion);\n\nnew Vue({\n el: '#app',\n template: `\n
\n \n \n

Selected Item: {{ selectedItem.name || 'None' }}

\n
\n `,\n components: {\n // No need to list VueSuggestion here if globally registered via Vue.use()\n },\n data() {\n return {\n selectedItem: {},\n items: [\n { id: 1, name: 'Golden Retriever' },\n { id: 2, name: 'Cat' },\n { id: 3, name: 'Squirrel' },\n { id: 4, name: 'Dolphin' },\n { id: 5, name: 'Elephant' },\n ],\n itemTemplate,\n };\n },\n methods: {\n itemSelected(item) {\n this.selectedItem = item;\n console.log('Selected:', item);\n },\n setLabel(item) {\n return item.name;\n },\n inputChange(text) {\n console.log('Input changed:', text);\n // Simulate asynchronous search or filter local data\n this.items = [\n { id: 1, name: 'Golden Retriever' },\n { id: 2, name: 'Cat' },\n { id: 3, name: 'Squirrel' },\n { id: 4, name: 'Dolphin' },\n { id: 5, name: 'Elephant' },\n ].filter((item) => item.name.toLowerCase().includes(text.toLowerCase()));\n },\n },\n});\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update build configurations if they were tightly coupled to the previous build system. For most users, this change will be transparent.","message":"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.","severity":"breaking","affected_versions":">=1.0.0 <2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"To register globally: `import VueSuggestion from 'vue-suggestion'; Vue.use(VueSuggestion);`. To register locally: `import { VueSuggestion } from 'vue-suggestion'; export default { components: { VueSuggestion } };`","cause":"The `VueSuggestion` component has not been registered with Vue, either globally via `Vue.use()` or locally within a parent component's `components` option.","error":"[Vue warn]: Unknown custom element: - did you register the component correctly? For recursive components, make sure to provide the 'name' option."},{"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`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'name')"},{"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.","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.","error":"Suggestion list appears empty or doesn't update when typing."}],"ecosystem":"npm"}