ListBox

Standalone, always-visible selectable list (single/multiple, sections, keyboard type-ahead).

Import

import { ListBox, ListBoxItem, ListBoxSection } from '@marbleui/ui'

Props

<ListBox>

Prop	Type	Default	Description
variant	`'card' \| 'plain'`	`'card'`

Also accepts React Aria props (102).

<ListBoxItem>

Prop	Type	Default	Description
description	`ReactNode`	`—`
icon	`ReactNode`	`—`

Also accepts React Aria props (101).

<ListBoxSection>

Prop	Type	Default	Description
title	`ReactNode`	`—`

Also accepts React Aria props (79).

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitives: React Aria Collection · React Aria Header · React Aria ListBox · React Aria ListBoxItem · React Aria ListBoxSection · React Aria Text. Follow the primitive's docs for the full keyboard map.

Usage notes

Always-visible selectable list with single or multiple selection. For a dropdown use Select; for rows with actions or nested buttons use ListView; for a hierarchy use Tree.

<ListBox aria-label="Plan" selectionMode="single" defaultSelectedKeys={['pro']}>
  <ListBoxItem id="free" description="For individuals">Free</ListBoxItem>
  <ListBoxItem id="pro" description="For small teams">Pro</ListBoxItem>
</ListBox>

Selection is uncontrolled via defaultSelectedKeys, or controlled with selectedKeys and onSelectionChange. Keys are item ids; the key sets are a Set.
Always give aria-label (or a labelled-by) since there is no visible label. Arrow keys and type-ahead move focus.
Group with ListBoxSection (title). Items take description and icon; use textValue when children aren’t a string.
variant is card (default) or plain. Wrap in VirtualList for very long lists.

Example source · show

import { ListBox, ListBoxItem, ListBoxSection } from './listbox'

export const styles = {
  Single: () => (
    <ListBox aria-label="Plan" selectionMode="single" defaultSelectedKeys={['pro']} className="w-72">
      <ListBoxItem id="free" description="For individuals">Free</ListBoxItem>
      <ListBoxItem id="pro" description="For small teams">Pro</ListBoxItem>
      <ListBoxItem id="enterprise" description="SSO, audit logs, SLA">Enterprise</ListBoxItem>
    </ListBox>
  ),
  Sections: () => (
    <ListBox aria-label="Notifications" selectionMode="multiple" defaultSelectedKeys={['mentions', 'email']} className="w-64">
      <ListBoxSection title="Events">
        <ListBoxItem id="mentions">Mentions</ListBoxItem>
        <ListBoxItem id="assigned">Assigned to me</ListBoxItem>
        <ListBoxItem id="status">Status changes</ListBoxItem>
      </ListBoxSection>
      <ListBoxSection title="Channels">
        <ListBoxItem id="email">Email</ListBoxItem>
        <ListBoxItem id="slack">Slack</ListBoxItem>
      </ListBoxSection>
    </ListBox>
  ),
}

Source: packages/ui/src/listbox/listbox.tsx

Catalog

Category: collections
Priority: Core
Primitive: react-aria
React Aria: ListBox