ListBox

Import

import { ListBox } from '@heroui/react';

Usage

import {Avatar, Description, Label, ListBox} from "@heroui/react";

export function Default() {
  return (
    <ListBox aria-label="Users" className="w-[220px]" selectionMode="single">

Anatomy

Import the ListBox component and access all parts using dot notation.

import { ListBox, Label, Description, Header } from '@heroui/react';

export default () => (
  <ListBox>
    <ListBox.Item>
      <Label />
      <Description />
      <ListBox.ItemIndicator />
    </ListBox.Item>
    <ListBox.Section>
      <Header />
      <ListBox.Item>
        <Label />
      </ListBox.Item>
    </ListBox.Section>
  </ListBox>
)

With Sections

"use client";

import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";

Multi Select

import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";

export function MultiSelect() {
  return (
    <Surface className="w-[256px] rounded-3xl shadow-surface">

With Disabled Items

"use client";

import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";

Custom Check Icon

"use client";

import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";

Controlled

Selected: 1

"use client";

import type {Selection} from "@heroui/react";

import {Check} from "@gravity-ui/icons";

Related Components

Select

ComboBox

Avatar

Styling

Passing Tailwind CSS classes

import { ListBox } from '@heroui/react';

function CustomListBox() {
  return (
    <ListBox className="border rounded-lg p-2 bg-surface">
      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
        Item 1
      </ListBox.Item>
    </ListBox>
  );
}

Customizing the component classes

To customize the ListBox component classes, you can use the @layer components directive.
Learn more.

@layer components {
  .listbox {
    @apply rounded-lg border border-border bg-surface p-2;
  }

  .listbox-item {
    @apply rounded px-2 py-1 cursor-pointer;
  }

  .listbox-item--danger {
    @apply text-danger;
  }

  .listbox-item__indicator {
    @apply text-accent;
  }
}

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The ListBox component uses these CSS classes (View source styles):

Base Classes

.listbox - Base listbox container
.listbox-item - Individual listbox item
.listbox-item__indicator - Selection indicator icon
.listbox-section - Section container for grouping items

Variant Classes

.listbox--default - Default variant styling
.listbox--danger - Danger variant styling
.listbox-item--default - Default item variant
.listbox-item--danger - Danger item variant

State Classes

.listbox-item[data-selected="true"] - Selected item state
.listbox-item[data-focus-visible="true"] - Focused item state
.listbox-item[data-disabled="true"] - Disabled item state
.listbox-item__indicator[data-visible="true"] - Visible indicator state

Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

Hover: :hover or [data-hovered="true"] on item
Focus: :focus-visible or [data-focus-visible="true"] on item
Selected: [data-selected="true"] on item
Disabled: :disabled or [data-disabled="true"] on item

API Reference

ListBox Props

Prop	Type	Default	Description
`aria-label`	`string`	-	Accessibility label for the listbox
`aria-labelledby`	`string`	-	ID of element that labels the listbox
`selectionMode`	`"none" \| "single" \| "multiple"`	`"single"`	Selection behavior
`selectedKeys`	`Selection`	-	Controlled selected keys
`defaultSelectedKeys`	`Selection`	-	Initial selected keys
`onSelectionChange`	`(keys: Selection) => void`	-	Handler called when selection changes
`disabledKeys`	`Iterable<Key>`	-	Keys of disabled items
`onAction`	`(key: Key) => void`	-	Handler called when an item is activated
`variant`	`"default" \| "danger"`	`"default"`	Visual variant
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	ListBox items and sections

ListBox.Item Props

Prop	Type	Default	Description
`id`	`Key`	-	Unique identifier for the item
`textValue`	`string`	-	Text value for accessibility and typeahead
`isDisabled`	`boolean`	`false`	Whether this item is disabled
`variant`	`"default" \| "danger"`	`"default"`	Visual variant
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode \| RenderFunction`	-	Item content or render function

ListBox.ItemIndicator Props

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode \| RenderFunction`	-	Custom indicator content or render function

ListBox.Section Props

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes
`children`	`ReactNode`	-	Section content including Header and Items

RenderProps

When using render functions with ListBox.Item or ListBox.ItemIndicator, these values are provided:

Prop	Type	Description
`isSelected`	`boolean`	Whether the item is selected
`isFocused`	`boolean`	Whether the item is focused
`isDisabled`	`boolean`	Whether the item is disabled
`isPressed`	`boolean`	Whether the item is being pressed

Examples

Basic Usage

import { ListBox, Label, Description } from '@heroui/react';

<ListBox aria-label="Users" selectionMode="single">
  <ListBox.Item id="1" textValue="Bob">
    <Label>Bob</Label>
    <Description>bob@heroui.com</Description>
  </ListBox.Item>
  <ListBox.Item id="2" textValue="Alice">
    <Label>Alice</Label>
    <Description>alice@heroui.com</Description>
  </ListBox.Item>
</ListBox>

With Sections

import { ListBox, Header, Separator } from '@heroui/react';

<ListBox aria-label="Actions" selectionMode="none" onAction={(key) => console.log(key)}>
  <ListBox.Section>
    <Header>Actions</Header>
    <ListBox.Item id="new" textValue="New file">New file</ListBox.Item>
    <ListBox.Item id="edit" textValue="Edit file">Edit file</ListBox.Item>
  </ListBox.Section>
  <Separator />
  <ListBox.Section>
    <Header>Danger zone</Header>
    <ListBox.Item id="delete" textValue="Delete" variant="danger">Delete</ListBox.Item>
  </ListBox.Section>
</ListBox>

Controlled Selection

import { ListBox, Selection } from '@heroui/react';
import { useState } from 'react';

function ControlledListBox() {
  const [selected, setSelected] = useState<Selection>(new Set(["1"]));

  return (
    <ListBox
      aria-label="Options"
      selectedKeys={selected}
      selectionMode="multiple"
      onSelectionChange={setSelected}
    >
      <ListBox.Item id="1" textValue="Option 1">Option 1</ListBox.Item>
      <ListBox.Item id="2" textValue="Option 2">Option 2</ListBox.Item>
      <ListBox.Item id="3" textValue="Option 3">Option 3</ListBox.Item>
    </ListBox>
  );
}

Custom Indicator

import { ListBox, ListBoxItemIndicator } from '@heroui/react';
import { Icon } from '@iconify/react';

<ListBox aria-label="Options" selectionMode="multiple">
  <ListBox.Item id="1" textValue="Option 1">
    Option 1
    <ListBox.ItemIndicator>
      {({isSelected}) =>
        isSelected ? <Icon icon="gravity-ui:check" /> : null
      }
    </ListBox.ItemIndicator>
  </ListBox.Item>
</ListBox>

Accessibility

The ListBox component implements the ARIA listbox pattern and provides:

Full keyboard navigation support
Screen reader announcements for selection changes
Proper focus management
Support for disabled states
Typeahead search functionality

For more information, see the React Aria ListBox documentation.

Related Components

On this page

Related Components