Listbox
A listbox displays a list of options and allows a user to select one or more of them.
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 asfalse
.
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 anaria-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 thelist
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
anddescription
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
istrue
.
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
Key | Description |
---|---|
Home | Moves focus to the first item. |
End | Moves focus to the last item. |
ArrowDown | When focus is on an item, moves focus to the next item. |
ArrowUp | When focus is on an item, moves focus to the previous item. |
Enter or Space | When focus is on an item, selects the item. |
A-Z or a-z | Moves 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
Attribute | Type | Description | Default |
---|---|---|---|
children* | ReactNode[] | The children to render. Usually a list of ListboxItem or ListboxSection | - |
items | Iterable<T> | Item objects in the collection. (dynamic) | - |
variant | solid | bordered | light | flat | faded | shadow | The listbox items appearance style. | solid |
color | default | primary | secondary | success | warning | danger | The listbox items color theme. | default |
selectionMode | none | single | multiple | The type of selection that is allowed in the collection. | - |
selectedKeys | React.Key[] | The currently selected keys in the collection (controlled). | - |
disabledKeys | React.Key[] | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. | - |
defaultSelectedKeys | all | React.Key[] | The initial selected keys in the collection (uncontrolled). | - |
disallowEmptySelection | boolean | Whether the collection allows empty selection. | false |
shouldHighlightOnFocus | boolean | Whether the focused item should be highlighted. It applies the same styles to the items as when hovered. | false |
autoFocus | boolean | first | last | Where the focus should be set. | false |
topContent | ReactNode | The content to display above the listbox items. | - |
bottomContent | ReactNode | The content to display below the listbox items. | - |
emptyContent | ReactNode | The content to display when the collection is empty. | No items. |
shouldFocusWrap | boolean | Whether keyboard navigation is circular. | false |
hideEmptyContent | boolean | Whether to not display the empty content when the collection is empty. | false |
hideSelectedIcon | boolean | Whether to hide the check icon when the items are selected. | false |
disableAnimation | boolean | Whether to disable the animation of the listbox items. | false |
classNames | Record<"base"| "list"| "emptyContent", string> | Allows to set custom class names for the listbox slots. | - |
itemClasses | Record<"base"| "wrapper"| "title"| "description"| "selectedIcon", string> | Allows to set custom class names for the listbox item slots. | - |
Listbox Events
Attribute | Type | Description |
---|---|---|
onAction | (key: React.Key) => void | Handler that is called when an item is selected. |
onSelectionChange | (keys: React.Key[]) => void | Handler that is called when the selection changes. |
ListboxSection Props
Attribute | Type | Description | Default |
---|---|---|---|
children* | ReactNode | The contents of the listbox section. Usually a list of ListboxItem components. (static) | - |
title | string | The title of the listbox section. | - |
items | Iterable<T> | Item objects in the collection. (dynamic) | - |
showDivider | boolean | Whether to show the divider between the groups. | false |
DividerProps | DividerProps | The divider component props. | - |
classNames | Record<"base"| "heading"| "group"| "divider", string> | Allows to set custom class names for the listbox section slots. | - |
itemClasses | Record<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string> | Allows to set custom class names for the listbox item slots. | - |
ListboxItem Props
Attribute | Type | Description | Default |
---|---|---|---|
children* | ReactNode | The contents of the listbox item. | - |
key | React.Key | The unique key for the listbox item. | - |
title | string | ReactNode | The title of the listbox item. | - |
textValue | string | A string representation of the item's contents, used for features like typeahead. | - |
description | string | ReactNode | The description of the listbox item. | - |
shortcut | string | ReactNode | The listbox item keyboard shortcut. | - |
startContent | ReactNode | The start content of the listbox item. | - |
endContent | ReactNode | The end content of the listbox item. This is positioned after the shortcut and the selected icon. | - |
selectedIcon | SelectedIconProps | Custom icon to render when the item is selected. | - |
href | string | A URL to link to. See MDN. | - |
target | HTMLAttributeAnchorTarget | The target window for the link. See MDN. | - |
rel | string | The relationship between the linked resource and the current page. See MDN. | - |
download | boolean | string | Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN. | - |
ping | string | A space-separated list of URLs to ping when the link is followed. See MDN. | - |
referrerPolicy | HTMLAttributeReferrerPolicy | How much of the referrer to send when following the link. See MDN. | - |
shouldHighlightOnFocus | boolean | Whether the focused item should be highlighted. It applies the same styles to the item as when hovered. | false |
hideSelectedIcon | boolean | Whether to hide the check icon when the item is selected. | false |
showDivider | boolean | Whether to show a divider below the item. | false |
isDisabled | boolean | Whether the listbox item should be disabled. (Deprecated) pass disabledKeys to Listbox instead. | false |
isSelected | boolean | Whether the listbox item should be selected. (Deprecated) pass selectedKeys to Listbox instead. | false |
isReadOnly | boolean | Whether the listbox item press events should be ignored. | false |
classNames | Record<"base"| "wrapper"| "title"| "description"| "shortcut" | "selectedIcon", string> | Allows to set custom class names for the listbox item slots. | - |
ListboxItem Events
Attribute | Type | Description |
---|---|---|
onAction | () => void | Handler that is called when the listbox item is selected. (Deprecated) pass to Listbox instead. |
onPress | (e: PressEvent) => void | Handler called when the press is released over the target. |
onPressStart | (e: PressEvent) => void | Handler called when a press interaction starts. |
onPressEnd | (e: PressEvent) => void | Handler called when a press interaction ends, either over the target or when the pointer leaves the target. |
onPressChange | (isPressed: boolean) => void | Handler called when the press state changes. |
onPressUp | (e: PressEvent) => void | Handler called when a press is released over the target, regardless of whether it started on the target or not. |
onKeyDown | (e: KeyboardEvent) => void | Handler called when a key is pressed. |
onKeyUp | (e: KeyboardEvent) => void | Handler called when a key is released. |
onClick | MouseEventHandler | The 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;};type selectedIcon?: ReactNode | ((props: ListboxItemSelectedIconProps) => ReactNode) | null;