Tree Table

ProNew

A table with expandable parent rows (role treegrid), sortable columns that sort within each parent and row navigation by keyboard.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it for hierarchical figures: budgets by team, file sizes by folder, tasks with subtasks, orders with line items.

Do not use it for a flat table (use a data grid) or when cells hold many interactive controls; row-level focus is not meant for that.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tree-table

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode<T>[]`	-	Rows. Put the figures in `data`.
`columns`	`TreeTableColumn<T>[]`	-	`id`, `header`, `cell`, `sortValue`, `align`. The first column holds the indent, chevron and label.
`sort / defaultSort / onSortChange`	`{ columnId, direction } \| null`	`null`	Sorting state.
`indent`	`number`	`20`	Pixels per level.
`aria-label`	`string`	-	Required name of the grid.
`...`	-	-	All `useTree` options (expansion, selection, `dir`).

Accessibility

The table has role treegrid; rows carry aria-level, aria-posinset, aria-setsize and aria-expanded.
Sortable headers have aria-sort and a button; the sort applies within each parent so a parent stays above its children.
Rows are the tab stops (one at a time), so a screen reader hears the row, then its cells.

Keyboard

ArrowDown / ArrowUp: move between rows. Home / End: first or last row.
ArrowRight: open a parent row; again to enter its first child. ArrowLeft: close it, or move to the parent.
Space: select the row when selection is on. Enter: activate.
The sort buttons in the header are normal buttons in the tab order.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (tree-table.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it for hierarchical figures: budgets by team, file sizes by folder, tasks with subtasks, orders with line items.

Do not use it for a flat table (use a data grid) or when cells hold many interactive controls; row-level focus is not meant for that.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tree-table

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode<T>[]`	-	Rows. Put the figures in `data`.
`columns`	`TreeTableColumn<T>[]`	-	`id`, `header`, `cell`, `sortValue`, `align`. The first column holds the indent, chevron and label.
`sort / defaultSort / onSortChange`	`{ columnId, direction } \| null`	`null`	Sorting state.
`indent`	`number`	`20`	Pixels per level.
`aria-label`	`string`	-	Required name of the grid.
`...`	-	-	All `useTree` options (expansion, selection, `dir`).

Accessibility

The table has role treegrid; rows carry aria-level, aria-posinset, aria-setsize and aria-expanded.
Sortable headers have aria-sort and a button; the sort applies within each parent so a parent stays above its children.
Rows are the tab stops (one at a time), so a screen reader hears the row, then its cells.

Keyboard

ArrowDown / ArrowUp: move between rows. Home / End: first or last row.
ArrowRight: open a parent row; again to enter its first child. ArrowLeft: close it, or move to the parent.
Space: select the row when selection is on. Enter: activate.
The sort buttons in the header are normal buttons in the tab order.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (tree-table.test.tsx) that covers its keyboard paths, roles and states.