# Select Primitive

Select is a Starwind Runtime primitive in the floating-value-control contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render Select anatomy with the Runtime wiring included.
```astro
---
import { Select } from "@starwind-ui/astro/select";
---

<Select.Root>
  <Select.Label>Choose a framework</Select.Label>
  <Select.Trigger>
    <Select.Value>Astro</Select.Value>
    <Select.Icon>v</Select.Icon>
  </Select.Trigger>
  <Select.Positioner>
    <Select.Popup />
  </Select.Positioner>
</Select.Root>
```

### React
Use the React primitive adapter when Select state participates in React rendering.
```tsx
import { Select } from "@starwind-ui/react/select";

export function Example() {
  return (
    <Select.Root>
      <Select.Label>Choose a framework</Select.Label>
      <Select.Trigger>
        <Select.Value>Astro</Select.Value>
        <Select.Icon>v</Select.Icon>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup />
      </Select.Positioner>
    </Select.Root>
  );
}
```

### HTML
Render the Select data-sw-* contract yourself, then initialize createSelect.
```html
<div data-sw-select>
  <div data-sw-select-label>Choose a framework</div>
  <button data-sw-select-trigger role="combobox" aria-haspopup="listbox">
    <span data-sw-select-value>Astro</span>
    <span data-sw-select-icon aria-hidden="true">v</span>
  </button>
  <div data-sw-select-positioner>
    <div data-sw-select-popup role="listbox" hidden tabindex="-1">
      <div data-sw-select-list>
        <div data-sw-select-item role="option" data-value="astro">
          <span data-sw-select-item-text>Astro</span>
          <span data-sw-select-item-indicator aria-hidden="true" hidden></span>
        </div>
      </div>
    </div>
  </div>
</div>

<script type="module">
  import { createSelect } from "@starwind-ui/runtime/select";

  const root = document.querySelector("[data-sw-select]");
  if (root) {
    createSelect(root);
  }
</script>
```
## Positioning
Select positions its popup from the trigger. Keep the `Positioner` and `Popup` parts near the trigger in source order so the relationship stays readable, then let the Runtime handle placement, collision, and open-state updates after hydration.

## Examples
### Positioned Select
Render Select with a positioned popup across Astro, React, and HTML surfaces.
#### Astro
```astro
---
import { Select } from "@starwind-ui/astro/select";
---

<Select.Root defaultValue="astro">
  <Select.Label>Framework</Select.Label>
  <Select.Trigger>
    <Select.Value>Astro</Select.Value>
    <Select.Icon>v</Select.Icon>
  </Select.Trigger>
  <Select.Positioner>
    <Select.Popup>
      <Select.List>
        <Select.Item value="astro">
          <Select.ItemText>Astro</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
        <Select.Item value="react">
          <Select.ItemText>React</Select.ItemText>
          <Select.ItemIndicator />
        </Select.Item>
      </Select.List>
    </Select.Popup>
  </Select.Positioner>
</Select.Root>

```

#### React
```tsx
import { Select } from "@starwind-ui/react/select";

export function Example() {
  return (
    <Select.Root defaultValue="astro">
      <Select.Label>Framework</Select.Label>
      <Select.Trigger>
        <Select.Value>Astro</Select.Value>
        <Select.Icon>v</Select.Icon>
      </Select.Trigger>
      <Select.Positioner>
        <Select.Popup>
          <Select.List>
            <Select.Item value="astro">
              <Select.ItemText>Astro</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
            <Select.Item value="react">
              <Select.ItemText>React</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          </Select.List>
        </Select.Popup>
      </Select.Positioner>
    </Select.Root>
  );
}

```

#### HTML
```html
<div data-sw-select data-default-value="astro">
  <span data-sw-select-label>Framework</span>
  <button data-sw-select-trigger type="button">
    <span data-sw-select-value>Astro</span>
    <span data-sw-select-icon>v</span>
  </button>
  <div data-sw-select-positioner>
    <div data-sw-select-popup>
      <div data-sw-select-list>
        <div data-sw-select-item data-value="astro">
          <span data-sw-select-item-text>Astro</span>
          <span data-sw-select-item-indicator></span>
        </div>
        <div data-sw-select-item data-value="react">
          <span data-sw-select-item-text>React</span>
          <span data-sw-select-item-indicator></span>
        </div>
      </div>
    </div>
  </div>
</div>

<script type="module">
  import { createSelect } from "@starwind-ui/runtime/select";

  const root = document.querySelector("[data-sw-select]");
  if (root) {
    createSelect(root);
  }
</script>

```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | trigger |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, alignOffset, avoidCollisions, alignItemWithTrigger |
## API Reference
### Root
The main element that owns the Select Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Select is open. |
| defaultOpen | `boolean` | - | control | Sets whether Select starts open. |
| value | `string \| null` | - | control | Controls the current Select value. |
| defaultValue | `string \| null` | - | control | Sets the initial Select value for uncontrolled usage. |
| autoComplete | `string` | - | option | Sets the native autocomplete behavior. |
| disabled | `boolean` | - | option | Disables the Root part. |
| form | `string` | - | option | Associates the control with a form element. |
| highlightItemOnHover | `boolean` | true | option | Highlights Select items when the pointer moves over them. |
| modal | `boolean` | true | option | Makes Select behave as a modal overlay. |
| name | `string` | - | option | Sets the submitted form field name. |
| readOnly | `boolean` | false | option | Marks the control as read-only. |
| required | `boolean` | - | option | Marks the form control as required. |
| onOpenChange | `(open: unknown, details: SelectOpenChangeDetails) => void` | - | callback | Runs when Select opens or closes. |
| onValueChange | `(value: unknown, details: SelectValueChangeDetails) => void` | - | callback | Runs when the Select value changes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-autocomplete` | prop | - | Reflects the autocomplete prop on the Root part. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-highlight-item-on-hover` | prop | - | Reflects the highlight item on hover prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Select is open. | React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Select value. | React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| openChange | onOpenChange | starwind:open-change | open | SelectOpenChangeDetails | - | - | Fires when Select opens or closes. |
| valueChange | onValueChange | starwind:value-change | value | SelectValueChangeDetails | - | - | Fires when the value changes for Select. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setOpen` | state: open | - | Yes | Opens or closes Select from Runtime code. |
| `setValue` | state: value | - | Yes | Updates the current Select value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Label
Text label associated with Select.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |

### Trigger
The control that opens, closes, or targets the Select content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-select-trigger` |
| Role | `combobox` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `aria-haspopup`, `aria-expanded`, `aria-readonly`, `data-state` | Keyboard and assistive technology affordances must be present before hydration. |

