# Select

> Select presents a list of options using the native dropdown, so it stays keyboard and screen-reader correct and behaves as expected on mobile.

Source: https://vaneui.com/docs/form-components/select

Import: `import { Select, Col, Field, Row } from "@vaneui/ui"`

Use Select to pick a value such as a country or a currency from a long list, with the options passed as `<option>` and `<optgroup>` children. A handful of options that should all stay visible reads better as a [Radio](/docs/form-components/radio) group, and commands belong in a [Menu](/docs/overlay-components/menu). Inside a [Field](/docs/form-components/field) set to `readOnly`, Select stays read-only even though a native select has no such attribute: opening and keyboard changes are blocked, while Tab still moves focus.

## Basic usage

Select renders a real `<select>`, so keyboard support, screen-reader semantics, form submission and constraint validation all come from the platform rather than from re-implemented JavaScript.

```tsx demo
<Select>
  <option>Cyprus</option>
  <option>Estonia</option>
  <option>Portugal</option>
</Select>
```

The native arrow is replaced with a themed chevron that scales with the size prop. The field reserves room for it, so a long option never runs underneath. The selected value stays on one line, and at the same size a Select is as tall as an `Input` or a `Button`. In a `Row`, `noShrink` keeps the Select at its natural width.

## The dropdown list

Historically a native `<select>` hands its option list to the operating system, which draws a flat, square, unpadded menu that no page CSS can reach. Only the option's text and background colour land, because the options get no layout box at all.

On engines that support `appearance: base-select` the list becomes real DOM instead, and VaneUI styles it to match a `Menu`: themed surface, border, radius, shadow, padded rows, a hover state, and a checkmark on the selected option. Everywhere else the OS picker still appears, with `option` and `optgroup` carrying the field's surface and text colours so the list at least stays on your palette in both light and dark mode.

The list opens below the field and flips above it only when it genuinely does not fit. Browsers default to whichever side has more room, which sends the list upward for any field past the middle of the window even when there is space below it.

Options are children of the field, so they inherit its colours: the list follows the appearance and variant you set rather than staying pinned to the light surface. A disabled option, typically a placeholder, fades toward the list's own background instead of a fixed grey, so it stays readable on a filled list too.

Nothing is required to opt in, and nothing breaks on engines without it: the enhancement sits behind an `@supports` rule and the control is the same `<select>` either way.

## Sizes

Selects come in five sizes: `xs`, `sm`, `md` (default), `lg`, `xl`. The chevron and the room reserved for it scale with the field.

```tsx demo
<Col>
  <Select xs defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select sm defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select lg defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
  <Select xl defaultValue="sm">
    <option value="xs">Extra small</option>
    <option value="sm">Small</option>
    <option value="md">Medium</option>
    <option value="lg">Large</option>
  </Select>
</Col>
```

## States

`invalid` adds a danger border and ring, turns the chevron danger, and emits `aria-invalid`. Pair it with `Field` to attach the message.

```tsx demo
<Col>
  <Select defaultValue="eur">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Select invalid placeholder="Select a currency">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Select disabled defaultValue="eur">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
</Col>
```

## Appearances

Selects are `primary` by default and take the same appearance props as `Input`.

```tsx demo
<Row flexWrap>
  <Select className="w-40" defaultValue="eur">
    <option value="eur">Primary</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select success className="w-40" defaultValue="eur">
    <option value="eur">Success</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select warning className="w-40" defaultValue="eur">
    <option value="eur">Warning</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select danger className="w-40" defaultValue="eur">
    <option value="eur">Danger</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Variants

`outline` is the default. The dropdown list takes its colours from the field, so a `filled` Select opens a filled list rather than a light one on a dark control. `ghost` drops the field's own surface but keeps the list opaque, since a see-through popup would render the options unreadable.

```tsx demo
<Row flexWrap>
  <Select className="w-40" defaultValue="eur">
    <option value="eur">Outline</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select filled className="w-40" defaultValue="eur">
    <option value="eur">Filled</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select ghost className="w-40" defaultValue="eur">
    <option value="eur">Ghost</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Shapes

