---
title: Combobox
description: Choose one collection item through an editable search input.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Combobox

> Choose one collection item through an editable search input.

## 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]
        │   ├── separator [slot]
        │   └── item [slot]
        │       ├── itemLeading [slot]
        │       ├── itemWrapper [slot]
        │       │   ├── itemLabel [slot]
        │       │   └── itemDescription [slot]
        │       └── itemIndicator [slot]
        └── empty [slot]
```

Combobox renders the portaled popup internally; the popup names are style slots, not attached parts.

## Usage

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, [MultiSelect](https://moraine.subf.dev/components/multi-select.md) for several collection values, or
[BaseSelect](https://moraine.subf.dev/components/base-select.md) to compose the listbox yourself.

```tsx
import { Field, Combobox } from 'moraine'

export function Example() {
  return (
    <Field label="Fruit">
      <Combobox
        items={[
          { label: 'Apple', value: 'apple' },
          { label: 'Pear', value: 'pear' },
        ]}
        placeholder="Search fruit"
      />
    </Field>
  )
}
```

### String items

Pass strings when the label and value are identical. You can mix strings and objects at the root
or inside a group. Whitespace is preserved, and an empty string is a valid value.

```tsx
<Combobox items={['Apple', 'Banana']} defaultValue="Apple" />
<Combobox
  items={[
    'Apple',
    { value: 'pear', label: 'Pear' },
    { type: 'group', label: 'More fruit', items: ['Banana'] },
  ]}
/>
```

String items are converted to the same item shape used by callbacks: `'Apple'` becomes
`{ value: 'Apple', label: 'Apple' }`. Object items keep their identity and custom fields.
`ComboboxT.NormalizedItem<TItem>` is the callback item type. Item values must be unique. When two
items share a value, the first one wins (including a string that collides with an object), and
development builds log an error.

### Value and query

Pair `value` with `onValueChange` for controlled selection, or use `defaultValue` for an initial
uncontrolled choice. `value={undefined}` keeps the selection uncontrolled; `value={null}` keeps it
controlled and empty. `onValueChange` receives `null` when the selection is cleared, and inside a
form field, clearing writes `null`.

While open, the input displays the query; while closed, it displays the selected item label.
Query text is never committed as a value, and filtering never changes the selection. Use `value` /
`onValueChange` for selection and `searchValue` / `onSearchValueChange` for query text. The query
resets to `''` when the popup finishes closing and after a native form reset; in controlled mode,
`onSearchValueChange('')` reports these resets and you decide whether to apply them.

```tsx
<Combobox
  items={frameworks}
  value={selected()}
  onValueChange={setSelected}
  searchValue={query()}
  onSearchValueChange={setQuery}
/>
```

### Clear and loading

`clearable` shows a clear button while there is a selected value or query text. Clearing resets the
selection and the query, calls `onValueChange(null)` if a value existed, then `onClear`, and returns
focus to the input. `loading` replaces the toggle icon with `loadingIcon` and disables the toggle
button; typing and the clear button keep working.

### Pointer opening

By default, clicking inside the control focuses the input without opening the popup. The trailing
chevron button toggles the popup, and typing non-blank text or pressing ArrowDown opens it. Set
`openOnControlClick` to open the popup on any click on the control outside its buttons.

```tsx
<Combobox items={items} placeholder="Click the chevron to open" />
<Combobox items={items} openOnControlClick placeholder="Click the field to open" />
```

### Keyboard interaction

Focus stays in the input; the highlighted option is exposed through `aria-activedescendant`.

| Key                 | Behavior                                                                          |
| ------------------- | --------------------------------------------------------------------------------- |
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options                     |
| PageUp / PageDown   | Move the highlight by one page of options while open                              |
| Enter               | Open the popup, or commit the highlighted option while open                       |
| Escape              | Close the popup; with the popup closed and `clearable`, clear the value and query |
| Backspace / Delete  | With an empty input and `clearable`, clear the value                              |
| Tab                 | Close the popup and move focus on                                                 |
| Home / End          | Move the text cursor; they never move the highlight                               |

### Virtualization

Pass a `virtualizer` from `createListVirtualizer` when rendering the full collection makes opening
or scrolling slow. Type it over `ComboboxT.Row`. Read the [Virtualization guide](https://moraine.subf.dev/docs/virtualization.md)
for setup, row measurement, stable keys, and keyboard navigation.

```tsx
<Combobox items={items} virtualizer={virtualizer} />
```

## Examples

### Search a framework

Filter a local collection as the user types. `clearable` removes the committed value and the
query text.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'

const FRAMEWORKS: ComboboxT.Item[] = [
  { label: 'SolidJS', value: 'solid' },
  { label: 'React', value: 'react' },
  { label: 'Vue.js', value: 'vue' },
  { label: 'Svelte', value: 'svelte' },
  { label: 'Astro', value: 'astro' },
  { label: 'Next.js', value: 'next' },
  { label: 'Nuxt', value: 'nuxt' },
]

export function Basic() {
  return (
    <div class="max-w-xs w-full">
      <Combobox
        items={FRAMEWORKS}
        placeholder="Search framework..."
        leading="i-lucide:search"
        clearable
      />
    </div>
  )
}
```

