React Combobox component

Preview

<StatefulCombobox placeholder="Select a fruit">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Item value="apple">Apple</Combobox.Item>
    <Combobox.Item value="banana">Banana</Combobox.Item>
    <Combobox.Item value="orange">Orange</Combobox.Item>

Usage

Use when

Lists too long to scan by eye
The user roughly knows the value they want
Autocomplete or typeahead
Multi-select from a searchable list

Avoid when

Under five options (use Select or RadioGroup)
Free-form text with no known options (use Input)
Short list nobody needs to search (use Select)
Actions rather than values (use Menu)

Implementation notes

Wrap in a Field for the label, description and error
Placeholder names what is searchable
With no match the list names the query; override it with Combobox.Empty when you have better wording
Set loading while options load from a server; the list says so
Group related options with Combobox.Group in long lists
Filtering keeps wrapper composition, so groups and fragments survive
Keep option text short and searchable
multiple turns selections into removable chips

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

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

Combobox.Input
Combobox.Trigger
Combobox.Content
Combobox.Item
Combobox.ItemIndicator
Combobox.Empty
Combobox.Group
Combobox.GroupLabel

Type to narrow the list; unmatched queries show a no-results row.

<StatefulCombobox placeholder="Select a fruit">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Item value="apple">Apple</Combobox.Item>
    <Combobox.Item value="banana">Banana</Combobox.Item>
    <Combobox.Item value="orange">Orange</Combobox.Item>
    <Combobox.Item value="grape">Grape</Combobox.Item>
  </Combobox.Content>
</StatefulCombobox>

Examples

Multiple Selection

Each pick becomes a removable chip in the field.

<StatefulCombobox multiple placeholder="Select fruits…">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Item value="apple">Apple</Combobox.Item>
    <Combobox.Item value="banana">Banana</Combobox.Item>
    <Combobox.Item value="orange">Orange</Combobox.Item>

In a Field

Field gives the input its label and description.

<Field>
  <Field.Label>Assignee</Field.Label>
  <StatefulCombobox placeholder="Search assignees…">
    <Combobox.Input />
    <Combobox.Content>
      <Combobox.Item value="alice">Alice Johnson</Combobox.Item>

Invalid

The danger edge with the reason under the field.

<Field invalid>
  <Field.Label>Reviewer</Field.Label>
  <Combobox placeholder="Search reviewers…" invalid>
    <Combobox.Input />
    <Combobox.Content>
      <Combobox.Item value="alice">Alice</Combobox.Item>

With Groups

Headed sections stay intact while filtering.

<StatefulCombobox placeholder="Search countries…">
  <Combobox.Input />
  <Combobox.Content>
    <>
      <Combobox.Group>
        <Combobox.GroupLabel>North America</Combobox.GroupLabel>

With Empty State

Combobox.Empty replaces the default no-results wording.

<StatefulCombobox placeholder="Filter languages…">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Empty>No language matches that search</Combobox.Empty>
    <Combobox.Item value="js">JavaScript</Combobox.Item>
    <Combobox.Item value="ts">TypeScript</Combobox.Item>

Loading

While options load, the list says Searching… instead of no match.

const repositories = ["fragments/web", "fragments/api", "fragments/docs"];

