---
title: MultiSelect
description: Choose multiple collection items in a searchable tag field.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# MultiSelect

> Choose multiple collection items in a searchable tag field.

## Anatomy

```text
MultiSelect [component; no DOM]
├── control [slot]
│   ├── leading [slot]
│   ├── tagsContainer [slot]
│   │   ├── tag [slot]
│   │   │   ├── tagLabel [slot]
│   │   │   └── tagRemove [slot]
│   │   ├── tagOverflow [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]
```

MultiSelect renders its portaled popup internally; the popup names are style slots, not attached parts. Replace tags with `tagRender`.

## Usage

Use MultiSelect for several collection items shown as tags, or for creatable free-form tags. Each
value resolves through a collection item. Use [Select](https://moraine.subf.dev/components/select.md) for one non-editable
choice, [Combobox](https://moraine.subf.dev/components/combobox.md) for editable single selection, or
[BaseSelect](https://moraine.subf.dev/components/base-select.md) to compose the listbox yourself. Unlike Select and Combobox,
`items` takes item objects only, with no string shorthand.

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

export function Example() {
  return (
    <Field label="Skills">
      <MultiSelect
        items={[
          { label: 'Design', value: 'design' },
          { label: 'Code', value: 'code' },
        ]}
        placeholder="Choose skills"
      />
    </Field>
  )
}
```

### Values and tag lifecycle

`value` is the array of selected item values, in selection order. An empty array means no
selection, and an empty string can be an item value. Pair `value` with `onValueChange` for controlled
selection, or use `defaultValue` for an initial uncontrolled selection. `onValueChange` receives the
full new array and clears the search text afterward. Without `searchable`, printable keys trigger
collection typeahead. Set `searchable` to let users type in the field to filter options.

```tsx
<MultiSelect
  searchable
  items={frameworks}
  value={selected()}
  onValueChange={setSelected}
  clearable
/>
```

`clearable` shows a clear button while there are selected values or search text. It does not always
empty a MultiSelect: selected values whose items are disabled stay selected because the user cannot
remove them, and values that match no item are dropped. Every other selection is cleared, the search
text is emptied, and `onClear` runs after `onValueChange`. Select and Combobox clear to an empty
value instead.

### Search and item creation

`searchable` and `createItem` decide whether the field is editable. Filtering follows editability, so
the four combinations behave as follows:

| `searchable` | `createItem` | Field                         | Filters options | Creates items | `openOnControlClick` default |
| ------------ | ------------ | ----------------------------- | --------------- | ------------- | ---------------------------- |
| unset        | unset        | Trigger button, no text input | No              | No            | `true`                       |
| `true`       | unset        | Editable input                | Yes             | No            | `false`                      |
| unset        | set          | Editable input                | Yes             | Yes           | `false`                      |
| `true`       | set          | Editable input                | Yes             | Yes           | `false`                      |

`searchable` alone filters the collection as the user types. `createItem` makes the input editable and
enables creation. It also filters the list, so `searchable` adds nothing once `createItem` is set.
`filterMethod` and `autocomplete` have no effect on a non-editable control.

`openOnControlClick` defaults to the opposite of editability. A non-editable control opens its popup
on click. An editable control focuses its input on click and opens from typing, the chevron button,
or ArrowDown. Set `openOnControlClick` explicitly to change either default.

### Item creation and delimiters

`createItem` receives the trimmed query text when the user commits text that matches no existing item
by label or value, and returns the `TItem` to select. The item is added to the top of the option list
until a native form reset. Nothing is created when the value is already selected or `maxValues` is
reached. Commit text with Enter, a token separator, or paste; all go through the same creation path.
`tokenSeparators` defaults to `[',']`.

```tsx
<MultiSelect
  value={tags()}
  onValueChange={setTags}
  createItem={(input) => ({ label: input.trim(), value: input.trim().toLowerCase() })}
  tokenSeparators={[',', ' ']}
/>
```

### Keyboard interaction

| Key                 | Behavior                                                                        |
| ------------------- | ------------------------------------------------------------------------------- |
| Backspace           | With an empty input, remove the last removable tag                              |
| ArrowLeft           | At the start of the input, focus the last tag's remove button                   |
| ArrowLeft / Right   | On a remove button, focus the neighboring removable tag, or return to the input |
| Backspace / Delete  | On a remove button, remove that tag and focus a neighbor                        |
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options                   |
| Enter               | Commit the highlighted option, or create an item from the input text            |
| Escape              | Close the popup; the search text resets once it closes                          |
| Tab                 | Close the popup and move focus on                                               |

### Virtualization

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

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

## Examples

### Color issue labels

Use `tagRender` to style tags from item data such as a color class. Selected values still come
from the collection.

```tsx
import { Icon, MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'

interface LabelItem extends MultiSelectT.Item {
  color: string
}

const LABELS: LabelItem[] = [
  {
    label: 'bug',
    value: 'bug',
    color: 'bg-red-500/15 border-red-500/30 text-red-700 dark:text-red-400',
  },
  {
    label: 'feature',
    value: 'feature',
    color: 'bg-purple-500/15 border-purple-500/30 text-purple-700 dark:text-purple-400',
  },
  {
    label: 'documentation',
    value: 'docs',
    color: 'bg-blue-500/15 border-blue-500/30 text-blue-700 dark:text-blue-400',
  },
  {
    label: 'performance',
    value: 'perf',
    color: 'bg-amber-500/15 border-amber-500/30 text-amber-700 dark:text-amber-400',
  },
  {
    label: 'security',
    value: 'security',
    color: 'bg-emerald-500/15 border-emerald-500/30 text-emerald-700 dark:text-emerald-400',
  },
]

export function CustomTags() {
  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Issue Labels</label>
      <MultiSelect<LabelItem>
        items={LABELS}
        defaultValue={['bug', 'perf']}
        searchable
        openOnControlClick
        placeholder="Select labels..."
        tagRender={(props) => {
          const color = () => props.item?.color ?? 'bg-muted border-border text-foreground'
          return (
            <span
              class={`text-xs font-medium px-2 py-0.5 border rounded-full inline-flex gap-1.5 items-center ${color()}`}
            >
              <span class="rounded-full bg-current opacity-70 h-1.5 w-1.5" />
              <span>{props.label}</span>
              <button
                type="button"
                aria-label={`Remove ${props.value}`}
                onClick={(event) => {
                  event.stopPropagation()
                  props.remove()
                }}
                class="p-0.5 rounded-full inline-flex transition-opacity items-center justify-center hover:opacity-80"
              >
                <Icon name="i-lucide:x" class="size-3" />
              </button>
            </span>
          )
        }}
      />
    </div>
  )
}
```

### Assign project members

Search teammates and keep each selection as a tag. Put the email or role in `description`.

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

const TEAM_MEMBERS: MultiSelectT.Item[] = [
  {
    label: 'Sarah Connor',
    value: 'sarah',
    icon: 'i-lucide:user',
    description: 'sarah@example.com · Admin',
  },
  {
    label: 'Alex Rivera',
    value: 'alex',
    icon: 'i-lucide:user',
    description: 'alex@example.com · Designer',
  },
  {
    label: 'Elena Rostova',
    value: 'elena',
    icon: 'i-lucide:user',
    description: 'elena@example.com · Engineer',
  },
  {
    label: 'David Kim',
    value: 'david',
    icon: 'i-lucide:user',
    description: 'david@example.com · DevOps',
  },
  {
    label: 'Marcus Vance',
    value: 'marcus',
    icon: 'i-lucide:user',
    description: 'marcus@example.com · QA',
  },
]

export function UserChips() {
  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Project Assignees</label>
      <MultiSelect
        items={TEAM_MEMBERS}
        defaultValue={['sarah', 'alex']}
        searchable
        openOnControlClick
        placeholder="Assign teammates..."
        clearable
      />
    </div>
  )
}
```

### Cap selection and visible tags

`maxValues` blocks additional selections by disabling unselected options. `maxVisible` is visual:
surplus selections stay committed and collapse into a `+N` summary. Use `tagOverflowRender` to
render the hidden tags yourself, for example in a tooltip.

```tsx
import { Icon, MultiSelect, Tooltip } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { For } from 'solid-js'

const TECH_STACK: MultiSelectT.Item[] = [
  { label: 'SolidJS', value: 'solid', icon: 'i-lucide:atom' },
  { label: 'TypeScript', value: 'ts', icon: 'i-lucide:code' },
  { label: 'Tailwind CSS', value: 'tailwind', icon: 'i-lucide:palette' },
  { label: 'Rust', value: 'rust', icon: 'i-lucide:cog' },
  { label: 'Docker', value: 'docker', icon: 'i-lucide:container' },
]

export function MaxValuesMaxVisible() {
  return (
    <div class="gap-6 grid max-w-2xl w-full sm:grid-cols-2">
      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Selection Limit (maxValues = 2)
        </label>
        <MultiSelect
          items={TECH_STACK}
          maxValues={2}
          placeholder="Select up to 2 skills..."
          defaultValue={['solid']}
          searchable
          openOnControlClick
        />
        <p class="text-xs text-muted-foreground">
          Hard cap: prevents adding more once limit is reached.
        </p>
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Display Limit (maxVisible = 1)
        </label>
        <MultiSelect
          items={TECH_STACK}
          defaultValue={['solid', 'ts', 'tailwind']}
          maxVisible={1}
          tagOverflowRender={(props) => (
            <Tooltip openDelay={200}>
              <Tooltip.Trigger
                as="span"
                class="text-muted-foreground px-1 flex cursor-default items-center"
              >
                +{props.count}
              </Tooltip.Trigger>
              <Tooltip.Content class="p-2 flex gap-1">
                <For each={props.tags}>
                  {(tag) => (
                    <span class="px-2 py-1 rounded bg-muted flex gap-1.5 items-center">
                      {tag.label}
                      <Icon name="i-lucide:x" class="text-muted-foreground size-3.5" />
                    </span>
                  )}
                </For>
              </Tooltip.Content>
            </Tooltip>
          )}
          placeholder="Select tags..."
          searchable
          openOnControlClick
        />
        <p class="text-xs text-muted-foreground">
          Visual only: hover +N to inspect the collapsed tags.
        </p>
      </div>
    </div>
  )
}
```

### Create a missing topic

Pass `createItem` and an `emptyRender` action so unmatched text can become a collection item.
The `create` function in the `emptyRender` state runs `createItem` for the current search text.

```tsx
import { Button, MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createSignal } from 'solid-js'

const INITIAL_TOPICS: MultiSelectT.Item[] = [
  { label: 'React', value: 'react' },
  { label: 'SolidJS', value: 'solid' },
  { label: 'Vue.js', value: 'vue' },
  { label: 'TypeScript', value: 'ts' },
]

export function CreateNewTags() {
  const [tags, setTags] = createSignal<MultiSelectT.Item['value'][]>(['solid'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">
        Topics (Select existing or type to create)
      </label>
      <MultiSelect
        searchable
        items={INITIAL_TOPICS}
        value={tags()}
        onValueChange={setTags}
        createItem={(input) => ({ value: input.trim().toLowerCase(), label: input.trim() })}
        tokenSeparators={[',', ';']}
        placeholder="Type to create or select..."
        openOnControlClick
        clearable
        emptyRender={(ctx) => (
          <div class="p-2 text-center">
            <Button
              variant="link"
              size="sm"
              class="text-xs text-primary"
              onClick={() => ctx.create()}
            >
              Create &ldquo;{ctx.searchValue}&rdquo;
            </Button>
          </div>
        )}
      />
      <p class="text-xs text-muted-foreground">Selected values: {tags().join(', ') || 'none'}</p>
    </div>
  )
}
```

### Enter free-form tags

With no predefined items, combine `createItem` and `tokenSeparators` for a tag input. Comma, space,
and paste all create tokens.

```tsx
import { MultiSelect } from 'moraine'
import { createSignal } from 'solid-js'

export function FreeFormTags() {
  const [tags, setTags] = createSignal<string[]>(['web', 'ui', 'components'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">
        Free-Form Tags (Comma or space separated)
      </label>
      <MultiSelect
        value={tags()}
        onValueChange={setTags}
        createItem={(input) => ({ value: input.trim().toLowerCase(), label: input.trim() })}
        tokenSeparators={[',', ' ']}
        placeholder="Type words, press space or comma..."
        clearable
      />
      <p class="text-xs text-muted-foreground">Tags array: {JSON.stringify(tags())}</p>
    </div>
  )
}
```

### Grant grouped permissions

Organize a large permission set with `type: 'group'`. Group labels are not selectable.

```tsx
import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createSignal } from 'solid-js'

const PERMISSION_GROUPS: MultiSelectT.Entry[] = [
  {
    label: 'User Management',
    type: 'group',
    items: [
      { label: 'Invite Members', value: 'users:invite', icon: 'i-lucide:user-plus' },
      { label: 'Edit Roles', value: 'users:roles', icon: 'i-lucide:shield' },
      { label: 'Remove Members', value: 'users:remove', icon: 'i-lucide:user-minus' },
    ],
  },
  {
    label: 'Content Management',
    type: 'group',
    items: [
      { label: 'Create Articles', value: 'content:create', icon: 'i-lucide:file-plus' },
      { label: 'Publish Content', value: 'content:publish', icon: 'i-lucide:send' },
      { label: 'Delete Content', value: 'content:delete', icon: 'i-lucide:trash-2' },
    ],
  },
  {
    label: 'Billing & Settings',
    type: 'group',
    items: [
      { label: 'View Invoices', value: 'billing:view', icon: 'i-lucide:receipt' },
      { label: 'Modify Subscriptions', value: 'billing:edit', icon: 'i-lucide:credit-card' },
    ],
  },
]

export function GroupedItems() {
  const [selected, setSelected] = createSignal(['users:invite', 'content:publish'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Role Permissions</label>
      <MultiSelect
        placeholder="Select permissions..."
        items={PERMISSION_GROUPS}
        value={selected()}
        onValueChange={setSelected}
        searchable
        openOnControlClick
        clearable
      />
    </div>
  )
}
```

### Lock required modules

Disable an option to keep it in the list without allowing toggle. `disabled` and `readOnly` on the
root freeze the whole control.

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

const MODULES: MultiSelectT.Item[] = [
  { label: 'Core Runtime (Locked)', value: 'core', disabled: true },
  { label: 'Analytics Engine', value: 'analytics' },
  { label: 'Push Notifications', value: 'notifications' },
  { label: 'Search Indexer', value: 'search' },
]

export function ClearAndDisabled() {
  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">
          Disabled Option inside List (Core Runtime cannot be toggled)
        </label>
        <MultiSelect
          items={MODULES}
          defaultValue={['core', 'analytics']}
          searchable
          openOnControlClick
          placeholder="Select optional modules..."
        />
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">Disabled Component</label>
        <MultiSelect
          items={MODULES}
          disabled
          defaultValue={['analytics', 'search']}
          placeholder="Disabled"
        />
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">Read-only Component</label>
        <MultiSelect
          items={MODULES}
          readOnly
          defaultValue={['core', 'notifications']}
          placeholder="Read-only"
        />
      </div>
    </div>
  )
}
```

### Search a large collection

Pass a `createListVirtualizer` instance as `virtualizer` when opening or scrolling the full list is
slow.

```tsx
import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'

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

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

  return (
    <div class="max-w-md w-full">
      <MultiSelect
        items={OPTIONS}
        searchable
        openOnControlClick
        placeholder="Search across 10,000 options..."
        virtualizer={virtualizer}
        classes={{ listbox: 'h-80 max-h-80' }}
      />
    </div>
  )
}
```

### Require a minimum number of tags

Validate the selected array with `createForm`. Use a `minLength` schema rule to fail short
selections; `required` only checks that something is selected. A selection made only of disabled
items passes constraint validation but submits no value to the native form, as a native
`<select multiple>` does.

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

const TOPICS = [
  { label: 'TypeScript', value: 'typescript' },
  { label: 'SolidJS', value: 'solidjs' },
  { label: 'Tailwind CSS', value: 'tailwind' },
  { label: 'UnoCSS', value: 'unocss' },
  { label: 'Vite', value: 'vite' },
] satisfies MultiSelectT.Item[]

export function FormIntegration() {
  const [submittedTags, setSubmittedTags] = createSignal<string[]>([])
  const form = createForm({
    schema: v.object({
      topics: v.pipe(
        v.array(v.string()),
        v.minLength(2, 'Please select at least 2 relevant topics.'),
      ),
    }),
    initialInput: { topics: ['typescript'] },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedTags(output.topics)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="topics"
          label="Interest Topics"
          description="Select at least 2 topics for your curated developer feed."
          required
        >
          <MultiSelect
            items={TOPICS}
            placeholder="Select topics..."
            searchable
            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">
            Submitted:{' '}
            <span class="text-foreground font-medium font-mono">
              {submittedTags().length ? submittedTags().join(', ') : 'none'}
            </span>
          </p>
        </div>
      </div>
    </form.Form>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-closed` | `multi-select-control`, `multi-select-content`, `multi-select-trigger` | Present when disclosure or transition content is closed. |
| `data-disabled` | `multi-select-control`, `multi-select-item`, `multi-select-trigger` | Present when the component, slot, or item is disabled. |
| `data-editable` | `multi-select-control` | Present when the value can be edited as text. |
| `data-expanded` | `multi-select-control`, `multi-select-content`, `multi-select-trigger` | Present when the panel, accordion, or menu is expanded. |
| `data-invalid` | `multi-select-control`, `multi-select-trigger` | Present when the field or form has a validation error. |
| `data-readonly` | `multi-select-control` | Present when the field is in read-only mode. |
| `data-required` | `multi-select-control` | Present when the field input is required. |
| `data-tags` | `multi-select-control` | Present when the control is displaying selected values as tags. |
| `data-side` | `multi-select-content` | Stores the resolved floating or drawer content side. |
| `data-highlighted` | `multi-select-item`, `multi-select-item-description` | Present when the item is highlighted by pointer or keyboard navigation. |
| `data-selected` | `multi-select-item` | Present when the item or tab is selected. |
| `data-duplicate` | `multi-select-input` | Present when the entered value duplicates an existing value. |
| `data-loading` | `multi-select-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 | false | Shows a clear button while there are selected values or search text. Clearing removes every<br>selected value except those of disabled items, empties the search text, calls `onClear`,<br>and returns focus to the control. |
| 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. |
| createItem | ((input: string) => TItem) \| undefined | — | Creates an item from free text. It is called with the trimmed text when the user commits<br>text that matches no existing item by label or value (ignoring case and accents), by<br>pressing `Enter`, completing a token separator, pasting, or calling `create` from<br>`emptyRender`. The returned item (its `value` must be a string or number) is selected and<br>added to the top of the option list until the form is reset. Nothing is created once<br>`maxValues` is reached or when the value is already selected. Providing it also enables the<br>editable search input, like `searchable`. |
| defaultOpen | boolean \| undefined | false | Initial popup state when `open` is not set. |
| defaultSearchValue | string \| undefined | "" | Initial search text when `searchValue` is not set. |
| defaultValue | TItem['value'][] \| undefined | — | Initial selected values 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 or `items` is empty. A<br>function receives `{ searchValue, hasMatches, selectedValues, isAtMaxValues, create, close }`,<br>where `create(value?)` runs `createItem` for `value` (default: the current search text) and<br>returns whether an item was added. Defaults to the `create` translation (`Press Enter to<br>create “text”`) when `createItem` is set and text was typed, otherwise to the `empty`<br>translation. |
| filterMethod | false \| 'contains' \| 'startsWith' \| 'endsWith' \| ((query: string, item: 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: 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 | — | Optional editable inner input element ref. Not assigned in non-editable mode. |
| isItemDisabled | ((item: TItem, values: readonly 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<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<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 | ({<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: ({<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: item objects (no string shorthand), optionally grouped with<br>`{ type: 'group', label, items }` and divided with `{ type: 'separator' }`. Item values must<br>be unique across the whole collection; a repeated value is ignored and logs an error in<br>development. Items created through `createItem` are added on top of this list. |
| leading | IconT.Name \| undefined | — | Icon rendered before the tags and 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 in the editable input. |
| loadingIcon | IconT.Name \| undefined | 'icon-loading' | Icon shown instead of `trailing` while `loading`. |
| maxValues | number \| undefined | — | Maximum number of selected values. Once reached, unselected options are disabled and typed<br>text is not committed; selected ones can still be removed. It does not truncate a larger<br>`value`. |
| maxVisible | number \| undefined | — | Maximum number of tags rendered in the control. The remaining selected values collapse into<br>a `+N` summary, or into `tagOverflowRender`. The selection itself is unaffected. `0` hides<br>every tag; unlimited when omitted. |
| 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`. |
| 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<TItem['value'][]>) => void) \| undefined | — | Called with the full new array of selected values when the user adds or removes an item<br>(clicking an option, `Enter`, removing a tag, or clearing). The search text is cleared<br>afterwards. Not called for prop updates or while disabled or 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 | — | Whether a pointer click on the control (outside its buttons) opens the popup. Defaults<br>to `false` when editable (`searchable` or `createItem` set) and `true` otherwise. Typing<br>non-blank text, `ArrowDown`, and the toggle button open it regardless. |
| overflowPadding | number \| undefined | 4 | Viewport collision padding in pixels. |
| placeholder | string \| undefined | "" | Text shown in the control while no value is selected: a label in the non-editable control,<br>or the input placeholder when editable. Hidden as soon as there is a tag. |
| 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`. |
| removeIcon | IconT.Name \| undefined | 'icon-close' | Icon used by tag remove buttons. |
| 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. |
| searchable | boolean \| undefined | false | Adds an editable input to the control so typing filters the options, using `filterMethod`.<br>It is also enabled implicitly by `createItem`. When neither is set the control is a<br>non-editable trigger: there is no input, and `filterMethod` and `autocomplete` have no<br>effect. |
| 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. |
| tagOverflowRender | JSX.Element \| Component<TagOverflowRenderProps<TItem>> \| undefined | — | Content shown in place of the default `+N` summary when `maxVisible` hides tags. A<br>function receives `{ count, tags }`, where `tags` are the hidden entries in selection order. |
| tagRender | Component<TagRenderProps<TItem>> \| undefined | — | Replaces the default tag (label plus remove button) of each visible tag. Receives<br>`{ item, value, label, remove }`; `item` is `undefined` for a selected value that matches<br>no item. Provide your own control that calls `remove()`, which does nothing for disabled<br>items. |
| tokenSeparators | string[] \| undefined | [','] | Strings that commit completed input tokens through `createItem` or an exact source match,<br>while typing or pasting into the editable input. Duplicate separators are ignored and<br>overlapping separators prefer the longest match. |
| 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 for this instance, merged over the messages from the<br>provider and locale: `clear`, `loading`, `toggle`, `empty`, `placeholder`, `overflow`,<br>`create`, and `remove`. `overflow({ count })`, `create({ value })`, and `remove({ title })`<br>are functions returning the text. |
| value | TItem['value'][] \| undefined | — | Controlled array of selected item values, in selection order. `undefined` keeps the<br>selection uncontrolled; `[]` keeps it controlled and empty. In controlled mode the<br>selection changes only when you update this prop in `onValueChange`. |
| variant | 'outline' \| 'subtle' \| 'ghost' \| 'none' \| undefined | 'outline' | Visual treatment of the component. |
| virtualizer | SelectVirtualizer<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. |

**`createItem` example**

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

<MultiSelect
  items={[{ label: 'Design', value: 'design' }]}
  createItem={(input) => ({ label: input, value: input.toLowerCase() })}
/>
```

