---
title: Select
description: Choose one item from a non-editable collection.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Select

> Choose one item from a non-editable collection.

## Anatomy

```text
Select [component; no DOM]
├── control [slot]
│   ├── trigger [slot]
│   │   ├── leading [slot]
│   │   ├── value [slot]
│   │   └── trailing [slot]
│   └── clear [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]
```

Select renders the portaled popup internally; the popup names are style slots, not attached parts. Use [BaseSelect](https://moraine.subf.dev/components/base-select.md) to compose the listbox yourself.

## Usage

Use Select for one choice from a non-editable collection. Use [Combobox](https://moraine.subf.dev/components/combobox.md) when
users need to type a query or the collection is large enough to need virtualization,
[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, Select } from 'moraine'

export function Example() {
  return (
    <Field label="Size">
      <Select
        items={[
          { label: 'Small', value: 'sm' },
          { label: 'Large', value: 'lg' },
        ]}
        placeholder="Choose a size"
      />
    </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
<Select items={['Apple', 'Banana']} defaultValue="Apple" />
<Select
  items={[
    'Apple',
    { value: 'pear', label: 'Pear', description: 'Fresh fruit' },
    { type: 'group', label: 'More fruit', items: ['Banana'] },
  ]}
/>
```

A string item normalizes to `{ value, label }` with both set to the string, so `'Apple'` becomes
`{ value: 'Apple', label: 'Apple' }`. Object items keep their custom fields, and
`SelectT.NormalizedItem<TItem>` is the item type passed to callbacks. Item values must be unique
across the collection. 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 collection

The value slot shows the selected label, or `String(value)` when the value matches no item.

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

```tsx
<Select items={countries} value={selected()} onValueChange={setSelected} clearable />
```

### Clear and loading

`clearable` shows a clear button beside the trigger while a value is selected. Clicking it clears
the selection without toggling the popup. Backspace or Delete on the focused trigger also clears.
Clearing calls `onValueChange(null)`, then `onClear`, and returns focus to the trigger. Neither
fires while the select is disabled or read-only.

`loading` swaps the `trailing` icon for `loadingIcon` and hides the clear button. It does not
disable the select.

### Popup positioning and dismissal

The popup opens below the control and aligns to its start edge. `placement`, `align`, `gutter`,
`shift`, `flip`, `slide`, and `overflowPadding` adjust that position. `closeOnEscape` and
`closeOnOutsideClick` default to `true`; set either to `false` to block that dismissal and listen
for it with `onClosePrevented`. Combobox and MultiSelect accept the same props. `open`,
`defaultOpen`, and `onOpenChange` control the popup state.

```tsx
<Select items={items} placement="top" align="end" flip={false} />
```

### Keyboard interaction

| Key                 | Behavior                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| Enter / Space       | Open the popup, or commit the highlighted option while open             |
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options           |
| Home / End          | Highlight the first or last enabled option while open                   |
| PageUp / PageDown   | Move the highlight by one page of options while open                    |
| Printable key       | Typeahead: highlight the matching label while open, select it if closed |
| Backspace / Delete  | Clear the value when `clearable` and a value is selected                |
| Escape              | Close the popup without changing the value                              |
| Tab                 | Close the popup and move focus on                                       |

## Examples

### Choose a subscription plan

Put an `icon` and `description` on each item when the choice needs more than a label. No custom
item template is required.

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

const PLANS: SelectT.Item[] = [
  {
    label: 'Starter',
    value: 'starter',
    icon: 'i-lucide:sparkles',
    description: 'Up to 3 members · Free forever',
  },
  {
    label: 'Professional',
    value: 'pro',
    icon: 'i-lucide:zap',
    description: '$19/mo · Ideal for growing teams',
  },
  {
    label: 'Team',
    value: 'team',
    icon: 'i-lucide:rocket',
    description: '$49/mo · Advanced collaboration tools',
  },
  {
    label: 'Enterprise',
    value: 'enterprise',
    icon: 'i-lucide:shield-check',
    description: 'Custom pricing · Dedicated support & SLA',
  },
]

export function RichItems() {
  return (
    <div class="max-w-sm w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Subscription Plan</label>
      <Select items={PLANS} defaultValue="pro" placeholder="Choose your plan..." />
    </div>
  )
}
```

### Assign a member role

Pick one permission role from a short collection. Keep the selected value as the role id.

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

const ROLES: SelectT.Item[] = [
  {
    label: 'Owner',
    value: 'owner',
    icon: 'i-lucide:crown',
    description: 'Full access to all resources and billing',
  },
  {
    label: 'Admin',
    value: 'admin',
    icon: 'i-lucide:shield',
    description: 'Can manage team members and settings',
  },
  {
    label: 'Member',
    value: 'member',
    icon: 'i-lucide:user',
    description: 'Can create and edit team projects',
  },
  {
    label: 'Viewer',
    value: 'viewer',
    icon: 'i-lucide:eye',
    description: 'Read-only access to published workflows',
  },
]

export function UserAssignee() {
  return (
    <div class="max-w-sm w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Member Permission Role</label>
      <Select items={ROLES} defaultValue="member" placeholder="Assign a role..." />
    </div>
  )
}
```

### Choose a workspace timezone

Organize options with `type: 'group'`. Insert `{ type: 'separator' }` between groups or items.
Group labels and separators are excluded from selection and keyboard navigation.

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

const TIMEZONE_GROUPS: SelectT.Entry[] = [
  {
    label: 'Americas',
    type: 'group',
    items: [
      { label: 'America/New_York (UTC-5)', value: 'America/New_York' },
      { label: 'America/Chicago (UTC-6)', value: 'America/Chicago' },
      { label: 'America/Los_Angeles (UTC-8)', value: 'America/Los_Angeles' },
      { label: 'America/Sao_Paulo (UTC-3)', value: 'America/Sao_Paulo' },
    ],
  },
  {
    label: 'Europe',
    type: 'group',
    items: [
      { label: 'Europe/London (UTC+0)', value: 'Europe/London' },
      { label: 'Europe/Frankfurt (UTC+1)', value: 'Europe/Frankfurt' },
      { label: 'Europe/Paris (UTC+1)', value: 'Europe/Paris' },
    ],
  },
  {
    label: 'Asia Pacific',
    type: 'group',
    items: [
      { label: 'Asia/Tokyo (UTC+9)', value: 'Asia/Tokyo' },
      { label: 'Asia/Singapore (UTC+8)', value: 'Asia/Singapore' },
      { label: 'Australia/Sydney (UTC+11)', value: 'Australia/Sydney' },
    ],
  },
]

export function GroupedItems() {
  return (
    <div class="max-w-xs w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Workspace Timezone</label>
      <Select
        items={TIMEZONE_GROUPS}
        defaultValue="Europe/London"
        placeholder="Select timezone..."
      />
    </div>
  )
}
```

### Load more options on scroll

Use `onBottomReached` and `scrollThreshold` to append pages as the listbox approaches the
bottom. Drive `loading` from the in-flight request.

```tsx
import { Select } from 'moraine'
import type { SelectT } from 'moraine'
import { createSignal } from 'solid-js'

export function InfiniteScroll() {
  function makeOptions(count: number, offset = 0): SelectT.Item[] {
    return Array.from({ length: count }, (_, i) => ({
      label: `Option ${offset + i + 1}`,
      value: `opt-${offset + i + 1}`,
    }))
  }

  const [infiniteOptions, setInfiniteOptions] = createSignal<SelectT.Item[]>(makeOptions(20))

  const [loadingMore, setLoadingMore] = createSignal(false)

  return (
    <div class="w-80 space-y-2">
      <Select
        items={infiniteOptions()}
        classes={{
          listbox: 'max-h-100',
        }}
        onBottomReached={() => {
          if (loadingMore()) {
            return
          }
          setLoadingMore(true)
          setTimeout(() => {
            const next = infiniteOptions().length
            setInfiniteOptions((prev) => [...prev, ...makeOptions(10, next)])
            setLoadingMore(false)
          }, 1000)
        }}
        scrollThreshold={30}
        loading={loadingMore()}
        placeholder="Scroll to load more..."
      />
      <p class="text-xs text-muted-foreground">Total items: {infiniteOptions().length}</p>
    </div>
  )
}
```

### Bind an empty select to a form

For an empty `form.Field`-bound Select, initialize the field with `null` and accept `null` in the
schema. `required` is satisfied by any selected value, including one whose item is disabled. In that
case the select passes constraint validation but submits no value, as a native `<select>` does with
a disabled selected option.

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

const COUNTRIES = [
  { label: 'United States', value: 'us' },
  { label: 'Germany', value: 'de' },
  { label: 'Japan', value: 'jp' },
  { label: 'United Kingdom', value: 'uk' },
  { label: 'Canada', value: 'ca' },
] satisfies SelectT.Item[]

export function FormIntegration() {
  const [submittedCountry, setSubmittedCountry] = createSignal<string | null>(null)
  const form = createForm({
    schema: v.object({
      country: v.pipe(
        v.nullable(v.string()),
        v.check(
          (value): value is string => value !== null,
          'Please select your country of residence.',
        ),
      ),
    }),
    initialInput: { country: null },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedCountry(output.country)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="country"
          label="Country / Region"
          description="Used for tax calculation and regional billing."
          required
        >
          <Select items={COUNTRIES} placeholder="Select a country..." />
        </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 country: {submittedCountry() || 'none'}
          </p>
        </div>
      </div>
    </form.Form>
  )
}
```

### Own the selected country code

Pair `value` with `onValueChange`. Clearing writes `null`. Nearby copy can read the same signal.

```tsx
import { Button, Select } from 'moraine'
import type { SelectT } from 'moraine'
import { createSignal } from 'solid-js'

const COUNTRIES: SelectT.Item[] = [
  { label: 'United States', value: 'us' },
  { label: 'Germany', value: 'de' },
  { label: 'Japan', value: 'jp' },
  { label: 'United Kingdom', value: 'uk' },
  { label: 'Canada', value: 'ca' },
]

export function UsageValue() {
  const [selected, setSelected] = createSignal<string | undefined>('de')

  return (
    <div class="max-w-xs w-full space-y-3">
      <Select
        placeholder="Select a country..."
        leading="i-lucide:globe"
        items={COUNTRIES}
        value={selected()}
        onValueChange={setSelected}
        clearable
      />
      <div class="text-xs flex items-center justify-between">
        <span class="text-muted-foreground">
          Selected code:{' '}
          <span class="text-foreground font-medium font-mono">{selected() ?? 'undefined'}</span>
        </span>
        <Button
          variant="ghost"
          size="sm"
          disabled={selected() === undefined}
          onClick={() => setSelected(undefined)}
        >
          Reset
        </Button>
      </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 { Select } from 'moraine'
import type { SelectT } from 'moraine'

const MIXED_REGIONS: SelectT.Entry[] = [
  'us-east-1',
  { value: 'eu-west-1', label: 'eu-west-1', description: 'Ireland' },
  {
    type: 'group',
    label: 'Asia Pacific',
    items: ['ap-northeast-1', { value: 'ap-south-1', label: 'ap-south-1', disabled: true }],
  },
]

export function StringItems() {
  return (
    <div class="flex flex-col gap-3 max-w-xs w-full">
      <Select
        aria-label="Deploy region"
        items={['us-east-1', 'eu-west-1', 'ap-northeast-1']}
        defaultValue="us-east-1"
        clearable
      />
      <Select
        aria-label="Deploy region with groups"
        items={MIXED_REGIONS}
        placeholder="Choose a region..."
        clearable
      />
    </div>
  )
}
```

### Custom option and empty state renderers

Use `itemRender` to customize row content with badges or status details. Use `emptyRender` to
render a message or recovery action when `items` is empty.

```tsx
import { Button, Select } from 'moraine'
import type { SelectT } from 'moraine'
import { createSignal } from 'solid-js'

interface FrameworkItem extends SelectT.Item {
  badge: string
}

const FRAMEWORKS: FrameworkItem[] = [
  { label: 'SolidJS', value: 'solid', badge: 'Reactive' },
  { label: 'Vue.js', value: 'vue', badge: 'Template' },
  { label: 'React', value: 'react', badge: 'Virtual DOM' },
]

export function CustomRender() {
  const [items, setItems] = createSignal<FrameworkItem[]>(FRAMEWORKS)

  return (
    <div class="max-w-xs w-full space-y-3">
      <Select<FrameworkItem>
        placeholder="Choose framework..."
        items={items()}
        defaultValue="solid"
        itemRender={(props) => (
          <div class="flex w-full items-center justify-between">
            <span>{props.item.label}</span>
            <span class="text-xs text-muted-foreground font-mono px-1.5 py-0.5 rounded bg-muted">
              {props.item.badge}
            </span>
          </div>
        )}
        emptyRender={(props) => (
          <div class="p-3 text-center space-y-2">
            <p class="text-sm text-muted-foreground">No options available.</p>
            <Button
              size="xs"
              variant="outline"
              onClick={() => {
                setItems(FRAMEWORKS)
                props.close()
              }}
            >
              Restore options
            </Button>
          </div>
        )}
      />
      <div class="flex justify-end">
        <Button
          size="xs"
          variant="ghost"
          onClick={() => setItems(items().length > 0 ? [] : FRAMEWORKS)}
        >
          Toggle empty list
        </Button>
      </div>
    </div>
  )
}
```

## API Reference

### Attributes

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | 'start' | Alignment of the popup along the anchor's edge: `'start'`, `'center'`, or `'end'`. |
| clearable | boolean \| undefined | — | Shows a clear button while a value is selected (hidden during `loading`). Backspace or<br>Delete on the focused trigger clears too. Clearing calls `onValueChange(null)`, then<br>`onClear`, and returns focus to the trigger. |
| clearIcon | IconT.Name \| undefined | 'icon-close' | Icon used by the clear affordance. |
| 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. |
| 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 `items` is empty; nothing is rendered when omitted. A<br>function receives `{ selectedValue, close }`. |
| 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. |
| 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. |
| leading | IconT.Name \| undefined | — | Icon rendered before the selected value or placeholder. |
| 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 `trailing` icon with `loadingIcon` and hides the clear button. It does not<br>disable the select. |
| 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 after a clear action (see `clearable`), following `onValueChange(null)`. Not called<br>while the select is disabled or read-only. |
| 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. |
| onValueChange | ((value: NoInfer<NormalizedItem<TItem>['value']> \| null) => void) \| undefined | — | Called with the new item `value` when the user changes the selection, or with `null` when<br>it is cleared. Not called for prop updates, when the same item is chosen again, or while<br>the select is 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. |
| overflowPadding | number \| undefined | 4 | Viewport collision padding in pixels. |
| placeholder | string \| undefined | "" | Text shown in the trigger while no value is selected. Takes precedence over the<br>`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. |
| 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 at the end of the trigger; replaced by `loadingIcon` while `loading`. |
| translations | Translations \| undefined | — | Overrides the built-in messages (`clear`, `placeholder`) for this instance, merged over<br>the messages from the provider and locale. |
| value | NormalizedItem<TItem>['value'] \| null \| undefined | — | Controlled selected value. `undefined` keeps the selection uncontrolled; `null` keeps it<br>controlled and empty. A value that matches no item is displayed as `String(value)`. 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. |
| 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 { Select } from 'moraine'

<Select
  items={[]}
  emptyRender={(state) => <button onClick={() => state.close()}>No options. Close</button>}
/>
```

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

<Select
  items={[
    { label: 'Apple', value: 'apple' },
    { type: 'separator' },
    {
      type: 'group',
      label: 'Citrus',
      items: [
        { label: 'Lemon', value: 'lemon' },
        { label: 'Lime', value: 'lime', disabled: true },
      ],
    },
    { label: 'Pear', value: 'pear' },
  ]}
/>
```

**`translations` example**

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

<Select
  items={['Small', 'Large']}
  clearable
  translations={{ clear: 'Remove size', placeholder: 'Pick a size' }}
/>
```
