Tree grid

Problem Context

• Rows represent nested objects such as folders and files, work breakdown structures, threaded records, accounts and subaccounts, requirements and tasks, or organization units and members.
• Users need to compare values across shared columns such as owner, status, due date, amount, count, permissions, or last activity.
• Parent rows can summarize, contain, select, lock, or expand child rows, and child rows may have independent values or actions.
• The interface may support editable cells, row actions, selection, bulk operations, sorting, filtering, lazy loading, pagination, or virtual scrolling.

Selection Rules

• Choose tree grid when hierarchical rows and tabular columns are both essential to the task.
• Use data grid when rows are flat and expansion is only a detail panel, grouping, or visual section.
• Use tree selection when users choose hierarchical nodes but do not need shared data columns or cell-level interaction.
• Use table when users only compare rows and any hierarchy can be represented by a separate column or grouping label.
• Use details panel or master-detail when a selected object's nested detail is easier to inspect beside the source grid than inline.
• Use accordion or disclosure details for short content groups that are not comparable rows.
• Avoid tree grid when parent-child relationships are decorative indentation rather than real containment.
• Avoid tree grid when sorting, filtering, lazy loading, or bulk selection cannot preserve descendant state truthfully.
• Avoid tree grid on narrow screens unless the product has a tested reduced-column, horizontal-scroll, or drill-in strategy.
• Avoid tree grid if the team cannot implement managed focus, aria-expanded, row levels, row positions, and screen reader verification.

Required States

• Default tree grid state with label, column headers, visible root rows, row hierarchy, row count context, and focused row or cell.
• Expanded parent row state with visible child rows, level indentation, and truthful aria-expanded state.
• Collapsed parent row state with child rows hidden, descendant count or state summary when relevant, and no focus left inside hidden rows.
• Leaf row state without expansion affordance or aria-expanded.
• Focused row or cell state that remains visually distinct from selected rows and checked rows.
• Single-select, multi-select, parent-selected, child-selected, and mixed-descendant states when selection is supported.
• Editable cell, readonly cell, dirty child row, invalid child value, saving, saved, and failed-save states when editing is supported.
• Sorted and filtered states that preserve hierarchy rules and explain hidden or empty parents.
• Lazy-loaded, loading-children, load-failed, virtualized, and paginated states with truthful row counts, levels, positions, and row indices.
• Narrow-screen state that preserves hierarchy, column meaning, expansion, and row actions or routes users to a focused detail view.

Interaction Contract

• The first column or row header communicates the hierarchical object name, level, expansion state, and parent-child relationship.
• Expansion and collapse affect only descendant rows and never leave keyboard focus on a hidden row.
• Rows without children do not expose expansion state or an inert disclosure control.
• Arrow keys move by row or cell according to the documented focus model; Right Arrow expands collapsed parents or moves into cells, and Left Arrow collapses expanded parents or moves toward row focus.
• Tab enters and exits the composite predictably and does not force users through every visible cell unless the row has an intentional inner-widget sequence.
• Selection is independent from focus in multi-select tree grids and makes descendant inclusion, exclusion, or mixed state explicit.
• Sorting, filtering, pagination, refresh, and lazy loading preserve expanded state, selected descendants, dirty edits, and focused row whenever possible.
• Parent rows state whether values are aggregates, inherited values, editable values, or actions that apply to descendants.

Implementation Checklist

• Define the hierarchy model, root rows, child rows, leaf rows, row identifiers, parent identifiers, columns, and expansion ownership.
• Choose whether focus is row-first, cell-first, or cell-only and document the keyboard model in the UI.
• Use treegrid, row, columnheader, rowheader, and gridcell semantics, or native table semantics with role treegrid when appropriate.
• Set aria-expanded only on parent rows or the controlling rowheader cell, and remove it from leaves.
• Expose aria-level, aria-posinset, aria-setsize, aria-rowcount, aria-colcount, aria-rowindex, and aria-colindex when rows or columns are dynamic, virtualized, lazy-loaded, or not all present in the DOM.
• Keep expansion icons decorative when their state is already exposed by the parent row or cell.
• Distinguish focus, selection, checked state, mixed descendant state, dirty edits, invalid cells, and loading children with text or programmatic state, not color alone.
• Define how sorting and filtering treat descendants, parent aggregates, collapsed selected children, lazy-loaded children, and empty parent branches.
• Test keyboard navigation, expansion, collapse, selection, editing, screen reader announcements, lazy loading, virtual scroll, high contrast, zoom, and mobile layouts.

Common Generated-UI Mistakes

• Using treegrid for a flat data grid with no expandable parent rows.
• Using treegrid for a simple folder tree that has only one label column and no tabular comparison.
• Putting aria-expanded on leaf rows or every first-column cell.
• Collapsing a parent while focus, validation, or dirty edits remain hidden inside descendants.
• Sorting child rows away from parents without explaining the hierarchy rule.
• Losing selected children when a parent is collapsed, filtered, virtualized, or paged away.
• Rendering nested tables inside expandable rows instead of one coherent row and column model.
• Treating parent rows, aggregate values, inherited values, and editable child values as the same interaction.

Critique Questions

• What parent-child relationship does the first column encode?
• Which rows are parents, which are leaves, and what happens to hidden descendants when a parent collapses?
• Does the task require comparing columns across hierarchical rows, or is a tree selection enough?
• Is focus row-first, cell-first, or cell-only, and can users recover after expansion, collapse, sort, filter, and lazy load?
• Are selected, focused, mixed, dirty, invalid, readonly, and loading states visibly and programmatically distinct?
• Would a flat data grid, table, tree selection, details panel, accordion, or drill-in route be less costly?