Data Grid

Usage

"use client";

import type { Selection } from "react-aria-components";

import { useState } from "react";

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.

Anatomy

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

import { DataGrid } from "@thenamespace/uikit";

<DataGrid />;

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 "@thenamespace/uikit";

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

"use client";

import type { Selection } from "react-aria-components";

import { useState } from "react";

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 client";

import { useState } from "react";

import {

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

Empty State

"use client";

import {
  Add01Icon,
  FolderOpenIcon,

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 client";

import { useState } from "react";

import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";

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-[400px] min-w-[900px] overflow-auto"
  rowHeight={58}
  headingHeight={37}
/>

Bulk Actions

// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";

import type { Selection } from "react-aria-components";

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.

Complex

Team Members

100

Add Member

Worker Type Status Sort Columns

	Worker ID	External Worker ID	Member	Country	Role	Worker Type	Status	Start Date	Teams
	WRK-7293027	EXT-O65TY0GW	AC Aaron Carteraaron.carter@example.com	Canada	Software Engineer	Contractor	Inactive	September 16, 2025	Product
	WRK-9145881	EXT-IJWM67YO	AJ Alice Johnsonalice.johnson@example.com	South Korea	Network Administrator	Contractor	Active	May 6, 2025	ProductEngineeringDesign+1
	WRK-4113931	EXT-VWXGQ2YR	AJ Alice Johnsonalice.johnson@example.com	United Kingdom	Technical Support Specialist	Employee	Active	July 13, 2025	ProductEngineeringDesign+2
	WRK-2903436	EXT-GB2GA8CY	AJ Alice Johnsonalice.johnson@example.com	United States	Operations Coordinator	Contractor	Vacation	April 14, 2025	ProductEngineeringDesign
	WRK-9738309	EXT-62IGY3A9	AJ Alice Johnsonalice.johnson@example.com	Brazil	Accountant	Employee	Vacation	January 15, 2025	Product
	WRK-9876926	EXT-CCSPUX9O	AJ Alice Johnsonalice.johnson@example.com	Japan	Graphic Designer	Contractor	Inactive	April 11, 2026	ProductEngineeringDesign+1
	WRK-8979921	EXT-TRXKAG0G	BB Bella Brownbella.brown@example.com	India	Technical Support Specialist	Employee	Active	April 24, 2026	ProductEngineering
	WRK-8443933	EXT-B3M1WFOO	BB Bella Brownbella.brown@example.com	China	QA Tester	Contractor	Active	June 18, 2025	ProductEngineeringDesign+1
	WRK-2672673	EXT-9H1WJGWE	BB Bella Brownbella.brown@example.com	Australia	Operations Coordinator	Contractor	Vacation	January 6, 2026	ProductEngineeringDesign+2
	WRK-4313540	EXT-45G6B6NL	BS Bob Smithbob.smith@example.com	Australia	Environmental Scientist	Contractor	Vacation	February 10, 2025	OtherManagementSupport

Rows per page10

 102550100

0 of 100 selected

PreviousNext

// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";

import type { Selection, SortDescriptor } from "react-aria-components";

Expand code

Drag And Drop Reorder

"use client";

import { useState } from "react";

import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";

Pinned Columns Compact

"use client";

import type { Selection } from "react-aria-components";

import { useMemo, useState } from "react";

Simple

"use client";

import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Link } from "@thenamespace/uikit/link";

Virtualized

// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";

import type { Selection } from "react-aria-components";

With Charts

// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";

import type { Selection, SortDescriptor } from "react-aria-components";

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: