@loke/ui/skills/select/references/select-components.md

# Select Sub-component Reference

All exports from `@loke/ui/select`.

---

## `Select`

Root provider. No DOM element.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `value` | `string \| undefined` | — | Controlled selected value. `undefined` = no selection. Never `""`. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onValueChange` | `(value: string) => void` | — | Fires when selection changes. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Uncontrolled initial open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Fires on open/close. |
| `name` | `string` | — | Name for the hidden native `<select>`. |
| `form` | `string` | — | Form `id` for detached form association. |
| `disabled` | `boolean` | `false` | Disables the entire select. |
| `required` | `boolean` | `false` | Marks the field required. |
| `dir` | `"ltr" \| "rtl"` | — | Text direction; falls back to `DirectionProvider`. |
| `autoComplete` | `string` | — | Passed to the hidden native `<select>`. |

---

## `SelectTrigger`

`role="combobox"` button that opens the select. Extends `Primitive.button`.

| Prop | Type | Notes |
|---|---|---|
| `disabled` | `boolean` | Overrides root `disabled`. |
| `data-state` | `"open" \| "closed"` | Set automatically. |
| `data-disabled` | `""` | Present when disabled. |
| `data-placeholder` | `""` | Present when no value is selected. |

---

## `SelectValue`

Renders the selected item's text (portaled from `SelectItemText`). Extends `Primitive.span`.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `placeholder` | `ReactNode` | — | Shown when `value` is `undefined`. |
| `asChild` | `boolean` | `false` | Merge props into child element. |

---

## `SelectIcon`

Decorative icon slot inside the trigger. Extends `Primitive.span`. Defaults to a `▼` character if no children provided.

---

## `SelectPortal`

Portals children into `document.body` (or a custom `container`). Wraps `Portal`.

| Prop | Type | Notes |
|---|---|---|
| `container` | `HTMLElement \| null` | Portal target. Defaults to `document.body`. |

---

## `SelectContent`

The dropdown panel. Extends `Primitive.div`. Must contain `SelectViewport`.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `position` | `"item-aligned" \| "popper"` | `"item-aligned"` | `item-aligned` centers selected item over trigger. `popper` anchors below trigger. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Popper mode only. |
| `sideOffset` | `number` | `0` | Popper mode only. Distance from trigger in px. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Popper mode only. |
| `alignOffset` | `number` | `0` | Popper mode only. |
| `avoidCollisions` | `boolean` | `true` | Popper mode only. |
| `collisionBoundary` | `Element \| Element[] \| null` | — | Popper mode only. |
| `collisionPadding` | `number \| Partial<Record<Side, number>>` | `10` | Popper mode only. |
| `sticky` | `"partial" \| "always"` | `"partial"` | Popper mode only. |
| `hideWhenDetached` | `boolean` | `false` | Popper mode only. |
| `onCloseAutoFocus` | `(e: Event) => void` | — | Focus management on close. |
| `onEscapeKeyDown` | `(e: KeyboardEvent) => void` | — | Override Escape key behavior. |
| `onPointerDownOutside` | `(e: PointerEvent) => void` | — | Override outside-click dismiss. |

---

## `SelectViewport`

Scroll container for items. Must be a direct child of `SelectContent`. Injects scrollbar-hiding styles.

No custom props beyond standard div props.

---

## `SelectGroup`

Groups related items. Renders as `role="group"`. Use with `SelectLabel` for an accessible group name.

---

## `SelectLabel`

Accessible label for a `SelectGroup`. Not selectable. Renders as `Primitive.div`.

---

## `SelectItem`

A selectable option. Extends `Primitive.div`.

| Prop | Type | Notes |
|---|---|---|
| `value` | `string` | **Required.** Must not be `""` — throws. |
| `disabled` | `boolean` | Prevents selection and grays out the item. |
| `textValue` | `string` | Override for typeahead matching. Use when `SelectItemText` content is not plain text. |
| `data-state` | `"checked" \| "unchecked"` | Set automatically. |
| `data-highlighted` | `""` | Present when keyboard-focused. |
| `data-disabled` | `""` | Present when disabled. |

---

## `SelectItemText`

**Required inside every `SelectItem`.** Portals its text into `SelectValue` when the item is selected. Also provides the typeahead string.

| Prop | Type | Notes |
|---|---|---|
| `asChild` | `boolean` | Merge into child element (e.g. `<span>`). |

---

## `SelectItemIndicator`

Renders only when the item is selected (`data-state="checked"`). Use for checkmark icons.

| Prop | Type | Notes |
|---|---|---|
| `forceMount` | `true` | Mount regardless of state (for exit animations). |

---

## `SelectScrollUpButton`

Appears at the top of `SelectContent` when the viewport is scrollable upward. Scrolls on pointer-over.

No custom props beyond standard div props.

---

## `SelectScrollDownButton`

Appears at the bottom of `SelectContent` when more items are below the viewport. Scrolls on pointer-over.

No custom props beyond standard div props.

---

## `SelectSeparator`

Visual divider between groups or items. `role` is presentational.

---

## `SelectArrow`

Decorative arrow pointing from content to trigger. Only meaningful with `position="popper"`.

| Prop | Type | Default | Notes |
|---|---|---|---|
| `width` | `number` | `10` | Arrow width in px. |
| `height` | `number` | `5` | Arrow height in px. |
| `asChild` | `boolean` | `false` | Render custom arrow shape. |