ListBox

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

Usage

1import { ListBox } from '@lenso/ui';

1"use client";2
3// Adapted from HeroUI v3.2.6 list-box-default (Apache-2.0).4import * as stylex from "@stylexjs/stylex";5import { descriptionStyles } from "@lenso/tokens/description";6import { labelStyles } from "@lenso/tokens/label";7import { Avatar, ListBox, ListBoxItem } from "@lenso/ui";8
9const users = [10  { key: "1", textValue: "Bob", color: "blue" },11  { key: "2", textValue: "Fred", color: "green" },12  { key: "3", textValue: "Martha", color: "purple" },13] as const;14const styles = stylex.create({15  root: { width: 220 },16  details: { display: "flex", flexDirection: "column" },17});18
19export function Default() {20  return (21    <ListBox aria-label="Users" xstyle={styles.root} selectionMode="single">22      {users.map((user) => (23        <ListBoxItem key={user.key} itemKey={user.key} textValue={user.textValue}>24          <Avatar size="sm">25            <Avatar.Image26              alt={user.textValue}27              src={`https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/${user.color}.jpg`}28            />29            <Avatar.Fallback>{user.textValue[0]}</Avatar.Fallback>30          </Avatar>31          <div {...stylex.props(styles.details)}>32            <span {...stylex.props(labelStyles.label)}>{user.textValue}</span>33            <span {...stylex.props(descriptionStyles.description)}>34              {user.textValue.toLowerCase()}@heroui.com35            </span>36          </div>37          <ListBoxItem.Indicator />38        </ListBoxItem>39      ))}40    </ListBox>41  );42}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

1import { ListBox, Label, Description, Header } from '@lenso/ui';2
3export default () => (4  <ListBox>5    <ListBox.Item>6      <Label />7      <Description />8      <ListBox.ItemIndicator />9    </ListBox.Item>10    <ListBox.Section>11      <Header />12      <ListBox.Item>13        <Label />14      </ListBox.Item>15    </ListBox.Section>16  </ListBox>17)

Examples

With Disabled Items

1"use client";2// HeroUI v3.2.6 with-disabled-items adaptation (Apache-2.0).3import { Actions } from "./actions";4export function WithDisabledItems() {5  return <Actions disabled />;6}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Sections

1"use client";2// HeroUI v3.2.6 with-sections adaptation (Apache-2.0).3import { Actions } from "./actions";4export function WithSections() {5  return <Actions />;6}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Multi Select

1"use client";2// HeroUI v3.2.6 multi-select adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { UsersList, styles } from "./users";5export function MultiSelect() {6  return (7    <div {...stylex.props(styles.surface)}>8      <UsersList selectionMode="multiple" />9    </div>10  );11}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

1"use client";2// HeroUI v3.2.6 controlled adaptation (Apache-2.0).3import { useState } from "react";4import * as stylex from "@stylexjs/stylex";5import { UsersList, styles } from "./users";6export function Controlled() {7  const [selected, setSelected] = useState<Set<React.Key>>(new Set(["1"]));8  return (9    <div {...stylex.props(styles.stack)}>10      <div {...stylex.props(styles.surface)}>11        <UsersList12          selectionMode="multiple"13          selectedKeys={selected}14          onSelectionChange={setSelected}15          customCheck16        />17      </div>18      <p {...stylex.props(styles.muted)}>19        Selected: {selected.size ? [...selected].join(", ") : "None"}20      </p>21    </div>22  );23}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Virtualization

ListBox supports virtualization through Virtualizer, enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.

1"use client";2// HeroUI v3.2.6 virtualization adaptation (Apache-2.0); native fixed-row window.3import * as stylex from "@stylexjs/stylex";4import { ListBox, ListBoxItem } from "@lenso/ui";5import { Description, Label } from "./text";6const first = [7  "Emma",8  "Liam",9  "Olivia",10  "Noah",11  "Ava",12  "James",13  "Sophia",14  "Oliver",15  "Isabella",16  "Lucas",17  "Mia",18  "Ethan",19  "Charlotte",20  "Mason",21  "Amelia",22  "Logan",23  "Harper",24  "Alexander",25  "Ella",26  "Benjamin",27];28const last = [29  "Smith",30  "Johnson",31  "Williams",32  "Brown",33  "Jones",34  "Garcia",35  "Miller",36  "Davis",37  "Rodriguez",38  "Martinez",39  "Anderson",40  "Taylor",41  "Thomas",42  "Jackson",43  "White",44  "Harris",45  "Clark",46  "Lewis",47  "Robinson",48  "Walker",49];50const users = Array.from({ length: 1000 }, (_, index) => ({51  key: index + 1,52  textValue: `${first[index % 20]} ${last[Math.floor(index / 20) % 20]}`,53  email: `${first[index % 20]!.toLowerCase()}.${last[Math.floor(index / 20) % 20]!.toLowerCase()}@acme.com`,54}));55const styles = stylex.create({56  list: { width: 300 },57  detail: { display: "flex", flexDirection: "column" },58});59export function Virtualization() {60  return (61    <ListBox62      aria-label="Virtualized list with 1000 items"63      xstyle={styles.list}64      items={users}65      virtualized={{ rowHeight: 50, height: 400 }}66    >67      {(item) => (68        <ListBoxItem itemKey={item.key} textValue={item.textValue}>69          <div {...stylex.props(styles.detail)}>70            <Label>{item.textValue}</Label>71            <Description>{users[Number(item.key) - 1]!.email}</Description>72          </div>73          <ListBoxItem.Indicator />74        </ListBoxItem>75      )}76    </ListBox>77  );78}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Custom Check Icon

