Skip to main content

Column Groups

Column groups organize related leaf columns under a shared visual header band. They make wide data grids easier to scan without changing the dataset schema or the behavior of the individual columns.

Column groups
Loading FDC sample…
FdcGrid(
  dataSet: customers,
  options: const FdcGridOptions(
    readOnly: true,
    allowColumnReordering: true,
  ),
  columnGroups: const <FdcGridColumnGroup>[
    FdcGridColumnGroup(id: 'customer', label: 'Customer'),
    FdcGridColumnGroup(id: 'location', label: 'Location'),
  ],
  columns: const <FdcGridColumn<dynamic>>[
    FdcIntegerColumn<dynamic>(fieldName: 'customer_id', width: 96),
    FdcTextColumn<dynamic>(
      fieldName: 'company_name',
      width: 210,
      groupId: 'customer',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'contact_name',
      width: 165,
      groupId: 'customer',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'city',
      width: 135,
      groupId: 'location',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'state',
      width: 90,
      groupId: 'location',
    ),
    FdcTextColumn<dynamic>(fieldName: 'industry', width: 145),
    FdcComboColumn<String>(fieldName: 'status', width: 110),
    FdcDecimalColumn<dynamic>(fieldName: 'credit_limit', width: 145),
  ],
);

The sample groups customer identity and location fields while leaving operational fields such as Status, Industry, and Credit Limit outside the groups. Long-press and drag a compatible header to reorder columns inside the same group.

Define column groups​

Declare the available groups on the grid, then connect each leaf column through groupId:

FdcGrid(
  dataSet: customers,
  columnGroups: const <FdcGridColumnGroup>[
    FdcGridColumnGroup(
      id: 'customer',
      label: 'Customer',
    ),
    FdcGridColumnGroup(
      id: 'location',
      label: 'Location',
    ),
  ],
  columns: const <FdcGridColumn<dynamic>>[
    FdcTextColumn<dynamic>(
      fieldName: 'company_name',
      groupId: 'customer',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'contact_name',
      groupId: 'customer',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'city',
      groupId: 'location',
    ),
    FdcTextColumn<dynamic>(
      fieldName: 'state',
      groupId: 'location',
    ),
  ],
)

FdcGridColumnGroup.id is the stable link between the group definition and its leaf columns. label is rendered in the upper header band.

What grouping changes​

Grouping is visual layout metadata. It does not change:

  • dataset fields or records;
  • editing, filtering, or sorting behavior;
  • summaries or row rendering;
  • column value callbacks.

A grouped column remains a normal field-bound column. The group only affects header layout and compatible column-moving boundaries.

Column moving inside groups​

When column reordering is enabled, a grouped column can move only within its current group. Grouped and ungrouped columns cannot be mixed by dragging, and a column cannot be dragged directly from one group into another.

These boundaries preserve the semantic meaning of each group while still allowing users to personalize the order of columns inside it.

Groups and pinning​

Column groups and pinning can coexist in the same grid, but a column cannot be pinned while it belongs to a group. Pinning actions are therefore available only for ungrouped columns.

For a focused example where every displayed column can be pinned interactively, see Column Pinning.