@brunnerh/autocomplete

Autocomplete Component

An autocomplete component which can be used as a regular ES module import or as a Svelte component.

It has no dependencies, handles synchronous and asynchronous data sources, supports item templating and escapes any HTML automatically.

(Change log)

Install

npm install @brunnerh/autocomplete

Usage

In a Svelte project the component can be imported in a <script> section and then used in the HTML like any other:

<script>
	// (Named import!)
	import { AutoComplete } from '@brunnerh/autocomplete';

	const items = ['Apple', 'Orange', 'Pear'];
</script>

<AutoComplete items={() => items}/>

In any other type of project, the component can be instantiated in the script:

<div id="autocomplete-target"></div>

<script type="module">
	import { AutoComplete } from '@brunnerh/autocomplete';

	const items = ['Apple', 'Orange', 'Pear'];
	new AutoComplete({
		target: document.querySelector('#autocomplete-target'),
		props: { items: () => items },
	});
</script>

For documentation of how to interact with component instances see Client-side component API in the Svelte docs.

Properties

Prop	Type	Default	Description
id	string | null	null	Sets the id of the input element.
name	string | null	null	Sets the name of the input element.
className	string	''	Sets additional class name/names of the input element (should be space separated).
placeholder	string | null	null	Sets the placeholder of the input element.
title	string | null	null	Sets the title of the input element.
required	boolean	false	Sets the required attribute on the input element if true.
disabled	boolean	false	Sets the disabled attribute on the input element if true.
tabindex	number | undefined	undefined	Sets the tabindex attribute on the input element.
autoScroll	boolean	true	Automatically scrolls the component into view. Can be helpful if the component is at the bottom a scrollable area and the dropdown ends up off-screen.
autoScrollCursor	boolean	true	Automatically scrolls to the cursor position in the list. Turn off if there are performance issues.
items	() => Item[]		Sets the suggestions. See Items Property.
isOpen	boolean	false	Gets or sets whether the suggestions dropdown is open.
key	any	null	Gets the last selected key. See Items Property.
value	any	null	Gets the last selected value. See Items Property.
results	any[]	[]	Gets the subset of items that match the user input, reduced to the first maxItems items.
search	string	''	Gets or sets the current search term/input value.
isLoading	boolean	false	Gets whether the component is currently loading the suggestions (if items returns a promise).
cursor	number	0	Gets or sets the index of the currently highlighted item within the suggestions list.
cursorItem	any	undefined	Gets the currently highlighted item.
maxItems	number?	undefined	Sets the maximal number of items to show in suggestions list at a time.
fromStart	boolean	false	Sets whether the search string has to appear at the start of the item.
caseSensitive	boolean	false	Sets whether the search is case-sensitive.
minChar	number	0	Sets the minimum number of characters required to trigger a search.
debounce	number	0	Sets the time to wait in milliseconds before triggering a search.
blindSelection	boolean	false	Sets whether suggested items are directly selected upon pressing arrow up/down while the dropdown is closed.
lazyDropdown	boolean	false	Whether the DOM elements for the suggestions list are only created upon filtering/opening the suggestions dropdown.
searchRegEx	(search: string) => RegExp | null	null	Custom search RegEx generator. If set, fromStart and caseSensitive will not be used.
searchFunction	Search Function	null	Custom search function. See Search Function Property.

Items Property

The items property has to be a function returning a list of items for the auto-completion.

The return value can be a promise to load data asynchronously. Returning an existing promise if the list of suggestions can be cached is recommended. E.g.:

<script>
	// Fetch once:
	const suggestions = fetch('/api/items');
</script>
<AutoComplete items={() => suggestions}/>

The items have to be strings or of the form:

{
	key: string,
	value?: any,
}

The key will be used for the search and displayed in the suggestions dropdown by default.

The value represents a technical item value that is assigned to the value property of the component upon selection. If no value is set, the whole item will be assigned.

For strings, the string will serve as key and value.

Search Function Property

The property searchFunction can be used to provide custom search logic when a custom regular expression (searchRegEx) is not enough.

The type of the function is as follows:

(search: string) => (text: string) => {
	/** Whether the item `text` matches `search`. */
	matches: boolean,
	/**
	 * An array of start and end index tuples for parts of the text that should be highlighted as matching.
	 * Should be an empty array if nothing matches or no highlighting should be shown.
	 */
	highlights: [number, number][],
}

If set, fromStart, caseSensitive and searchRegEx will not be used.

Events

The following events are emitted by the component, event data/forwarded event can be found in the detail property:

Type	Description
filtered	Fired after the suggestion list has been filtered.
item-selected	Fired upon item selection, either by pressing Enter or clicking on one. The event data is the selected item.
focus	Forwarded from input.
blur	Forwarded from input.
input	Forwarded from input.
keydown	Forwarded from input.
click	Forwarded from input.

Slots

The following slots can be used in Svelte projects:

Name	Injected Props	Description
loading		The loading indicator that is displayed while items are loading asynchronously. Default: Loading data...
template	result	A custom template for rendering the items. See Template

template

By default, items show the item key with matching parts of the text highlighted. This slot can be used to customize this output.

The injected result prop has the following type:

{
	/** The index of the item in the filtered results list (0-based). */
	index: number,

	/** The key of the item. Either the `key` property or the item itself, if it a string. */
	key: string,

	/** The value of the item. Either the `value` property or the whole item. */
	value: any,

	/** An HTML string that contains highlighted parts in spans with the class `ac-match`. */
	label: string,
}

Example:

<AutoComplete items={() => data} let:result>
	<!-- Renders item with index prefix and value in parentheses on a second line. -->
	<div slot="template">
		{result.index + 1}: {@html result.label}
		<br/>
		<span style="font-size: smaller; opacity: 0.7">({result.value})</span>
	</div>
</AutoComplete>

Styling

The component comes with a default style and defines various CSS custom properties to make theming easier.

It can also be styled via the classes of the various parts.

Structure

.autocomplete
	input.autocomplete-input
	.autocomplete-results-dropdown
		.autocomplete-loading
		ul.autocomplete-results-list
			li.autocomplete-result[.ac-highlighted]
				span[.ac-match]

• ac-highlighted is applied to the item highlighted via arrow/up or mouse hover.
• ac-match is applied to the parts of the item text that match the search.
  • E.g.: Search: ap, item text: Apple => <span class="ac-match">Ap</span>ple

CSS Custom Properties

Target	Name	Default Value
.autocomplete-input	--ac-input-color	black
.autocomplete-input	--ac-input-background	white
.autocomplete-input	--ac-input-border	1px solid hsl(0, 0%, 60%)
.autocomplete-input	--ac-input-border-radius	0
.autocomplete-input	--ac-input-padding	3px
.autocomplete-input	--ac-input-margin	0
.autocomplete-input	--ac-input-font-size	small
.autocomplete-input	--ac-input-font-weight	normal
.autocomplete-results-dropdown	--ac-dropdown-color	Fallback: --ac-input-color
.autocomplete-results-dropdown	--ac-dropdown-background	Fallback: --ac-input-background
.autocomplete-results-dropdown	--ac-dropdown-box-shadow	0px 2px 5px hsla(0, 0%, 0%, 0.7)
.autocomplete-results-dropdown	--ac-dropdown-margin:	0
.autocomplete-results-dropdown	--ac-dropdown-padding:	0
.autocomplete-results-dropdown	--ac-dropdown-border-radius	0
.autocomplete-loading	--ac-loading-color	inherit
.autocomplete-loading	--ac-loading-background	none
.autocomplete-loading	--ac-loading-padding	0
.autocomplete-loading	--ac-loading-margin	5px
.autocomplete-result	--ac-result-color	inherit
.autocomplete-result	--ac-result-background	none
.autocomplete-result	--ac-result-border	none
.autocomplete-result	--ac-result-margin	0
.autocomplete-result	--ac-result-padding	0.2em 0.5em
.autocomplete-result	--ac-result-border-radius	0
.autocomplete-result.ac-highlighted	--ac-result-highlighted-color	inherit + Fallback: --ac-result-color
.autocomplete-result.ac-highlighted	--ac-result-highlighted-background	#dbdbdb + Fallback: --ac-result-background
.autocomplete-result.ac-highlighted	--ac-result-highlighted-border	Fallback: --ac-result-border
.autocomplete-result.ac-highlighted	--ac-result-highlighted-margin	Fallback: --ac-result-margin
.autocomplete-result.ac-highlighted	--ac-result-highlighted-padding	Fallback: --ac-result-padding
.autocomplete-result.ac-highlighted	--ac-result-highlighted-border-radius	Fallback: --ac-result-border-radius
.autocomplete-result .ac-match	--ac-result-match-color	inherit
.autocomplete-result .ac-match	--ac-result-match-background	none
.autocomplete-result .ac-match	--ac-result-match-border-radius	0
.autocomplete-result .ac-match	--ac-result-match-font-weight	bold
.autocomplete-result .ac-match	--ac-result-match-font-style	inherit

Attribution

• patoi/svelte-component-library-template (License) - Repo built on template.
• elcobvg/svelte-autocomplete (License) - Original code-base.