**`emptyRender` example**

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

<MultiSelect
  items={[{ label: 'Design', value: 'design' }]}
  createItem={(input) => ({ label: input, value: input })}
  emptyRender={(state) => (
    <button type="button" onClick={() => state.create()}>
      Add "{state.searchValue}"
    </button>
  )}
/>
```

**`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 { MultiSelect } from 'moraine'

<MultiSelect
  items={[
    { label: 'Design', value: 'design' },
    { type: 'separator' },
    {
      type: 'group',
      label: 'Engineering',
      items: [
        { label: 'Frontend', value: 'frontend' },
        { label: 'Backend', value: 'backend', disabled: true },
      ],
    },
  ]}
/>
```

**`tagOverflowRender` example**

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

<MultiSelect
  items={[
    { label: 'Design', value: 'design' },
    { label: 'Code', value: 'code' },
  ]}
  defaultValue={['design', 'code']}
  maxVisible={1}
  tagOverflowRender={(overflow) => <span>and {overflow.count} more</span>}
/>
```

**`tagRender` example**

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

<MultiSelect
  items={[{ label: 'Design', value: 'design' }]}
  defaultValue={['design']}
  tagRender={(tag) => (
    <button type="button" onClick={() => tag.remove()}>
      {tag.label} ×
    </button>
  )}
/>
```

**`translations` example**

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

<MultiSelect
  items={[{ label: 'Design', value: 'design' }]}
  createItem={(input) => ({ label: input, value: input })}
  translations={{
    create: ({ value }) => `Add "${value}"`,
    remove: ({ title }) => `Remove tag ${title}`,
    overflow: ({ count }) => `${count} more selected`,
  }}
/>
```

**`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} />
```
