Skip to content
opsinjs
Edit this page

Components

Select

A trigger that opens a floating list to choose one option from, built on Base UI Select and drawing only neutral chrome.

Usage

pnpm dlx shadcn@latest add @opsinjs/select

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Select } from "@/components/ui/select"
<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

Theme
Density
Text
Status
Accent theme
Accent
select · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
select-choosing-from-a-list · base base · style base-lyraOpen under the product theme
select-choosing-from-a-list.tsx
"use client"

import { useState } from "react"

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

export default function SelectChoosingFromAList() {
  const [zone, setZone] = useState("berlin")
  return (
    <div className="w-full max-w-xs">
      <Select
        label="Timezone"
        placeholder="Choose a timezone"
        value={zone}
        onValueChange={setZone}
        options={[
          { value: "lisbon", label: "Lisbon" },
          { value: "berlin", label: "Berlin" },
          { value: "nairobi", label: "Nairobi" },
          { value: "mumbai", label: "Mumbai" },
          { value: "tokyo", label: "Tokyo" },
          { value: "auckland", label: "Auckland" },
        ]}
      />
    </div>
  )
}

With a placeholder

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

Theme
Density
Text
Status
Accent theme
Accent
select-with-a-placeholder · base base · style base-lyraOpen under the product theme
select-with-a-placeholder.tsx
"use client"

import { useState } from "react"

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

export default function SelectWithAPlaceholder() {
  const [frequency, setFrequency] = useState("")
  return (
    <div className="w-full max-w-xs">
      <Select
        label="Reminder frequency"
        placeholder="Choose how often"
        value={frequency}
        onValueChange={setFrequency}
        options={[
          { value: "daily", label: "Every day" },
          { value: "weekdays", label: "Weekdays only" },
          { value: "weekly", label: "Once a week" },
          { value: "fortnightly", label: "Every two weeks" },
          { value: "monthly", label: "Once a month" },
        ]}
      />
    </div>
  )
}

When to use it

Use it when

  • Choosing one value from a list too long to lay flat, such as a timezone.
  • A single choice on a dense form, where a closed trigger keeps a long list from pushing fields down.
  • A setting the reader changes rarely, so opening the list costs little.

Do not use it when

  • Fewer than about seven options, easier scanned flat.Use radio-group instead.
  • A clinical value with a range and a verdict, needing a control that formats it.Use reading-input instead.
  • The options open different views, so choosing one swaps what the reader sees.Use tabs instead.

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.
KeyActionNotes
TabMoves focus onto the triggerOne tab stop; disabled selects are skipped.
Shift+TabMoves focus back off the triggerNever enters the list.
Enter, Space, Arrow Down, Arrow UpOpens the list from the triggerHighlight lands on the chosen or first enabled option.
Arrow Down, Arrow UpMoves the highlight through the open listDisabled options are skipped. No wrapping.
Home, EndMoves the highlight to the first or last optionBoth skip disabled options.
EnterChooses the highlighted option and closes the listFocus returns to the trigger, showing the value.
EscapeCloses the list without choosingThe value is left as it was.
Type a letterJumps to the next option whose label starts with what was typedBase UI type-to-find, unchecked against a screen reader.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from SelectProps in registry/bases/base/select.tsx.

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.