# Native Select

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[240px]">
  <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
  <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
  <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[240px]">
        <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
        <NativeSelectOption value="apple">Apple</NativeSelectOption>
        <NativeSelectOption value="banana">Banana</NativeSelectOption>
        <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
        <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <NativeSelect class="w-[240px]">
    <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
    <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
    <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
  </NativeSelect>
</template>
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** For a styled select component, see the [Select](/docs/components/select/) component.

## Installation

```bash
npx starwind@latest add native-select --framework astro
```
</DocsTabsContent>
```bash
npx starwind@latest add native-select --framework react
```
</DocsTabsContent>
```bash
npx starwind@latest add native-select --framework vue
```
</DocsTabsContent>
</DocsTabs>

## Usage

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[240px]">
  <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
  <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
  <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[240px]">
        <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
        <NativeSelectOption value="apple">Apple</NativeSelectOption>
        <NativeSelectOption value="banana">Banana</NativeSelectOption>
        <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
        <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <NativeSelect class="w-[240px]">
    <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
    <NativeSelectOption value="blueberry">Blueberry</NativeSelectOption>
    <NativeSelectOption value="pineapple">Pineapple</NativeSelectOption>
  </NativeSelect>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Composition

Place options directly inside `NativeSelect`, or organize them with `NativeSelectOptGroup`:

```text
NativeSelect
├── NativeSelectOption
└── NativeSelectOptGroup
    ├── NativeSelectOption
    └── NativeSelectOption
```

## Groups

Use `NativeSelectOptGroup` to organize options into categories.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[260px]">
  <NativeSelectOption value="" disabled>Select an option</NativeSelectOption>
  <NativeSelectOptGroup label="Fruits">
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
  </NativeSelectOptGroup>
  <NativeSelectOptGroup label="Vegetables">
    <NativeSelectOption value="carrot">Carrot</NativeSelectOption>
    <NativeSelectOption value="spinach">Spinach</NativeSelectOption>
  </NativeSelectOptGroup>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[260px]">
        <NativeSelectOption value="" disabled>Select an option</NativeSelectOption>
        <NativeSelectOptGroup label="Fruits">
          <NativeSelectOption value="apple">Apple</NativeSelectOption>
          <NativeSelectOption value="banana">Banana</NativeSelectOption>
        </NativeSelectOptGroup>
        <NativeSelectOptGroup label="Vegetables">
          <NativeSelectOption value="carrot">Carrot</NativeSelectOption>
          <NativeSelectOption value="spinach">Spinach</NativeSelectOption>
        </NativeSelectOptGroup>
      </NativeSelect>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/components/starwind/native-select";
</script>

<template>
  <NativeSelect class="w-[260px]">
    <NativeSelectOption value="" disabled>Select an option</NativeSelectOption>
    <NativeSelectOptGroup label="Fruits">
      <NativeSelectOption value="apple">Apple</NativeSelectOption>
      <NativeSelectOption value="banana">Banana</NativeSelectOption>
    </NativeSelectOptGroup>
    <NativeSelectOptGroup label="Vegetables">
      <NativeSelectOption value="carrot">Carrot</NativeSelectOption>
      <NativeSelectOption value="spinach">Spinach</NativeSelectOption>
    </NativeSelectOptGroup>
  </NativeSelect>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Disabled

Add the `disabled` prop to disable the entire select, or disable specific options.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect class="w-[220px]" disabled>
  <NativeSelectOption value="" disabled>Select framework</NativeSelectOption>
  <NativeSelectOption value="astro">Astro</NativeSelectOption>
  <NativeSelectOption value="next">Next.js</NativeSelectOption>
</NativeSelect>

<NativeSelect class="w-[220px]">
  <NativeSelectOption value="astro" selected>Astro</NativeSelectOption>
  <NativeSelectOption value="next" disabled>Next.js (Disabled)</NativeSelectOption>
  <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect className="w-[220px]" disabled>
        <NativeSelectOption value="" disabled>Select framework</NativeSelectOption>
        <NativeSelectOption value="astro">Astro</NativeSelectOption>
        <NativeSelectOption value="next">Next.js</NativeSelectOption>
      </NativeSelect>

      <NativeSelect className="w-[220px]" defaultValue="astro">
        <NativeSelectOption value="astro">Astro</NativeSelectOption>
        <NativeSelectOption value="next" disabled>Next.js (Disabled)</NativeSelectOption>
        <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <NativeSelect class="w-[220px]" disabled>
    <NativeSelectOption value="" disabled>Select framework</NativeSelectOption>
    <NativeSelectOption value="astro">Astro</NativeSelectOption>
    <NativeSelectOption value="next">Next.js</NativeSelectOption>
  </NativeSelect>

  <NativeSelect class="w-[220px]">
    <NativeSelectOption value="astro" selected>Astro</NativeSelectOption>
    <NativeSelectOption value="next" disabled>Next.js (Disabled)</NativeSelectOption>
    <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
  </NativeSelect>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Invalid

Use `aria-invalid` for assistive technology and `data-error-visible` to opt into the visible error
state after validation has run.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Label } from "@/components/starwind/label";
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<div class="grid w-full max-w-sm gap-2">
  <Label for="native-select-invalid">Framework</Label>
  <NativeSelect
    id="native-select-invalid"
    class="w-full"
    aria-invalid
    data-error-visible
  >
    <NativeSelectOption value="" disabled>Select a framework</NativeSelectOption>
    <NativeSelectOption value="astro">Astro</NativeSelectOption>
    <NativeSelectOption value="next">Next.js</NativeSelectOption>
    <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
  </NativeSelect>
  <p class="text-error text-sm">Please select a framework.</p>