<Combobox loading placeholder="Search repositories…" defaultOpen>
  <Combobox.Input aria-label="Repository" />
  <Combobox.Content>
    {repositories.map((repo) => (

Scrollable List

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

<StatefulCombobox placeholder="Search languages…">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Empty>No results found</Combobox.Empty>
    <Combobox.Item value="js">JavaScript</Combobox.Item>
    <Combobox.Item value="ts">TypeScript</Combobox.Item>

Custom Max Visible Items

maxVisibleItems raises the cap to six rows.

<StatefulCombobox placeholder="Search cities…">
  <Combobox.Input />
  <Combobox.Content maxVisibleItems={6}>
    <Combobox.Empty>No results found</Combobox.Empty>
    <Combobox.Item value="nyc">New York</Combobox.Item>
    <Combobox.Item value="lon">London</Combobox.Item>

Disabled

Dimmed and unfocusable.

<Combobox disabled placeholder="Search…">
  <Combobox.Input />
  <Combobox.Content>
    <Combobox.Item value="1">Option 1</Combobox.Item>
  </Combobox.Content>
</Combobox>

Explicit Trigger

showTrigger={false} hands the open control to your own Combobox.Trigger.

<StatefulCombobox placeholder="Search assignees…">
  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
    <Combobox.Input showTrigger={false} />
    <Combobox.Trigger aria-label="Open assignee list" />
  </div>
  <Combobox.Content>

API reference

Component props
Prop	Type	Default	Description
`autoComplete`	`string \| undefined`	Not set	—
`autoHighlight`	`boolean \| undefined`	`true`	Auto-highlight first matching item while filtering
`children`Required	`React.ReactNode`	Not set	Combobox input and content
`Content.align`	`"center" \| "start" \| "end" \| undefinedcenterstartend`	Not set	—
`Content.children`Required	`React.ReactNode`	Not set	—
`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`	`false`	Initial open state for uncontrolled usage
`defaultValue`	`string \| string[] \| undefined`	Not set	Default selected value (uncontrolled)
`disabled`	`boolean \| undefined`	`false`	Disable the combobox
`Empty.children`Required	`React.ReactNode`	Not set	—
`form`	`string \| undefined`	Not set	—
`Group.children`Required	`React.ReactNode`	Not set	—
`GroupLabel.children`Required	`React.ReactNode`	Not set	—
`Input.className`	`string \| undefined`	Not set	—
`Input.showTrigger`	`boolean \| undefined`	Not set	Render the built-in chevron trigger beside the input. Automatically disabled when an explicit <Combobox.Trigger /> is mounted.
`inputRef`	`React.Ref<HTMLInputElement> \| undefined`	Not set	—
`invalid`	`boolean \| undefined`	`false`	The danger edge and aria-invalid; say why in a Field.Error
`Item.children`Required	`React.ReactNode`	Not set	—
`Item.disabled`	`boolean \| undefined`	Not set	—
`Item.value`Required	`string`	Not set	—
`loading`	`boolean \| undefined`	`false`	Options are on their way: the list says Searching… and is aria-busy
`multiple`	`boolean \| undefined`	`false`	Allow multiple selections with chips
`name`	`string \| undefined`	Not set	Form field name
`onInputValueChange`	`((query: string) => void) \| undefined`	Not set	Called with the typed query as it changes
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Called when dropdown open state changes
`onValueChange`	`((value: string \| null) => void) \| ((value: string[]) => void) \| undefined`	Not set	Called when selection changes
`open`	`boolean \| undefined`	Not set	Controlled open state of the dropdown
`placeholder`	`string \| undefined`	Not set	Placeholder text for the input
`readOnly`	`boolean \| undefined`	`false`	Shows the value on a dashed edge without letting it change
`required`	`boolean \| undefined`	Not set	Marks the field required for form validation
`size`	`ComboboxSize \| undefinedxssmmdlg`	`"md"`	Field height on the shared control track: 24, 28, 32 or 40
`Trigger.children`	`React.ReactNode`	Not set	—
`Trigger.className`	`string \| undefined`	Not set	—
`value`	`string \| string[] \| null \| undefined`	Not set	Controlled selected value (string for single, string[] for multiple)

Accessibility

Arrow keys, Enter, and Escape all work
Typing filters the list in place
Options sit inside a listbox; Field.Label names the input
The empty and loading rows are polite status messages
The open button is named Show options and every chip remove button names its chip

Standards references

SelectalternativeUse Select when search/filtering is not needed
InputsiblingUse Input for free-form text entry
ListboxsiblingUse Listbox for inline option lists

Next steps

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