Grouping & Hierarchy
A single auto group column with indented hierarchy, expand/collapse, drag-and-drop dimension reordering, and per-group counts/aggregation.
Installation
Grouping is an opt-in prop on Data Table — pass grouping and get an auto group column, expand/collapse, and per-group aggregation. Dimension Picker adds a drag-and-drop control for changing the hierarchy at runtime; it's optional and the only piece that depends on dnd-kit.
Works with:Data TableDimension Picker
npx shadcn@latest add @kotsas-ui/data-tablenpx shadcn@latest add @kotsas-ui/dimension-pickerUsage
Group by a single dimension with a name-only leaf — the smallest useful config.
| Account | Bank | Ccy | Balance |
|---|---|---|---|
Acme Robotics Inc(3) | 1,828,610.52 | ||
Globex Trading Ltd(3) | 1,181,045.90 | ||
Initech Software BV(3) | 846,380.75 | ||
Umbrella Health SAS(3) | 307,321.02 | ||
Wayne Industries GmbH(3) | 3,420,430.00 |
Examples
Two-level grouping with a rich leaf: the left-most column renders the hierarchy, and leaf rows use the declarative leaf (primary required; icon and secondary optional) or renderLeaf for full control.
| Account | Ccy | Balance |
|---|---|---|
Acme Robotics Inc(3) | 1,828,610.52 | |
Globex Trading Ltd(3) | 1,181,045.90 | |
Initech Software BV(3) | 846,380.75 | |
Umbrella Health SAS(3) | 307,321.02 | |
Wayne Industries GmbH(3) | 3,420,430.00 |
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| grouping.dimensions | { id; label }[] | — | Which columns the Group-by picker offers. Each id must match a column with enableGrouping: true. |
| grouping.initial? | string[] | [] | Hierarchy order at mount, e.g. ["entity", "bank"]. Applied once — use the renderControl slot's setGrouping to change it after mount. |
| grouping.renderControl? | (ctx) => ReactNode | — | Toolbar control for changing the hierarchy at runtime. Pass Dimension Picker's <DimensionPicker /> here, or omit for a fixed hierarchy. |
| grouping.column.header? | string | — | Header text for the synthesized group column, e.g. "Account". |
| grouping.column.leaf? | { primary; secondary?; icon? } | — | Declarative leaf rendering — a primary label with optional icon and muted secondary line. |
| grouping.column.renderLeaf? | (row) => ReactNode | — | Full-control leaf renderer; takes precedence over leaf. |
| grouping.column.countMode? | "leaf" | "immediate" | "leaf" | How the (count) next to a group label is computed — total leaf descendants, or direct sub-rows. |
| ColumnDef.aggregationFn? | "sum" | "mean" | … | — | Per-column TanStack aggregation shown on group rows (pair with aggregatedCell for formatting). |