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.

import { DataGrid, type DataGridColumn } from "@blakeui/pro-react";

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

const data: Payment[] = [
  { id: "1", customer: "Olivia Martin", amount: 316, status: "succeeded" },
  { id: "2", customer: "Jackson Lee", amount: 242, status: "pending" },
];

const columns: DataGridColumn<Payment>[] = [
  { id: "customer", header: "Customer", accessorKey: "customer", isRowHeader: true },
  { id: "amount", header: "Amount", accessorKey: "amount", align: "end" },
  { id: "status", header: "Status", accessorKey: "status" },
];

function App() {
  return (
    <DataGrid
      aria-label="Payments"
      columns={columns}
      data={data}
      getRowId={(item) => item.id}
    />
  );
}

Anatomy

Import the DataGrid component. It is not a compound component and has no DataGrid.* sub-parts.

import { DataGrid } from "@blakeui/pro-react";

<DataGrid />;

Column definitions

Columns are 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. The cell function receives the full row item and returns any ReactNode.

const columns: DataGridColumn<Payment>[] = [
  {
    id: "customer",
    header: "Customer",
    accessorKey: "customer",
    isRowHeader: true,
    allowsSorting: true,
    minWidth: 180,
    cell: (item) => (
      <div className="flex flex-col">
        <span className="font-medium">{item.customer}</span>
        <span className="text-muted text-xs">{item.email}</span>
      </div>
    ),
  },
  {
    id: "amount",
    header: "Amount",
    accessorKey: "amount",
    align: "end",
    allowsSorting: true,
    minWidth: 120,
    cell: (item) => <span className="tabular-nums">${item.amount.toFixed(2)}</span>,
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    minWidth: 120,
    cell: (item) => (
      <Chip color={STATUS_COLOR[item.status]} size="sm" variant="soft">
        {item.status}
      </Chip>
    ),
  },
];

Custom Cell Rendering

A column's cell function receives the row item and the column definition and returns any ReactNode.

{
  id: "status",
  header: "Status",
  accessorKey: "status",
  cell: (item) => (
    <Chip color={STATUS_COLOR[item.status]} size="sm" variant="soft">
      {item.status}
    </Chip>
  ),
}

Custom Header Rendering

A column's header accepts a string, a ReactNode, or a render function that receives { sortDirection } for sortable columns.

{
  id: "amount",
  accessorKey: "amount",
  align: "end",
  allowsSorting: true,
  header: ({ sortDirection }) => (
    <span className="inline-flex items-center gap-1">
      Amount
      {sortDirection && (
        <Icon
          icon={sortDirection === "ascending" ? "ic:twotone-arrow-upward" : "ic:twotone-arrow-downward"}
          width={14}
          height={14}
        />
      )}
    </span>
  ),
}

Row selection

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

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

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

Bulk actions

Selecting rows raises a Dock — a floating action bar with a live selection count and bulk operations — anchored to the grid; the header checkbox toggles every row at once.

Editable cells

Compose editors — inline text, a select, a stepper, and a toggle — into column cell renderers with caller-managed row state; the text editor opens in a popover portaled outside the grid so its keystrokes stay clear of the grid's keyboard navigation.

Team Members

A full-featured team directory composed from the DataGrid primitives — controlled sorting, multi-row selection, pinned Member and actions columns, column resizing and visibility, search, worker-type and status filters, and pagination.

Servers

A server-monitoring grid composed from the DataGrid primitives — controlled sorting, multi-row selection, column visibility and resizing, search, and status filtering, with a circular-progress capacity ring and an inline request sparkline as custom cell renderers.

Sorting

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

Uncontrolled (client-side)

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

Controlled (server-side)

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

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

Custom Sort Function

Provide a custom sortFn on a column for non-default comparison logic; it falls back to locale-aware string comparison.

{
  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 each resizable column; resizable columns should define a minWidth.

const columns: DataGridColumn<Payment>[] = [
  { id: "customer", header: "Customer", accessorKey: "customer", isRowHeader: true, allowsResizing: true, minWidth: 160 },
  { id: "email", header: "Email", accessorKey: "email", allowsResizing: true, minWidth: 200 },
  { id: "amount", header: "Amount", accessorKey: "amount", align: "end", allowsResizing: true, minWidth: 120 },
];

<DataGrid
  aria-label="Payments"
  columns={columns}
  data={data}
  getRowId={(item) => item.id}
  allowsColumnResize
  onColumnResize={(widths) => console.log("resizing", widths)}
  onColumnResizeEnd={(widths) => console.log("resized", 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, and they use logical directions ("start" is left in LTR).

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.

For advanced scenarios (cross-list, custom drag items), pass dragAndDropHooks directly from React Aria Components' useDragAndDrop. When provided, dragAndDropHooks overrides onReorder.

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.

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.

Empty state

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

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.

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.

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:

All other props are forwarded to the root element.