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

<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";
</script>

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

Installation

pnpx starwind@latest add select --framework astro

npx starwind@latest add select --framework astro

yarn dlx starwind@latest add select --framework astro

pnpx starwind@latest add select --framework react

npx starwind@latest add select --framework react

yarn dlx starwind@latest add select --framework react

pnpx starwind@latest add select --framework vue

npx starwind@latest add select --framework vue

yarn dlx starwind@latest add select --framework vue

Usage

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

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

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

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

<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";
</script>

<template>
  <Select name="framework">
    <SelectTrigger placeholder="Choose a framework" />
    <SelectContent>
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="react">React</SelectItem>
    </SelectContent>
  </Select>
</template>

Composition

Use this structure for a Select with grouped options:

Select
├── SelectTrigger
└── SelectContent
    ├── SelectGroup
    │   ├── SelectLabel
    │   └── SelectItem
    ├── SelectSeparator
    └── SelectItem

Sizes

Set size on SelectTrigger and SelectContent separately. Both accept sm, md (the default), or lg. Set both to the same value for a consistent control, or use a larger content size when the popup needs more room.

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

{(["sm", "md", "lg"] as const).map((size) => (
  <Select defaultValue="astro">
    <SelectTrigger size={size} placeholder={`${size} trigger`} />
    <SelectContent size={size}>
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
    </SelectContent>
  </Select>
))}

<Select defaultValue="astro">
  <SelectTrigger size="sm" placeholder="Compact trigger" />
  <SelectContent size="lg">
    <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 (
    <>
      {(["sm", "md", "lg"] as const).map((size) => (
        <Select key={size} defaultValue="astro">
          <SelectTrigger size={size} placeholder={`${size} trigger`} />
          <SelectContent size={size}>
            <SelectItem value="astro">Astro</SelectItem>
            <SelectItem value="react">React</SelectItem>
            <SelectItem value="vue">Vue</SelectItem>
          </SelectContent>
        </Select>
      ))}

      <Select defaultValue="astro">
        <SelectTrigger size="sm" placeholder="Compact trigger" />
        <SelectContent size="lg">
          <SelectItem value="astro">Astro</SelectItem>
          <SelectItem value="react">React</SelectItem>
          <SelectItem value="vue">Vue</SelectItem>
        </SelectContent>
      </Select>
    </>
  );
}

<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";
const sizes = ["sm", "md", "lg"] as const;
</script>

<template>
  <template v-for="size in sizes" :key="size">
    <Select defaultValue="astro">
      <SelectTrigger :size="size" :placeholder="`${{ size }} trigger`" />
      <SelectContent :size="size">
        <SelectItem value="astro">Astro</SelectItem>
        <SelectItem value="react">React</SelectItem>
        <SelectItem value="vue">Vue</SelectItem>
      </SelectContent>
    </Select>
  </template>

  <Select defaultValue="astro">
    <SelectTrigger size="sm" placeholder="Compact trigger" />
    <SelectContent size="lg">
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
    </SelectContent>
  </Select>
</template>

Form Participation

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

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

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

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

export function Example() {
  const [submittedRole, setSubmittedRole] = useState<string | null>(null);

  return (
      <form
        onSubmit={(event) => {
          event.preventDefault();
          const data = new FormData(event.currentTarget);
          setSubmittedRole(String(data.get("role") ?? ""));
        }}
      >
        <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>
        {submittedRole !== null && (
          <output aria-live="polite">Submitted role: {submittedRole}</output>
        )}
      </form>
  );
}

<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";
</script>

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

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.

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

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

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

export function Example() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <>
      <Select
        name="role"
        value={value}
        onValueChange={(nextValue) => {
          setValue(nextValue);
          console.log(nextValue);
        }}
      >
        <SelectTrigger placeholder="Choose a role" />
        <SelectContent>
          <SelectItem value="admin">Administrator</SelectItem>
          <SelectItem value="member">Member</SelectItem>
        </SelectContent>
      </Select>
      <button type="button" onClick={() => setValue("admin")}>
        Choose administrator
      </button>
    </>
  );
}

<script setup lang="ts">
import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/starwind/select";
import { ref } from "vue";
const role = ref<string | null>(null);
</script>

<template>
  <Select v-model="role" @value-change="(value) => console.log(value)" id="role-select" name="role">
    <SelectTrigger placeholder="Choose a role" />
    <SelectContent>
      <SelectItem value="admin">Administrator</SelectItem>
      <SelectItem value="member">Member</SelectItem>
    </SelectContent>
  </Select>

  <button @click="role = 'admin'" type="button">Choose administrator</button>
</template>

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 styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. 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

disablePortal boolean false

Description: Keeps the public Portal wrapper inline instead of moving it to a target.
Classification: Wrapper prop

portalContainer string —

Description: Sets the CSS selector for the public Portal wrapper target.
Classification: Wrapper prop

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

View version history v2.1.1 5 releases

v2.1.1

Connected group headings to their groups with aria-labelledby so assistive technology can identify each group.

v2.1.0

Added portalContainer and disablePortal to SelectContent for custom portal targets and inline rendering.
Corrected touch interaction so tapping an open trigger closes the popup and tapping an item selects its value on mobile browsers.

v2.0.2

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v2.0.1

SelectTrigger and SelectContent now expose their independently resolved size as data-size, including the md default. No prop migration is required; set both props when the control and portal should match.

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.