Select

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

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Select" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Frameworks</SelectLabel>
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="next">Next.js</SelectItem>
      <SelectItem value="svelte">SvelteKit</SelectItem>
      <SelectItem value="solid">SolidStart</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Installation

pnpx starwind@latest add select

npx starwind@latest add select

yarn dlx starwind@latest add select

Usage

size

You can control the size of the select trigger and content using the size prop. Available sizes are "sm", "md" (default), and "lg".

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

<Select>
  <SelectTrigger size="sm" class="w-[180px]">
    <SelectValue placeholder="Small select" />
  </SelectTrigger>
  <SelectContent size="sm">
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
  </SelectContent>
</Select>

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Default select" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
  </SelectContent>
</Select>

<Select>
  <SelectTrigger size="lg" class="w-[180px]">
    <SelectValue placeholder="Large select" />
  </SelectTrigger>
  <SelectContent size="lg">
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
  </SelectContent>
</Select>

side, align, and sideOffset

You can control the position of the select dropdown using the side, align and sideOffset props on SelectContent.

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

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Opens above" />
  </SelectTrigger>
  <SelectContent side="top" align="center" sideOffset={12}>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
  </SelectContent>
</Select>

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Opens below" />
  </SelectTrigger>
  <SelectContent side="bottom" align="end" sideOffset={4}>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
  </SelectContent>
</Select>

disabled

You can disable the select trigger or individual items.

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

<Select>
  <SelectTrigger disabled class="w-[180px]">
    <SelectValue placeholder="Disabled trigger" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
  </SelectContent>
</Select>

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="With disabled items" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2" disabled>Option 2 (Disabled)</SelectItem>
    <SelectItem value="3">Option 3</SelectItem>
    <SelectItem value="4" disabled>Option 4 (Disabled)</SelectItem>
    <SelectItem value="5">Option 5</SelectItem>
  </SelectContent>
</Select>

Form Handling

This component mirrors the behavior of a standard HTML select element. Internally, it renders a hidden <select> to integrate seamlessly with forms.

Tip

Open up the dev tools console to see the form data on submission.

Create project

Deploy your new project in one-click.

---
import { Button } from "@/components/starwind/button";

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/starwind/card";

import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";

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

<Card class="w-[400px]">
  <CardHeader>
    <CardTitle>Create project</CardTitle>
    <CardDescription>Deploy your new project in one-click.</CardDescription>
  </CardHeader>
  <form id="create-project-form">
    <CardContent class="flex flex-col gap-4">
      <div class="flex w-full flex-col gap-2">
        <Label for="name">Name</Label>
        <Input type="text" id="name" name="name" placeholder="Name of your project" />
      </div>
      <div class="flex w-full flex-col gap-2">
        <Label for="framework">Framework</Label>
        <Select required id="framework" name="framework">
          <SelectTrigger class="w-full">
            <SelectValue placeholder="Select" />
          </SelectTrigger>
          <SelectContent>
            <SelectGroup>
              <SelectLabel>Frameworks</SelectLabel>
              <SelectItem value="astro">Astro</SelectItem>
              <SelectItem value="next">Next.js</SelectItem>
              <SelectItem value="svelte">SvelteKit</SelectItem>
              <SelectItem value="solid">SolidStart</SelectItem>
            </SelectGroup>
          </SelectContent>
        </Select>
      </div>
    </CardContent>
    <CardFooter class="flex justify-between">
      <Button variant="outline">Cancel</Button>
      <Button type="submit">Deploy</Button>
    </CardFooter>
  </form>
</Card>

<script>
  function handleFormSubmit() {
    const form = document.querySelector("#create-project-form") as HTMLFormElement;
    if (form) {
      form.addEventListener("submit", (e) => {
        e.preventDefault();
        const formData = new FormData(form);
        const formValues = Object.fromEntries(formData.entries());

        // demo form data logging
        console.log("Form submission values:", formValues);

        // You can add additional logic here like:
        // - Form validation
        // - API submission
        // - Success/error handling
      });
    }
  }

  handleFormSubmit();

  document.addEventListener("astro:after-swap", handleFormSubmit);
</script>

With Search (Combobox)

New Add a search input to filter through select options, creating a combobox pattern. The SelectSearch component provides built-in filtering functionality.

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

<Select id="select-demo-framework" name="framework">
  <SelectTrigger class="w-[240px]" required>
    <SelectValue placeholder="Select a framework" />
  </SelectTrigger>
  <SelectContent>
    <SelectSearch placeholder="Search frameworks..." emptyText="No frameworks found." />
    <SelectGroup>
      <SelectItem value="astro">Astro</SelectItem>
      <SelectItem value="next">Next.js</SelectItem>
      <SelectItem value="svelte">SvelteKit</SelectItem>
      <SelectItem value="solid">SolidStart</SelectItem>
      <SelectItem value="remix">Remix</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

With Groups and Labels

Group related items together and add labels for better organization.

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

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Select a food" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Fruits</SelectLabel>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>Vegetables</SelectLabel>
      <SelectItem value="carrot">Carrot</SelectItem>
      <SelectItem value="spinach">Spinach</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Programmatic Control

You can programmatically select an option by dispatching a custom SelectEvent with the value property set to the desired option’s value. You also need to pass either the name or id of the select element to the event.

---
import { Button } from "@/components/starwind/button";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@/components/starwind/select";
---