### Pick an issue status

Put `icon` and `description` on each item when the option needs a status mark and secondary line.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'

const STATUSES: ComboboxT.Item[] = [
  {
    label: 'Backlog',
    value: 'backlog',
    icon: 'i-lucide:circle-dashed',
    description: 'Ideas and unprioritized tasks',
  },
  {
    label: 'Todo',
    value: 'todo',
    icon: 'i-lucide:circle',
    description: 'Ready to be picked up',
  },
  {
    label: 'In Progress',
    value: 'in-progress',
    icon: 'i-lucide:circle-dot',
    description: 'Work actively underway',
  },
  {
    label: 'In Review',
    value: 'review',
    icon: 'i-lucide:clock',
    description: 'PR open and waiting for review',
  },
  {
    label: 'Done',
    value: 'done',
    icon: 'i-lucide:check-circle-2',
    description: 'Completed and merged',
  },
  {
    label: 'Canceled',
    value: 'canceled',
    icon: 'i-lucide:x-circle',
    description: 'Discarded or not planned',
  },
]

export function CustomItems() {
  return (
    <div class="max-w-sm w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Issue Status</label>
      <Combobox
        items={STATUSES}
        defaultValue="in-progress"
        placeholder="Filter status..."
        openOnControlClick
      />
    </div>
  )
}
```

### Assign a teammate

Search people by name; each item's `description` shows the email and role. The default filter
matches the label only. Set `openOnControlClick` to open the list as soon as the user clicks the
control.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'

const USERS: ComboboxT.Item[] = [
  {
    label: 'Sarah Connor',
    value: 'sarah',
    icon: 'i-lucide:user',
    description: 'sarah@example.com · Engineering Lead',
  },
  {
    label: 'Alex Rivera',
    value: 'alex',
    icon: 'i-lucide:user',
    description: 'alex@example.com · Product Designer',
  },
  {
    label: 'Elena Rostova',
    value: 'elena',
    icon: 'i-lucide:user',
    description: 'elena@example.com · Frontend Engineer',
  },
  {
    label: 'David Kim',
    value: 'david',
    icon: 'i-lucide:user',
    description: 'david@example.com · DevOps Specialist',
  },
]

export function UserPicker() {
  return (
    <div class="max-w-sm w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Assignee</label>
      <Combobox
        items={USERS}
        placeholder="Assign to teammate..."
        leading="i-lucide:user-plus"
        openOnControlClick
        clearable
      />
    </div>
  )
}
```

### Match by contains or prefix

`filterMethod` defaults to `'contains'`, which matches the query anywhere in the label. Set
`'startsWith'` or `'endsWith'` to match only at that end of the label, or pass a predicate for
custom matching.

```tsx
import { Button, Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createSignal } from 'solid-js'

const CITIES: ComboboxT.Item[] = [
  { label: 'San Francisco', value: 'sf' },
  { label: 'San Jose', value: 'sj' },
  { label: 'Santa Clara', value: 'sc' },
  { label: 'Los Angeles', value: 'la' },
  { label: 'New York', value: 'ny' },
  { label: 'Boston', value: 'bos' },
]

export function FilterStrategies() {
  const [strategy, setStrategy] = createSignal<'contains' | 'startsWith'>('contains')

  return (
    <div class="max-w-xs w-full space-y-3">
      <div class="flex gap-2 items-center">
        <span class="text-xs text-muted-foreground font-medium">Filter mode:</span>
        <Button
          size="sm"
          variant={strategy() === 'contains' ? 'solid' : 'outline'}
          onClick={() => setStrategy('contains')}
        >
          contains
        </Button>
        <Button
          size="sm"
          variant={strategy() === 'startsWith' ? 'solid' : 'outline'}
          onClick={() => setStrategy('startsWith')}
        >
          startsWith
        </Button>
      </div>

      <Combobox
        items={CITIES}
        filterMethod={strategy()}
        placeholder={`Search cities (${strategy()})...`}
        leading="i-lucide:search"
        openOnControlClick
      />
    </div>
  )
}
```

