skills/syncfusion-flutter-datagrid/references/stacked-headers.md

Stacked Headers — Flutter DataGrid

Overview

SfDataGrid supports multi-level column headers (stacked headers) via SfDataGrid.stackedHeaderRows. Each StackedHeaderRow contains StackedHeaderCell entries that span multiple columns, creating a hierarchical header structure.

---

Required Imports

import 'package:syncfusion_flutter_core/theme.dart';
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

---

Basic Stacked Header

Group columns under a single stacked header row:

SfDataGrid(
  gridLinesVisibility: GridLinesVisibility.both,
  headerGridLinesVisibility: GridLinesVisibility.both,
  source: _productDataSource,
  columns: <GridColumn>[
    GridColumn(
      columnName: 'orderId',
      label: Container(
        padding: EdgeInsets.symmetric(horizontal: 16.0),
        alignment: Alignment.centerRight,
        child: Text('ID', overflow: TextOverflow.ellipsis)
      )
    ),
    GridColumn(
      columnName: 'customerName',
      label: Container(
        padding: EdgeInsets.symmetric(horizontal: 16.0),
        alignment: Alignment.centerLeft,
        child: Text('Name', overflow: TextOverflow.ellipsis)
      )
    ),
    GridColumn(
      columnName: 'productId',
      label: Container(
        padding: EdgeInsets.symmetric(horizontal: 16.0),
        alignment: Alignment.centerRight,
        child: Text('ID', overflow: TextOverflow.ellipsis)
      )
    ),
    GridColumn(
      columnName: 'product',
      label: Container(
        padding: EdgeInsets.symmetric(horizontal: 16.0),
        alignment: Alignment.centerLeft,
        child: Text('Product', overflow: TextOverflow.ellipsis)
      )
    ),
  ],
  stackedHeaderRows: <StackedHeaderRow>[
    StackedHeaderRow(cells: [
      StackedHeaderCell(
        columnNames: ['orderId', 'customerName'],
        child: Container(
          color: const Color(0xFFF1F1F1),
          child: Center(child: Text('Customer Details'))
        )
      ),
      StackedHeaderCell(
        columnNames: ['productId', 'product'],
        child: Container(
          color: const Color(0xFFF1F1F1),
          child: Center(child: Text('Product Details'))
        )
      )
    ])
  ]
)

---

Multi-Level Stacked Headers

Add multiple StackedHeaderRow entries for a deeper hierarchy (first row = topmost header):

stackedHeaderRows: <StackedHeaderRow>[
  StackedHeaderRow(cells: [
    StackedHeaderCell(
      columnNames: ['orderId', 'customerName', 'productId', 'product'],
      child: Container(
        color: const Color(0xFFF1F1F1),
        child: Center(child: Text('Order Shipment Details'))
      )
    ),
  ]),
  StackedHeaderRow(cells: [
    StackedHeaderCell(
      columnNames: ['orderId', 'customerName'],
      child: Container(
        color: const Color(0xFFF1F1F1),
        child: Center(child: Text('Customer Details'))
      )
    ),
    StackedHeaderCell(
      columnNames: ['productId', 'product'],
      child: Container(
        color: const Color(0xFFF1F1F1),
        child: Center(child: Text('Product Details'))
      )
    )
  ])
]

---

Changing Stacked Header Row Height

Use onQueryRowHeight to set height for stacked header rows. Stacked header rows appear before the column header row (row index 0 = first stacked header, last row = column headers):

SfDataGrid(
    source: _productDataSource,
    onQueryRowHeight: (RowHeightDetails details) {
      if (details.rowIndex == 0) {
        return 70.0;  // height for first stacked header row
      }
      return details.rowHeight;
    },
    columns: columns,
    stackedHeaderRows: stackedHeaderRows)

You can also change the header row height globally using SfDataGrid.headerRowHeight (applies to both column header row and stacked header rows).

---

Key Property Reference

SfDataGrid Properties

Property	Type	Description
stackedHeaderRows	List<StackedHeaderRow>	Collection of stacked header rows to display above column headers

StackedHeaderRow Properties

Property	Type	Description
cells	List<StackedHeaderCell>	Stacked header cells in this row

StackedHeaderCell Properties

Property	Type	Description
columnNames	List<String>	Column names this cell spans (must match GridColumn.columnName)
child	Widget	Widget to display in the stacked header cell

---

Key Notes

• StackedHeaderCell.columnNames must exactly match GridColumn.columnName values.
• The first StackedHeaderRow in the list appears at the top; the column headers appear last.
• Use gridLinesVisibility and headerGridLinesVisibility together for consistent grid lines across stacked headers.