1"use client";2// HeroUI v3.2.6 custom-check-icon adaptation (Apache-2.0).3import * as stylex from "@stylexjs/stylex";4import { UsersList, styles } from "./users";5export function CustomCheckIcon() {6  return (7    <div {...stylex.props(styles.surface)}>8      <UsersList selectionMode="multiple" customCheck />9    </div>10  );11}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Function

1"use client";2// HeroUI v3.2.6 render-function adaptation (Apache-2.0).3import { UsersList, styles } from "./users";4export function RenderFunction() {5  return (6    <UsersList7      xstyle={styles.list}8      selectionMode="single"9      render={(props) => <div {...props} data-custom="true" />}10      renderItems11    />12  );13}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Customization

Tailwind CSS

1"use client";2// HeroUI v3.2.6 custom-styles adaptation (Apache-2.0).3import { UsersList, styles } from "./users";4export function CustomStyles() {5  return (6    <UsersList7      aria-label="Assignee"8      xstyle={styles.custom}9      selectionMode="single"10      customStyles11      count={2}12    />13  );14}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

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

1@layer components {2  .list-box {3    @apply rounded-lg border border-border bg-surface p-2;4  }5
6  .list-box-item {7    @apply rounded px-2 py-1 cursor-pointer;8  }9
10  .list-box-item--danger {11    @apply text-danger;12  }13
14  .list-box-item__indicator {15    @apply text-accent;16  }17}

Styling Reference

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 [!toc]

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

Variant Classes [!toc]

.list-box--default - Default variant styling
.list-box--danger - Danger variant styling
.list-box-item--default - Default item variant
.list-box-item--danger - Danger item variant

State Classes [!toc]

.list-box-item[data-selected="true"] - Selected item state
.list-box-item[data-focus-visible="true"] - Focused item state
.list-box-item[data-disabled="true"] - Disabled item state
.list-box-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

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
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>`	-	Overrides the default DOM element with a custom render function.

ListBox.Item

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
`render`	`(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement`	-	Overrides the default DOM element with a custom render function.

ListBox.ItemIndicator

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

ListBox.Section

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

Render Props

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

ListLayout

Name	Type	Default	Description
`rowHeight`	`number \| undefined`	48	The fixed height of a row in px.
`estimatedRowHeight`	`number \| undefined`	—	The estimated height of a row, when row heights are variable.
`headingHeight`	`number \| undefined`	48	The fixed height of a section header in px.
`estimatedHeadingHeight`	`number \| undefined`	—	The estimated height of a section header, when the height is variable.
`loaderHeight`	`number \| undefined`	48	The fixed height of a loader element in px. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections.
`dropIndicatorThickness`	`number \| undefined`	2	The thickness of the drop indicator.
`gap`	`number \| undefined`	0	The gap between items.
`padding`	`number \| undefined`	0	The padding around the list.

Examples

Basic Usage

1import { ListBox, Label, Description } from '@lenso/ui';2
3<ListBox aria-label="Users" selectionMode="single">4  <ListBox.Item id="1" textValue="Bob">5    <Label>Bob</Label>6    <Description>[email protected]</Description>7  </ListBox.Item>8  <ListBox.Item id="2" textValue="Alice">9    <Label>Alice</Label>10    <Description>[email protected]</Description>11  </ListBox.Item>12</ListBox>

With Sections

1import { ListBox, Header, Separator } from '@lenso/ui';2
3<ListBox aria-label="Actions" selectionMode="none" onAction={(key) => console.log(key)}>4  <ListBox.Section>5    <Header>Actions</Header>6    <ListBox.Item id="new" textValue="New file">New file</ListBox.Item>7    <ListBox.Item id="edit" textValue="Edit file">Edit file</ListBox.Item>8  </ListBox.Section>9  <Separator />10  <ListBox.Section>11    <Header>Danger zone</Header>12    <ListBox.Item id="delete" textValue="Delete" variant="danger">Delete</ListBox.Item>13  </ListBox.Section>14</ListBox>

Controlled Selection

1import { ListBox, Selection } from '@lenso/ui';2import { useState } from 'react';3
4function ControlledListBox() {5  const [selected, setSelected] = useState<Selection>(new Set(["1"]));6
7  return (8    <ListBox9      aria-label="Options"10      selectedKeys={selected}11      selectionMode="multiple"12      onSelectionChange={setSelected}13    >14      <ListBox.Item id="1" textValue="Option 1">Option 1</ListBox.Item>15      <ListBox.Item id="2" textValue="Option 2">Option 2</ListBox.Item>16      <ListBox.Item id="3" textValue="Option 3">Option 3</ListBox.Item>17    </ListBox>18  );19}

Custom Indicator

1import { ListBox, ListBoxItemIndicator } from '@lenso/ui';2import { Icon } from '@iconify/react';3
4<ListBox aria-label="Options" selectionMode="multiple">5  <ListBox.Item id="1" textValue="Option 1">6    Option 17    <ListBox.ItemIndicator>8      {({isSelected}) =>9        isSelected ? <Icon icon="gravity-ui:check" /> : null10      }11    </ListBox.ItemIndicator>12  </ListBox.Item>13</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.

Select

A select displays a collapsible list of options and allows a user to select one of them

ComboBox

A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query

Avatar

Display user profile images with customizable fallback content

ListBox

Usage

Anatomy

Examples

With Disabled Items

With Sections

Multi Select

Controlled

Virtualization

Custom Check Icon

Render Function

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Variant Classes [!toc]

State Classes [!toc]

Interactive States

API Reference

ListBox

ListBox.Item

ListBox.ItemIndicator

ListBox.Section

Render Props

ListLayout

Examples

Basic Usage

With Sections

Controlled Selection

Custom Indicator

Accessibility

Related Components