### Search remote repositories

Drive `searchValue`, `onSearchValueChange`, and `loading` from a debounced request. Set
`filterMethod={false}` when the server already returns the matched items.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createSignal } from 'solid-js'

interface RepoItem extends ComboboxT.Item {
  label: string
}

const ALL_REPOS: RepoItem[] = [
  { label: 'subframe7536/moraine', value: 'moraine', icon: 'i-lucide:box' },
  { label: 'solidjs/solid', value: 'solid', icon: 'i-lucide:box' },
  { label: 'tailwindlabs/tailwindcss', value: 'tailwind', icon: 'i-lucide:box' },
  { label: 'unocss/unocss', value: 'unocss', icon: 'i-lucide:box' },
  { label: 'vitejs/vite', value: 'vite', icon: 'i-lucide:box' },
]

export function AsyncSearch() {
  const [query, setQuery] = createSignal('')
  const [loading, setLoading] = createSignal(false)
  const [items, setItems] = createSignal<ComboboxT.Item[]>(ALL_REPOS)

  let timer: ReturnType<typeof setTimeout> | undefined

  function handleSearch(search: string) {
    setQuery(search)
    setLoading(true)
    clearTimeout(timer)

    timer = setTimeout(() => {
      const filtered = ALL_REPOS.filter((item) =>
        item.label.toLowerCase().includes(search.toLowerCase()),
      )
      setItems(filtered)
      setLoading(false)
    }, 400)
  }

  return (
    <div class="max-w-xs w-full space-y-2">
      <Combobox
        items={items()}
        searchValue={query()}
        onSearchValueChange={handleSearch}
        loading={loading()}
        filterMethod={false}
        placeholder="Type to search repositories..."
        leading="i-lucide:search"
        openOnControlClick
        clearable
      />
      <p class="text-xs text-muted-foreground">
        {loading() ? 'Searching remote index...' : `${items().length} repositories found`}
      </p>
    </div>
  )
}
```

### Browse grouped technologies

Organize options into `type: 'group'` entries. Use `emptyRender` to customize the empty state when
the query has no matches.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'

const TECH_GROUPS: ComboboxT.Entry[] = [
  {
    type: 'group',
    label: 'Frontend Frameworks',
    items: [
      { label: 'SolidJS', value: 'solid', icon: 'i-lucide:atom' },
      { label: 'Vue.js', value: 'vue', icon: 'i-lucide:sparkles' },
      { label: 'React', value: 'react', icon: 'i-lucide:box' },
      { label: 'Svelte', value: 'svelte', icon: 'i-lucide:flame' },
    ],
  },
  {
    type: 'group',
    label: 'Backend & Systems',
    items: [
      { label: 'Rust', value: 'rust', icon: 'i-lucide:cog' },
      { label: 'Go', value: 'go', icon: 'i-lucide:zap' },
      { label: 'Node.js', value: 'node', icon: 'i-lucide:server' },
    ],
  },
  {
    type: 'group',
    label: 'Databases',
    items: [
      { label: 'PostgreSQL', value: 'postgres', icon: 'i-lucide:database' },
      { label: 'Redis', value: 'redis', icon: 'i-lucide:database' },
      { label: 'SQLite', value: 'sqlite', icon: 'i-lucide:database' },
    ],
  },
]

export function Groups() {
  return (
    <div class="max-w-xs w-full space-y-2">
      <Combobox
        items={TECH_GROUPS}
        placeholder="Filter technologies..."
        leading="i-lucide:search"
        openOnControlClick
        emptyRender={(ctx) => (
          <div class="text-xs text-muted-foreground p-3 text-center">
            No technology found matching &ldquo;
            <span class="text-foreground font-medium">{ctx.searchValue}</span>&rdquo;.
          </div>
        )}
      />
    </div>
  )
}
```

### Search a large collection

Pass a `createListVirtualizer` instance as `virtualizer` when rendering every row on open is slow.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'

const ITEMS: ComboboxT.Item<string>[] = Array.from({ length: 10_000 }, (_, index) => ({
  value: `option-${index}`,
  label: `Option ${index + 1}`,
}))

