React Select component

Preview

<Field>
  <Field.Label>Team</Field.Label>
  <Select placeholder="Choose a team">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="design">Design</Select.Item>

Usage

Use when

Picking one value from a known list
More than 4-5 options — radios would crowd the form
Tight forms where the list should stay collapsed

Avoid when

Two or three options (use RadioGroup)
Users may type their own value (use Combobox)
Multiple selections (use a Checkbox group)
Actions rather than values (use Menu)

Implementation notes

Placeholder names the decision, e.g. "Choose a team"
Wrap in a Field: Field.Label names it, Field.Description guides, Field.Error gives the reason
Set invalid with a Field.Error; colour is never the only signal
Group related options with Select.Group
Keep option text short
Order options predictably: alphabetical, by frequency, or by category

Do not use Select for a list of actions.

Don’t

<Select>Delete</Select>

<Field>
  <Field.Label>Team</Field.Label>
  <Select options={[{ value: "design", label: "Design" }]} />
</Field>

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import Select once, then compose its parts with dot notation.

Select.Trigger
Select.Content
Select.Item
Select.Group
Select.GroupLabel

A Field label, a placeholder, three options.

<Field>
  <Field.Label>Team</Field.Label>
  <Select placeholder="Choose a team">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="design">Design</Select.Item>
      <Select.Item value="engineering">Engineering</Select.Item>
      <Select.Item value="product">Product</Select.Item>
    </Select.Content>
  </Select>
</Field>

Examples

With Groups

Headed sections separate related options.

<Select placeholder="Choose a country">
  <Select.Trigger />
  <Select.Content>
    <Select.Group>
      <Select.GroupLabel>Americas</Select.GroupLabel>
      <Select.Item value="us">United States</Select.Item>

With Label and Helper Text

A Field description explains what the choice affects.

<Field>
  <Field.Label>Timezone</Field.Label>
  <Select>
    <Select.Trigger placeholder="Select a timezone" />
    <Select.Content>
      <Select.Item value="pt">Pacific Time</Select.Item>

Error State

The danger edge, with the reason in a Field.Error beside an icon.

<Field invalid>
  <Field.Label>Team</Field.Label>
  <Select placeholder="Choose a team" invalid>
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="design">Design</Select.Item>

With Disabled Options

Unavailable options stay visible but cannot be picked.

<Select placeholder="Select a plan">
  <Select.Trigger />
  <Select.Content>
    <Select.Item value="free">Free</Select.Item>
    <Select.Item value="pro">Pro</Select.Item>
    <Select.Item value="enterprise" disabled>

Scrollable List

Caps at four rows and half-shows the fifth as a scroll hint.

<Select placeholder="Select a timezone">
  <Select.Trigger />
  <Select.Content maxVisibleItems={4}>
    <Select.Item value="utc-8">Pacific Time (UTC-8)</Select.Item>
    <Select.Item value="utc-7">Mountain Time (UTC-7)</Select.Item>
    <Select.Item value="utc-6">Central Time (UTC-6)</Select.Item>

Custom Max Visible Items

maxVisibleItems raises the cap to six rows.

<Select placeholder="Select a color">
  <Select.Trigger />
  <Select.Content maxVisibleItems={6}>
    <Select.Item value="red">Red</Select.Item>
    <Select.Item value="orange">Orange</Select.Item>
    <Select.Item value="yellow">Yellow</Select.Item>

Read Only

A dashed edge and no caret: it opens to show the choices but cannot change.

<Select readOnly defaultValue="engineering">
  <Select.Trigger aria-label="Team" />
  <Select.Content>
    <Select.Item value="design">Design</Select.Item>
    <Select.Item value="engineering">Engineering</Select.Item>
  </Select.Content>

Disabled

Dimmed and cannot be opened.

<Select disabled placeholder="Select an option">
  <Select.Trigger />
  <Select.Content>
    <Select.Item value="one">Option 1</Select.Item>
  </Select.Content>
</Select>

Options Prop

The options array replaces hand-written Select.Item children.

<Select
  placeholder="Select a team"
  options={[
    { value: "engineering", label: "Engineering" },
    { value: "design", label: "Design" },
    { value: "product", label: "Product" },

Long Localized Option

The trigger grows to fit a long label instead of clipping it.

<Field>
  <Field.Label>Workspace region</Field.Label>
  <Select placeholder="Choose a workspace region">
    <Select.Trigger />
    <Select.Content>
      <Select.Item value="eu-central">

API reference

Component props
Prop	Type	Default	Description
`autoComplete`	`string \| undefined`	Not set	Browser autofill hint for the hidden input
`children`	`React.ReactNode`	Not set	—
`Content.align`	`"center" \| "start" \| "end" \| undefinedcenterstartend`	Not set	—
`Content.children`	`React.ReactNode`	Not set	Omit to render the items the root's `options` prop describes.
`Content.maxVisibleItems`	`number \| undefined`	Not set	Maximum number of visible options before scrolling. Shows half of the next item as a scroll hint.
`Content.sideOffset`	`number \| undefined`	Not set	—
`defaultOpen`	`boolean \| undefined`	Not set	Default open state
`defaultValue`	`string \| undefined`	Not set	Default value for uncontrolled usage
`disabled`	`boolean \| undefined`	Not set	Whether the select is disabled
`form`	`string \| undefined`	Not set	ID of the form that owns the hidden input
`Group.children`Required	`React.ReactNode`	Not set	—
`GroupLabel.children`Required	`React.ReactNode`	Not set	—
`inputRef`	`React.Ref<HTMLInputElement> \| undefined`	Not set	Ref to the hidden input element
`invalid`	`boolean \| undefined`	`false`	Marks the selection invalid: the danger edge and `aria-invalid` on the trigger. Say why in a Field.Error; inside a Field, its `invalid` does the same.
`Item.children`Required	`React.ReactNode`	Not set	—
`Item.disabled`	`boolean \| undefined`	Not set	—
`Item.value`Required	`string`	Not set	—
`name`	`string \| undefined`	Not set	Form field name
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Called when open state changes
`onValueChange`	`((value: SelectValue \| null) => void) \| undefined`	Not set	Called when the selection changes
`open`	`boolean \| undefined`	Not set	Controlled open state
`options`	`SelectOption[] \| undefined`	Not set	Convenience API for simple selects (renders Select.Item entries when children are omitted)
`placeholder`	`string \| undefined`	Not set	Placeholder text when no value is selected
`readOnly`	`boolean \| undefined`	Not set	Whether the user cannot choose a different option
`required`	`boolean \| undefined`	Not set	Whether a selection is required
`size`	`SelectSize \| undefinedxssmmdlg`	`"md"`	Trigger height on the shared control track: 24, 28, 32 or 40.
`Trigger.children`	`React.ReactNode`	Not set	—
`Trigger.icon`	`React.ReactNode`	Not set	Leading adornment shown before the value — usually says what the choice is about, so the visible text can be the choice itself. Ignored when you pass your own `children`.
`Trigger.placeholder`	`string \| undefined`	Not set	—
`value`	`string \| null \| undefined`	Not set	Controlled selected value

Accessibility

Full keyboard navigation
Type-ahead jumps to matching options
Trigger and list carry the right ARIA roles

MenualternativeUse Menu for action-based dropdowns
InputsiblingUse Input for free-form text entry
CheckboxalternativeUse Checkbox group for multiple selections

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.