Autocomplete

The Bits UI primitive integration, keyboard-navigation tests, and prop documentation for Autocomplete were contributed by Teddy (@uhteddy).

Installation

Barrel

import { Autocomplete } from "kumo-svelte";

Granular

import { Autocomplete } from "kumo-svelte/components/autocomplete";

When to use

Use Autocomplete when the input value can be free-form text and suggestions are optional hints. Use Combobox instead when the selected value must come from the predefined list.

Controlled

Pass value and onValueChange for controlled usage.

With Field

Add label, description, and required to enable the built-in Field wrapper.

Error State

Display validation errors with the error prop.

Grouped

Group items into categories using Autocomplete.Group and Autocomplete.GroupLabel.

Sizes

The size prop on Autocomplete.InputGroup supports four variants matching the Input component: xs, sm, base (default), and lg.

Filtering

Filtering is case- and accent-insensitive by default, powered by Intl.Collator under the hood. For string items, no custom filter is needed.

When filtering on a property of object items, use Autocomplete.useFilter() to preserve the built-in accent-insensitive matching:

<script lang="ts">  import { Autocomplete } from "kumo-svelte";  const { contains } = Autocomplete.useFilter();  const languages = [    { value: "pt", label: "Portuguese", emoji: "🇵🇹" },    { value: "es", label: "Spanish", emoji: "🇪🇸" }  ];  const filter = (item, query) => contains(item.label, query);</script><Autocomplete items={languages} {filter}>  <!-- ... --></Autocomplete>

To disable filtering entirely (for example, when results come from a server), pass filter={null}:

<Autocomplete items={results} filter={null}>  <!-- ... --></Autocomplete>

API Reference

Root component. Wraps all sub-components and manages state.

Prop	Type	Default	Description
items *	`unknown[]`	-	Array of items to display in the dropdown.
value	`string \| number \| string[]`	-	Controlled input value.
open	`boolean`	`false`	Controlled open state.
children	`Snippet`	-	Child snippet rendered by the component.
class	`string`	-	Additional classes merged onto the root element.
label	`string \| Snippet`	-	Visible label content.
required	`boolean`	-	Marks the field as required.
labelTooltip	`string \| Snippet`	-	Optional help content for the label.
description	`string \| Snippet`	-	Supporting description text.
error	`FieldError`	-	Validation error message or matcher.
defaultValue	`string \| number \| string[]`	-	Uncontrolled default input value.
onValueChange	`(value: string \| number \| string[]) => void`	-	Called when the value changes.
onOpenChange	`(open: boolean) => void`	-	Called when open state changes.
disabled	`boolean`	`false`	Prevents interaction with the field.
size	`'xs' \| 'sm' \| 'base' \| 'lg'`	`"base"`	Size preset.
filter	`((item: AutocompleteItem, query: string) => boolean) \| null`	-	Custom filter function. Set to null to disable filtering.

Autocomplete.InputGroup

Autocomplete text input with Input component styling.

Prop	Type	Default	Description
size	`'xs' \| 'sm' \| 'base' \| 'lg'`	`"base"`	Size of the autocomplete input. Matches Input component sizes.
placeholder	`string`	-	Placeholder text.

Autocomplete.Content

Dropdown popup container.

Prop	Type	Default	Description
align	`'start' \| 'center' \| 'end'`	`"start"`	Alignment of the popup relative to the input.
alignOffset	`number \| string`	-	Offset along the alignment axis.
side	`'top' \| 'right' \| 'bottom' \| 'left'`	`"bottom"`	Side of the input where the popup is placed.
sideOffset	`number \| string`	`4`	Offset between the popup and the input.

Autocomplete.List

Scrollable list container with render prop.

Prop	Type	Default	Description
No component-specific props. Accepts standard HTML attributes.

Autocomplete.Item

Individual suggestion item in the list.

Prop	Type	Default	Description
value *	`unknown`	-	Value associated with this item.
disabled	`boolean`	-	Disables the component.

Autocomplete.Group

Groups items under a heading.

Prop	Type	Default	Description
items	`AutocompleteItem[]`	`[]`	Items rendered by the component.

Autocomplete.GroupLabel

Heading label for a group.

Prop	Type	Default	Description
No component-specific props. Accepts standard HTML attributes.

Autocomplete.Collection

Item container within a group.

Prop	Type	Default	Description
No component-specific props. Accepts standard HTML attributes.

Autocomplete.Separator

Horizontal divider between items.

Prop	Type	Default	Description
No component-specific props. Accepts standard HTML attributes.