List View

Usage

The ListView component displays a list of interactive items with built-in keyboard navigation, typeahead search, and selection.

Selection Modes

ListView supports three selection modes: none (read-only), single (radio-style), and multiple (checkboxes). Selection checkboxes are rendered automatically when selection is enabled.

// No selection
<ListView aria-label="Files" selectionMode="none">
  ...
</ListView>

// Single selection
<ListView aria-label="Files" selectionMode="single">
  ...
</ListView>

// Multiple selection
<ListView
  aria-label="Files"
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={setSelected}
>
  ...
</ListView>

Variants

Primary

The default variant. Gray background wrapper with white surface items forming a card shape.

Secondary

No background wrapper. Items are transparent with bottom borders. Uses primary (accent) checkboxes for contrast.

Disabled Items

Use the disabledKeys prop to disable specific items. Disabled items cannot be selected, focused, or interacted with.

<ListView
  aria-label="Files"
  disabledKeys={["3", "5"]}
  selectionMode="multiple"
>
  ...
</ListView>

Empty State

Use renderEmptyState to show placeholder content when the list has no items. Works well with the EmptyState Pro component.

<ListView
  aria-label="Files"
  renderEmptyState={() => (
    <EmptyState size="sm">
      <EmptyState.Header>
        <EmptyState.Media variant="icon">
          <FolderOpen />
        </EmptyState.Media>
        <EmptyState.Title>No Files</EmptyState.Title>
        <EmptyState.Description>Upload a file to get started.</EmptyState.Description>
      </EmptyState.Header>
    </EmptyState>
  )}
>
  {[]}
</ListView>

With Action Bar

Combine with ActionBar for bulk selection workflows. The ActionBar appears when items are selected and provides contextual actions.

Anatomy

import {ListView} from "@heroui-pro/react";

<ListView aria-label="Files" items={files} selectionMode="multiple">
  {(file) => (
    <ListView.Item id={file.id} textValue={file.name}>
      <ListView.ItemContent>
        <FileIcon />
        <div>
          <ListView.Title>{file.name}</ListView.Title>
          <ListView.Description>{file.size}</ListView.Description>
        </div>
      </ListView.ItemContent>
      <ListView.ItemAction>
        <Button isIconOnly size="sm" variant="ghost">
          <Ellipsis />
        </Button>
      </ListView.ItemAction>
    </ListView.Item>
  )}
</ListView>

CSS Classes

Base Classes

• .list-view — Root container. Sets min-height: 0, width: 100%, and outline: none.
• .list-view--primary — Gray background wrapper with padding and large border-radius. Items have white surface backgrounds.
• .list-view--secondary — No background or padding. Items are transparent with bottom borders.

Element Classes

• .list-view__item — Individual row. Flex layout with gap, padding, and interactive states.
• .list-view__item-content — Main content area (icon + text). Flex with min-width: 0 for truncation.
• .list-view__title — Primary text. Truncated, text-sm font-medium.
• .list-view__description — Secondary text. Truncated, text-xs text-muted.
• .list-view__item-action — Trailing action slot. Auto-margin to the end.
• .list-view__selection-cell — Checkbox area. Fixed width, flex-shrink: 0.
• .list-view__empty-state — Centered empty state container.

Interactive States

• Hover: bg-surface/40 (primary) or bg-default/50 (secondary).
• Selected: bg-surface/10 (primary) or bg-accent-soft (secondary).
• Focus visible: Inset focus ring via box-shadow: inset 0 0 0 2px var(--color-focus).
• Disabled: status-disabled utility.
• Dragging: opacity: 0.5.

API Reference

ListView

The root list component. Accepts a generic type parameter T for the item data shape. Extends RAC GridListProps.

ListView.Item

Individual list item. Extends RAC GridListItemProps.

ListView.ItemContent

Main content container for the item (icon/avatar + text).

ListView.Title

Primary text element inside an item.

ListView.Description

Secondary/muted text element inside an item.

ListView.ItemAction

Trailing action slot inside an item.