### Value
Displays the current Select value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |

### Icon
Decorative icon rendered by Select.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-icon` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-icon` | runtime | - | Marks the Icon part so Starwind Runtime can find it. |

### Input
The native input synchronized by Select.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-select-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |

### Portal
Moves Select overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |

### Positioner
Positions the Select content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Select content. |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Select content aligns to its trigger. |
| sideOffset | `number` | 4 | option | Sets the distance between Select content and its trigger. |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Select content. |
| avoidCollisions | `boolean` | true | option | Allows Select content to shift or flip to stay visible. |
| alignItemWithTrigger | `boolean` | true | option | Configures the align item with trigger option for the Positioner part. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Positioner part. |
| `data-align-item-with-trigger` | prop | - | Reflects the align item with trigger prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |

### Popup
The floating content container for Select.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-popup` |
| Role | `listbox` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Select content. |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Select content aligns to its trigger. |
| sideOffset | `number` | 4 | option | Sets the distance between Select content and its trigger. |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Select content. |
| avoidCollisions | `boolean` | true | option | Allows Select content to shift or flip to stay visible. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `hidden`, `data-state`, `data-side`, `data-align` | Floating content starts closed and is positioned by the runtime once opened. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### List
The list of selectable Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |

### Group
Groups related Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |

### Group Label
Labels a group of Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-group-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-group-label` | runtime | - | Marks the Group Label part so Starwind Runtime can find it. |

### Item
An interactive item inside the Select collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-item` |
| Role | `option` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Item Text
Text content for a Select item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-item-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item-text` | runtime | - | Marks the Item Text part so Starwind Runtime can find it. |

### Item Indicator
Shows the selected state for a Select item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-select-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-item-indicator` | runtime | - | Marks the Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Item Indicator part. |
| `data-hidden` | state | - | Reflects the hidden state on the Item Indicator part. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Separator
Separates groups of Select items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |

### Scroll Up Arrow
Scrolls Select options upward.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-scroll-up-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-scroll-up-arrow` | runtime | - | Marks the Scroll Up Arrow part so Starwind Runtime can find it. |

### Scroll Down Arrow
Scrolls Select options downward.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-select-scroll-down-arrow` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-select-scroll-down-arrow` | runtime | - | Marks the Scroll Down Arrow part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSelect`](/docs/runtime/#create-select) |
| Import | `@starwind-ui/runtime/select` |
| Root part | root |
| Option props | autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value |
| Option lifecycles | autoComplete: constructor-only, defaultOpen: constructor-only, defaultValue: constructor-only, disabled: constructor-only, form: constructor-only, highlightItemOnHover: constructor-only, modal: constructor-only, open: setter-backed, readOnly: constructor-only, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | input (hidden) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Select](/docs/components/select/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/select` | `createSelect` |
| Astro Primitive | `@starwind-ui/astro/select` | `Select`, `SelectRoot`, `SelectLabel`, `SelectTrigger`, `SelectValue`, `SelectIcon`, `SelectPortal`, `SelectPositioner`, `SelectPopup`, `SelectGroup`, `SelectGroupLabel`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectSeparator`, `SelectScrollUpArrow`, `SelectScrollDownArrow` |
| React Primitive | `@starwind-ui/react/select` | `Select`, `SelectRoot`, `SelectLabel`, `SelectTrigger`, `SelectValue`, `SelectIcon`, `SelectPortal`, `SelectPositioner`, `SelectPopup`, `SelectGroup`, `SelectGroupLabel`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectSeparator`, `SelectScrollUpArrow`, `SelectScrollDownArrow` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Select` |
| runtime-factory | `createSelect` |
| part | `Select.Root` |
| part | `Select.Label` |
| part | `Select.Trigger` |
| part | `Select.Value` |
| part | `Select.Icon` |
| part | `Select.Portal` |
| part | `Select.Positioner` |
| part | `Select.Popup` |
| part | `Select.Group` |
| part | `Select.GroupLabel` |
| part | `Select.Item` |
| part | `Select.ItemText` |
| part | `Select.ItemIndicator` |
| part | `Select.Separator` |
| part | `Select.ScrollUpArrow` |
| part | `Select.ScrollDownArrow` |