`rounded` is the default, and the shape carries through to the dropdown: a `sharp` Select opens a sharp list rather than a rounded one on a square field.

`pill` is the exception. It reshapes the field only, because a pill radius is effectively infinite and a tall list box given that radius swallows its own first and last rows.

```tsx demo
<Row flexWrap>
  <Select rounded className="w-40" defaultValue="eur">
    <option value="eur">Rounded</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select pill className="w-40" defaultValue="eur">
    <option value="eur">Pill</option>
    <option value="usd">US dollar</option>
  </Select>
  <Select sharp className="w-40" defaultValue="eur">
    <option value="eur">Sharp</option>
    <option value="usd">US dollar</option>
  </Select>
</Row>
```

## Placeholder

`placeholder` adds a muted first option that prompts for a choice. It is disabled and hidden from the list, so it can't be picked again, and an uncontrolled Select starts on it; with `required`, the empty value fails validation. `multiple` ignores it, and `<Field select placeholder="...">` passes it through. The prop needs `@vaneui/ui` 1.5.0 or later.

```tsx demo
<Col>
  <Select placeholder="Choose a currency">
    <option value="eur">Euro</option>
    <option value="usd">US dollar</option>
    <option value="gbp">Pound sterling</option>
  </Select>
  <Field select required placeholder="Choose a region" label="Region" description="Required.">
    <option>Cyprus</option>
    <option>Estonia</option>
    <option>Portugal</option>
  </Field>
</Col>
```

## Groups and placeholders

An `optgroup` labels a run of related options, and the placeholder stays above the groups.

```tsx demo
<Field label="Region" description="Sets your default currency.">
  <Select placeholder="Choose a region">
    <optgroup label="Europe">
      <option>Cyprus</option>
      <option>Estonia</option>
    </optgroup>
    <optgroup label="Americas">
      <option>Canada</option>
    </optgroup>
  </Select>
</Field>
```

## Props

