Auto complete

Auto complete is a text field that suggests matching options as you type. Unlike a select it does not restrict the input: what the user types is the value, and the menu is only there to help them get there faster.

It accepts every text field attribute, so variant, label, supportingText, required and the rest work the same way here.

Usage

Pass an array of options. Each one needs a label; a value, a supportingText and leading or trailing content are optional. By default the menu shows the options whose label contains what has been typed, and picking one writes its label into the field.

<AutoComplete
	variant="filled"
	label="Fruits"
	name="fruit"
	options={[{ label: 'Apple' }, { label: 'Banana' }]}
/>

Multiple values

To collect more than one value, keep the chosen options in your own state and render them as input chips inside the field. Two props do the work: onoptionselect replaces the default behaviour of writing the label into the input, and optionsFilter takes over the filtering so options that are already picked disappear from the menu.

<AutoComplete
	options={fruitOptions}
	placeholder="Add fruit..."
	style="width:340px"
	label="Fruits"
	name="fruit"
	populated={fruits.length > 0}
	bind:value={fruitValue}
	onoptionselect={(option) => {
		fruits.push(option)
	}}
	optionsFilter={(option) => {
		return (
			(!fruitValue ||
				option.label.toLocaleLowerCase().includes(fruitValue.toLocaleLowerCase())) &&
			!fruits.find((f) => f.value === option.value)
		)
	}}
>
	<ChipSet chipsCount={fruits.length}>
		{#each fruits as fruit, index (fruit.value)}
			<InputChip
				name="fruit"
				value={fruit.value}
				label={fruit.label}
				ariaLabelRemove="Remove {fruit.label}"
				onremove={() => {
					if (index > -1) {
						fruits.splice(index, 1)
					}
				}}
			/>
		{/each}
	</ChipSet>
</AutoComplete>

Long option lists

Once more than virtualThreshold options are visible at the same time, the menu switches to a virtual list and only renders what is on screen, so a list of thousands of entries stays responsive. The threshold defaults to 300; lower it if your options are expensive to render. A virtual list needs a fixed width, so the menu is clamped to the width of the field in that mode, the same as with clampMenuWidth.

<AutoComplete
	label="City"
	options={cities}
	virtualThreshold={100}
	clampMenuWidth
/>

Accessibility

The field is a combobox: it renders role="combobox" with aria-expanded, aria-controls and aria-activedescendant, and the menu renders as a listbox whose options carry role="option". Because the active option is pointed at rather than focused, focus stays in the input while the user browses the list.

↓ and ↑ move through the suggestions and open the menu if it is closed, Home and End jump to the first and the last one, Enter picks the active option and Escape closes the menu without changing the value. Typing anything reopens the menu with the filtered list.

Always pass a label. The suggestions are a convenience, so the field has to be understandable before the menu ever opens.

Theming

Auto complete has no tokens of its own. The field follows the text field tokens and the suggestion list follows the menu and list tokens, so it picks up whatever you already set for those.

<AutoComplete
	label="Fruits"
	options={fruitOptions}
	--np-outlined-text-field-focus-outline-color="var(--np-color-tertiary)"
	--np-menu-container-color="var(--np-color-surface-container-highest)"
/>

API

Attributes

Auto complete takes every TextField attribute in addition to the ones below.

AutoCompleteOption