export function Virtualization() {
  const virtualizer = createListVirtualizer<ComboboxT.Row<ComboboxT.Item<string>>>({
    estimateSize: (entry) => (entry.type === 'label' ? 30 : 32),
    getItemKey: (entry) => entry.key,
    overscan: 8,
  })

  return (
    <div class="max-w-xs w-full">
      <Combobox
        items={ITEMS}
        placeholder="Search 10,000 options..."
        leading="i-lucide:search"
        openOnControlClick
        virtualizer={virtualizer}
        classes={{ listbox: 'h-80 max-h-80' }}
      />
    </div>
  )
}
```

### Bind a searchable field to a form

Use `form.Field` from `createForm` when the selected value needs schema validation and error
display. `required` is satisfied by any selected item, including a disabled one. In that case the
combobox passes constraint validation but submits no value, as a native `<select>` does with a
disabled selected option.

```tsx
import { Button, createForm, Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

const FRAMEWORKS = [
  { label: 'SolidJS', value: 'solid' },
  { label: 'Vue.js', value: 'vue' },
  { label: 'React', value: 'react' },
  { label: 'Svelte', value: 'svelte' },
  { label: 'Astro', value: 'astro' },
] satisfies ComboboxT.Item[]

export function FormIntegration() {
  const [submitted, setSubmitted] = createSignal<string | null>(null)
  const form = createForm({
    schema: v.object({
      framework: v.pipe(
        v.nullable(v.string()),
        v.check(
          (value): value is string => value !== null && value.length > 0,
          'Please select a primary framework.',
        ),
      ),
    }),
    initialInput: { framework: null },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmitted(output.framework)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="framework"
          label="Primary Framework"
          description="Used to configure your starter template and linting rules."
          required
        >
          <Combobox
            items={FRAMEWORKS}
            placeholder="Search and select framework..."
            leading="i-lucide:search"
            openOnControlClick
            clearable
          />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">
            Selected:{' '}
            <span class="text-foreground font-medium font-mono">{submitted() ?? 'none'}</span>
          </p>
        </div>
      </div>
    </form.Form>
  )
}
```

### Keep the query separate from the committed value

`value` is the selected item. `searchValue` is the text in the field. Reset both when the page
clears the picker.

```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<string | undefined>('solid')
  const [query, setQuery] = createSignal('')

  return (
    <div class="max-w-xs w-full space-y-3">
      <Combobox
        items={FRAMEWORKS}
        value={selected()}
        onValueChange={setSelected}
        searchValue={query()}
        onSearchValueChange={setQuery}
        placeholder="Search framework..."
        leading="i-lucide:search"
        clearable
      />
      <div class="text-xs text-muted-foreground space-y-1">
        <p>
          Committed Value:{' '}
          <span class="text-foreground font-medium font-mono">{selected() ?? 'undefined'}</span>
        </p>
        <p>
          Query Text:{' '}
          <span class="text-foreground font-medium font-mono">
            {query() ? `"${query()}"` : '(idle)'}
          </span>
        </p>
      </div>
      <Button
        variant="ghost"
        size="sm"
        disabled={selected() === undefined && !query()}
        onClick={() => {
          setSelected(undefined)
          setQuery('')
        }}
      >
        Reset Both
      </Button>
    </div>
  )
}
```

### Open the list from the whole field

By default, typing and the chevron button open the popup. Set `openOnControlClick` when a click
anywhere on the control should open it, as in an assignee picker.

```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 (
    <div class="max-w-md w-full space-y-4">
      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Default (Only typing or chevron button toggles popup)
        </label>
        <Combobox items={ITEMS} openOnControlClick={false} placeholder="Click chevron to open..." />
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Open on control click (Click anywhere inside field to open)
        </label>
        <Combobox
          items={ITEMS}
          openOnControlClick={true}
          placeholder="Click anywhere in the field..."
        />
      </div>
    </div>
  )
}
```

### Accept string labels or mixed items

Pass a string array when the label is the value. Mix strings, item objects, and `type: 'group'`
entries in one `items` list.

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'

const MIXED_STATUSES: ComboboxT.Entry[] = [
  'Open',
  { value: 'progress', label: 'In progress', description: 'Someone is actively working this' },
  {
    type: 'group',
    label: 'Closed',
    items: ['Done', { value: 'wontfix', label: "Won't fix", disabled: true }],
  },
]

export function StringItems() {
  return (
    <div class="flex flex-col gap-3 max-w-xs w-full">
      <Combobox
        aria-label="Issue status"
        items={['Open', 'In progress', 'Blocked', 'Done']}
        defaultValue="Open"
        clearable
      />
      <Combobox
        aria-label="Issue status with groups"
        items={MIXED_STATUSES}
        placeholder="Choose a status..."
        clearable
      />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-closed` | `combobox-control`, `combobox-content` | Present when disclosure or transition content is closed. |
