---
title: "Select"
description: "A trigger that opens a floating list to choose one option from, built on Base UI Select and drawing only neutral chrome."
url: "https://opsinjs.pensievelabs.org/docs/components/select"
source: "https://opsinjs.pensievelabs.org/docs/components/select.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["dropdown", "picker"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="select"
  status="shipped"
  questions="[
  &#x22;Nobody has heard this in a screen reader, so whether the open, move and choose sequence reads cleanly is unknown.&#x22;,
  &#x22;No contrast pair has been measured; the trigger ink, the popup ink, the placeholder and the hairline are argued, not checked.&#x22;,
  &#x22;Whether the popup's one shadow rung still separates the list under forced colours is untested, and no prefers-contrast rule exists.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="select" unbuilt="false" importPath="@/components/ui/select" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

```tsx
import { Select } from "@/components/ui/select"
```

```tsx
<Select
  label="Timezone"
  placeholder="Choose a timezone"
  value={timezone}
  onValueChange={setTimezone}
  options={[
    { value: "lisbon", label: "Lisbon" },
    { value: "berlin", label: "Berlin" },
    { value: "tokyo", label: "Tokyo" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="select" />

### Choosing from a list [#choosing-from-a-list]

`options` drives the list, here a set of fictional timezones. A tick and a
neutral highlight carry the selection, not a colour.

<ComponentPreview name="select-choosing-from-a-list" kind="example" align="start" />

### With a placeholder [#with-a-placeholder]

`placeholder` fills the trigger before anything is chosen: a prompt, not a
value, and it never appears in the list.

<ComponentPreview name="select-with-a-placeholder" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Choosing one value from a list too long to lay flat, such as a timezone.&#x22;,
  &#x22;A single choice on a dense form, where a closed trigger keeps a long list from pushing fields down.&#x22;,
  &#x22;A setting the reader changes rarely, so opening the list costs little.&#x22;,
]"
  avoid="[
  { case: &#x22;Fewer than about seven options, easier scanned flat.&#x22;, instead: &#x22;radio-group&#x22; },
  { case: &#x22;A clinical value with a range and a verdict, needing a control that formats it.&#x22;, instead: &#x22;reading-input&#x22; },
  { case: &#x22;The options open different views, so choosing one swaps what the reader sees.&#x22;, instead: &#x22;tabs&#x22; },
]"
/>

## Accessibility [#accessibility]

Base UI supplies a combobox trigger, a listbox popup and `aria-selected` options, and
icons are `aria-hidden`. Selection is shown by a Check glyph and `aria-selected`, not
colour. The focus ring, the `--opsin-target-minimum` hit area, neutral chrome colours
and non-`px` type sizes all hold. The list unfolds from the trigger, and under
`prefers-reduced-motion` only a short opacity crossfade remains.

**Residual items.**

* The required `label` becomes the trigger's `aria-label`, so once a value fills the
  trigger a reader can lose its programmatic name. Several wrappers share this gap,
  and it waits on one system-wide repair.
* At 200% text a long value truncates in the trigger, with no loss of function, since
  the full label stays readable in the open list.
* Contrast pairs and the popup under `forced-colors: active` are still unmeasured.

<KeyboardTable
  name="select"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus onto the trigger&#x22;,
    notes: &#x22;One tab stop; disabled selects are skipped.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back off the trigger&#x22;,
    notes: &#x22;Never enters the list.&#x22;,
  },
  {
    keys: &#x22;Enter, Space, Arrow Down, Arrow Up&#x22;,
    action: &#x22;Opens the list from the trigger&#x22;,
    notes: &#x22;Highlight lands on the chosen or first enabled option.&#x22;,
  },
  {
    keys: &#x22;Arrow Down, Arrow Up&#x22;,
    action: &#x22;Moves the highlight through the open list&#x22;,
    notes: &#x22;Disabled options are skipped. No wrapping.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Moves the highlight to the first or last option&#x22;,
    notes: &#x22;Both skip disabled options.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Chooses the highlighted option and closes the list&#x22;,
    notes: &#x22;Focus returns to the trigger, showing the value.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Closes the list without choosing&#x22;,
    notes: &#x22;The value is left as it was.&#x22;,
  },
  {
    keys: &#x22;Type a letter&#x22;,
    action: &#x22;Jumps to the next option whose label starts with what was typed&#x22;,
    notes: &#x22;Base UI type-to-find, unchecked against a screen reader.&#x22;,
  },
]"
/>

<ContrastReport component="select" />

## Props interface [#props-interface]

<PropsTable name="SelectProps" />

`value` and `onValueChange` make this controlled: no internal selection state,
and a value matching no option shows the placeholder. `label` is required, so
the trigger always has an accessible name.
