Skip to main content

Listbox

Shows a keyboard-navigable list of options with no trigger of its own.

import { Listbox } from "@/fragments/ui";Source

Preview

<Listbox aria-label="Options">
  <Listbox.Item selected>First option</Listbox.Item>
  <Listbox.Item>Second option</Listbox.Item>
  <Listbox.Item>Third option</Listbox.Item>
</Listbox>

Installation

npx @usefragments/cli add listbox

Writes src/fragments/ui/components/Listbox plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Listbox is a compound: import the root and reach its parts through dot notation.

  • Listbox.Item
  • Listbox.Group
  • Listbox.Empty

Plain options, one selectable at a time.

<Listbox aria-label="Options">
  <Listbox.Item selected>First option</Listbox.Item>
  <Listbox.Item>Second option</Listbox.Item>
  <Listbox.Item>Third option</Listbox.Item>
</Listbox>

Examples

Search Results

Trailing metadata explains each match.

<Listbox aria-label="Search results">
  <Listbox.Item selected>
    <span style={{ fontWeight: 500 }}>Button</span>
    <span style={{ marginLeft: 'auto', fontSize: '0.75rem', color: 'var(--fui-text-tertiary)' }}>Components</span>
  </Listbox.Item>
  <Listbox.Item>

With Groups

Labels split the list by source.

<Listbox aria-label="Commands">
  <Listbox.Group label="Recent">
    <Listbox.Item selected>Open file...</Listbox.Item>
    <Listbox.Item>Save as...</Listbox.Item>
  </Listbox.Group>
  <Listbox.Group label="Actions">

Empty State

Says so when nothing matches.

<Listbox aria-label="Search results">
  <Listbox.Empty>No results found</Listbox.Empty>
</Listbox>

With Disabled Items

Unavailable rows stay visible but inert.

<Listbox aria-label="Options">
  <Listbox.Item>Available option</Listbox.Item>
  <Listbox.Item disabled>Disabled option</Listbox.Item>
  <Listbox.Item>Another option</Listbox.Item>
</Listbox>

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setListbox.Item, Listbox.Group, or Listbox.Empty components
styleobjectNot set—
tabIndexnumberNot set—
onFocusfunctionNot set—
onKeyDownfunctionNot set—

Accessibility

  • Uses listbox and option ARIA roles
  • aria-selected indicates current selection
  • aria-disabled for non-interactive items
  • Connect to input with aria-controls for full combobox pattern

Guidance

Use when

  • Results under a search field
  • Autocomplete suggestions
  • Command palette results
  • Any list the user drives with arrow keys

Avoid when

  • A list nobody selects from (use List)
  • Actions behind a button (use Menu)
  • A form field (use Select)
  • Navigation (use Sidebar or Tabs)

Related

  • InputsiblingPair with Input for search/autocomplete patterns
  • MenualternativeUse Menu when you need a trigger button
  • SelectalternativeUse Select for form field selection
  • ListalternativeUse List for static, non-interactive lists

Next steps