Vue Autocomplete

A simple, powerful, lightweight and customizable autocomplete tool programmed for Vue projects!

Requirements

Recommended vue version - 3.2.25 or higher. This module was completely tested from the version 3.2.5.

It would also work from the version 3.2.13 in which @vue/compiler-sfc was merged with vue package. We recommend you to check if the package is getting installed if your vue version is between 3.2.13 and 3.2.24.

Package information

• Lightweight module with complete customization
• Supports both JS and TS projects
• No 3rd party packages installed in this module
• Supports lazy loading and large dataset
• Advanced and customizable scroll functionality
• Supports custom events
• Relative Search (Searching through the objects in the dropdown array.)
• Keyboard navigation events to scroll through dropdown list
• Virtual scrolling for large data sets
• Supports custom classes and custom css styles at various DOM levels
• Ability to integrate 3rd party styling packages like bootstrap, tailwind or other CSS libraries.
• Complete test case coverage using vitest

Web documentation

Documentation is now available on modulejs.org

Package version

| Package version | Description | | :-------- | :-----------| | 1.0.2 | Recommended. Relative Search feature has been introduced to search the entire object. Refer API usage for details. Upgrading from lower version to 1.0.2 is safe without any configuration change. | | 1.0.1 | Updated vite & @vitejs/plugin-vue versions with ^ in devDependencies as they continuously address vulnerabilties in their package. Upgrading from lower version to 1.0.1 is safe without any configuration change. | | 1.0.0 | Vue autocomplete search package |

Other information

Adjust the width of the autocomplete list based on the project requirement. This module will inherit the width of parent container by default. But it can be customized as per the project need. It is very easy to control the UX design of this module with CSS, styles, bootstrap, tailwind and so on. Take the control of this module as per your requirement. Checkout below documenttaion for complete details.

Installation

Install vue-autocomplete-plugin with npm

  npm install vue-autocomplete-plugin --save

or

  npm i vue-autocomplete-plugin

Running Tests

vue-autocomplete-plugin has solid test cases to make sure components executes without any issues.

To run tests, clone the repository, install the packages and run the following command. If you are facing any issues, you may need to check your node version which may require v18+ version.

  npm run test

To run tests with Vitest UI for viewing test results in the screen, run below command.

  npm run test:ui

Demo & Examples

| Demo Description | Stackblitz Example | | :-------- | :-----------| | Vue Autocomplete Basic Example | Vue Autocomplete basic - Stackblitz | | Vue Autocomplete Basic with Dropdown as object | Vue Autocomplete - Stackblitz | | Vue Autocomplete With Huge Dataset | Vue Autocomplete with Large Dataset| | Vue Autocomplete With Bootstrap | Vue Autocomplete with bootstrap| | Vue Autocomplete With Tailwind | Vue Autocomplete with Tailwind| | Vue Autocomplete Disabled Example | Vue Autocomplete Disabled Example| | Vue Autocomplete With API Lazyload | Vue Autocomplete with API Lazyload| | Vue Autocomplete Disable list with a custom function | Vue Autocomplete Disable list with a custom function| | Vue Autocomplete View More feature Example | Vue Autocomplete View More feature Example | | Vue Autocomplete Relative Search | Vue Autocomplete Relative Search | | Vue Autocomplete Relative Search with conditions | Vue Autocomplete Relative Search with conditions |

API Usage

