Listbox

The Listbox component allows users to select one or more items from a list. It can be used to build menus, select inputs, and other list-based UIs.

Installation

$ cbui-cli install @crossbuildui/listbox

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Listbox, ListboxItem, ListboxSection } from '@/crossbuildui/listbox';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // If using icons
// import { View, Text } from 'react-native'; // For content

The default selected icon in ListboxItem uses react-native-vector-icons/MaterialIcons. Ensure this library is installed and linked if you rely on the default icon or plan to use custom icons from this library.

Basic Usage

Create a listbox by nesting ListboxItem components within a Listbox container. Each item needs a unique itemKey.

index.tsx

<Listbox aria-label="Basic Listbox Example">
  <ListboxItem itemKey="item1">Item One</ListboxItem>
  <ListboxItem itemKey="item2">Item Two</ListboxItem>
  <ListboxItem itemKey="item3">Item Three</ListboxItem>
</Listbox>

With Sections

Organize items into groups using the ListboxSection component. Sections can have titles and optional dividers.

index.tsx

<Listbox aria-label="Listbox with Sections">
  <ListboxSection title="Actions" itemKey="actions-section">
    <ListboxItem itemKey="new">New file</ListboxItem>
    <ListboxItem itemKey="copy">Copy link</ListboxItem>
    <ListboxItem itemKey="edit">Edit file</ListboxItem>
  </ListboxSection>
  <ListboxSection title="Danger Zone" itemKey="danger-section" showDivider>
    <ListboxItem itemKey="delete" style={{color: 'red'}}>Delete file</ListboxItem>
  </ListboxSection>
</Listbox>

Selection Modes

Control selection behavior with selectionMode: 'single', 'multiple', or 'none'. Use defaultSelectedKeys for uncontrolled initial selection or selectedKeys for controlled selection.

index.tsx

// Single Selection (default behavior if selectionMode is not 'none')
<Listbox selectionMode="single" defaultSelectedKeys={["cat"]}>
  <ListboxItem itemKey="dog">Dog</ListboxItem>
  <ListboxItem itemKey="cat">Cat</ListboxItem>
  <ListboxItem itemKey="mouse">Mouse</ListboxItem>
</Listbox>

// Multiple Selection
<Listbox selectionMode="multiple" defaultSelectedKeys={["apple", "orange"]}>
  <ListboxItem itemKey="apple">Apple</ListboxItem>
  <ListboxItem itemKey="banana">Banana</ListboxItem>
  <ListboxItem itemKey="orange">Orange</ListboxItem>
</Listbox>

// No Selection
<Listbox selectionMode="none">
  <ListboxItem itemKey="view">View Details</ListboxItem>
  <ListboxItem itemKey="info">Information</ListboxItem>
</Listbox>

Disabled Items & Listbox

Disable specific items using the disabledKeys prop on Listbox or the isDisabled prop on ListboxItem. The entire Listbox can be disabled using its disabled prop.

index.tsx

<Listbox disabledKeys={["edit"]}>
  <ListboxItem itemKey="new">New File</ListboxItem>
  <ListboxItem itemKey="copy">Copy Link</ListboxItem>
  <ListboxItem itemKey="edit">Edit File (Disabled)</ListboxItem>
  <ListboxItem itemKey="delete" isDisabled>Delete File (Explicitly Disabled)</ListboxItem>
</Listbox>

// Entire Listbox disabled
<Listbox disabled defaultSelectedKeys={["one"]}>
 <ListboxItem itemKey="one">One</ListboxItem>
 <ListboxItem itemKey="two">Two</ListboxItem>
</Listbox>

Item Content & Structure

ListboxItem supports title, description, startContent, endContent, and custom selectedIcon. Providing children to ListboxItem will override the title.

index.tsx

<Listbox>
  <ListboxItem
    itemKey="profile"
    title="User Profile"
    description="Manage your account settings"
    startContent={<Icon name="account-circle-outline" size={24} />}
    endContent={<Icon name="chevron-right" size={20} />}
  >
    {/* Children override title, so title prop is ignored here */}
    <View><Text style={{fontWeight: 'bold'}}>Custom Profile View</Text></View>
  </ListboxItem>
  <ListboxItem
    itemKey="notifications"
    title="Notifications"
    description="Configure alerts"
    startContent={<Icon name="bell-outline" size={24} />}
    selectedIcon={<Icon name="star" size={20} color="gold" />}
  />
