Vue3-bootstrap-typeahead NPM

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.

vue vuejs typeahead autocomplete bootstrap

vue

1.0.0

9 months ago