| Props | Type | Required | Description | | -------- | ------- | ------- | ------- | | dropdownData | string[], number[], object[] or any[] | Yes. | Accepts array of strings, numbers or array of objects. | | | objectProperty | string |Yes | Required only if dropdownData is object[]. objectProperty will determine the value to be displayed in dropdown. | |initialVisibleData| number | No | initialVisibleData denotes the number of records that will be displayed in dropdown list. Default value is 1000. It can be customized as per project requirement or can be left untouched. | |broadcastSelectedValue|Function |Yes | Custom function to broadcast the selected value when dropdown value is selected from list. Accepts one parameter which will give the selected value. | | placeHolder | string | No | Custom placeholder for auto-complete input field. | | scrollThreshold | number | No | 3 by default. Helps to boost performance. It controls the scroll data and removes top or botton records during user scroll based on the scrollThreshold & scrollData configured. Check below for more details. | |defaultValue| string or object | No | defaultValue pre-populates the value in input textfield by matching the value from dropdown data. It can be a simple value or simple json object. For simple json object, objectProperty value should be available. | |totalRecords | number | No | If total number of records is known, totalRecords can be provided which will avoid extra condtions that will be executed in the package. |disableProperty | string | No | To disable specific dropdown list in dropdown from being selected. This property can be used when dropdownData is an object[] and the disableProperty should be a property name from the object which can determine whether the specific list should be disabled from selection. Eg: If an object conatins a property disabled, then this property name can be passed to disableProperty props to disable the list from selection when condition matches. | |disableListFn |Function |No | If disable should be calculated dynamically using a function and custom code, assign customized function to disableListFn. disableListFn accepts two parameters (index, data)| |searchFn |Function |No | Customized search function. Customized search function accepts one parameter, event. On keyUp, the customized search function will be called to perform custom execution.| |noSearchResultMessage |string |No | By default No results found message will be displayed when search result is 0 | |isAutoCompleteDisabled |boolean |No | By default value is false. If updated as true, the input fields gets disabled. | |customClass | object |No | Allows custom class styling at various dom levels. Check below for more information| |customStyle | object |No | Allows custom css style. Check below for more information | |showdropDownArrow | boolean |No | Show or hide dropdown icon in autocomplete field. Default is true. | |showClearOption |boolean |No | Shows clear option to allow user to clear the selected value. Default is true. | |triggerOnFocusEvent| Function |No|Triggers on-focus event when input field is focussed.triggerOnFocusEvent accepts a function as props. The function can have one event parameter (Eg: triggerOnFocusEvent(event)) and the parameter will be a focus event. By default, triggerOnFocusEvent will be undefined and will not be triggered until a function is assigned to it.| | triggerBlurEvent|Function |No | Triggers blur event when input field is out of focus. triggerBlurEvent accepts a function as props. The function can have one event parameter (Eg: triggerBlurEvent(event)) and the parameter will be a blur event. By default, triggerBlurEvent will be undefined and will not be triggered until function is assigned to it.| |triggerApiLoadEvent |Function |No | A custom function for lazy loading the dropdown data. triggerApiLoadEvent accepts a function as props. It triggers a custom function to call the API when the end of scroll is reached. Depends on props.isApiLoad. Pass isApiLoad as true if triggerApiLoadEvent function needs to be triggered. The custom function can have one parameter which would return an object with length of the dropdown data. This object can be used to calculate next paginated data, and using this param is optional. When lazy loading of the API is complete or all the dropdown data has been loaded, set isApiLoad as false, so that triggerApiLoadEvent will not be called. Alternatively instead of setting isApiLoad to false, you can also set totalRecords, so that the module does not trigger triggerApiLoadEvent event further| | isApiLoad | boolean | No | Default value is false. This props is required if the dropdown data is being lazy-loaded. To trigger triggerApiLoadEvent, isApiLoad must be set to true. Once lazy loading or API calls are complete, set isApiLoad to false or set the total records so that the module does not trigger the lazy-load calls further. | |optViewMoreOnlyForApiCall|boolean|No|Default is false. When set to true, API Call will not be executed automatically on reaching the end of the scroll, instead View More list item will be displayed at the end of scroll and the list has to be clicked to call the API or any custom function to load further data. Please note that isApiLoad should be true as well to load further data.| |triggerClearSelectionEvent |Function |No | Triggers custom function triggerClearSelectionEvent(event) input field is cleared. | |isScrollThresholdRequired|boolean|No | Default is true. If scrollData and scrollThreshold is performance calculation is not required, set it to false. See below for more information.| |inspectAutoCompleteList|boolean|No|Default value is false. When set to true, it will not allow hiding the dropdown list on blur. This is helpful to inspect the dropdown list in dom and is recommended only for development.| |showInputlabel|boolean|No|Default value is false. making it true will show the input text label.| |inputLabel|string|No|Default value is Select a value and can be customized. inputLabel will be shown when showInputlabel is set to true.| |showLoadingSpinner | boolean|No | Shows the spinner at the botton of the list if lazy loaded. Default is true | |isCustomSpinner|boolean|No|Set as true to set customize spinner during lazy load or paginated API calls. Set your own class properties in customClass.customSpinnerClass. showLoadingSpinner must be set to true to show the spinner.| |aria|object|No|Helps to set aria roles at various levels of DOM to provide Accessible Rich Internet Application. Check below for more details.| |viewMoreText|string|No|Default text is View More. It can be updated through viewMoreText as per requirement| |loadAllDataAtOnce|boolean|No|Default value is false. If set to true, all the dropdown list will be loaded at once without lazy loading. May not be recommended for large data set to avoid performance issues.| | additionalData | object | No | Undefined by default. Has relativeSearch as one of the property.| | relativeSearch | boolean or object | No | Not enabled by default. relativeSearch is available under additionalData props. If relativeSearch is set as true, entire object will be searched during input search. relativeSearch can also be set as an object to set more custom options during search. More details found in below sections. |

Useful Tips

Incase the Autocomplete component is mounted on a nested or multiple nested child components and if the dropdownData is rendered or fetched only during onMounted life-cycle, consider initializing the module with v-if condition to make sure Autocomplete component loads as expected.

