Skip to main content

Column groups

Nest children to create multi-row headers. Groups may be nested to any depth, and leaf columns keep their ordinary pinning, filtering, sizing, and state.

Loading interactive example…
React
const columns: ReactColDef[] = [{
  label: "Revenue",
  openByDefault: true,
  children: [
    { key: "revenue", label: "Gross" },
    { key: "margin", label: "Margin", columnGroupShow: "open" },
  ],
}];

<Grid rowData={rows} columnDefs={columns} />

Nested column groups​

const columnDefs: ColDef[] = [
  {
    colId: "customer",
    label: "Customer",
    openByDefault: true,
    children: [
      { key: "firstName", label: "First name", columnGroupShow: "open" },
      { key: "lastName", label: "Last name" },
    ],
  },
  {
    label: "Order",
    children: [
      { key: "total", label: "Total", type: ColumnType.CURRENCY },
      { key: "status", label: "Status" },
    ],
  },
];

The group chevron expands/collapses children. Nested groups may be used at more than one level.

Expansion​

openByDefault controls a group's initial state. A leaf with columnGroupShow: "open" is visible only while its parent is expanded; "closed" provides the inverse behavior. Manually hidden active leaves remain hidden when the group state changes. A group renders its expander only when its children mix columnGroupShow values — a group whose children all toggle together has nothing to expand.

The same state is readable and settable programmatically, by the group's colId: api.getColumnGroupState() lists every group as { colId, open }, and api.setColumnGroupState(groups) opens or closes the groups it names in one rebuild, leaving the rest alone. Saved views capture and restore it, so give groups an explicit colId for that state to survive a reload.

api.setColumnGroupState([{ colId: "customer", open: false }]);
api.getColumnGroupState(); // [{ colId: "customer", open: false }, ...]

Groups also appear as collapsible branches in the column panel. Searching a group name reveals its descendants, while reordering remains constrained to a valid hierarchy.

Pinned boundaries

A group can contain leaves in different pinned sections, but cell spans and drag targets never cross a pinned-section boundary.