| Prop | Category | Default | Description |
| --- | --- | --- | --- |
| `primary` | Appearance | yes | Primary color appearance (gray) |
| `accent` | Appearance |  | Accent color appearance (rose) |
| `secondary` | Appearance |  | Secondary color appearance (gray) |
| `tertiary` | Appearance |  | Tertiary color appearance |
| `success` | Appearance |  | Success color appearance (green) |
| `danger` | Appearance |  | Danger color appearance (red) |
| `warning` | Appearance |  | Warning color appearance (amber) |
| `info` | Appearance |  | Info color appearance (cyan) |
| `inheritAppearance` | Appearance |  | Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables |
| `disabled` | Disabled |  | Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction |
| `flex1` | Flex |  | Take up remaining space (= `flex-1`, i.e. `flex: 1 1 0%`) |
| `flexAuto` | Flex |  | Grow but respect intrinsic size (= `flex-auto`, i.e. `flex: 1 1 auto`) |
| `flexNone` | Flex |  | Don't grow and don't shrink (= `flex-none`, i.e. `flex: none`) |
| `fontSans` | Font Family | yes | Sans-serif font family (default) — emits font-sans |
| `fontSerif` | Font Family |  | Serif font family — emits font-serif |
| `fontMono` | Font Family |  | Monospace font family — emits font-mono |
| `fontHeading` | Font Family |  | Heading font family (defaults to sans, customizable via --font-heading) — emits font-heading |
| `italic` | Font Style |  | Italic font style |
| `notItalic` | Font Style |  | Not italic (normal) font style |
| `fontThin` | Font Weight |  | Thin font weight (100) — emits font-thin |
| `fontExtralight` | Font Weight |  | Extra light font weight (200) — emits font-extralight |
| `fontLight` | Font Weight |  | Light font weight (300) — emits font-light |
| `fontNormal` | Font Weight | yes | Normal font weight (400) — emits font-normal |
| `fontMedium` | Font Weight |  | Medium font weight (500) — emits font-medium |
| `fontSemibold` | Font Weight |  | Semibold font weight (600) — emits font-semibold |
| `fontBold` | Font Weight |  | Bold font weight (700) — emits font-bold |
| `fontExtrabold` | Font Weight |  | Extra bold font weight (800) — emits font-extrabold |
| `fontBlack` | Font Weight |  | Black font weight (900) — emits font-black |
| `padding` | Padding | yes | Enable internal padding |
| `paddingX` | Padding |  | Enable only horizontal padding |
| `paddingY` | Padding |  | Enable only vertical padding |
| `noPadding` | Padding |  | Disable internal padding |
| `readOnly` | Read Only |  | Render the field read-only — mutes it (lighter than disabled) and sets a default cursor; the value stays selectable and submittable |
| `pill` | Shape |  | Fully rounded corners (circular) |
| `sharp` | Shape |  | No rounded corners (square) |
| `rounded` | Shape | yes | Medium rounded corners (default) |
| `noShrink` | Shrink |  | Prevent the flex item from shrinking below its content size (= `shrink-0`) |
| `xs` | Size |  | Extra small size |
| `sm` | Size |  | Small size |
| `md` | Size | yes | Medium size (default) |
| `lg` | Size |  | Large size |
| `xl` | Size |  | Extra large size |
| `textLeft` | Text Align |  | Align text to left (physical side, does not flip under RTL) |
| `textCenter` | Text Align |  | Align text to center |
| `textRight` | Text Align |  | Align text to right (physical side, does not flip under RTL) |
| `textJustify` | Text Align |  | Justify text |
| `textStart` | Text Align |  | Align text to the reading-direction start (left in LTR, right in RTL) |
| `textEnd` | Text Align |  | Align text to the reading-direction end (right in LTR, left in RTL) |
| `underline` | Text Decoration |  | Add underline decoration below text |
| `lineThrough` | Text Decoration |  | Add strikethrough/line-through decoration across text |
| `noUnderline` | Text Decoration |  | Remove ALL text-decoration — underline, line-through, and overline (text-decoration: none) |
| `overline` | Text Decoration |  | Add overline decoration above text |
| `uppercase` | Text Transform |  | Transform text to uppercase |
| `lowercase` | Text Transform |  | Transform text to lowercase |
| `capitalize` | Text Transform |  | Capitalize first letter of each word |
| `normalCase` | Text Transform |  | Normal text case (no transformation) |
| `truncate` | Truncate |  | Single line truncation with ellipsis |
| `lineClamp2` | Truncate |  | Truncate at 2 lines with ellipsis |
| `lineClamp3` | Truncate |  | Truncate at 3 lines with ellipsis |
| `lineClamp4` | Truncate |  | Truncate at 4 lines with ellipsis |
| `lineClamp5` | Truncate |  | Truncate at 5 lines with ellipsis |
| `noTruncate` | Truncate |  | Remove truncation |
| `invalid` | Validity |  | Mark the field invalid (red border/ring), layered over any appearance |
| `filled` | Variant |  | Filled variant - solid background with contrasting text color |
| `outline` | Variant | yes | Outline variant - transparent background with border and colored text (default) |
| `ghost` | Variant |  | Ghost variant - transparent background, no border, appearance-colored text, tinted hover background |

Layout and utility props (Border, Cursor, Display, Flex Direction, Focus Visible, Gap, Height, Hide, Items, Justify, Overflow, Position, Responsive Sizing, Responsive Width, Ring, Shadow, Show, Transition, Transparent, Whitespace, Width, Wrap) are listed on [Common Props](https://vaneui.com/docs/reference/common-props.md).
