@isoftdata/svelte-autocomplete

Svelte Autocomplete

This component is an "autocomplete" style input - that is, you type in the input to filter the list of options, and then choose one. It also supports keyboard navigation of the option list, with similar behavior to a normal select element.

Currently, it does not support selecting multiple options or entering new options.

Install

pnpm i @isoftdata/svelte-autocomplete

A Note on Types

This component uses the generic type O to represent the type of the value prop, and the type of each "option" in the options array. Mostly commonly, O will either be a string or some Object type, and will need handled differently depending on the type. (See: "On Options and Labels")

Breaking changes

2.0.0

• Require Svelte 5
• Slots -> Snippets
• Events -> Callbacks

Props

Name	Type	Description	Default Value
canAddNew	boolean	If true, the user can add new options to the options array by typing in the input.	false
createOption	(filterValue: string) => O	A function that takes the current value of the input and returns a new option to add to the list.	A function that, if labelProp is specified, adds {[labelProp]: filterValue} to options, otherwise adds filterValue to options.
emptyValue	O | undefined	If specified (and not undefined), will allow the "X" button to clear the selection, and set it to this value.	undefined
hint	string | Snippet | undefined	Text to show after the label	undefined
hintClass	string | undefined	Extra classes to apply to the hint text	undefined
hintClickable	boolean | undefined	Whether to allow clicking on the label hint	undefined
id	string	The ID of the underlying input.	id${uuid()}
isLoading	boolean | undefined	Whether to show the loading spinner	undefined
label	string	The label shown above the autocomplete input.	""
labelProp	keyof O | undefined	The property of the option object to use as the label. If this is not specified, and you don't pass getLabel, the component will assume that each option is a string.	undefined
options	Array<O>	The list of options to choose from.	Required
getLabel	(option: O) => string	Given an option, it returns the string that is shown to the user and used to filter the list.	See "On Options and Labels"
placeholder	string	The placeholder text to display when no option is selected.	-- Select a ${label} --
showAppend	boolean	Whether to show or hide the contents of the append snippet of this component	!!$$slots.append
value	O	The currently selected option.	Required

Any extra props are passed to the underlying Input component.

On Options and Labels

(Will return option[labelProp] if labelProp is specified, or just option if not)

There are a couple ways to interact with this component when it comes to the options and labels used to display and filter those options.

The simplest way to use the component is to pass an Array of strings for options, and no labelProp or getLabel. In this scenario, the value of each option is used as-is when filtering, being displayed to the user and being passed to the consumer with either bind:value or on:change.

The second way is useful when options is an Array of Objects. You can pass labelProp, and the value of option[labelProp] will be used as the "value" when filtering, and being displayed to the user. The value prop will still be of type O, and will be an element from the options array.

The third way is useful when options is an Array of Objects but you don't have a dedicated "label" property on your data. You can specify the getLabel property, whose value should be a function of type (option: O) => string, meaning the first argument will be one of your options, and it should return a string to use as the label.

Snippet

• option({ option }) - The inner HTML of the dropdown buttons. If this is not specified, the value of getLabel will be used instead.
  • exposes the option prop, which is the value of the current option.
• hint - You can specify a hint via the hint prop or this snippet (which is also the same prop technically)
• append - appends to the input, after the button appended by this component

Callbacks

• change - Called when an option is selected
• filterChange - Called when the filter changes

Since any extra props are passed to the input, if you want to handle a different event, you can pass the handler (e.g. onblur) to this component and it will be handled.

Example

<script lang="ts">
	import Autocomplete from '@isoftdata/svelte-autocomplete'

	type Person = {
		firstName: string
		lastName: string
		email: string
		fullName: string
	}

	type InventoryType = {
		id: number
		name: string
	}

	const people: Array<Person> = [
		// People go here
	]

	const inventoryTypes: Array<InventoryType> = [
		// InventoryTypes go here
	]

	const categories = ["Used", "New", "Rebuilt", "Core"]
	let selectedPerson: Person
	let selectedType: InventoryType = inventoryTypes[10]
	let selectedCategory: string

	// ... The rest of your component code ...
</script>

<div class="row">
	<div class="col-12 col-lg-4">
		Object option with labelProp specified
		<Autocomplete
			label="Person Autocomplete"
			options={people}
			bind:value={selectedPerson}
			labelProp="fullName"
		/>
	</div>
	<div class="col-12 col-lg-4">
		Object option with getLabel function and "option" snippet
		<Autocomplete
			label="Inventory Type AC"
			options={inventoryTypes}
			bind:value={selectedType}
			getLabel={option => (option ? `${option.id} - ${option.name}` : "")}
		>
			{#snippet option({ option })}
				<span class="badge bg-primary text-white">{option.id}</span> {option.name}
			{/snippet}
		</Autocomplete>
	</div>
	<div class="col-12 col-lg-4">
		String option (no labelProp or getLabel; Autocomplete assumes options is array of strings)
		<Autocomplete
			label="Category"
			options={categories}
			bind:value={selectedCategory}
		/>
	</div>
</div>