Select Primitive

Select is a Starwind Runtime primitive in the floating-value-control contract family.

Anatomy

Use the Astro primitive adapter to render Select anatomy with the Runtime wiring included.

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

Use the React primitive adapter when Select state participates in React rendering.

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>
  );
}

Render the Select data-sw-* contract yourself, then initialize createSelect.

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

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

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>
  );
}

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

Default element: div
Discovery hook: data-sw-select
Role: -

Props

Prop Type Default

open boolean -

Description: Controls whether Select is open.
Kind: control
Targets: -
Full type: boolean

defaultOpen boolean -

Description: Sets whether Select starts open.
Kind: control
Targets: -
Full type: boolean

value string | null -

Description: Controls the current Select value.
Kind: control
Targets: -
Full type: string | null

defaultValue string | null -

Description: Sets the initial Select value for uncontrolled usage.
Kind: control
Targets: -
Full type: string | null

autoComplete string -

Description: Sets the native autocomplete behavior.
Kind: option
Targets: -
Full type: string

disabled boolean -

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

form string -

Description: Associates the control with a form element.
Kind: option
Targets: -
Full type: string

highlightItemOnHover boolean true

Description: Highlights Select items when the pointer moves over them.
Kind: option
Targets: -
Full type: boolean

modal boolean true

Description: Makes Select behave as a modal overlay.
Kind: option
Targets: root
Full type: boolean

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

readOnly boolean false

Description: Marks the control as read-only.
Kind: option
Targets: -
Full type: boolean

required boolean -

Description: Marks the form control as required.
Kind: option
Targets: -
Full type: boolean

onOpenChange (open: unknown, details: SelectOpenChangeDetails) => void -

Description: Runs when Select opens or closes.
Kind: callback
Targets: -
Full type: (open: unknown, details: SelectOpenChangeDetails) => void

onValueChange (value: unknown, details: SelectValueChangeDetails) => void -

Description: Runs when the Select value changes.
Kind: callback
Targets: -
Full type: (value: unknown, details: SelectValueChangeDetails) => void

Events

Event Callback Value

openChange onOpenChange open

Description: Fires when Select opens or closes.
DOM event: starwind:open-change
Details type: SelectOpenChangeDetails
Timing: -
Cancelable: No

valueChange onValueChange value

Description: Fires when the value changes for Select.
DOM event: starwind:value-change
Details type: SelectValueChangeDetails
Timing: -
Cancelable: No

State

State Type Props

open boolean open / defaultOpen

Description: Tracks whether Select is open.
Initial attribute: data-default-open
Runtime getter: getOpen
Runtime setter: setOpen
State control support: 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

Description: Tracks the current Select value.
Initial attribute: data-default-value
Runtime getter: getValue
Runtime setter: setValue
State control support: 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.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-autocomplete - Reflects the autocomplete prop on the Root part.

data-default-open - Reflects the default open prop on the Root part.

data-default-value - Reflects the default value prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-form - Reflects the form prop on the Root part.

data-highlight-item-on-hover - Reflects the highlight item on hover prop on the Root part.

data-modal - Reflects the modal prop on the Root part.

data-name - Reflects the name prop on the Root part.

data-readonly - Reflects the readonly prop on the Root part.

data-required - Reflects the required prop on the Root part.

Label

Text label associated with Select.

Default element: div
Discovery hook: data-sw-select-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-label - Marks the Label part so Starwind Runtime can find it.

Trigger

The control that opens, closes, or targets the Select content.

Default element: button
Discovery hook: data-sw-select-trigger
Role: combobox

Props

Prop Type Default

asChild boolean -

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Metadata

Attribute Value Description

data-readonly - Reflects the readonly prop on the Trigger part.

Value

Displays the current Select value.

Default element: span
Discovery hook: data-sw-select-value
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-value - Marks the Value part so Starwind Runtime can find it.

Icon

Decorative icon rendered by Select.

Default element: span
Discovery hook: data-sw-select-icon
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-icon - Marks the Icon part so Starwind Runtime can find it.

Input

The native input synchronized by Select.

Default element: input
Discovery hook: data-sw-select-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-input - Marks the Input part so Starwind Runtime can find it.

Portal

Moves Select overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-select-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

Positions the Select content relative to its trigger.

Default element: div
Discovery hook: data-sw-select-positioner
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Select content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets how Select content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Select content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

