Vue3-simple-typeahead NPM

vue3-simple-typeahead

A Vue3 component for a simple typeahead component. It will show a list of suggested items based on the user input.

The component includes it's own input and when the user types on it the suggested options appear.

Demo

Installation

NPM

npm install vue3-simple-typeahead

Browser

You can also use the browser bundle in a script tag.

<script src="https://unpkg.com/vue3-simple-typeahead"></script>

Add installed component to your app

Import the vue3-simple-typeahead component and register it globally in your Vue app. Import the CSS as well if you wish to use the default styling.

import { createApp } from 'vue';
import App from './App.vue';
import SimpleTypeahead from 'vue3-simple-typeahead';
import 'vue3-simple-typeahead/dist/vue3-simple-typeahead.css'; //Optional default CSS

let app = createApp(App);
app.use(SimpleTypeahead);
app.mount('#app');

You can also import vue3-simple-typeahead locally in your component if you prefer.

import SimpleTypeahead from 'vue3-simple-typeahead';
import 'vue3-simple-typeahead/dist/vue3-simple-typeahead.css'; //Optional default CSS

export default {
	name: 'my-vue-component',
	components: {
		SimpleTypeahead,
	},
};

Usage

Use the component on your own app components

<vue3-simple-typeahead
	id="typeahead_id"
	placeholder="Start writing..."
	:items="['One','Two','Three']"
	:minInputLength="1"
	:itemProjection="itemProjectionFunction"
	@selectItem="selectItemEventHandler"
	@onInput="onInputEventHandler"
	@onFocus="onFocusEventHandler"
	@onBlur="onBlurEventHandler"
>
</vue3-simple-typeahead>

With custom slots template

<vue3-simple-typeahead
	id="typeahead_id"
	placeholder="Start writing..."
	:items="['One','Two','Three']"
	:minInputLength="1"
	:itemProjection="itemProjectionFunction"
	@selectItem="selectItemEventHandler"
	@onInput="onInputEventHandler"
	@onFocus="onFocusEventHandler"
	@onBlur="onBlurEventHandler"
>
	<template #list-header>
		LIST HEADER
	</template>
	<template #list-item-text="slot"><span v-html="slot.boldMatchText(slot.itemProjection(slot.item))"></span></template>
	<template #list-footer>
		LIST FOOTER
	</template>
</vue3-simple-typeahead>

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.abnf

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 (if `selectOnTab` is `true`)

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

User controls

Fallthrough attributes

All attributes added to the component not provided by props fallthrough the input control. For example if you added the disabled attribute:

<vue3-simple-typeahead
	id="typeahead_id"
	placeholder="Start writing..."
	:items="['One','Two','Three']"
	:minInputLength="1"
	:itemProjection="itemProjectionFunction"
	@selectItem="selectItemEventHandler"
	@onInput="onInputEventHandler"
	@onFocus="onFocusEventHandler"
	@onBlur="onBlurEventHandler"
	:disabled="disabled"
>
</vue3-simple-typeahead>

It would fallthrough to the input control of the component:

<!---->
<input [...] :disabled="disabled" />
<!---->

Props

Prop	Type	Default	Description
`id`	String	Random id generation	The id for the input control. Can be useful to link with a `label for=""`
`placeholder`	String	`''`	Placeholder text for the input
`items`	Array (Required)		List of objects or strings with the elements for suggestions
`defaultItem`	Any		Default item to be selected
`minInputLength`	Number	2	Minimum input length for the suggestion length to appear, the prop value has to be >= 0
`minItemLength`	Number	0	Minimum number of items that need to be visible for suggestions to appear, the prop value has to be >= 0
`itemProjection`	Function: String	`(item) => {return item;}`	Projection function to map the items to a string value for search and display
`selectOnTab`	Boolean	`true`	Enable/Disable item selection on TAB

Remember you can always use lower-kebap-case for camelCase props like min-input-length

Events

Event	Signature	Description
`selectItem`	`function (item: String): void`	Emitted when the user selects an item from the suggestion list
`onInput`	`function (event: Object { input: String, items: Array }): void`	Emitted when the user types anything
`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

Slots

Slot	Parent	Props	Description
`#list-header`	`div.simple-typeahead-list-header`		Slot to be show at top of the suggestion list
`#list-item-text`	`span.simple-typeahead-list-item-text'`	`item`, `itemProjection`, `boldMatchText`	Slot to customize the text of every item in the suggestion list
`#list-footer`	`div.simple-typeahead-list-footer`		Slot to be show at bottom of the suggestion list

Slot `#list-item-text` 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 `vue3-simple-typeahead` element
`boldMatchText`	function	A function that receives a string and add strong tags to the parts of the text matched by the search criteria

Methods

Method	Signature	Description
`clearInput`	`function (): void`	Clean the input with an empty string `''`
`focusInput`	`function (): void`	Trigger focus on the input and called `onFocus` event handler
`blurInput`	`function (): void`	Trigger blur on the input and called `onBlur` event handler
`getInput`	`function (): HTMLInputElement`	Return the `HTMLInputElement` corresponding to the input control

This methods are accesible via refs

<vue3-simple-typeahead ref="inputRef"> </vue3-simple-typeahead>

{
	this.$refs.inputRef;
}

Styling

Overwrite styles when using the default css included or add custom styles basing your rules on this structure.

div#{:id}_wrapper.simple-typeahead
    input#{:id}.simple-typeahead-input
    div.simple-typeahead-list
        .simple-typeahead-list-header
        .simple-typeahead-list-item &.simple-typeahead-list-item-active
            .simple-typeahead-list-item-text
        .simple-typeahead-list-footer