On this page

Select

    ---
    import {
      Select,
      SelectContent,
      SelectItem,
      SelectTrigger,
    } from "@/components/starwind/select";
    ---

    <Select name="framework" defaultValue="astro" required>
      <SelectTrigger placeholder="Choose a framework" />
      <SelectContent>
        <SelectItem value="astro">Astro</SelectItem>
        <SelectItem value="react">React</SelectItem>
        <SelectItem value="vue">Vue</SelectItem>
      </SelectContent>
    </Select>

import {
      Select,
      SelectContent,
      SelectItem,
      SelectTrigger,
    } from "@/components/starwind/select";

export function Example() {
  return (
    <>
      <Select name="framework" defaultValue="astro" required>
            <SelectTrigger placeholder="Choose a framework" />
            <SelectContent>
              <SelectItem value="astro">Astro</SelectItem>
              <SelectItem value="react">React</SelectItem>
              <SelectItem value="vue">Vue</SelectItem>
            </SelectContent>
          </Select>
    </>
  );
}

Runtime example adjustment

Form props such as name, required, readOnly, and defaultValue belong on Select. The trigger now focuses on presentation and uses its placeholder prop for the installed value part.

Installation

pnpx starwind@latest add select

npx starwind@latest add select

yarn dlx starwind@latest add select

Framework Availability

Astro Available React Available

Select is available for Astro and React.

Usage

Form participation

Select serializes its value through a hidden input and follows native form reset behavior.

<form>
  <Select name="role" required>
    <SelectTrigger placeholder="Choose a role" />
    <SelectContent>
      <SelectItem value="admin">Administrator</SelectItem>
      <SelectItem value="member">Member</SelectItem>
    </SelectContent>
  </Select>
  <button type="submit">Save</button>
</form>

Programmatic value changes

Dispatch starwind:set-value on the Select root. Listen for the root-scoped starwind:value-change event when the selected value changes.

<Select id="role-select" name="role">
  <SelectTrigger placeholder="Choose a role" />
  <SelectContent>
    <SelectItem value="admin">Administrator</SelectItem>
    <SelectItem value="member">Member</SelectItem>
  </SelectContent>
</Select>

<button id="choose-admin" type="button">Choose administrator</button>

<script>
  const select = document.querySelector<HTMLElement>("#role-select");
  const button = document.querySelector<HTMLElement>("#choose-admin");

  button?.addEventListener("click", () => {
    select?.dispatchEvent(
      new CustomEvent("starwind:set-value", {
        detail: { value: "admin" },
      }),
    );
  });

  select?.addEventListener("starwind:value-change", (event) => {
    const { value } = (event as CustomEvent<{ value: string | null }>).detail;
    console.log(value);
  });
</script>

Runtime example adjustment

The legacy document-wide selection event has been replaced by the root-targeted starwind:set-value command, preventing unrelated Select instances from doing extra work.

For a searchable text input with listbox suggestions, install Combobox instead of adding the removed search part.

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Select

Inherits div attributes. Omits `defaultValue` and `onChange`.

Contains the following additional props:

Prop Type Default

defaultOpen boolean false

Description: Sets the initial open state when the component is uncontrolled.
Classification: Primitive override
Primitive prop: select.Root.defaultOpen

disabled boolean false

Description: Disables interaction with the component.
Classification: Primitive override
Primitive prop: select.Root.disabled

required boolean false

Description: Marks the control as required for form validation.
Classification: Primitive override
Primitive prop: select.Root.required

Select Trigger

Inherits button attributes.

Contains the following additional props:

Prop Type Default

asChild boolean false

Description: Merges the component behavior and props into its child element.
Classification: Primitive override
Primitive prop: select.Trigger.asChild

iconClass string —

Description: Adds classes to the component's generated icon.
Classification: Wrapper prop

placeholder string —

Description: Provides fallback text for the value element generated inside the trigger.
Classification: Wrapper prop

showIcon boolean true

Description: Shows the component's generated icon.
Classification: Wrapper prop

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

valueClass string —

Description: Adds classes to the generated value element.
Classification: Wrapper prop

Select Value

Inherits span attributes.

Contains the following additional props:

Prop Type Default

placeholder string —

Description: Provides fallback text when no value is available.
Classification: Wrapper prop

Select Content

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Wrapper prop

Select Item

Inherits div attributes. Omits `role`.

Contains the following additional props:

Prop Type Default

disabled boolean false

Description: Disables interaction with the component.
Classification: Styled variant
Primitive prop: select.Item.disabled

indicatorClass string —

Description: Adds classes to the generated selection indicator.
Classification: Wrapper prop

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Styled variant

showIndicator boolean true

Description: Shows the generated selection indicator.
Classification: Wrapper prop

value Required string —

Description: Controls or identifies the component value.
Classification: Primitive override
Primitive prop: select.Item.value

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Select.

Primitive API

Select Primitive

Runtime API

Select primitive: createSelect from @starwind-ui/runtime/select

Changelog

v2.0.0

Rebuilt Select on Starwind Runtime for selection, forms, events, and scroll behavior; search is now provided by Combobox.
See the Select Primitive for the underlying unstyled anatomy and behavior API.