Data Grid

Usage

The DataGrid component takes a flat data array, a columns definition, and a getRowId function. It renders a fully accessible table with built-in support for sorting, selection, column resizing, and more.

Column Definitions

Columns are defined as an array of DataGridColumn<T> objects. Each column has an id, a header, and either an accessorKey (to read a value from the row object) or a custom cell renderer.

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

interface Payment {
  id: string;
  customer: string;
  amount: number;
  status: "succeeded" | "failed";
}

const columns: DataGridColumn<Payment>[] = [
  {
    id: "customer",
    header: "Customer",
    accessorKey: "customer",
    isRowHeader: true,
    allowsSorting: true,
  },
  {
    id: "amount",
    header: "Amount",
    accessorKey: "amount",
    align: "end",
    cell: (item) => `$${item.amount.toFixed(2)}`,
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
  },
];

Custom Cell Rendering

The cell function receives the full row item and column definition. Return any ReactNode:

{
  id: "status",
  header: "Status",
  cell: (item) => (
    <Chip color={item.status === "succeeded" ? "success" : "danger"} size="sm" variant="soft">
      {item.status}
    </Chip>
  ),
}

Custom Header Rendering

The header property accepts a string, a ReactNode, or a render function that receives { sortDirection } for sortable columns:

{
  id: "amount",
  header: ({ sortDirection }) => (
    <span>Amount {sortDirection === "ascending" ? "↑" : sortDirection === "descending" ? "↓" : ""}</span>
  ),
  allowsSorting: true,
}

Row Selection

Enable row selection with selectionMode and showSelectionCheckboxes. Supports both "single" and "multiple" modes with controlled or uncontrolled state.

const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set());

<DataGrid
  aria-label="Users"
  columns={columns}
  data={users}
  getRowId={(item) => item.id}
  selectionMode="multiple"
  showSelectionCheckboxes
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
/>

Sorting

Mark columns as sortable with allowsSorting: true. In uncontrolled mode, the DataGrid sorts data client-side using locale-aware string comparison (or a custom sortFn). For server-side sorting, pass a controlled sortDescriptor and handle onSortChange.

Uncontrolled (client-side)

<DataGrid
  aria-label="Payments"
  columns={columns}
  data={payments}
  getRowId={(item) => item.id}
  defaultSortDescriptor={{ column: "customer", direction: "ascending" }}
/>

Controlled (server-side)

const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({
  column: "date",
  direction: "descending",
});

<DataGrid
  aria-label="Payments"
  columns={columns}
  data={payments}
  getRowId={(item) => item.id}
  sortDescriptor={sortDescriptor}
  onSortChange={setSortDescriptor}
/>

Custom Sort Function

Provide a sortFn on a column for custom comparison logic:

{
  id: "priority",
  header: "Priority",
  allowsSorting: true,
  sortFn: (a, b) => priorityOrder[a.priority] - priorityOrder[b.priority],
}

Column Resizing

Enable column resizing with allowsColumnResize on the DataGrid and allowsResizing on individual columns. Columns must have minWidth set.

<DataGrid
  aria-label="Payments"
  columns={columns}
  data={payments}
  getRowId={(item) => item.id}
  allowsColumnResize
  onColumnResize={(widths) => console.log("Resizing:", widths)}
  onColumnResizeEnd={(widths) => console.log("Final widths:", widths)}
/>

Pinned Columns

Pin columns to the start or end edge so they stay visible during horizontal scroll. Pinned columns must have a numeric width or minWidth.

const columns: DataGridColumn<Company>[] = [
  {
    id: "name",
    header: "Company",
    pinned: "start",
    minWidth: 160,
    // ...
  },
  // ... scrollable columns ...
  {
    id: "actions",
    header: "",
    pinned: "end",
    width: 50,
    cell: (item) => <RowActions id={item.id} />,
  },
];

Drag and Drop

