TableUpdated

Import

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

Usage

Anatomy

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

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

export default () => (
  <Table>
    <Table.ScrollContainer>
      <Table.Content aria-label="Example table">
        <Table.Header>
          <Table.Column allowsSorting>
            {({ sortDirection }) => (
              <Table.SortableColumnHeader sortDirection={sortDirection}>
                Name
              </Table.SortableColumnHeader>
            )}
          </Table.Column>
          <Table.Column>Role</Table.Column>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Kate Moore</Table.Cell>
            <Table.Cell>CEO</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Content>
    </Table.ScrollContainer>
    <Table.Footer>{/* Optional footer content */}</Table.Footer>
  </Table>
);

Secondary Variant

Sorting

Columns can be made sortable using the allowsSorting prop on Table.Column. Use sortDescriptor and onSortChange on Table.Content to manage sort state. Wrap the label in Table.SortableColumnHeader and forward the sortDirection from the column's render prop to render the default ascending/descending indicator.

Selection

Enable row selection with selectionMode on Table.Content. Use Checkbox with slot="selection" for select-all and per-row checkboxes.

Custom Cells

Expandable Rows

Rows can be nested to display hierarchical data. Use the treeColumn prop to designate a column, and render a Button with slot="chevron" in that column’s cells so users can expand and collapse the row. Use the expandedKeys prop to control which rows are expanded.

Pagination

Use Table.Footer to add a pagination component below the table.

Column Resizing

Wrap the table in Table.ResizableContainer and add Table.ColumnResizer inside each resizable column.

Empty State

Use renderEmptyState on Table.Body to display a custom message when the table has no data.

Async Loading

Use Table.LoadMore for infinite scrolling. It renders a sentinel row that triggers onLoadMore when scrolled into view.

Virtualization

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

TanStack Table

HeroUI's Table works as a rendering layer on top of headless table libraries. This example uses TanStack Table for column definitions, sorting, and pagination — while HeroUI handles styling and accessibility.

Styling

Passing Tailwind CSS classes

You can customize individual Table parts:

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

function CustomTable() {
  return (
    <Table className="border border-purple-200">
      <Table.ScrollContainer>
        <Table.Content aria-label="Custom styled table">
          <Table.Header className="bg-purple-50">
            <Table.Column>Name</Table.Column>
          </Table.Header>
          <Table.Body>
            <Table.Row className="hover:bg-purple-50">
              <Table.Cell>Kate Moore</Table.Cell>
            </Table.Row>
          </Table.Body>
        </Table.Content>
      </Table.ScrollContainer>
    </Table>
  );
}

Customizing the component classes

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

@layer components {
  .table-root {
    @apply relative grid w-full overflow-clip;
  }

  .table__header {
    @apply bg-gray-100;
  }

  .table__column {
    @apply px-4 py-2.5 text-left text-xs font-medium text-gray-600;
  }

  .table__row {
    @apply bg-white border-b border-gray-200;
  }

  .table__cell {
    @apply px-4 py-3 text-sm;
  }

  .table__footer {
    @apply flex items-center px-4 py-2.5;
  }
}

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

CSS Classes

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

Base Classes

• .table-root - Root container (named table-root instead of table because table is a built-in Tailwind CSS utility class for display: table)
• .table__scroll-container - Horizontal scroll wrapper with custom scrollbar
• .table__content - The <table> element
• .table__header - Header row (<thead>)
• .table__column - Column header cell (<th>)
• .table__body - Body section (<tbody>)
• .table__row - Row element (<tr>)
• .table__cell - Data cell (<td>)
• .table__footer - Footer container (outside table)

Advanced Classes

• .table__column-resizer - Drag handle for column resizing
• .table__resizable-container - Wrapper enabling column resizing
• .table__load-more - Sentinel row for infinite scrolling
• .table__load-more-content - Styled container for the loading indicator
• .table__sortable-column-header - Sortable column label + indicator wrapper
• .table__sortable-column-indicator - Sort direction chevron (rotates via [data-direction="descending"])

Variant Classes

• .table-root--primary - Gray background container with card-style body (default)
• .table-root--secondary - No background, standalone rounded headers

Interactive States

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

• Hover: :hover or [data-hovered="true"] (row background change)
• Selected: [data-selected="true"] (row highlight)
• Focus: :focus-visible or [data-focus-visible="true"] (inset focus ring on rows, columns, and cells)
• Disabled: :disabled or [aria-disabled="true"] (reduced opacity)
• Sortable: [data-allows-sorting="true"] (interactive cursor on columns)
• Dragging: [data-dragging="true"] (reduced opacity)
• Drop Target: [data-drop-target="true"] (accent background)

API Reference

Table Props

Table.ScrollContainer Props

Table.Content Props

Inherits from React Aria Table.

Table.Header Props

Inherits from React Aria TableHeader.

Table.Column Props

Inherits from React Aria Column.

Table.Body Props

Inherits from React Aria TableBody.

Table.Row Props

Inherits from React Aria Row.

Table.Cell Props

Inherits from React Aria Cell.

Table.SortableColumnHeader Props

Renders a sortable column label with an ascending/descending indicator. Use it inside a Table.Column render-prop callback and forward the sortDirection value.

Table.Footer Props

Table.ColumnResizer Props

Inherits from React Aria ColumnResizer.

Table.ResizableContainer Props

Inherits from React Aria ResizableTableContainer.

Table.LoadMore Props

Inherits from React Aria TableLoadMoreItem.

Table.LoadMoreContent Props

Table.Collection Props

Re-exported from React Aria Collection. Used to render dynamic cells within rows alongside static cells (e.g., checkboxes).

TableLayout