<div class="flex w-full max-w-[400px] flex-col gap-4">
  <Select id="select-programmatic-control" name="options">
    <SelectTrigger class="w-full" required>
      <SelectValue placeholder="Select" />
    </SelectTrigger>
    <SelectContent>
      <SelectGroup>
        <SelectLabel>Options</SelectLabel>
        <SelectItem value="1">Option 1</SelectItem>
        <SelectItem value="2">Option 2</SelectItem>
        <SelectItem value="3">Option 3</SelectItem>
      </SelectGroup>
    </SelectContent>
  </Select>

  <Button variant="primary" id="select-option-1-btn">Programmatically select "option 1"</Button>
</div>

<script>
  function setupProgrammaticSelectDemo() {
    const selectOption1Btn = document.querySelector("#select-option-1-btn");
    if (selectOption1Btn) {
      selectOption1Btn.addEventListener("click", () => {
        // Dispatch the custom event to programmatically select 'option 1'
        document.dispatchEvent(
          new CustomEvent("starwind-select:select", {
            detail: {
              // You can use either the name or id of the select
              selectName: "options", // This is the name attribute of the select
              // selectId: "select-programmatic-control", // This is the id attribute of the select
              value: "1",
            },
          }),
        );

        console.log("Dispatched event to select option 1");
      });
    }
  }

  setupProgrammaticSelectDemo();
  document.addEventListener("astro:after-swap", () => {
    setupProgrammaticSelectDemo();
  });
</script>

Change Event Handling

The select component emits a starwind-select:change event when a selection is made. The selected value can be accessed through event.detail.value.

<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Select option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
  </SelectContent>
</Select>

<script>
  document.querySelector('.starwind-select')?.addEventListener('starwind-select:change', (event) => {
    console.log('Selected value:', event.detail.value);
  });
</script>

API Reference

Select

The root component that manages the select state.

Prop	Type	Default
`id`	`string`	-
`name`	`string`	-
`defaultValue`	`string`	-
`class`	`string`	-

<Select name="framework">
  <!-- Select components -->
</Select>

Additional Notes:

name: Name attribute for form handling

SelectTrigger

The button that toggles the select dropdown.

Prop	Type	Default
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`required`	`boolean`	`false`
`disabled`	`boolean`	`false`
`class`	`string`	-

<SelectTrigger class="w-[180px]">
  <SelectValue placeholder="Select" />
</SelectTrigger>

SelectContent

The dropdown content that appears when the select is open.

Prop	Type	Default
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`side`	`"top" \| "bottom"`	`"bottom"`
`align`	`"start" \| "center" \| "end"`	`"start"`
`sideOffset`	`number`	`4`
`animationDuration`	`number`	`150`
`class`	`string`	-

<SelectContent>
  <!-- Select items -->
</SelectContent>

Additional Notes:

side: Side of the dropdown relative to the trigger
align: Alignment of the dropdown relative to the trigger
sideOffset: Offset distance in pixels from the trigger
animationDuration: Open and close animation duration in milliseconds

SelectItem

An item that can be selected. Requires a value prop.

Prop	Type	Default
`value`	`string`	Required
`disabled`	`boolean`	`false`
`class`	`string`	-

<SelectItem value="astro">Astro</SelectItem>

SelectValue

The component that displays the selected value or placeholder text in the trigger.

Prop	Type	Default
`placeholder`	`string`	`"select"`
`class`	`string`	-

<SelectValue placeholder="Select a framework" />

SelectGroup

A component used to group related select items together.

Prop	Type	Default
`class`	`string`	-

<SelectGroup>
  <SelectLabel>Frameworks</SelectLabel>
  <!-- Select items -->
</SelectGroup>

SelectLabel

A label component used to give a title to a group of items.

Prop	Type	Default
`class`	`string`	-

<SelectLabel>Frameworks</SelectLabel>

SelectSeparator

A visual separator that can be used between select items.

Prop	Type	Default
`class`	`string`	-

<SelectSeparator />

SelectSearch

A search input component that filters select items in real-time, creating a combobox pattern.

Prop	Type	Default
`placeholder`	`string`	`"Search..."`
`emptyText`	`string`	`"No results found."`
`class`	`string`	-

<SelectSearch placeholder="Search frameworks..." />

Additional Notes:

Place inside SelectContent before the items you want to filter
emptyText: Text to display when no items match the search

Changelog

v1.8.0

Add required prop to Select to enable form validation

v1.7.0

Add SelectSearch component to enable combobox capability
Add size prop to SelectTrigger and SelectContent
Styling improvements

v1.6.1

Add named slot “icon” to SelectItem and SelectTrigger to enable easy icon swapping

v1.6.0

style and focus state updates

v1.5.0

Add data-slot attribute to enable global styling updates

v1.4.1

Add type exports for SelectEvent and SelectChangeEvent.

v1.4.0

Add the ability to programmatically select an item through a new event listener for a custom SelectEvent.

v1.3.2

No longer return focus if clicking outside of the select menu. Focus will now only return to the select trigger on item selection, or when closing with the keyboard.

v1.3.1

Fix exit animation

v1.3.0

Add support for a defaultValue prop to enable initial selection of an option
Add support for align prop on SelectContent
Update open and close animations to match DropdownContent

v1.2.0

Allow a “name” attribute to enable simple form handling by leveraging the hidden html <select> element that is auto-generated.
Add empty aria-controls="" to SelectTrigger to make eslint happy. It is still assigned by the script.

v1.1.0

tailwind-variants now implemented. This uses tailwind-merge under the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the “class” prop.