</div>
```
  </div>
  <div slot="react">
```tsx
import { Label } from "@/components/starwind/label";
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <div className="grid w-full max-w-sm gap-2">
        <Label htmlFor="native-select-invalid">Framework</Label>
        <NativeSelect
          id="native-select-invalid"
          className="w-full"
          aria-invalid
          data-error-visible
        >
          <NativeSelectOption value="" disabled>Select a framework</NativeSelectOption>
          <NativeSelectOption value="astro">Astro</NativeSelectOption>
          <NativeSelectOption value="next">Next.js</NativeSelectOption>
          <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
        </NativeSelect>
        <p className="text-error text-sm">Please select a framework.</p>
      </div>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { Label } from "@/components/starwind/label";
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <div class="grid w-full max-w-sm gap-2">
    <Label for="native-select-invalid">Framework</Label>
    <NativeSelect id="native-select-invalid" class="w-full" aria-invalid="true" data-error-visible>
      <NativeSelectOption value="" disabled>Select a framework</NativeSelectOption>
      <NativeSelectOption value="astro">Astro</NativeSelectOption>
      <NativeSelectOption value="next">Next.js</NativeSelectOption>
      <NativeSelectOption value="svelte">SvelteKit</NativeSelectOption>
    </NativeSelect>
    <p class="text-error text-sm">Please select a framework.</p>
  </div>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Size

Use the `size` prop to render compact or larger controls.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<NativeSelect size="sm" class="w-[180px]">
  <NativeSelectOption value="" disabled>Small</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>

<NativeSelect size="md" class="w-[180px]">
  <NativeSelectOption value="" disabled>Medium</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>

<NativeSelect size="lg" class="w-[180px]">
  <NativeSelectOption value="" disabled>Large</NativeSelectOption>
  <NativeSelectOption value="one">Option 1</NativeSelectOption>
  <NativeSelectOption value="two">Option 2</NativeSelectOption>
</NativeSelect>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <NativeSelect size="sm" className="w-[180px]">
        <NativeSelectOption value="" disabled>Small</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>

      <NativeSelect size="md" className="w-[180px]">
        <NativeSelectOption value="" disabled>Medium</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>

      <NativeSelect size="lg" className="w-[180px]">
        <NativeSelectOption value="" disabled>Large</NativeSelectOption>
        <NativeSelectOption value="one">Option 1</NativeSelectOption>
        <NativeSelectOption value="two">Option 2</NativeSelectOption>
      </NativeSelect>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <NativeSelect size="sm" class="w-[180px]">
    <NativeSelectOption value="" disabled>Small</NativeSelectOption>
    <NativeSelectOption value="one">Option 1</NativeSelectOption>
    <NativeSelectOption value="two">Option 2</NativeSelectOption>
  </NativeSelect>

  <NativeSelect size="md" class="w-[180px]">
    <NativeSelectOption value="" disabled>Medium</NativeSelectOption>
    <NativeSelectOption value="one">Option 1</NativeSelectOption>
    <NativeSelectOption value="two">Option 2</NativeSelectOption>
  </NativeSelect>

  <NativeSelect size="lg" class="w-[180px]">
    <NativeSelectOption value="" disabled>Large</NativeSelectOption>
    <NativeSelectOption value="one">Option 1</NativeSelectOption>
    <NativeSelectOption value="two">Option 2</NativeSelectOption>
  </NativeSelect>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Native Select vs Select

Use [Native Select](/docs/components/native-select/) for simple forms when you want browser-native behavior and mobile pickers. Use [Select](/docs/components/select/) when you need custom popover behavior, search, and advanced interaction patterns.

> **Tip:** Prefer `NativeSelect` for straightforward form controls and mobile-first flows where native platform
pickers are beneficial. Choose [Select](/docs/components/select/) when you need richer UI features
like searchable options, custom popover positioning, and advanced interactions.

## RTL

Set `dir="rtl"` to support right-to-left languages.

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
---

<div dir="rtl">
  <NativeSelect class="w-[240px]">
    <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
    <NativeSelectOption value="apple">Apple</NativeSelectOption>
    <NativeSelectOption value="banana">Banana</NativeSelectOption>
    <NativeSelectOption value="grape">Grape</NativeSelectOption>
  </NativeSelect>
</div>
```
  </div>
  <div slot="react">
```tsx
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";

export function Example() {
  return (
    <>
      <div dir="rtl">
        <NativeSelect className="w-[240px]">
          <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
          <NativeSelectOption value="apple">Apple</NativeSelectOption>
          <NativeSelectOption value="banana">Banana</NativeSelectOption>
          <NativeSelectOption value="grape">Grape</NativeSelectOption>
        </NativeSelect>
      </div>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import { NativeSelect, NativeSelectOption } from "@/components/starwind/native-select";
</script>

<template>
  <div dir="rtl">
    <NativeSelect class="w-[240px]">
      <NativeSelectOption value="" disabled>Select a fruit</NativeSelectOption>
      <NativeSelectOption value="apple">Apple</NativeSelectOption>
      <NativeSelectOption value="banana">Banana</NativeSelectOption>
      <NativeSelectOption value="grape">Grape</NativeSelectOption>
    </NativeSelect>
  </div>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## API Reference
### NativeSelect
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits select attributes. Omits `size`.

### NativeSelectOption
- Inherits option attributes.

### NativeSelectOptGroup
- Inherits optgroup attributes.

## Changelog

### v1.1.1

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

### v1.1.0

- Added contract-generated Astro and React implementations while preserving the component's existing public API and styling.
- Native Select follows Astro and HTML option-selection semantics. Omitting a value selects the
first option naturally; the legacy React-style `defaultValue` prop is no longer used.

### v1.0.1

- Refactor tailwind variants functions into separate `variants.ts` file

### v1.0.0

- Initial release with starwind v1.16.0