Components

TreeGrid

Headless hierarchical grid primitives combining tree expansion with grid cell navigation.

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

• 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.
• 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

See CHANGELOG.md.