@tresinternet/vue3-autocomplete NPM

@tresinternet/vue3-autocomplete

@tresinternet/vue3-autocomplete - Table of contents - Installation - Usage - Properties - Events - Public functions - Available slots - Examples - Todo - Origin - License

Installation

Using npm

npm install @tresinternet/vue3-autocomplete

Usage

Load the component locally into your component.

<script setup lang="ts">
import Autocomplete from '@tresinternet/vue3-autocomplete'
// Optional: Import default CSS
import '@tresinternet/vue3-autocomplete/dist/style.css'
</script>

Use the component into your template.

<template>
	<Autocomplete
			@on-input="updateAutocompleteItems"
			:results="items"
	></Autocomplete>
</template>

Properties

Property	Type	Description	Required	Default
`auto-select-first-result`	`Boolean`	If true, selects the first item in the list when pressing 'Enter'-key	No	`false`
`debounce`	`Integer`	Time to wait before each call to the *@input* event	No	`0`
`display-item`	`Function`	Describes how to render each item in results	No	`return typeof item === 'string' ? item as any : item.name` - If the item type is a string, it returns this string. Otherwise, return `item.name`
`display-value`	`String`	The property to display in the input field	No
`input-class`	`Array`	Override input default classes	No	`[]`
`max`	`Integer`	Define a render limit for results items	No	`10`
`placeholder`	`String`	Default input placeholder	No	`''`
`results-container-class`	`Array`	Override results container default classes	No	`[]`
`results-item-class`	`Array`	Override results item default classes	No	`[]`
`results`	`Array`	Items to display in the results list	No	`[]`
`use-html-for-results`	`Boolean`	If true, displayItem method will display results as html	No	`false`

Events

Event	Description	Parameters
`@on-cancel`	Triggered when the user cancels the input by pressing the Escape key
`@on-clear-input`	Triggered when the user clicks the clear button
`@on-input`	Triggered on user input, should update the local results list	`query: string`
`@on-invalid-input`	Triggered when the user clicks the return-key but no valid results are available
`@on-select`	Triggered when user click on a list item and return the selected item	`item: unknown`

Public functions

Function	Description
`setText(query: string)`	Manually set the text of the input-field of the autocomplete component

Available slots

Slot	Description
`clearInput`	The contents of the clear-button. Defaults to an SVG-element with an ×

Examples

To correctly use the component, you need to provide a list of items to display in the results list. You can do this by using the results property. This list needs to be filtered by the user input. You can do this by using the @input event. This event is triggered on user input and should update the local results list. Also sorting the results list is a good idea.

<script setup lang="ts">
import Autocomplete from '@tresinternet/vue3-autocomplete'
// Optional: Import default CSS
import '@tresinternet/vue3-autocomplete/dist/style.css'

// Define a ref to the autocomplete component
const autocomplete = ref()

// Define the initial list of items
const items: Ref<{ value: string; name: string }[]> = ref([])
// Define the list of items to display in the results list
const filteredItems: Ref<{ value: string; name: string }[]> = ref([])

// Store the current value of the autocomplete field
const currentValue = ref('')

/**
 * Update the filtered items based on the search query
 * Triggered when the user types in the autocomplete
 * @param query The query to filter the items on
 */
function updateAutocompleteItems(query: string) {
	// Filter the items based on the query
	filteredItems.value = items.value.filter((item) =>
		item.label.toLowerCase().includes(query.toLowerCase()))

	// Sort the items, starting with the ones that start with the query, and sort them alphabetically
	// Sort the rest of the items alphabetically
	// This is just an example, you can sort the items however you want
	filteredItems.value.sort((a, b) => {
		if (a.label.toLowerCase().startsWith(query.toLowerCase())) {
			if (b.label.toLowerCase().startsWith(query.toLowerCase())) {
				return a.label.localeCompare(b.label)
			}
			return -1
		}
		if (b.label.toLowerCase().startsWith(query.toLowerCase())) {
			return 1
		}
		return a.label.localeCompare(b.label)
	})
}

/**
 * Select an item from the autocomplete.
 * Triggered when the user selects an item from the autocomplete
 * @param item The selected item
 */
function selectAutocompleteItem(item: { value: number; name: string }) {
	// Do something with the selected item
	...

	// Trigger the `updateAutocompleteItems` function to update the filtered items list with the selected item
	updateAutocompleteItems(item.name)
}


/**
 * Cancel the autocomplete
 */
function cancelAutocomplete() {
	// If there is no initial value, clear the filtered items and clear the text
	// (in that case, the input should revert to an empty value)
	// Otherwise, revert the text to the initial value
	// The `currentValue` variable should be replaced with your own variable / check
	if (!currentValue) {
		autocomplete.value?.setText('')
		updateAutocompleteItems('')
	}
	else {
		autocomplete.value?.setText(currentValue)
		updateAutocompleteItems(currentValue)
	}
}

/**
 * Clear the autocomplete
 */
function clearAutocomplete() {
	// Clear the currently selected item
	...

	// Trigger the `updateAutocompleteItems` function with an empty string to clear the filtered items list
	updateAutocompleteItems('')
}

</script>

<Autocomplete
	ref="autocomplete"
	:results="filteredItems"
	:auto-select-first-result="true"
	:display-value="currentValue"
	@on-input="updateAutocompleteItems"
	@on-select="selectAutocompleteItem"
	@on-cancel="cancelAutocomplete"
	@on-clear-input="clearAutocomplete"
/>