alignOffset number 0

Description: Adjusts the cross-axis alignment offset for Select content.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Select content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

alignItemWithTrigger boolean true

Description: Configures the align item with trigger option for the Positioner part.
Kind: option
Targets: positioner
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-positioner - Marks the Positioner part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Positioner part.

data-align - Reflects the align prop on the Positioner part.

data-side-offset - Reflects the side offset prop on the Positioner part.

data-align-offset - Reflects the align offset prop on the Positioner part.

data-align-item-with-trigger - Reflects the align item with trigger prop on the Positioner part.

data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

The floating content container for Select.

Default element: div
Discovery hook: data-sw-select-popup
Role: listbox

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Select content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets how Select content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Select content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

alignOffset number 0

Description: Adjusts the cross-axis alignment offset for Select content.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Select content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

data-align - Reflects the align prop on the Popup part.

data-side-offset - Reflects the side offset prop on the Popup part.

data-align-offset - Reflects the align offset prop on the Popup part.

data-avoid-collisions - Reflects the avoid collisions prop on the Popup part.

List

The list of selectable Select items.

Default element: div
Discovery hook: data-sw-select-list
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-list - Marks the List part so Starwind Runtime can find it.

Group

Groups related Select items.

Default element: div
Discovery hook: data-sw-select-group
Role: group

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-group - Marks the Group part so Starwind Runtime can find it.

Group Label

Labels a group of Select items.

Default element: div
Discovery hook: data-sw-select-group-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-group-label - Marks the Group Label part so Starwind Runtime can find it.

Item

An interactive item inside the Select collection.

Default element: div
Discovery hook: data-sw-select-item
Role: option

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-item - Marks the Item part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Item part.

data-disabled - Reflects the disabled prop on the Item part.

Item Text

Text content for a Select item.

Default element: span
Discovery hook: data-sw-select-item-text
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-item-text - Marks the Item Text part so Starwind Runtime can find it.

Item Indicator

Shows the selected state for a Select item.

Default element: span
Discovery hook: data-sw-select-item-indicator
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-item-indicator - Marks the Item Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Item Indicator part.

data-hidden - Reflects the hidden state on the Item Indicator part.

Separator

Separates groups of Select items.

Default element: div
Discovery hook: data-sw-select-separator
Role: separator

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-separator - Marks the Separator part so Starwind Runtime can find it.

Scroll Up Arrow

Scrolls Select options upward.

Default element: div
Discovery hook: data-sw-select-scroll-up-arrow
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-scroll-up-arrow - Marks the Scroll Up Arrow part so Starwind Runtime can find it.

Scroll Down Arrow

Scrolls Select options downward.

Default element: div
Discovery hook: data-sw-select-scroll-down-arrow
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-select-scroll-down-arrow - Marks the Scroll Down Arrow part so Starwind Runtime can find it.

Runtime API

Factory: createSelect
Import: @starwind-ui/runtime/select
Root hook: root data-sw-select
Option props: autoComplete, defaultOpen, defaultValue, disabled, form, highlightItemOnHover, modal, open, readOnly, value

Option Lifecycles

Option	Lifecycle
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

Runtime Setters

Method Target Description

setOpen state: open Opens or closes Select from Runtime code.

setValue state: value Updates the current Select value from Runtime code.

Form Participation

Fact	Value
Form props	autoComplete, form, name, required, value
Hidden input	input (hidden)
Field integration	Yes

Component Relationship

Select Direct primitive

Layer Metadata

Select Primitive uses createSelect. Styled components: Select.