| `data-disabled` | `combobox-control`, `combobox-item` | Present when the component, slot, or item is disabled. |
| `data-editable` | `combobox-control` | Present when the value can be edited as text. |
| `data-expanded` | `combobox-control`, `combobox-content` | Present when the panel, accordion, or menu is expanded. |
| `data-invalid` | `combobox-control` | Present when the field or form has a validation error. |
| `data-readonly` | `combobox-control` | Present when the field is in read-only mode. |
| `data-required` | `combobox-control` | Present when the field input is required. |
| `data-side` | `combobox-content` | Stores the resolved floating or drawer content side. |
| `data-highlighted` | `combobox-item`, `combobox-item-description` | Present when the item is highlighted by pointer or keyboard navigation. |
| `data-selected` | `combobox-item` | Present when the item or tab is selected. |
| `data-loading` | `combobox-trigger` | Present when the component or async operation is loading. |

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | 'start' | Alignment of the popup along the anchor's edge: `'start'`, `'center'`, or `'end'`. |
| autocomplete | JSX.InputHTMLAttributes<HTMLInputElement>['autocomplete'] \| undefined | 'off' | Native `autocomplete` attribute of the search input. In `MultiSelect` the input exists only<br>when `searchable` or `createItem` is set. |
| clearable | boolean \| undefined | — | Shows a clear button while there is a selected value or search text. Escape (with the popup<br>closed) and Backspace or Delete (with an empty input) clear too. Clearing resets the<br>selection (`onValueChange(null)` if one existed) and the search text, calls `onClear`, and<br>returns focus to the input. |
| clearIcon | IconT.Name \| undefined | 'icon-close' | Icon of the clear button. |
| closeOnEscape | boolean \| undefined | true | Whether `Escape` closes the popup. When `false` the popup stays open and `onClosePrevented`<br>is called instead. |
| closeOnOutsideClick | boolean \| undefined | true | Whether an outside interaction, pointer press or focus moving elsewhere, closes the popup.<br>When `false` the popup stays open and `onClosePrevented` is called instead. Tabbing out of<br>the control still closes it. |
| closeOnSelect | boolean \| undefined | — | Whether choosing an item closes the popup and returns focus to the control. Defaults to<br>`true` for single selection and `false` when `multiple` is set on `BaseSelect`; `MultiSelect`<br>always keeps the popup open. |
| defaultOpen | boolean \| undefined | false | Initial popup state when `open` is not set. |
| defaultSearchValue | string \| undefined | "" | Initial search text when `searchValue` is not set. |
| defaultValue | NormalizedItem<TItem>['value'] \| undefined | — | Initial selected value when `value` is not set. Read once on creation; a native form reset<br>restores it. |
| disabled | boolean \| undefined | false | Whether the control is disabled: it cannot be interacted with and sets `aria-disabled`.<br>When omitted, the control inherits `disabled` from the surrounding `Field`; an explicit<br>`false` overrides the `Field`. |
| emptyRender | JSX.Element \| Component<EmptyRenderProps<TItem>> \| undefined | — | Content shown in the popup when no item matches the search text. A function receives<br>`{ searchValue, hasMatches, selectedValue, close }`. Defaults to the `empty` translation<br>(`'No items'`). |
| filterMethod | false \| 'contains' \| 'startsWith' \| 'endsWith' \| ((query: string, item: NormalizedItem<TItem>) => boolean) \| undefined | 'contains' | How items are matched against the search text; filtering runs only while the text is not<br>empty. The named strategies compare the item's plain-text label (see `getItemLabel`)<br>ignoring case and accents using the active locale. A predicate receives the search text and<br>the item (string items arrive as `{ value, label }`) and returns whether the item stays<br>visible; it replaces the built-in matching. `false` always shows every item (use it when you<br>filter on the server). Groups with no visible items are hidden. In `MultiSelect`, filtering<br>applies only when `searchable` or `createItem` is set. |
| flip | boolean \| string \| undefined | true | Whether to flip placement when the preferred side lacks space. `false` disables flipping. A<br>string is a space-delimited list of fallback placements tried in order, each `top`,<br>`bottom`, `left`, or `right` optionally followed by `-start` or `-end` (for example<br>`'top bottom-end'`); an invalid entry throws. |
| getItemLabel | ((item: NormalizedItem<TItem>) => string) \| undefined | — | Plain-text label of an item, used for typeahead, filtering, form values, and plain-text<br>displays such as an input value or tag title; does not change rendered labels.<br>Defaults to the string `label`, otherwise `String(value)`. In `Select` and `Combobox`,<br>string items arrive as `{ value, label }`. |
| gutter | number \| undefined | 4 | Gap in pixels between anchor and popup. |
| id | string \| undefined | — | The ID of the control's main focusable element, which a surrounding `Field` label points to<br>with `for`. A unique ID is generated when omitted. The control's related parts (hidden<br>input, label, description) derive their IDs from it, so keep it unique on the page. |
| inputRef | Ref<HTMLInputElement> \| undefined | — | Receives the inner `<input>` element, for example to focus it programmatically. |
| isItemDisabled | ((item: NormalizedItem<TItem>, values: readonly NormalizedItem<TItem>['value'][]) => boolean) \| undefined | — | Extra disabled rule, evaluated for every item together with the current selected values;<br>return `true` to disable the item in addition to `item.disabled`. Disabled items cannot be<br>selected, highlighted, or reached by typeahead. In `MultiSelect`, a selected disabled item<br>keeps its tag (it cannot be removed) and survives clearing. In `Select` and `Combobox`,<br>string items arrive as `{ value, label }`. |
| itemProps | ((state: BaseSelectT.ItemRenderProps<NormalizedItem<TItem>>) => ElementProps<HTMLDivElement> \| undefined) \| undefined | — | Returns extra attributes spread on each item row, computed per item from the same state as<br>`itemRender`. `class`, `style`, `ref`, and the `onClick`, `onPointerMove`, and `onPointerDown`<br>handlers are merged with the component's own; calling `event.preventDefault()` in `onClick`<br>stops the selection. `id`, `tabIndex`, `aria-selected`, and `aria-disabled` stay<br>component-owned. |
| itemRender | Component<BaseSelectT.ItemRenderProps<NormalizedItem<TItem>>> \| undefined | — | Replaces the default content of every item row (icon, label, description, and selected<br>check). The row element itself (`role="option"`, click and hover handling) stays owned by the<br>component. Receives `{ item, selected, highlighted, disabled }`; for `Select` and `Combobox`<br>string items arrive as `{ value, label }`. Declare the parameter even when unused: a<br>zero-argument function is called as an accessor, not mounted as a component. |
| items | (string \| {<br>  /** Unique selection and form value. Values compare by identity, so `1` and `'1'` differ. */<br>  value: string \| number;<br>  /** Visual label. May be any JSX; when it is not a string, plain-text uses (typeahead,<br>filtering) fall back to `String(value)` unless `getItemLabel` is set. */<br>  label: JSX.Element;<br>  /** Whether this item cannot be selected. A disabled item is also left out of form submission. */<br>  disabled?: boolean;<br>  /** Icon rendered before the label in the default item content. Ignored when `itemRender` is set. */<br>  icon?: IconT.Name;<br>  /** Secondary text rendered under the label in the default item content. Ignored when `itemRender` is set. */<br>  description?: JSX.Element;<br>} \| {<br>  /** Structural group discriminator. */<br>  type: 'group';<br>  /** Heading rendered above the group's items. Not selectable. */<br>  label: JSX.Element;<br>  /** Items in the group. Item values must be unique across the whole collection, not just the<br>group: a repeated value is ignored (the first occurrence wins). A group with no remaining<br>items, or none matching the current search, renders nothing. */<br>  items: (string \| {<br>    /** Unique selection and form value. Values compare by identity, so `1` and `'1'` differ. */<br>    value: string \| number;<br>    /** Visual label. May be any JSX; when it is not a string, plain-text uses (typeahead,<br>  filtering) fall back to `String(value)` unless `getItemLabel` is set. */<br>    label: JSX.Element;<br>    /** Whether this item cannot be selected. A disabled item is also left out of form submission. */<br>    disabled?: boolean;<br>    /** Icon rendered before the label in the default item content. Ignored when `itemRender` is set. */<br>    icon?: IconT.Name;<br>    /** Secondary text rendered under the label in the default item content. Ignored when `itemRender` is set. */<br>    description?: JSX.Element;<br>  })[];<br>} \| {<br>  /** Structural separator discriminator. */<br>  type: 'separator';<br>})[] \| undefined | — | Options of the popup list: plain strings (shorthand for `{ value, label }`), item objects,<br>`{ type: 'group', label, items }` groups, and `{ type: 'separator' }` dividers. Item values<br>must be unique across the whole collection; a repeated value is ignored and logs an error<br>in development. Filtering by the search text hides non-matching items from the list but<br>never changes the selection. |
| leading | IconT.Name \| undefined | — | Icon rendered before the input. |
| listboxProps | ElementProps<HTMLDivElement> \| undefined | — | Extra attributes spread on the listbox `div` inside the popup, such as `aria-label`, `data-*`<br>or an `onScroll` handler (calling `event.preventDefault()` there skips `onBottomReached`).<br>`id` and `tabIndex` stay component-owned. |
| loading | boolean \| undefined | — | Replaces the toggle icon with `loadingIcon`, and disables the toggle button and marks it<br>`aria-busy`. Typing and the clear button keep working. |
| loadingIcon | IconT.Name \| undefined | 'icon-loading' | Icon shown instead of `trailing` while `loading`. |
| name | string \| undefined | — | The name of the control, used for native form submission. When omitted, the control uses<br>the name of its form binding or a string `name` set on the surrounding `Field`. |
| onBottomReached | (() => void) \| undefined | — | Called once each time scrolling brings the listbox within `scrollThreshold` of its end,<br>for example to load the next page. It fires again only after the user scrolls away from the<br>bottom and back. |
| onClear | (() => void) \| undefined | — | Called once after a clear action (see `clearable`), following `onValueChange(null)`. |
| onClosePrevented | (() => void) \| undefined | — | Called, without arguments, when `Escape` or an outside interaction was blocked by<br>`closeOnEscape={false}` or `closeOnOutsideClick={false}`. The popup remains open. |
| onOpenChange | ((open: boolean) => void) \| undefined | — | Called with the next state whenever the popup should open or close (typing, arrow keys,<br>selecting an item, `Escape`, `Tab`, or an outside press). Not called when the state would not<br>change. A disabled select never opens. |
| onReset | (() => void) \| undefined | — | Called after a native `<form>` reset has restored the initial selection (and, in `Combobox`<br>and `MultiSelect`, cleared the search text). It runs in a microtask after the `reset` event<br>and is skipped when the event was default-prevented. In controlled mode the selection stays<br>at `value`, so use this callback to reset your own state. |
| onSearchValueChange | ((value: string) => void) \| undefined | — | Called with the new search text when it changes, including the component's own resets to<br>`''`. The text is already truncated to `searchMaxLength`. During IME composition it fires<br>once the composition ends. |
| onValueChange | ((value: NoInfer<NormalizedItem<TItem>['value']> \| null) => void) \| undefined | — | Called with the new item `value` when the user commits a different item, or with `null`<br>when the selection is cleared. Typing alone does not call it (see `onSearchValueChange`).<br>Not called for prop updates, when the same item is chosen again, or while disabled or<br>read-only. |
| open | boolean \| undefined | — | Controlled popup state. `undefined` keeps it uncontrolled. In controlled mode the popup<br>opens or closes only when you update this prop in `onOpenChange`. Page scrolling is locked<br>while the popup is open. |
| openOnControlClick | boolean \| undefined | false | Whether a pointer click on the control (outside the toggle and clear buttons) opens the<br>popup. Typing non-blank text, `ArrowDown`, and the toggle button open it regardless. |
| overflowPadding | number \| undefined | 4 | Viewport collision padding in pixels. |
| placeholder | string \| undefined | — | Native placeholder of the input, so it shows whenever the input text is empty. Takes<br>precedence over the `placeholder` translation. |
| placement | 'top' \| 'right' \| 'bottom' \| 'left' \| undefined | 'bottom' | Preferred side of the anchor (the control) on which the popup opens. Combined with `align`;<br>see `flip` for when the side can change. |
| readOnly | boolean \| undefined | false | Whether the control is read-only: the value is visible and focusable but cannot be changed,<br>and `aria-readonly` is set. When omitted, the control inherits `readOnly` from the<br>surrounding `Field`. |
| required | boolean \| undefined | false | Whether the control is required, which sets `aria-required` (and the native `required`<br>attribute where the control renders a native input). When omitted, the control inherits<br>`required` from the surrounding `Field`. |
| scrollThreshold | number \| undefined | 20 | Distance from the end of the listbox, in pixels, within which `onBottomReached` fires. |
| searchMaxLength | number \| undefined | — | Maximum number of characters in the search text. Applied as the input's `maxLength` and by<br>truncating text the user commits; a controlled `searchValue` is not truncated. Unlimited when<br>omitted. |
| searchValue | string \| undefined | — | Controlled search text. `undefined` keeps the text uncontrolled. The component also resets<br>the text to `''` when the popup finishes closing, after a native form reset, and (in<br>`MultiSelect`) after the selection changes; in controlled mode these resets are reported<br>through `onSearchValueChange('')` and you decide whether to apply them. |
| shift | number \| undefined | 0 | Cross-axis offset in pixels from the resolved placement. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| slide | boolean \| undefined | true | Whether the popup may slide along its main axis to remain visible. |
| trailing | IconT.Name \| undefined | 'icon-chevron-down' | Icon of the toggle button that opens and closes the popup; replaced by `loadingIcon` while<br>`loading`. |
| translations | Translations \| undefined | — | Overrides the built-in messages (`clear`, `loading`, `toggle`, `empty`, `placeholder`) for<br>this instance, merged over the messages from the provider and locale. `empty` is the<br>default text of the empty state. |
| value | NormalizedItem<TItem>['value'] \| null \| undefined | — | Controlled committed value. `undefined` keeps the selection uncontrolled; `null` keeps it<br>controlled and empty. Typed search text is never a value; it lives in `searchValue`. In<br>controlled mode the selection changes only when you update this prop in `onValueChange`. |
| variant | 'outline' \| 'subtle' \| 'ghost' \| 'none' \| undefined | 'outline' | Visual treatment of the component. |
| virtualizer | SelectVirtualizer<NormalizedItem<TItem>> \| undefined | — | Renders only the visible rows, such as `createListVirtualizer()` from `moraine/virtualizer`<br>typed over `ComboboxT.Row`. Rows include group labels and separators. The listbox is the<br>scroll container, items get `aria-posinset` and `aria-setsize`, and keyboard highlight scrolls<br>through the virtualizer. Not available on `Select`. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`emptyRender` example**