Enable row reorder with the onReorder callback. The DataGrid provides built-in drag handles, keyboard support (Enter to grab, arrows to move, Enter to drop), and fires the callback with the reordered data array.

const [tasks, setTasks] = useState(initialTasks);

<DataGrid
  aria-label="Backlog"
  columns={columns}
  data={tasks}
  getRowId={(item) => item.id}
  onReorder={(event) => setTasks(event.reorderedData)}
/>

For advanced drag-and-drop scenarios (cross-list, custom drag items), pass dragAndDropHooks directly from RAC's useDragAndDrop.

Expandable Rows

Render hierarchical data by providing a getChildren function. The DataGrid recursively renders child rows, auto-generates a chevron toggle in the treeColumn, and indents each nested level by treeIndent pixels.

interface FileRow {
  id: string;
  name: string;
  type: "Folder" | "File";
  children?: FileRow[];
}

const [expandedKeys, setExpandedKeys] = useState<Selection>(new Set(["1"]));

<DataGrid
  aria-label="Files"
  columns={columns}
  data={files}
  getRowId={(item) => item.id}
  getChildren={(item) => item.children}
  treeColumn="name"
  expandedKeys={expandedKeys}
  onExpandedChange={setExpandedKeys}
/>

The treeColumn prop specifies which column displays the chevron. If omitted, it defaults to the first isRowHeader column (or the first column). Use defaultExpandedKeys for uncontrolled expansion, or pair expandedKeys with onExpandedChange for controlled behavior. Set treeIndent={0} to disable automatic per-level indentation.

Expandable rows compose with selection, drag-and-drop, sorting, pinned columns, and column resizing.

Editable Cells

Use the cell render function to embed any interactive component — text fields, selects, switches, number steppers, etc.

Empty State

Provide a renderEmptyState function to display a custom empty state when data is empty.

<DataGrid
  aria-label="Projects"
  columns={columns}
  data={[]}
  getRowId={(item) => item.id}
  renderEmptyState={() => (
    <EmptyState size="sm">
      <EmptyState.Header>
        <EmptyState.Media variant="icon">
          <FolderOpen />
        </EmptyState.Media>
        <EmptyState.Title>No Projects Yet</EmptyState.Title>
        <EmptyState.Description>
          Get started by creating your first project.
        </EmptyState.Description>
      </EmptyState.Header>
    </EmptyState>
  )}
/>

Async Loading

Use onLoadMore, isLoadingMore, and loadMoreContent to implement infinite scroll loading. The DataGrid renders a sentinel row that triggers onLoadMore when it scrolls into view.

<DataGrid
  aria-label="Invoices"
  columns={columns}
  data={items}
  getRowId={(item) => item.id}
  scrollContainerClassName="max-h-[400px] overflow-y-auto"
  onLoadMore={hasMore ? handleLoadMore : undefined}
  isLoadingMore={isLoading}
  loadMoreContent={<Spinner size="md" />}
/>

Virtualization

Enable row virtualization for large datasets (1,000+ rows) with the virtualized prop. Only visible rows are rendered to the DOM. You must set rowHeight and headingHeight.

<DataGrid
  virtualized
  aria-label="Product inventory"
  columns={columns}
  data={products}
  getRowId={(item) => item.id}
  contentClassName="h-[600px] min-w-[900px] overflow-auto"
  rowHeight={58}
  headingHeight={37}
/>

Bulk Actions

Combine row selection with an ActionBar to provide bulk operations like export, archive, or delete.

Users

A minimal user directory using the "secondary" variant with accessorKey-only columns and a row action link — no selection, no sorting.

Team Members

A full-featured HR table with controlled sorting, multi-selection, pinned columns, column resizing, column visibility toggling, search, filters, and client-side pagination.

Servers

A server monitoring dashboard with controlled sorting, selection, column visibility toggling, search, status filtering, and rich cell renderers including sparkline charts and circular progress indicators.

CSS Classes

