Vue.js 3 typeahead component for Bootstrap 4/5

Born as a fork of vue3-simple-typeahead (thanks man 👍🏻), later rebuilt with composition API.

Tested with Bootstrap from version 4.6.1 to 5.3.0.
Works fine with the only Boostrap CSS, no Bootstrap JS library required.

This component is distributed under the Apache License 2.0.

Features

• Composition API
• Autocomplete
• Match highlighter
• REST API data source
• Slot template
• Item projection
• Styling
• Events
• Keystrokes

Add component to your app

Global registration:

...
import TypeAhead from "@/components/TypeAhead.vue";

let app = createApp(App);
app.component('TypeAhead', TypeAhead);
...
app.mount('#app');

Local registration:

import TypeAhead from "@/components/TypeAhead.vue";

export default {
	components: {
		...
		TypeAhead
	}
	...
}

Demo

Please vist demo page to see the component in action 😎

Usage

Basic example

<TypeAhead
	:items="['Black','Blue','Brown','Cyan','Gray','Green','Lime','Magenta','Orange','Red','Yellow']"
	v-model="color"
/>

Fetching items remotely

<template>
	<TypeAhead
		:items="countries"
		v-model="country"
		@request:fired="loading = true"
		@request:completed="loading = false"
		@request:canceled="loading = false"
	/>
	<div v-show="loading">Loading data...</div>
</template>

<script>
export default {
	...
	methods: {
		countries(query) {
			if (!query) return;
			return fetch("https://restcountries.com/v3.1/name/" + query).then(res => {
				return res.json();
			});
		},
	}
}
</script>

User interaction

When the user types on the typeahead input and the minimum input length is meeted a suggestion list appears below the input with the items that match the user input. You can continue to type further to filter the selection, but you could use keyboard or mouse input to make your selection.

When the suggestion list show up, you can continue to type to filter the selection or you use the Arrow Up↑ or Arrow Down↓ keys to navigate the list of suggestions. When you have selected the desired element press Enter or TAB to select the current element.

| Control | Effect | | :--------------- | :--------------------------------------------------------------------------- | | ↑ | Navigate up on the suggestion list, selecting the previous element | | ↓ | Navigate down on the suggestion list, selecting the next element | | Enter | Choose the current element selection | | TAB | Choose the current element selection and give focus to the next form control | | ESC | Close the dropdown and blur element |

You can use the mouse instead, simply hover you cursor over the desire element and click on it.

Props

| Prop | Type | Default | Description | | :------------------------------------------------ | :---------------- | :------------------------- | :------------------------------------------------------------------- | | allowNew | Boolean | false | When true values not present in items are kept, when false are discarded | | disabled | Boolean | false | Disable input element when true | | itemProjection | Function: String | (item) => {return item;} | Projection function to map the items to a string value for search and display | | items | Array or function(query): Promise (Required) | | Array of objects or strings with the elements for suggestions, or function returning a Promise | | maxItems | Number | -1 | Maximum items to show, the prop value has to be != 0 (-1 means show all) | | minInputLength | Number | 2 | Minimum input length for the suggestion length to appear, the prop value has to be >= 0 | | placeholder | String | | Placeholder text for the input | | requestDelay | Number | 250 | Used in conjuction with item function, delays the function call after a keystroke (time in milliseconds). Safe to set to 0 when the item function is not fetching data remotely | | v-model | Vue data variable | | Vue data binding. For special needs modelValue property and update:modelValue event can be used as well | | inputClass | String | form-control | <input> element class | | dropdownClass | String | dropdown | Outer element class | | dropdownMenuClass | String | dropdown-menu | List class | | dropdownItemClass | String | dropdown-item | Item class | | currentSelectionClass | String | active | In addition to dropdownItemClass |

Events

| Event | Signature | Description | | :-------------------------- | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- | | onFocus | function (event: Object { input: String, items: Array }): void | Emitted when the input control get the focus | | onBlur | function (event: Object { input: String, items: Array }): void | Emitted when the input control lost the focus [When the user select an item, the focus is lost too] | | request:queued | function (query, timeoutID): void | Emitted when the items function is queued | | request:fired | function (query): void | Emitted when the items function is fired | | request:completed | function (query): void | Emitted when the items function Promise is resolved | | request:canceled | function (timeoutID): void | Emitted when the queued items function is canceled due to a keystroke pressed during the requestDelay time | | request:failed | function (Exception): void | Emitted when the items function promise fails |

Slot

| Slot | Props | Description | | :--------------- | :---------------------------------------- | :-------------------------------------------------- | | #item | item, itemProjection, boldMatchText | Slot to customize the content of the <li> element |

Slot #item props

| Prop | Type | Description | | :---------------------------------- | :--------------- | :------------------------------------------------------------------------------------------- | | item | String or Object | The item of the items array | | itemProjection | function | Use the item projection function provided as prop to the component | | boldMatchText | function | Receives a string and add <strong> to the parts of the text matched by the search criteria |

Get started

Clone the repository and download the dependencies with npm install then run the project with npm run serve.