---
title: Combobox
description: Choose one collection item through an editable search input.
package: moraine
version: 0.6.0
repository: https://github.com/subframe7536/moraine
---
# Combobox
> Choose one collection item through an editable search input.
Use Combobox when users should type to find one item in a collection. Use [Select](https://moraine.subf.dev/components/select.md) for a non-editable choice and [MultiSelect](https://moraine.subf.dev/components/multi-select.md) for multiple collection values.
## Basic usage
```tsx
import { Field, Combobox } from 'moraine'
export function Example() {
return (
)
}
```
## Anatomy
```text
Combobox [component; no DOM]
├── control [slot]
│ ├── leading [slot]
│ ├── input [slot]
│ ├── clear [slot]
│ └── trigger [slot]
└── positioner [internal]
└── content [slot]
├── listbox [slot]
│ ├── group [slot]
│ │ └── groupLabel [slot]
│ └── item [slot]
│ ├── itemLeading [slot]
│ ├── itemWrapper [slot]
│ │ ├── itemLabel [slot]
│ │ └── itemDescription [slot]
│ └── itemIndicator [slot]
└── empty [slot]
```
Combobox renders the portaled popup collection internally; its content and item names are style slots, rather than attached child parts.
## Usage
### String items
Pass strings when the label and value are identical. Strings and objects can be mixed at the
root or inside a group. Whitespace is preserved, and an empty string is a valid value.
```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
const MIXED_ITEMS: ComboboxT.Entry[] = [
'Apple',
{ value: 'pear', label: 'Pear', description: 'Fresh fruit' },
{
type: 'group',
label: 'More fruit',
items: ['Banana', { value: 'cherry', label: 'Cherry', disabled: true }],
},
]
export function StringItems() {
return (
)
}
```
String items are converted to the same item shape used by callbacks: `'Apple'` becomes
`{ value: 'Apple', label: 'Apple' }`. Object items retain their identity and custom fields.
`ComboboxT.NormalizedItem` names the callback item type. Duplicate values use the first
occurrence, including collisions between strings and objects.
### Value and query
Pair `value` with `onValueChange` for controlled selection, or use `defaultValue` for an initial
uncontrolled choice. `null` means no selection; an empty string is a valid item value.
While open, the input displays the query; while closed, it displays the selected item label.
Arbitrary query text is never committed as a value. Use `value` / `onValueChange` for selection and
`searchValue` / `onSearch` for query text.
```tsx
import { Button, Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createSignal } from 'solid-js'
const FRAMEWORKS: ComboboxT.Item[] = [
{ label: 'SolidJS', value: 'solid' },
{ label: 'Vue.js', value: 'vue' },
{ label: 'React', value: 'react' },
{ label: 'Svelte', value: 'svelte' },
{ label: 'Astro', value: 'astro' },
]
export function UsageQuery() {
const [selected, setSelected] = createSignal('solid')
const [query, setQuery] = createSignal('')
return (
)
}
```
### Pointer opening
By default, clicking inside the input focuses the field without opening the popup immediately. The trailing
chevron button toggles the dropdown, while typing or pressing ArrowDown opens it. Set `openOnControlClick={true}`
if you want any click on the field to open the options list.
```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
const ITEMS: ComboboxT.Item[] = [
{ label: 'Development', value: 'dev' },
{ label: 'Design', value: 'design' },
{ label: 'Marketing', value: 'marketing' },
{ label: 'Product', value: 'product' },
]
export function ExplicitTrigger() {
return (
)
}
```
### Keyboard interaction
| Key | Behavior |
| ------------------- | --------------------------------------------------------------------------- |
| ArrowDown / ArrowUp | Open the popup or navigate through matched options |
| Enter | Commit the currently highlighted option |
| Escape | Revert query text or close the dropdown |
| Home / End | Move text cursor within input (or navigate options when listbox is focused) |
### Virtualization
Add `createListVirtualizer` when rendering the full collection makes opening or scrolling slow.
Read the [Virtualization guide](https://moraine.subf.dev/docs/virtualization.md) for setup, row measurements, stable keys, and keyboard navigation.
```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'
const ITEMS: ComboboxT.Item[] = Array.from({ length: 10_000 }, (_, index) => ({
value: `option-${index}`,
label: `Option ${index + 1}`,
}))
export function Virtualization() {
const virtualizer = createListVirtualizer<
ComboboxT.Row>,
HTMLDivElement,
HTMLDivElement
>({
estimateSize: (entry) => (entry.type === 'label' ? 30 : 32),
getItemKey: (entry) => entry.key,
overscan: 8,
})
return (