Data Grid

When to Use

Use DataGrid when users must move through rows and columns with the keyboard or select rows in an interactive table. Use a native table when people only need to read data; native tables are simpler and already accessible. Use TreeGrid when rows expand into a hierarchy. DataGrid does not provide sorting logic, editing, resizing, filtering, or virtualization—it exposes the states needed to connect those application features.

Features

The behavior Atom owns before your product adds appearance.

• Implements grid, rowgroup, row, columnheader, and gridcell semantics.
• Keeps focus on Root and identifies the active cell with aria-activedescendant.
• Supports controlled active cell and none, single, or multiple row selection.
• Navigates in document order while skipping disabled cells.
• Supports row/column counts, looping, row wrapping, and row-click selection.
• Gives actionable column headers equivalent pointer and Enter activation.
• Mirrors horizontal arrows in RTL.
• Supports native table rendering plus asChild and render composition.

Import

import { DataGrid } from "@flowstack-ui/atom";

Anatomy

<DataGrid.Root>
  <DataGrid.Caption />
  <DataGrid.Header>
    <DataGrid.Row>
      <DataGrid.ColumnHeader />
    </DataGrid.Row>
  </DataGrid.Header>
  <DataGrid.Body>
    <DataGrid.Row>
      <DataGrid.Cell />
    </DataGrid.Row>
  </DataGrid.Body>
  <DataGrid.Footer />
</DataGrid.Root>

API Reference

All rendered parts accept the native props for their default table element and support asChild and render.

Root

Renders a focusable table, owns active-cell navigation and row selection, and provides the grid context.

Counts are truncated to positive integers. Missing or invalid counts are announced as -1, meaning the total is unknown.

Caption

Renders the native caption that names or summarizes the grid for table users.

Header

Renders a thead row group for heading rows.

Row

Renders a tr, supplies row metadata to its cells, and optionally participates in selection. rowIndex is one-based; zero-based index is converted to one-based.

Rows need value to be selectable. selectable={false} keeps an identified header, footer, or summary row out of selection without disabling its cells.

ColumnHeader

Renders a th registered as a navigable cell. It exposes sort state but does not change sorting when clicked.

Body

Renders a tbody row group for the main data rows.

Cell

Renders a registered td. Clicking an enabled indexed Cell makes it active and focuses Root; missing indexes make it non-navigable without announcing it as disabled.

Footer

Renders a tfoot row group for totals and summary rows.

Advanced custom parts can use the public useDataGridContext and useDataGridRowContext hooks. The row hook returns null outside Row; the main hook must be used inside Root. Prefer the namespaced parts for standard grids.

Examples

Selectable Project Grid

import { DataGrid } from "@flowstack-ui/atom";

const projects = [
  { id: "alpha", name: "Alpha", status: "Ready" },
  { id: "bravo", name: "Bravo", status: "Review" },
];

export function ProjectGrid() {
  return (
    <DataGrid.Root
      aria-label="Projects"
      rowCount={projects.length + 1}
      columnCount={2}
      selectionMode="multiple"
      defaultValue={["alpha"]}
      selectOnRowClick
    >
      <DataGrid.Caption>Current projects</DataGrid.Caption>
      <DataGrid.Header>
        <DataGrid.Row rowIndex={1} selectable={false}>
          <DataGrid.ColumnHeader columnIndex={1}>Name</DataGrid.ColumnHeader>
          <DataGrid.ColumnHeader columnIndex={2}>Status</DataGrid.ColumnHeader>
        </DataGrid.Row>
      </DataGrid.Header>
      <DataGrid.Body>
        {projects.map((project, index) => (
          <DataGrid.Row key={project.id} rowIndex={index + 2} value={project.id}>
            <DataGrid.Cell columnIndex={1}>{project.name}</DataGrid.Cell>
            <DataGrid.Cell columnIndex={2}>{project.status}</DataGrid.Cell>
          </DataGrid.Row>
        ))}
      </DataGrid.Body>
    </DataGrid.Root>
  );
}

Controlled Sort Metadata

import { useState } from "react";
import { DataGrid, type DataGridSortDirection } from "@flowstack-ui/atom";

export function SortableHeader() {
  const [direction, setDirection] = useState<DataGridSortDirection>("ascending");

  return (
    <DataGrid.Root aria-label="People" rowCount={1} columnCount={1}>
      <DataGrid.Header>
        <DataGrid.Row rowIndex={1} selectable={false}>
          <DataGrid.ColumnHeader
            columnIndex={1}
            sortDirection={direction}
            onAction={() => setDirection(
              direction === "ascending" ? "descending" : "ascending",
            )}
          >
            Name
          </DataGrid.ColumnHeader>
        </DataGrid.Row>
      </DataGrid.Header>
    </DataGrid.Root>
  );
}

Accessibility

DataGrid follows the WAI-ARIA Grid pattern. Provide an accessible name with Caption, aria-label, or aria-labelledby. Every navigable row and cell needs a valid one-based index. Root receives DOM focus while aria-activedescendant identifies the active Cell.

readOnly prevents selection changes but still permits navigation. disabled prevents Root keyboard handling. Rows with selectable={false} ignore row selection from click, Enter, and Space.

ColumnHeader.onAction is the pointer/keyboard activation boundary for application-controlled sorting or another header command. Atom calls it after an enabled indexed header is clicked and when Enter is pressed while that header is active. Atom does not change sortDirection or reorder data. Consumer onClick remains a native pointer-only escape hatch and may prevent Atom's composed pointer behavior with event.preventDefault().

Changelog

Unreleased

0.24.0

• Added source-led Agent Knowledge for grid selection, indexed semantics, active-descendant focus, row selection, header actions, and virtualization boundaries.

0.17.0

• Added ColumnHeader.onAction with data-actionable and equivalent pointer and active-header Enter dispatch for application-controlled sorting.

0.2.0

• Fixed vertical keyboard navigation to preserve the active column while skipping disabled cells in intervening rows.
• Added DataGrid.Row selectable behavior with data-selectable and data-selection-disabled attributes so rows can opt out of selection without being disabled.
• Added dir and Direction.Provider support so horizontal cell navigation mirrors in RTL.

0.1.0

• Initial Atom release.