primitive Select Primitive Select Primitive uses createSelect. Styled components: Select. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters select Select Floating Value Control Value controls with popup selection surfaces and floating placement. /docs/primitives/select/ createSelect @starwind-ui/runtime/select /docs/runtime/#create-select root autoComplete defaultOpen defaultValue disabled form highlightItemOnHover modal open readOnly value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Select data-sw-* contract yourself, then initialize createSelect. html Use the Astro primitive adapter to render Select anatomy with the Runtime wiring included. Use the React primitive adapter when Select state participates in React rendering. tsx div data-sw-select boolean Controls whether Select is open. Sets whether Select starts open. string | null Controls the current Select value. Sets the initial Select value for uncontrolled usage. string Sets the native autocomplete behavior. Disables the Root part. Associates the control with a form element. Highlights Select items when the pointer moves over them. Makes Select behave as a modal overlay. name Sets the submitted form field name. Marks the control as read-only. required Marks the form control as required. onOpenChange (open: unknown, details: SelectOpenChangeDetails) => void SelectOpenChangeDetails Runs when Select opens or closes. onValueChange (value: unknown, details: SelectValueChangeDetails) => void SelectValueChangeDetails Runs when the Select value changes. 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 Reflects the default open prop on the Root part. data-default-value Reflects the default value prop on the Root part. data-disabled Reflects the disabled prop on the Root part. data-form Reflects the form prop on the Root part. data-highlight-item-on-hover Reflects the highlight item on hover prop on the Root part. data-modal Reflects the modal prop on the Root part. data-name Reflects the name prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-required Reflects the required prop on the Root part. getOpen setOpen getValue setValue openChange starwind:open-change valueChange starwind:value-change label data-sw-select-label Marks the Label part so Starwind Runtime can find it. trigger button data-sw-select-trigger combobox asChild Merges behavior onto your child element instead of rendering the default Trigger element. Marks the Trigger part so Starwind Runtime can find it. Reflects the current state on the Trigger part. Reflects the readonly prop on the Trigger part. span data-sw-select-value Marks the Value part so Starwind Runtime can find it. icon data-sw-select-icon Marks the Icon part so Starwind Runtime can find it. input data-sw-select-input Marks the Input part so Starwind Runtime can find it. portal data-sw-select-portal Marks the Portal part so Starwind Runtime can find it. positioner data-sw-select-positioner side "top" | "right" | "bottom" | "left" Sets the preferred side for Select content. align "start" | "center" | "end" Sets how Select content aligns to its trigger. sideOffset number Sets the distance between Select content and its trigger. alignOffset Adjusts the cross-axis alignment offset for Select content. avoidCollisions Allows Select content to shift or flip to stay visible. alignItemWithTrigger Configures the align item with trigger option for the Positioner part. Marks the Positioner part so Starwind Runtime can find it. data-side Reflects the side prop on the Positioner part. data-align Reflects the align prop on the Positioner part. data-side-offset Reflects the side offset prop on the Positioner part. data-align-offset Reflects the align offset prop on the Positioner part. data-align-item-with-trigger Reflects the align item with trigger prop on the Positioner part. data-avoid-collisions Reflects the avoid collisions prop on the Positioner part. popup data-sw-select-popup listbox Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. Reflects the side prop on the Popup part. Reflects the align prop on the Popup part. Reflects the side offset prop on the Popup part. Reflects the align offset prop on the Popup part. Reflects the avoid collisions prop on the Popup part. list data-sw-select-list Marks the List part so Starwind Runtime can find it. group data-sw-select-group Marks the Group part so Starwind Runtime can find it. groupLabel data-sw-select-group-label Marks the Group Label part so Starwind Runtime can find it. item data-sw-select-item option Marks the Item part so Starwind Runtime can find it. data-value Reflects the value prop on the Item part. Reflects the disabled prop on the Item part. itemText data-sw-select-item-text Marks the Item Text part so Starwind Runtime can find it. itemIndicator data-sw-select-item-indicator Marks the Item Indicator part so Starwind Runtime can find it. Reflects the current state on the Item Indicator part. data-hidden Reflects the hidden state on the Item Indicator part. separator data-sw-select-separator Marks the Separator part so Starwind Runtime can find it. scrollUpArrow data-sw-select-scroll-up-arrow Marks the Scroll Up Arrow part so Starwind Runtime can find it. scrollDownArrow data-sw-select-scroll-down-arrow Marks the Scroll Down Arrow part so Starwind Runtime can find it. Root Label Trigger aria-haspopup aria-expanded aria-readonly Value Icon aria-hidden Input type autocomplete Portal Positioner Popup hidden tabIndex List Group Group Label Item aria-selected aria-disabled Item Text Item Indicator Separator aria-orientation Scroll Up Arrow Scroll Down Arrow @starwind-ui/astro @starwind-ui/astro/select Generate static listbox markup plus self-init; do not promise controlled props. @starwind-ui/react @starwind-ui/react/select Bridge open/value as separate controlled models and keep callbacks in latest refs. /docs/components/select/ Direct primitive direct-primitive Styled component Select