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>
);
}
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

KeyDescription
HomeMoves focus to the first item.
EndMoves focus to the last item.
ArrowDownWhen focus is on an item, moves focus to the next item.
ArrowUpWhen focus is on an item, moves focus to the previous item.
Enter or SpaceWhen focus is on an item, selects the item.
A-Z or a-zMoves focus to the next menu item with a label that starts with the typed character if such an menu item exists.

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

AttributeTypeDescriptionDefault
children*ReactNode[]The children to render. Usually a list of ListboxItem or ListboxSection-
itemsIterable<T>Item objects in the collection. (dynamic)-
variantsolid | bordered | light | flat | faded | shadowThe listbox items appearance style.solid
colordefault | primary | secondary | success | warning | dangerThe listbox items color theme.default
selectionModenone | single | multipleThe type of selection that is allowed in the collection.-
selectedKeysReact.Key[]The currently selected keys in the collection (controlled).-
disabledKeysReact.Key[]The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.-
defaultSelectedKeysall | React.Key[]The initial selected keys in the collection (uncontrolled).-
disallowEmptySelectionbooleanWhether the collection allows empty selection.false
shouldHighlightOnFocusbooleanWhether the focused item should be highlighted. It applies the same styles to the items as when hovered.false
autoFocusboolean | first | lastWhere the focus should be set.false
topContentReactNodeThe content to display above the listbox items.-
bottomContentReactNodeThe content to display below the listbox items.-
emptyContentReactNodeThe content to display when the collection is empty.No items.
shouldFocusWrapbooleanWhether keyboard navigation is circular.false
hideEmptyContentbooleanWhether to not display the empty content when the collection is empty.false
hideSelectedIconbooleanWhether to hide the check icon when the items are selected.false
disableAnimationbooleanWhether to disable the animation of the listbox items.false
classNamesRecord<"base"| "list"| "emptyContent", string>Allows to set custom class names for the listbox slots.-
itemClassesRecord<"base"| "wrapper"| "title"| "description"| "selectedIcon", string>Allows to set custom class names for the listbox item slots.-

Listbox Events

AttributeTypeDescription
onAction(key: React.Key) => voidHandler that is called when an item is selected.
onSelectionChange(keys: React.Key[]) => voidHandler that is called when the selection changes.

ListboxSection Props

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the listbox section. Usually a list of ListboxItem components. (static)-
titlestringThe title of the listbox section.-
itemsIterable<T>Item objects in the collection. (dynamic)-
hideSelectedIconbooleanWhether to hide the check icon when the items are selected.false
showDividerbooleanWhether to show the divider between the groups.false
dividerPropsDividerPropsThe divider component props.-
classNamesRecord<"base"| "heading"| "group"| "divider", string>Allows to set custom class names for the listbox section slots.-
itemClassesRecord<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string>Allows to set custom class names for the listbox item slots.-

ListboxItem Props

AttributeTypeDescriptionDefault
children*ReactNodeThe contents of the listbox item.-
keyReact.KeyThe unique key for the listbox item.-
titlestring | ReactNodeThe title of the listbox item.-
textValuestringA string representation of the item's contents, used for features like typeahead.-
descriptionstring | ReactNodeThe description of the listbox item.-
shortcutstring | ReactNodeThe listbox item keyboard shortcut.-
startContentReactNodeThe start content of the listbox item.-
endContentReactNodeThe end content of the listbox item. This is positioned after the shortcut and the selected icon.-
selectedIconSelectedIconPropsCustom icon to render when the item is selected.-
hrefstringA URL to link to. See MDN.-
targetHTMLAttributeAnchorTargetThe target window for the link. See MDN.-
relstringThe relationship between the linked resource and the current page. See MDN.-
downloadboolean | stringCauses the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.-
pingstringA space-separated list of URLs to ping when the link is followed. See MDN.-
referrerPolicyHTMLAttributeReferrerPolicyHow much of the referrer to send when following the link. See MDN.-
shouldHighlightOnFocusbooleanWhether the focused item should be highlighted. It applies the same styles to the item as when hovered.false
hideSelectedIconbooleanWhether to hide the check icon when the item is selected.false
showDividerbooleanWhether to show a divider below the item.false
isDisabledbooleanWhether the listbox item should be disabled. (Deprecated) pass disabledKeys to Listbox instead.false
isSelectedbooleanWhether the listbox item should be selected. (Deprecated) pass selectedKeys to Listbox instead.false
isReadOnlybooleanWhether the listbox item press events should be ignored.false
classNamesRecord<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string>Allows to set custom class names for the listbox item slots.-

ListboxItem Events

AttributeTypeDescription
onAction() => voidHandler that is called when the listbox item is selected. (Deprecated) pass to Listbox instead.
onPress(e: PressEvent) => voidHandler called when the press is released over the target.
onPressStart(e: PressEvent) => voidHandler called when a press interaction starts.
onPressEnd(e: PressEvent) => voidHandler called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange(isPressed: boolean) => voidHandler called when the press state changes.
onPressUp(e: PressEvent) => voidHandler called when a press is released over the target, regardless of whether it started on the target or not.
onKeyDown(e: KeyboardEvent) => voidHandler called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler called when a key is released.
onClickMouseEventHandlerThe native button click event handler (Deprecated) use onPress instead.

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;
};
/**
* 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;