Base Classes

• .data-grid — Root wrapper. Sets position: relative and width: 100%. Defines --data-grid-selection-column-width and --data-grid-drag-handle-column-width custom properties.

Element Classes

• .data-grid__selection-column — Narrow <th> for the select-all checkbox. Fixed width from --data-grid-selection-column-width.
• .data-grid__selection-cell — Narrow <td> for row selection checkboxes. Same fixed width.
• .data-grid__drag-handle-column — Narrow <th> for the drag handle column. Fixed width from --data-grid-drag-handle-column-width.
• .data-grid__drag-handle-cell — Narrow <td> for the drag handle. Same fixed width.
• .data-grid__drag-handle — The grip button inside each row. Styled with cursor: grab and subtle color.
• .data-grid__sort-icon — Chevron indicator next to sortable column headers. Rotates 180° when descending.
• .data-grid__empty-state — Centered container for the empty state message. Muted text, vertical padding.
• .data-grid__tree-cell — Flex wrapper inside the treeColumn cell that holds the chevron toggle and cell content. Per-level indentation is applied inline via padding-inline-start.
• .data-grid__tree-toggle — Expand/collapse chevron button, rendered when a row has children. Sized via --data-grid-tree-toggle-size.
• .data-grid__tree-toggle-icon — Chevron icon inside the toggle. Rotates 90° when the row is expanded via [data-expanded].
• .data-grid__tree-toggle-spacer — Invisible placeholder rendered for leaf rows so their content aligns with sibling rows that have a chevron.

Interactive States

• Drag handle hover: &:hover / [data-hovered="true"] on .data-grid__drag-handle — text transitions to foreground.
• Drag handle pressed: &:active / [data-pressed="true"] on .data-grid__drag-handle — cursor changes to grabbing.
• Drag handle focus: [data-focus-visible="true"] on .data-grid__drag-handle — applies focus ring via status-focused.
• Row dragging: .table__row[data-dragging="true"] — reduced opacity (0.5).
• Drop indicator: .react-aria-DropIndicator[data-drop-target] td — accent background line.

Alignment

• [data-align="end"] — Right-aligns both header and cell content.
• [data-align="center"] — Center-aligns both header and cell content.

Vertical Alignment

Controlled by the verticalAlign prop via [data-vertical-align] on the root:

• [data-vertical-align="top"] — vertical-align: top (flexbox items-start in virtualized mode).
• [data-vertical-align="middle"] — vertical-align: middle (flexbox items-center in virtualized mode).
• [data-vertical-align="bottom"] — vertical-align: bottom (flexbox items-end in virtualized mode).

Pinned Columns

• [data-pinned] — Makes the cell position: sticky with z-index: 2.
• [data-pinned="start"] — Sticky to inset-inline-start.
• [data-pinned="end"] — Sticky to inset-inline-end.
• [data-pinned-edge] — Boundary column that shows a separator line when the pinned group detaches from the scrollable content.
• [data-pinned-start-detached] — Set on root when content has scrolled past the start-pinned columns. Shows separator via ::after.
• [data-pinned-end-detached] — Set on root when content hasn't scrolled to the end edge. Shows separator via ::after.

CSS Variables

• --data-grid-selection-column-width — Width of the selection checkbox column (default: 40px).
• --data-grid-drag-handle-column-width — Width of the drag handle column (default: 32px).
• --data-grid-tree-toggle-size — Size of the expand/collapse chevron button and its leaf-row spacer (default: 24px).
• --data-grid-tree-gap — Gap between the chevron/spacer and the cell content in a treeColumn cell (default: 4px).

API Reference

DataGrid

The root data grid component. Accepts a generic type parameter T for the row data shape.

DataGridColumn<T>

Column definition object passed to the columns prop.

DataGridReorderEvent<T>

Event object passed to the onReorder callback.

Type Exports

The following types are re-exported from the DataGrid module for convenience: