@tresinternet/vue3-autocomplete

Table of contents

• @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"
/>

Todo

• [ ] Fix inline documentation and add Typescript support

Origin

This code was initially written by Takachi67 and can be found on https://github.com/Takachi67/vue3-autocomplete

License

MIT