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

Go to demo page

vue3-simple-typeahead-demo source code

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.

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