# Combobox

An input combined with a list of predefined items to select.

## 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 { Combobox } from "coss-svelte";
</script>

<Combobox
	aria-label="Select a item"
	placeholder="Select a item…"
	options={[
		"Apple",
		"Banana",
		"Orange",
		"Grape",
		"Strawberry",
		"Mango",
		"Pineapple",
		"Kiwi",
		"Peach",
		"Pear",
	]}
/>

```

## Anatomy

- `Combobox`
- `ComboboxClear`
- `ComboboxCollection`
- `ComboboxEmpty`
- `ComboboxGroup`
- `ComboboxGroupLabel`
- `ComboboxInput`
- `ComboboxItem`
- `ComboboxList`
- `ComboboxPopup`
- `ComboboxSeparator`
- `ComboboxTrigger`
- `ComboboxValue`

## API Reference

### Combobox

An input combined with a list of predefined items to select.

**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` | `"Choose"` | 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).

### ComboboxClear

Renders a control that clears the current value.

**Composition and refs**

- `children: Snippet<[]>`

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

### ComboboxCollection

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).

### ComboboxEmpty

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).

### ComboboxGroup

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).

### ComboboxGroupLabel

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).

### ComboboxInput

Renders the input field for the parent component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showTrigger` | `boolean` | `true` | 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).

### ComboboxItem

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).

### ComboboxList

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).

### ComboboxPopup

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).

### ComboboxSeparator

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).

### ComboboxTrigger

Renders the control that opens, closes, or selects related content.

**Composition and refs**

- `children: Snippet<[]>`
- `child: Snippet<[{ props: Record<string, unknown> }]>`
- `bind:ref: HTMLElement \| null`

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

### ComboboxValue

Renders the current value for the parent component.

**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 | bits |
| Category | Selection & Input |
| Particles | 18 |

## 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/combobox.json` for the complete local file and dependency closure.
- Combobox is stable in the current source catalog.