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 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, ListboxContext, useListboxContext } 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. The glass variant for Listbox uses expo-blur. Ensure these libraries are installed and linked if you rely on these features.

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, shadow, and glass variants. Apply thematic colors using the color prop.

index.tsx

<View style={{flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'space-around', gap: 10}}>
  <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>
  <Listbox variant="glass" color="primary" defaultSelectedKeys={["g1"]} style={{margin:5, width: 150}} glassIntensity={70} glassTint="light">
    <ListboxItem itemKey="g1">Glass Primary</ListboxItem>
  </Listbox>
</View>

Glass Variant

The glass variant applies a frosted glass effect to the Listbox container background using expo-blur. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). Item text colors adapt for better contrast on the blurred background, but you might need to adjust them manually for certain tints using slotStyles on ListboxItem or itemStyle on Listbox/ListboxSection.

index.tsx

<View style={{gap: 16}}>
  <Listbox variant="glass" glassIntensity={80} glassTint="light" style={{paddingVertical: 8}} aria-label="Light Glass Listbox">
    <ListboxItem itemKey="profile" title="Profile" description="View your profile" />
    <ListboxItem itemKey="settings" title="Settings" description="Configure application settings" />
  </Listbox>

  <Listbox variant="glass" glassIntensity={50} glassTint="dark" style={{paddingVertical: 8, marginTop: 10}} aria-label="Dark Glass Listbox">
    {/* Item text colors might need manual adjustment for dark glass if default doesn't contrast well */}
    <ListboxItem itemKey="dashboard" title="Dashboard" slotStyles={{title: {color: 'white'}, description: {color: 'lightgray'}}} description="Analytics overview" />
    <ListboxItem itemKey="logout" title="Logout" color="danger" slotStyles={{title: {color: 'pink'}}} />
  </Listbox>
</View>
/*
  Note: For the 'glass' variant, the Listbox container itself gets the blur effect.
  ListboxItems within it typically have transparent backgrounds to show the blur.
*/

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>

Using Listbox Context

For advanced customization or to build components that react to the Listbox state, you can use the useListboxContext hook. This hook provides access to properties like selectionMode, selectedKeys, variant, color, disabledKeys, and more.

Any component that calls useListboxContext must be a descendant of a Listbox component. This is useful for custom topContent, bottomContent, or deeply integrated custom items.

MyCustomListboxComponent.tsx

import { Listbox, ListboxItem, useListboxContext } from '@/crossbuildui/listbox';
import { Text, View } from 'react-native';

const ListboxInfoDisplay = () => {
  const context = useListboxContext();

  if (!context) {
    return <Text>This component must be used within a Listbox.</Text>;
  }

  const { selectionMode, selectedKeys, variant, color, disabledKeys } = context;

  return (
    <View style={{ padding: 8, backgroundColor: '#f0f0f0', borderTopWidth: 1, borderColor: '#ccc' }}>
      <Text>Listbox Context Info:</Text>
      <Text>- Selection Mode: {selectionMode}</Text>
      <Text>- Variant: {variant}, Color: {color}</Text>
      <Text>- Selected: {Array.from(selectedKeys).join(', ') || 'None'}</Text>
      <Text>- Disabled Keys: {Array.from(disabledKeys).join(', ') || 'None'}</Text>
    </View>
  );
};

// <Listbox selectionMode="multiple" variant="flat" color="primary" topContent={<ListboxInfoDisplay />}><ListboxItem itemKey="1">Item 1</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.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the 'glass' variant blur effect.
`glassIntensity`	`number`	50	Intensity (0-100) for the 'glass' variant blur effect.

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).
- For the glass variant, glassTint and glassIntensity control the blur. The Listbox container background becomes transparent, and a BlurView is rendered underneath.
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