Skip to main content

Starwind UI v3.0 is now available! Migration guide

Select Primitive

Select is a Starwind Runtime primitive in the floating-value-control contract family. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

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>

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>

Floating Behavior

FactValue
Anchor parttrigger
Positioner partpositioner
Popup partpopup
Portal partportal
Option propsside, 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 Toggle
open boolean -
Description
Controls whether Select is open.
Kind
control
Targets
-
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
defaultOpen boolean -
Description
Sets whether Select starts open.
Kind
control
Targets
-
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
value string | null -
Description
Controls the current Select value.
Kind
control
Targets
-
Full type
string | null
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
defaultValue string | null -
Description
Sets the initial Select value for uncontrolled usage.
Kind
control
Targets
-
Full type
string | null
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
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: boolean, details: SelectOpenChangeDetails) => void -
Description
Runs when Select opens or closes.
Kind
callback
Targets
-
Full type
(open: boolean, details: SelectOpenChangeDetails) => void
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
onValueChange (value: string | null, details: SelectValueChangeDetails) => void -
Description
Runs when the Select value changes.
Kind
callback
Targets
-
Full type
(value: string | null, details: SelectValueChangeDetails) => void
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

Events

Event Callback Value Toggle
openChange onOpenChange open: boolean
Description
Fires when Select opens or closes.
DOM event
starwind:open-change
Details type
SelectOpenChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.
valueChange onValueChange value: string | null
Description
Fires when the value changes for Select.
DOM event
starwind:value-change
Details type
SelectValueChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.

State

State Type Props Toggle
open boolean open / defaultOpen
Description
Tracks whether Select is open.
Initial attribute
data-default-open
Runtime getter
getOpen
Runtime setter
setOpen
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
value string | null value / defaultValue
Description
Tracks the current Select value.
Initial attribute
data-default-value
Runtime getter
getValue
Runtime setter
setValue
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

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

OptionLifecycle
autoCompleteconstructor-only
defaultOpenconstructor-only
defaultValueconstructor-only
disabledconstructor-only
formconstructor-only
highlightItemOnHoverconstructor-only
modalconstructor-only
opensetter-backed
readOnlyconstructor-only
valuesetter-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

FactValue
Form propsautoComplete, form, name, required, value
Hidden inputinput (hidden)
Field integrationYes
Component Relationship
Select Direct primitive

Changelog

View version history v1.0.0 6 releases

v1.0.0

  • Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.4

  • Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
  • Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
  • Initialized React Select from silent programmatic value commands so composed format controls show their configured value before interaction.
  • Preserved selected-value styling when React Select triggers are composed inside Color Picker format controls.

v0.1.3

  • Preserved intentionally empty item labels and their lazy hidden form values in React.

v0.1.2

  • Deferred React controller initialization and improved closed-mount behavior while preserving state and form synchronization.

v0.1.1

  • Enabled modal background-scroll locking by default while the listbox is open.

v0.1.0

  • Introduced selection state, keyboard navigation, floating listbox placement, events, and form participation.