<Autocomplete v-if="data.length > 0" :dropdownData="data"/>

Adding v-if condition is solely based on the application's business logic and is just optional.

Relative Search

Relative search is breaking feature introduced in 1.0.2 version which allows to search the whole object. relativeSearch is available under additionalData props.

dropdownData should be an object and objectProperty should be available to make relativeSearch feature work.

If relativeSearch is set to true, entire object will be searched during the input search.

const dropdownData = `[{ sku: 12345, name: 'Apple'}, { sku: 67890, name: 'Samsung'}]`

<Autocomplete
    :dropdownData="dropdownData"
    objectProperty="name"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)"
    :additionalData="{ relativeSearch: true }">
</Autocomplete>

In the above example, when searched with the inputs 12345 or Apple, first object will be filtered and produced as result.

relativeSearch also supports custom settings apart from boolean. Below attributes are supported in relativeSearch object.

| Property | Type | Required | Description | | -------- | ------- | ------- | ------- | | includeOnly | string[] | optional | Searches only the value of mentioned keys or attributes available in the object.| | customRelativeSearchFunction | Function | optional | Implementing your own custom function for relative search. This is helpful when the object has nested objects. Custom function will accept one parameter 'searchValue' in which typed input value will be passed. Use the dropdown data available in yoor component for custom filtering. Example: [{ sku: 12345, name: 'Apple', country: [{ name: 'USA'}, { name: 'China'}]}, { sku: 67890, name: 'Samsung', country: [{ name: 'USA'}, { name: 'China'}] }]. The module will not search the country array as they are nested and the module would not predict the nested objects or arrays as they are based on project requirements. In this case you can write your own customRelativeSearchFunction.| | setDefaultValueWithACustomFunction| Function | optional | If relativeSearch is enabled, the setting up default value using defaultValue props will not work. Implement your own setDefaultValueWithACustomFunction and return the object (not array of objects). The returned object should be available in dropdownData and should contain the objectProperty to allow the module to set default value.|

Please note that searchFn in the props and additionalData.relativeSearch.customRelativeSearchFunction has minor difference. While you can use searchFn to completely customize the onSearch function, customRelativeSearchFunction can be used to search nested objects with a custom function. Based on the requirements, any of the both custom functions can be used based on how it suits the application.

const dropdownData = `[{ sku: 12345, name: 'Apple'}, { sku: 67890, name: 'Samsung'}]`

<Autocomplete
    :dropdownData="dropdownData"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)"
    :additionalData="{ relativeSearch: { includeOnly: ['sku'] } }">
</Autocomplete>

In the above example, only the sku attribute in the object will be searched.

Checkout the stackblitz example to know how it works.

It's your responsibility to check the performance impact when using the relative search for large data.

Using the module

import Autocomplete Module into your component.

import { Autocomplete } from 'vue-autocomplete-plugin';

In your HTML template

For dropdown string array,Eg: ["Apple", "Banana", "Kiwi"], do as below.

<Autocomplete
    :dropdownData="YOUR_DROPDOWN_DATA"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)">
</Autocomplete>

For dropdown object array, Eg: [{"name": "Alex"}, {"name": "John"}], do as below.

<Autocomplete
    :dropdownData="YOUR_DROPDOWN_DATA"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)"
    :objectProperty="'name'">
</Autocomplete>

Setting scrollThreshold & initialVisibleData for maximizing performance

By default, initialVisibleData is set to 1000 and scrollThreshold is set to 3. It can be customized as per requirement.

What is scrollThreshold & initialVisibleData?

Both scrollThreshold & initialVisibleData helps to improve virtual scrolling for better performance.

initialVisibleData is the number of records / data that will be loaded virtually during initial load.

Consider, there are 5000 records to be shown. initialVisibleData is 1000 and scrollThreshold is 3.

During initial load, dropdown list will show 1000 records. When user reaches the end of scroll, the formula will be calculated based on initialVisibleData & scrollThreshold and number of filteredData records.

Math.ceil(filteredData.length /scrollThreshold);

Math.ceil(1000/3);

If calculated result does not exceed initialVisibleData, next set of data will be loaded. And now the dropdown list(filteredData) will hold 2000 records.

Similary same calculation will be performed during the end of scroll and when the result exceeds initialVisibleData, first set of records will be removed from the dropdown list and next set of records will be loaded everytime, to improve performance.

When scrollThreshold is set to 1, the virtual dropdown list will hold the records based on initialVisibleData configuration. When end of scroll is reached, the current set will be replaced by next set.

initialVisibleData & scrollThreshold does not affect or mutate original data and will update only the virtually filtered data.

initialVisibleData & scrollThreshold is customizable based on project needs. If this performance calculation is not required, set isScrollThresholdRequired to false.

