Tree Grid

When to Use

Use TreeGrid when hierarchical rows expand and each row also contains several navigable columns, such as a file browser with size and modified-date columns. Use Tree for one-column hierarchies and DataGrid when rows are flat rather than parent and child nodes.

Features

The behavior Atom owns before your product adds appearance.

• Implements role="treegrid" with row, row header, column header, and gridcell parts.
• Supports controlled and uncontrolled expansion.
• Supports controlled and uncontrolled active cell state.
• Supports optional row selection with selectable parent rows.
• Hides descendant rows when parent rows are collapsed.
• Supports RTL-aware cell navigation and tree expand/collapse keys through dir and Direction.Provider.
• Moves an active descendant cell to its collapsed ancestor's tree-column cell when controlled or uncontrolled expansion hides that descendant.
• Gives actionable column headers equivalent pointer and Enter activation.
• Keeps sorting, filtering, resizing, editing, and virtualization outside the primitive.

Import

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

Anatomy

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

API Reference

Root

Owns hierarchical visibility, active-cell navigation, optional row selection, expansion, direction, and the single focus target for the entire grid.

Caption

Provides a visible accessible name or description for the treegrid.

Header

Groups header Rows and ColumnHeader cells above the scrollable body.

Row

Registers one hierarchical row, its parent, visibility, expansion, selection, and normalized row index for all cells inside it.

ColumnHeader

Renders a navigable header cell, optional sort state, and the normalized column coordinate used by Root navigation.

Body

Groups the visible hierarchical data Rows below Header.

RowHeader

Renders the cell that names its Row. Clicking it focuses the cell and toggles the row when expandable.

Cell

Renders a navigable data cell and registers its normalized column coordinate with the current Row.

Footer

Groups optional summary Rows after Body.

Advanced compound parts can use useTreeGridContext and useTreeGridRowContext with their matching public providers.

Examples

Expandable Rows

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

export default function PlatformTreeGrid() {
  return (
    <TreeGrid.Root
      defaultExpandedValue={["platform"]}
      aria-label="Platform files"
      columnCount={2}
    >
      <TreeGrid.Header>
        <TreeGrid.Row value="headers">
          <TreeGrid.ColumnHeader columnIndex={1}>Name</TreeGrid.ColumnHeader>
          <TreeGrid.ColumnHeader columnIndex={2}>Type</TreeGrid.ColumnHeader>
        </TreeGrid.Row>
      </TreeGrid.Header>
      <TreeGrid.Body>
        <TreeGrid.Row rowIndex={1} value="platform" expandable selectable={false}>
          <TreeGrid.RowHeader columnIndex={1}>Platform</TreeGrid.RowHeader>
          <TreeGrid.Cell columnIndex={2}>Folder</TreeGrid.Cell>
        </TreeGrid.Row>
        <TreeGrid.Row rowIndex={2} value="api" parentValue="platform">
          <TreeGrid.RowHeader columnIndex={1}>API</TreeGrid.RowHeader>
          <TreeGrid.Cell columnIndex={2}>Folder</TreeGrid.Cell>
        </TreeGrid.Row>
      </TreeGrid.Body>
    </TreeGrid.Root>
  );
}

Accessibility

TreeGrid follows the WAI-ARIA treegrid pattern with Root focus and aria-activedescendant. Provide an accessible name with Caption, aria-label, or aria-labelledby.

Changelog

Unreleased

0.24.0

• Added source-led Agent Knowledge for hierarchical grid selection, indexed relationships, expansion, active-cell focus, row selection, header actions, and virtualization boundaries.

0.18.0

• Added ColumnHeader.onAction with equivalent enabled pointer and active-cell Enter activation.
• Relocate active state to a collapsed ancestor's tree-column cell when a controlled or uncontrolled collapse hides the active descendant.

0.2.0

• Added Direction.Provider and dir support to mirror TreeGrid horizontal cell navigation and expand/collapse arrow behavior in RTL.

0.1.0

• Initial Atom release.