BetaForms

Select

A field that opens a list. It is the TextField's twin: the same field tokens, the same four levels, the same heights — so the two sit in a form and read as one control.

Source Markdown

Overview

A field that opens a list. It is the TextField's twin: the same field* tokens, the same four levels, the same heights — so the two sit in a form and read as one control.

First example

<Select onValueChange={setLocale}>
  <Select.Label>Langue</Select.Label>
  <Select.Trigger>
    <Select.Value placeholder="Choisir une langue" />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Overlay />
  <Select.Content>
    <Select.Item value="fr">Français</Select.Item>
    <Select.Item value="en">English</Select.Item>
  </Select.Content>
  <Select.Description>Celle de l'interface.</Select.Description>
</Select>

Anatomy

<Select>
  <Select.Label>…</Select.Label>
  <Select.Trigger>
    <Select.Value />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Overlay />
  <Select.Content>
    <Select.GroupLabel>…</Select.GroupLabel>
    <Select.Item value="…">
      <Select.ItemLabel>…</Select.ItemLabel>
      <Select.ItemDescription>…</Select.ItemDescription>
      <Select.ItemIndicator />
    </Select.Item>
  </Select.Content>
  <Select.Description>…</Select.Description>
  <Select.Error>…</Select.Error>
</Select>

Select — the column, and the state and resolved style behind it.
Select.Label — what the field is for, above the trigger.
Select.Trigger — the control. The field the user sees, and the node a ref reaches.
Select.Value — what is chosen, or the placeholder until something is.
Select.Indicator — the chevron, turning on a spring with the list.
Select.Overlay — the backdrop. Optional, and what closes the list on an outside press.
Select.Content — the list, positioned against the trigger and rendered in a portal.
Select.GroupLabel — a heading over a run of rows, inside the panel.
Select.Item — one row.
Select.ItemLabel / Select.ItemDescription — its two lines.
Select.ItemIndicator — the check on the chosen row.
Select.Description / Select.Error — the help line under the field.

The root is the column, a View stacking the label, the trigger and the help line with one gap — the TextField's shape and the Autocomplete's, token for token, so a text field and a select on the same form read as one control. ref, style and R14's style props on the root dress that column; the control itself is Select.Trigger, which keeps its own ref and its own a11y props.

Select.Overlay and Select.Content render into the nearest PortalHost rather than where they are written, so they add nothing to the column. Their place in the JSX says when they exist, not where they appear.

Select.Label is the field's label, not the panel's. The heading over a run of rows is Select.GroupLabel — the two were one name until the field grew a label of its own.

Usage

Basic

<Select onValueChange={setLocale}>
  <Select.Label>Langue</Select.Label>
  <Select.Trigger>
    <Select.Value placeholder="Choisir une langue" />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Overlay />
  <Select.Content>
    <Select.Item value="fr">Français</Select.Item>
    <Select.Item value="en">English</Select.Item>
  </Select.Content>
  <Select.Description>Celle de l'interface.</Select.Description>
</Select>

A stringifiable child becomes the row's label (R3), and that same string is what the trigger shows once the row is chosen — the label is written once.

Label, hint and error

<Select isInvalid={!locale} onValueChange={setLocale}>
  <Select.Label>Langue</Select.Label>
  <Select.Trigger>
    <Select.Value placeholder="Choisir une langue" />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Overlay />
  <Select.Content>…</Select.Content>
  {locale ? (
    <Select.Description>Celle de l'interface.</Select.Description>
  ) : (
    <Select.Error>Choisissez une langue.</Select.Error>
  )}
</Select>

isInvalid paints the trigger's border, turns the label and the description danger, and mounts nothing: Select.Error renders exactly what it is given, so the condition stays where you can read it. The label and the description carry the ids the trigger points at with aria-labelledby / aria-describedby.

Composed rows

<Select.Item value="fr" label="Français">
  <View>
    <Select.ItemLabel>Français</Select.ItemLabel>
    <Select.ItemDescription>La langue par défaut</Select.ItemDescription>
  </View>
  <Select.ItemIndicator />
</Select.Item>

label is what the trigger shows. It is needed as soon as the children are not one string: an avatar and two lines of text have no single label to infer.

The labels are read off the elements, before any row mounts. That matters because the list lives in a portal that only exists while it is open — without it, a select with a defaultValue would show its placeholder until the user had opened it once. A row wrapped in a component of your own is not reachable that way, and children on Select.Value is the answer for that case.

Controlled

const [value, setValue] = useState('fr')

<Select value={value} onValueChange={setValue}>…</Select>

Open state is controllable the same way, with isOpen / onOpenChange. Which half is controlled is decided on the first render and then held — a component that changes hands mid-life produces a bug nobody can read from the call site.

Placement

<Select.Content placement="top" align="start" width="content-fit" offset={12} />

width defaults to 'trigger', because a list wider than the control it drops out of reads as a different surface. 'content-fit' hugs the longest label instead, bounded by the screen insets.

avoidCollisions is on by default: the list flips to the other side when the one it was asked for does not fit. It flips only when the other side has strictly more room, so a list two points short stays where it was put rather than jumping.

No backdrop

<Select>
  <Select.Trigger>…</Select.Trigger>
  {/* no Select.Overlay */}
  <Select.Content>…</Select.Content>
</Select>

Omit Select.Overlay and only a choice closes the list. That is the answer for a select inside a sheet that already dims its own background.

Style as props

<Select.Trigger paddingHorizontal={20} borderRadius={8} />
<Select.Content backgroundColor="#111" padding={8} />
<Select.ItemLabel fontSize={18} />

Full RN names, full RN values (R14). Every node takes them — the trigger, the panel, the overlay, each row and each of its texts.

Everything else goes through `style`

A gradient panel, a tinted shadow, a transform — style is the last word and wins over everything above it.