Adding Custom CSS Class to autocomplete

Import CustomClassType from the module (Optional).

import { type CustomClassType } from 'vue-autocomplete-plugin';

| CustomClassTypes | Required | Description | | :-------- | :-----------| :-----------| | parentContainerClass | No | Adds class to parent div surrounding the input field and dropdown list. | | inputFieldClass | No | Adds class to input textfield| | listContainerClass | No | Adds class to div that surrounds ul of dropdown list. | | dropdownUnorderedListClass | No | Adds class to ul of dropdown list. | | dropdownListClass | No | Adds class to each li items| | disableListClass | No | Add class to disabled li items | | noResultClass | No | Adds class to separate li item to show no result message. | | inputLabelClass | No | Adds class to <label> field | | inputLabelContainerClass | No | Adds class to surrounding div of input label.| | customSpinnerClass | No | Adds class to span to show customized spinner.| | viewMoreClass | No | Adds class to View More li item |

customClassType: CustomClassType = {
    inputFieldClass: 'class1',
    dropdownListClass: 'class1 class2'
}

<Autocomplete
    :dropdownData="YOUR_DROPDOWN_DATA"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)"
    :objectProperty="'name'"
    :customClassType="customClassType">
</Autocomplete>

Adding Custom CSS styles to autocomplete

Import CustomStyleType from the module (Optional).

import { type CustomStyleType } from 'vue-autocomplete-plugin';

| CustomStyleTypes | Required | Description | | :-------- | :-----------| :-----------| | parentContainerStyle | No | Adds style to div surrounding the input field and dropdown list. | | inputFieldStyle | No | Adds style to input textfield| | listContainerStyle | No | Adds style to div that surrounds ul of dropdown list. | | dropdownUnorderedListStyle | No | Adds style to ul of dropdown list. | | dropdownListStyle | No | Adds style to each li items| | noResultStyle | No | Adds style to separate li item to show no result message. | | inputLabelStyle | No | Adds style to <label> field | | inputLabelContainerStyle | No | Adds style to surrounding div of input label.| | customSpinnerStyle | No | Adds style to span to style the customized spinner.| | viewMoreStyle | No | Adds style to View More li item. |

customStyle: CustomStyleType = {
    inputFieldStyle: {color: '#FFFFFF' },
    dropdownListStyle: {padding: 2px }
}

<Autocomplete
    :dropdownData="YOUR_DROPDOWN_DATA"
    :broadcastSelectedValue="YOUR_CUSTOM_FUNTION($event)"
    :objectProperty="'name'"
    :customStyle="customStyle">
</Autocomplete>

Debugging Autocomplete list during development

For inspecting the classes or styles during develeopment, pass inspectAutoCompleteList as true so that the dropdown list will not close which will help to inspect the list. But don't forget to remove or make it false during production deployment

Adding Accessible Rich Internet Applications (ARIA)

ARIA provides easy access to the content for people with disabilities with help of screen reader.

Import CustomAriaType from the module (Optional).

import { type CustomAriaType } from 'vue-autocomplete-plugin';

| Attributes | Required | Description | | :-------- | :-----------| :-----------| | ariaRole | No | Adds ARIA role to input textfield. Default value is textbox. | | ariaRoleDescription | No | Adds ARIA role description to input textfield. Default value is Autocomplete input field. | | ariaInputField | No | Adds ARIA label to input textfield| | ariaNoSearchResult | No | Adds ARIA label to no result found li item| | ariaULList | No | Adds ARIA label to ul list item | | ariaListContainer | No | Adds ARIA label to list container div. | | ariaInputLabel | No | Adds ARIA label to label field. | | ariaViewMore | No | Adds ARIA label to View More li item. |

Running the github code locally to test autocomplete module in local vue-app.

• Download the vue-autocomplete-plugin code locally through github.

• Execute npm install.

• Create App.vue and main.ts (to mount the app) in the src folder and execute npm run dev.

• Or alternatively you can skip the above step and use npm link to test the feature locally with a vue web application.

• In vue-autocomplete-plugin module, run npm link. This will add the vue-autocomplete-plugin in node_modules locally.

• From the vue web application run npm link vue-autocomplete-plugin.

• Import the Autocomplete module from vue-autocomplete-plugin like usual npm package and start using the module.

Change Logs and version history

Refer the change history by viewing this link - CHANGELOG

Github link

Github Link - vue-autocomplete-plugin

Roadmap

• Multi select dropdown feature

Other plugins

Checkout similar Autocomplete plugin in Angular Framework ng-autocomplete-plugin with same features

Checkout similar Autocomplete plugin in React Framework react-autocomplete-plugin with same features

Support

Please raise an issue in github repository

Github Link - Raise an issue

Happy Autocompleting!