# Autocomplete

An input that suggests options as you type.

## Installation

Start from a Svelte 5 application, then install the component package, shared theme, and Bits UI peer:

```bash
pnpm add coss-svelte @coss-svelte/theme bits-ui
```

Import `@coss-svelte/theme/style-coss.css` after Tailwind from the application's global stylesheet.

## Usage

```svelte
<script lang="ts">
import { Autocomplete } from "coss-svelte";
</script>

<Autocomplete
	aria-label="Search items"
	placeholder="Search items…"
	options={[
		"Apple",
		"Banana",
		"Orange",
		"Grape",
		"Strawberry",
		"Mango",
		"Pineapple",
		"Kiwi",
		"Peach",
		"Pear",
	]}
/>

```

## Anatomy

- `Autocomplete`
- `AutocompleteCollection`
- `AutocompleteEmpty`
- `AutocompleteGroup`
- `AutocompleteGroupLabel`
- `AutocompleteInput`
- `AutocompleteItem`
- `AutocompleteList`
- `AutocompletePopup`
- `AutocompleteSeparator`
- `AutocompleteStatus`

## API Reference

### Autocomplete

An input that suggests options as you type.

**Signatures**

- `{ type?: "single"; value?: string; onValueChange?: OnChangeFn<string> }`
- `{ type: "multiple"; value?: string[]; onValueChange?: OnChangeFn<string[]> }`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single" \| "multiple"` | `"single"` | Behavior, selection, or HTML type passed to the underlying control. |
| `bind:value` | `string \| string[]` | `""` | Current value for the component. Bind with `bind:value` when supported. |
| `bind:open` | `boolean` | `false` | Open state for the popup or disclosure. Bind with `bind:open`. |
| `options` | `Option[]` | `[]` | Options rendered by the component's built-in fallback composition. |
| `placeholder` | `string` | `"Search"` | Placeholder text shown by the built-in input. |

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Bits UI Combobox.Root and Bits UI Combobox.Input](https://bits-ui.com/docs/components/combobox#root).

### AutocompleteCollection

Connects repeated items to the parent collection state.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte component attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### AutocompleteEmpty

Renders fallback content when the collection has no results.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte component attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

### AutocompleteGroup

Groups related items inside the parent component.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Group](https://bits-ui.com/docs/components/combobox#group).

### AutocompleteGroupLabel

Labels a group of related items.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.GroupHeading](https://bits-ui.com/docs/components/combobox#group-heading).

### AutocompleteInput

Renders the input field for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showTrigger` | `boolean` | `false` | Shows a trigger button beside the input. |
| `triggerProps` | `(Omit<{}, "child" \| "children"> & { child?: Snippet<[{ props: Record<string, unknown> }]> \| undefined; children?: Snippet<[]> \| undefined; style?: StyleProperties \| string \| null \| undefined; ref?: HTMLElement \| null \| undefined } & Without<BitsPrimitiveButtonAttributes, SelectTriggerPropsWithoutHTML>)` | `{}` | Props forwarded to the optional trigger button. |

**Composition and refs**

- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Input and Bits UI Combobox.Trigger](https://bits-ui.com/docs/components/combobox#input).

### AutocompleteItem

Renders one selectable or repeated item.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Item](https://bits-ui.com/docs/components/combobox#item).

### AutocompleteList

Wraps a list of related items.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Viewport](https://bits-ui.com/docs/components/combobox#viewport).

### AutocompletePopup

Renders the floating or modal surface for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `portalProps` | `{ disabled?: boolean; to?: PortalTarget }` | `{}` | Configures the exact Bits Portal target (`to`) or renders inline when `disabled`. |

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Content](https://bits-ui.com/docs/components/combobox#content).

### AutocompleteSeparator

Visually separates related content.

**Composition and refs**

- `children: Snippet<[]>`
- `bind:ref: HTMLElement \| null`

Inherits from [Bits UI Combobox.Separator](https://bits-ui.com/docs/components/combobox#separator).

### AutocompleteStatus

Renders status text for the current collection state.

**Composition and refs**

- `children: Snippet<[]>`

Inherits from [Svelte component attributes](https://svelte.dev/docs/svelte/basic-markup#Attributes).

## Implementation Details

| Field | Value |
| --- | --- |
| Status | Stable |
| Foundation | compound |
| Category | Selection & Input |
| Particles | 15 |

## Status

Stable for the current coss-svelte surface.

## Agent Notes

- Import Svelte exports directly from `coss-svelte`.
- This is Svelte 5 code: use `class`, lowercase event properties, runes, snippets, and documented `bind:*` contracts. Do not emit JSX, React hooks, `className`, `asChild`, or Base UI imports.
- Prefer this route's example and generated API table over React COSS snippets; COSS React particles are design references only.
- The copy-and-own registry is a preview. Inspect `/r/autocomplete.json` for the complete local file and dependency closure.
- Autocomplete is stable in the current source catalog.