```tsx
import { Combobox } from 'moraine'

<Combobox
  items={['Apple', 'Pear']}
  emptyRender={(state) => <span>No fruit matches "{state.searchValue}"</span>}
/>
```

**`filterMethod` example**

```tsx
import { Combobox } from 'moraine'

<Combobox
  items={[
    { label: 'Apple', value: 'apple', description: 'Red fruit' },
    { label: 'Lime', value: 'lime', description: 'Green fruit' },
  ]}
  filterMethod={(query, item) =>
    `${item.value} ${item.description}`.toLowerCase().includes(query.toLowerCase())
  }
/>
```

**`getItemLabel` example**

```tsx
import { Combobox } from 'moraine'

<Combobox
  items={[
    { label: <strong>Apple</strong>, value: 'apple' },
    { label: <strong>Pear</strong>, value: 'pear' },
  ]}
  getItemLabel={(item) => String(item.value)}
/>
```

**`isItemDisabled` example**

```tsx
import { MultiSelect } from 'moraine'

<MultiSelect
  items={[
    { label: 'Admin', value: 'admin' },
    { label: 'Guest', value: 'guest' },
  ]}
  isItemDisabled={(item, values) => item.value === 'guest' && values.includes('admin')}
/>
```

**`itemProps` example**

```tsx
import { Select } from 'moraine'

<Select
  items={['Apple', 'Pear']}
  itemProps={(state) => ({ 'data-testid': `option-${state.item.value}` })}
/>
```

**`itemRender` example**

```tsx
import { Select } from 'moraine'

<Select
  items={[
    { label: 'Free', value: 'free' },
    { label: 'Pro', value: 'pro' },
  ]}
  itemRender={(state) => (
    <span>
      {state.item.label}
      {state.selected ? ' ✓' : ''}
    </span>
  )}
/>
```

**`items` example**

```tsx
import { Combobox } from 'moraine'

<Combobox
  items={[
    { type: 'group', label: 'Fruit', items: ['Apple', { label: 'Pear', value: 'pear' }] },
    { type: 'separator' },
    { type: 'group', label: 'Veg', items: [{ label: 'Leek', value: 'leek' }] },
  ]}
/>
```

**`virtualizer` example**

```tsx
import { Combobox } from 'moraine'
import type { ComboboxT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'

const items = Array.from({ length: 5000 }, (_, index) => `Item ${index}`)
const virtualizer = createListVirtualizer<ComboboxT.Row<string>>({ estimateSize: () => 32 })

<Combobox items={items} virtualizer={virtualizer} />
```