</Listbox>

Variants & Colors

Listbox supports solid, bordered, light, flat, faded, and shadow variants. Apply thematic colors using the color prop.

index.tsx

<View style={{flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'space-around'}}>
  <Listbox variant="solid" color="primary" defaultSelectedKeys={["s1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="s1">Solid Primary</ListboxItem>
  </Listbox>
  <Listbox variant="bordered" color="secondary" defaultSelectedKeys={["b1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="b1">Bordered Secondary</ListboxItem>
  </Listbox>
  <Listbox variant="light" color="success" defaultSelectedKeys={["l1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="l1">Light Success</ListboxItem>
  </Listbox>
  <Listbox variant="flat" color="warning" defaultSelectedKeys={["f1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="f1">Flat Warning</ListboxItem>
  </Listbox>
  <Listbox variant="faded" color="danger" defaultSelectedKeys={["fd1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="fd1">Faded Danger</ListboxItem>
  </Listbox>
  <Listbox variant="shadow" color="default" defaultSelectedKeys={["sh1"]} style={{margin:5, width: 150}}>
    <ListboxItem itemKey="sh1">Shadow Default</ListboxItem>
  </Listbox>
</View>

Dynamic Items

Render items dynamically by providing an items array and a renderItem function, or by passing a function as children.

index.tsx

const users = [
  { id: '1', name: 'Alice', avatar: 'https://i.pravatar.cc/150?u=alice' },
  { id: '2', name: 'Bob', avatar: 'https://i.pravatar.cc/150?u=bob' },
  { id: '3', name: 'Charlie', avatar: 'https://i.pravatar.cc/150?u=charlie' },
];

<Listbox
  items={users}
  renderItem={(user) => (
    <ListboxItem
      itemKey={user.id}
      title={user.name}
      startContent={<Image source={{ uri: user.avatar }} style={{ width: 30, height: 30, borderRadius: 15 }} />}
    />
  )}
  aria-label="User List"
/>

// Alternative with children as a function
<Listbox items={users} aria-label="User List Alt">
  {(user) => (
    <ListboxItem
      itemKey={user.id}
      title={user.name}
      description={`User ID: ${user.id}`}
    />
  )}
</Listbox>

Top & Bottom Content

Add custom content at the beginning or end of the list using topContent and bottomContent props.

index.tsx

<Listbox topContent={<Text style={{padding:10, fontWeight:'bold'}}>Available Options</Text>}
           bottomContent={<Text style={{padding:10, fontSize:10, textAlign:'center'}}>End of list</Text>}>
  <ListboxItem itemKey="opt1">Option 1</ListboxItem>
  <ListboxItem itemKey="opt2">Option 2</ListboxItem>
</Listbox>

Empty State

Display custom content when the list is empty using the emptyContent prop.

index.tsx

<Listbox items={[]} emptyContent={<View style={{padding:20, alignItems:'center'}}><Text>No data found.</Text></View>}>
  {(item) => <ListboxItem itemKey={item.id}>{item.name}</ListboxItem>}
</Listbox>

Props Overview

Listbox Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode \| (item) => ReactElement`	-	Static items or render function for dynamic items.
`items`	`T[]`	-	Array of data for dynamic rendering.
`renderItem`	`(item: T) => ReactElement`	-	Function to render each item from the `items` array.
`variant`	`ListboxVariant`	`'solid'`	Visual style.
`color`	`ListboxColor`	`'default'`	Thematic color.
`selectionMode`	`ListboxSelectionMode`	`'none'`	Selection behavior.
`selectedKeys`	`Iterable<string\|number>`	-	Controlled selected item keys.
`defaultSelectedKeys`	`Iterable<string\|number>`	`[]`	Initially selected keys (uncontrolled).
`disabledKeys`	`Iterable<string\|number>`	`[]`	Keys of disabled items.
`disallowEmptySelection`	`boolean`	`false`	Prevent deselection if it results in no selection.
`topContent`	`ReactNode`	-	Content displayed above the list items.
`bottomContent`	`ReactNode`	-	Content displayed below the list items.
`emptyContent`	`ReactNode`	"No items."	Content displayed when list is empty.
`hideSelectedIcon`	`boolean`	`false`	Hide selected state icon globally.
`style`	`StyleProp<ViewStyle>`	-	Style for the Listbox container.
`itemStyle`	`Partial<ListboxItemSlots>`	-	Global styles for all `ListboxItem` slots.
`onSelectionChange`	`(keys: Set<string\|number>) => void`	-	Callback when selection changes.
`disabled`	`boolean`	`false`	Disable the entire Listbox.

ListboxItem Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Custom content, overrides `title`.
`itemKey`	`string \| number`	-	Unique key for the item. Required.
`title`	`ReactNode`	-	Primary text content of the item.
`textValue`	`string`	-	Plain text representation for accessibility/typeahead.
`description`	`ReactNode`	-	Secondary text content below the title.
`startContent`	`ReactNode`	-	Content displayed before the main text.
`endContent`	`ReactNode`	-	Content displayed after the selected icon (if visible).
`selectedIcon`	`ReactNode \| (props) => ReactNode`	Default Icon	Custom icon for selected state.
`showDivider`	`boolean`	`false`	Show a divider below this item.
`hideSelectedIcon`	`boolean`	Contextual	Override Listbox/Section setting for this item.
`style`	`StyleProp<ViewStyle>`	-	Style for the item's outer `Pressable`.
`slotStyles`	`Partial<ListboxItemSlots>`	-	Styles for inner parts of the item (title, description, etc.).
`isDisabled`	`boolean`	`false`	Explicitly disable this item.

ListboxSection Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	`ListboxItem` components within this section.
`itemKey`	`string \| number`	-	Unique key for the section. Required.
`title`	`string`	-	Title displayed above the section items.
`hideSelectedIcon`	`boolean`	Contextual	Override Listbox's `hideSelectedIcon` for items in this section.
`showDivider`	`boolean`	`false`	Show a divider after the section.
`dividerProps`	`StyleProp<ViewStyle>`	-	Custom style for the section divider.
`style`	`StyleProp<ViewStyle>`	-	Style for the section container.
`itemStyle`	`Partial<ListboxItemSlots>`	-	Styles for `ListboxItem` slots within this section, overrides Listbox's `itemStyle`.

Styling

Customize appearance using:

Listbox:
- style: For the main Listbox container (View).
- itemStyle: Global styles for all ListboxItem slots (e.g., base, title, description).
ListboxSection:
- style: For the section wrapper View.
- itemStyle: Styles for ListboxItem slots within this section, overriding Listbox's itemStyle.
- dividerProps: Style for the section's bottom divider.
ListboxItem:
- style: For the item's root Pressable component.
- slotStyles: Specific styles for inner parts of this item (e.g., wrapper, title, startContentWrapper), overriding section and Listbox itemStyle.

Style precedence for item slots: ListboxItem.slotStyles > ListboxSection.itemStyle > Listbox.itemStyle.

index.tsx

<Listbox
  style={{ marginVertical: 10, borderColor: 'purple', borderWidth: 1, borderRadius: 12 }} // Styles the Listbox container
  itemStyle={{ // Global styles for all ListboxItem slots
    base: { paddingVertical: 15 },
    title: { fontWeight: '600', color: 'navy' },
    description: { fontStyle: 'italic' }
  }}
  variant="flat"
  color="primary"
>
  <ListboxSection
    title="Custom Section"
    itemKey="custom-sec"
    style={{ backgroundColor: 'rgba(200,200,255,0.3)' }}
    itemStyle={{ // Overrides Listbox's itemStyle for this section
      title: { color: 'darkgreen' }
    }}
  >
    <ListboxItem
      itemKey="styled1"
      title="Item with Specific Slot Styles"
      slotStyles={{ // Styles for slots of this specific item
        base: { borderLeftWidth: 3, borderLeftColor: 'orange' },
        wrapper: { paddingLeft: 10 },
        title: { textDecorationLine: 'underline', color: 'red' } // Overrides section and listbox itemStyle
      }}
      style={{ backgroundColor: 'lightyellow' }} // Style for the Pressable of this item
    />
    <ListboxItem itemKey="styled2" title="Section Styled Item" description="Inherits from section" />
  </ListboxSection>
  <ListboxItem itemKey="styled3" title="Listbox Styled Item" description="Inherits from listbox" />
</Listbox>

Accessibility

The Listbox components are designed with accessibility in mind:

Listbox container has accessibilityRole="list".
Each ListboxItem has accessibilityRole="menuitem" (can be adjusted if used as a general selectable list).
ListboxItem includes accessibilityState for selected and disabled states.
ListboxItem uses textValue or title for its accessibilityLabel.

Code Snippet