Table·hook·@astryxdesign/core

useTableTreeData

Headless tree plugin for Table: renders nested rows with per-level indentation and expand/collapse chevrons in the tree column (the first column by default), and reflects hierarchy on body rows via aria-level and aria-expanded. Composable with the other Table plugins: the canonical plugin order places tree before selection, so the checkbox column lands left of the indented tree column. Feed it the treeConfig from useTableTreeState, or construct the config directly for server-driven or pre-flattened trees. When no row is expandable (flat data), every transform is a pass-through and the table renders identically to one without the plugin. Known limitation: the tree column wraps its cell content, so textOverflow="truncate" tooltips do not apply within the tree column.

Open in Playground @astryxdesign/core/Table

Signature

Call shape

useTableTreeData()

Showcases and examples

1 documented example

useTableTreeData: Tree Table

A file-tree table built from nested data. useTableTreeState flattens the tree into the visible rows and owns the expanded set; useTableTreeData draws the per-level indent and the expand/collapse chevron in the tree column. The two hooks are designed to work together, so this one example covers both. hasExpandAllControl adds the expand-all/collapse-all toggle to the tree column header. Collapsed branches are unmounted, not hidden.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · table-tree-table

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {
  Table,
  useTableTreeData,
  useTableTreeState,
  proportional,
  pixel,
} from '@astryxdesign/core/Table';

interface FileNode extends Record<string, unknown> {
  id: string;
  name: string;
  kind: 'folder' | 'file';
  size: string;
  children?: FileNode[];
}

const fileTree: FileNode[] = [
  {
    id: 'src',
    name: 'src',
    kind: 'folder',
    size: '',
    children: [
      {
        id: 'src/components',
        name: 'components',
        kind: 'folder',
        size: '',
        children: [
          {
            id: 'src/components/Button.tsx',
            name: 'Button.tsx',
            kind: 'file',
            size: '4.2 KB',
          },
          {
            id: 'src/components/Table.tsx',
            name: 'Table.tsx',
            kind: 'file',
            size: '12.8 KB',
          },
        ],
      },
      {id: 'src/index.ts', name: 'index.ts', kind: 'file', size: '0.4 KB'},
    ],
  },
  {id: 'package.json', name: 'package.json', kind: 'file', size: '1.8 KB'},
];

const columns = [
  {key: 'name', header: 'Name', width: proportional(2)},
  {key: 'kind', header: 'Kind', width: pixel(90)},
  {key: 'size', header: 'Size', width: pixel(90)},
];

export default function TableTreeTable() {
  // useTableTreeState owns the expanded set and flattens the nested data into
  // the visible rows; useTableTreeData draws the indent + expander in the tree
  // column. hasExpandAllControl adds the expand-all toggle to the header.
  const {visibleData, treeConfig} = useTableTreeState<FileNode>({
    data: fileTree,
    idKey: 'id',
    defaultExpandedIds: ['src'],
  });

  const tree = useTableTreeData({...treeConfig, hasExpandAllControl: true});

  return (
    <Table
      data={visibleData}
      columns={columns}
      idKey="id"
      hasHover
      plugins={{tree}}
    />
  );
}

Usage

Typed props

Prop	Type and behavior
`getRowMeta`	`(item: T) => TableTreeRowMeta \| undefined` · required Structural meta for a visible row: {id, level (0-based), hasChildren, isExpanded}.
`onToggleItem`	`(item: T) => void` · required Toggle a row's expansion.
`hasExpandableRows`	`boolean` · required Whether any row in the dataset is expandable. When false the plugin is a no-op: no expanders, no indent, no tree ARIA.
`hasExpandAllControl`	`boolean` · default false Show an expand-all/collapse-all toggle in the tree column header. Requires isAllExpanded plus onExpandAll/onCollapseAll (all supplied by useTableTreeState).
`isAllExpanded`	`boolean \| 'indeterminate'` Aggregate expansion state across every expandable row, driving the header expand-all toggle. true when all are expanded, false when none are, indeterminate when some are.
`onExpandAll`	`() => void` Expand every expandable row. Wired to the header control.
`onCollapseAll`	`() => void` Collapse every row. Wired to the header control.
`indent`	`'sm' \| 'md' \| 'lg'` · default 'md' Indent step per level, mapped to the spacing-3 / spacing-4 / spacing-6 tokens.
`treeColumnKey`	`string` Column that carries the indent + expander. Defaults to the first column.
`hasRowClickExpansion`	`boolean` · default false When true, clicking anywhere on an expandable row toggles its expansion, in addition to the chevron. A pointer-only convenience: keyboard and assistive-tech users toggle via the chevron button. Clicks on interactive cell content (buttons, links, form controls) or a text selection do not toggle. Leaf rows stay inert, and it is a no-op on flat data.