Documentation
Guides

Master-detail

Let rows expand into an area below their cells that holds another grid or any component, under virtualization, from the keyboard, as divs or as a table.

A row can expand. An expanded row grows by its detail's height, and below its cells a detail area shows whatever you put there: another grid, a summary, controls. The rows keep their indexes, so the windows, getRow and rows.changed work as before.

Master-detail
Gallery

Install row expansion

Expanding rows is a feature: rowExpansion() from the /row-expansion entry, which holds the detail's part too (RowDetail and useRowDetail; Angular: DataGridRowDetail, injectRowDetail and the root's DataGridRowExpansion). Without it, no row expands and no detail renders: the expansion's commands, keys and props (expandedRowKeys, detailHeight, estimatedDetailHeight) do not compile. A detail's place on the rows' axis, its size and its measuring stay the core's.

orders.tsx
import { navigation } from "@fragiola/data-grid-react/navigation";
import { RowDetail, rowExpansion } from "@fragiola/data-grid-react/row-expansion";

const features = [navigation(), rowExpansion()];

Expanding rows

The grid keeps which rows are expanded, by their key (rowKey, else their index). Keyed by row, an expansion follows its record when you sort or filter the rows you pass. A row that is not loaded yet is never expanded, because its key is unknown until it loads.

The control that expands a row is yours, for example a button in a cell. It runs a command and carries aria-expanded:

expander.tsx
function Expander({ rowIndex }: { rowIndex: number }) {
    const { model } = useDataGrid<Order, typeof features>();
    const expanded = model.is("row-expanded", { rowIndex });
    return (
        <button
            type="button"
            aria-expanded={expanded}
            aria-label={expanded ? "Hide items" : "Show items"}
            onClick={() => model.run("expanded-rows.toggle", { rowIndex })}
        />
    );
}
commanddoes
expanded-rows.toggle { rowIndex }expands a loaded row, or collapses it
expanded-rows.toggle { rowKey }the same, by key, whether its row is loaded or not
expanded-rows.set { rowKeys }replaces the expanded keys (an "expand all" is yours)

model.is("row-expanded", { rowIndex }) tells whether a row shows its detail, and model.get("expanded-row-keys") lists the keys. A middleware can refuse a toggle, as any command.

On Root, the expansion is controlled or not, like the sort: defaultExpandedRowKeys starts it, and expandedRowKeys with onExpandedRowKeysChange controls it.

The detail area

Give Root a detailHeight, a number or a function of the row, and render RowDetail inside each Row, after its cells:

orders.tsx
// a function defined once: a new one on every render would lay the rows out again each time
const detailHeight = (order: Order) => 40 + order.items.length * 24;

<DataGrid.Root
    features={features}
    columns={columns}
    rows={orders}
    rowKey={(order) => order.id}
    detailHeight={detailHeight}
>
    <DataGrid.Grid aria-label="Orders">
        <DataGrid.Header />
        <DataGrid.Body>
            <DataGrid.Rows<Order>>
                {(row) => (
                    <DataGrid.Row row={row}>
                        <DataGrid.Cells />
                        <RowDetail>
                            {row.row ? <OrderItems order={row.row} /> : null}
                        </RowDetail>
                    </DataGrid.Row>
                )}
            </DataGrid.Rows>
        </DataGrid.Body>
    </DataGrid.Grid>
</DataGrid.Root>

RowDetail renders its children only while its row is expanded. It sits below the row's own height, as wide as the visible area, and it stays in view while the grid scrolls sideways, with or without pinned columns. The row carries data-expanded meanwhile, and its box holds the detail, so a row's background covers both.

The part is a block, so lay out its content inside your own element. As a table, render it as a <td> (render={<td />}), which then gets a colSpan over every column.

Rows expanding or collapsing above the view keep the view where it is.

A detail as tall as its content

detailHeight="auto" measures each detail once it renders: no height to compute, the detail is as tall as what you put in it (its padding and borders included), and estimatedDetailHeight (300 by default) until it is measured. A detail that grows later (content loading into it) lays the rows out again, the view kept where it is. It works with rows of a fixed height and with measured rows. The example's switch measures its details.

Keys and focus

  • The arrows, Home, End, Page Up and Page Down move between rows' cells and never land in a detail. Moving onto an expanded row brings its cells into view, not the end of its detail.
  • A detail's content owns its keys and its focus. A grid inside it is its own grid, with its own active cell, and a control inside it is yours, like content in DataGrid.Empty.
  • A grid in a detail is in the tab order only while its row holds the active cell, so Tab goes from the row into its items and Shift+Tab comes back, and Escape in a detail returns to the row's first cell. See Nested grids.

ARIA

A detail is one cell of its row: role="gridcell", aria-colindex="1" and an aria-colspan over every column. Expanding a row changes no aria-rowcount and no aria-rowindex, so the counts stay the data's, even in a getRow grid whose rows load as you scroll.