Listbox

A listbox displays a list of options and allows a user to select one or more of them.

Installation

npx nextui-cli@latest add listbox

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

NextUI exports 3 listbox-related components:

• Listbox: The main component, which is a wrapper for the other components.
• ListboxSection: The component that contains a group of listbox items.
• ListboxItem: The component that represents a listbox item.

Usage

Dynamic items

Listbox follows the Collection Components API, accepting both static and dynamic collections.

• Static: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
• Dynamic: The example below can be used when the options come from an external data source such as an API call, or update over time.

Disabled Keys

Listbox items can be disabled using the disabledKeys prop to the Listbox component.

Note: It's important to have a unique key for each item, otherwise the disabled keys will not work.

Variants

You can use the variant in the Listbox component to change the hover style of the listbox items.

Single Selection

You can set the selectionMode property as single to allow the user to select only one item at a time.

Multiple Selection

You can set the selectionMode property as multiple to allow the user to select multiple items at a time.

Note: To allow empty selection, you can set the disallowEmptySelection property as false.

With Icons

It is possible to add icons to the listbox items using the startContent / endContent props.

Note: If you use currentColor as the icon color, the icon will have the same color as the item text.

With Description

You can use the description prop to add a description to the listbox item.

With Top & Bottom Content

You can use the topContent and bottomContent props to add content above and below the listbox items.

With Sections

You can use the ListboxSection component to group listbox items.

Note: Sections without a title must provide an aria-label for accessibility.

Routing

The <ListboxItem> component works with frameworks and client side routers like Next.js and React Router. See the Routing guide to learn how to set this up.

import {Listbox, ListboxItem} from "@nextui-org/react";

function App() {
  return (
    <Listbox>
      <ListboxItem key="home" href="/home">
        Home
      </ListboxItem>
      <ListboxItem key="about" href="/about">
        About
      </ListboxItem>
    </Listbox>
  );
}

Slots

Listbox has 3 components with slots the base one Listbox, ListboxItem and ListboxSection components.

Listbox

• base: The main wrapper for the listbox component. This slot wraps the topContent, bottomContent and the list slot.
• list: The slot for the listbox component. You can see this slot as the ul slot.
• emptyContent: The slot content to display when the collection is empty.

ListboxItem

• base: The main slot for the listbox item. It wraps all the other slots.
• wrapper: The title and description wrapper.
• title: The title of the listbox item.
• description: The description of the listbox item.
• selectedIcon: The selected icon slot. This is only visible when the item is selected.

ListboxSection

• base: The main slot for the listbox section. It wraps all the other slots.
• heading: The title that is render on top of the section group.
• group: The group of listbox items.
• divider: The divider that is render between the groups. This is only visible when showDivider is true.

Customizing the listbox

You can customize the Listbox items style by using the itemClasses prop and passing custom Tailwind CSS classes.

Note: In the above example, we've utilized the Boxicons icons collection.

Keyboard Interactions

Data Attributes

ListboxItem has the following attributes on the base element:

• data-disabled: When the listbox item is disabled. Based on listbox disabledKeys prop.
• data-selected: When the listbox item is selected. Based on listbox selectedKeys prop.
• data-selectable: When the listbox item is selectable. Based on listbox selectionMode prop.
• data-hover: When the listbox item is being hovered. Based on useHover
• data-pressed: When the listbox item is pressed. Based on usePress
• data-focus: When the listbox item is being focused. Based on useFocusRing.
• data-focus-visible: When the listbox item is being focused with the keyboard. Based on useFocusRing.

Accessibility

• Exposed to assistive technology as a listbox using ARIA.
• Support for single, multiple, or no selection.
• Support for disabled items.
• Support for sections.
• Labeling support for accessibility.
• Support for mouse, touch, and keyboard interactions.
• Tab stop focus management.
• Keyboard navigation support including arrow keys, home/end, page up/down, select all, and clear.
• Automatic scrolling support during keyboard navigation.
• Typeahead to allow focusing options by typing text.

API

Listbox Props

Listbox Events

ListboxSection Props

ListboxItem Props

ListboxItem Events

Types

Listbox Item Selected Icon Props

export type ListboxItemSelectedIconProps = {
  /**
   * The current icon, usually an checkmark icon.
   */
  icon?: ReactNode;
  /**
   * The current selected status.
   */
  isSelected?: boolean;
  /**
   * The current disabled status.
   * @default false
   */
  isDisabled?: boolean;
};

type selectedIcon?: ReactNode | ((props: ListboxItemSelectedIconProps) => ReactNode) | null;