flutter_grouped_table

A Flutter package for creating tables with merged cells (cell merge) support, especially useful for grouped headers.

Features

• ✅ Cell Merge Support: Merge cells across multiple rows/columns in headers and data rows
• ✅ Grouped Headers: Automatic multi-row header layout with nested structures (e.g., "Sales" with "Q1", "Q2", "Q3", "Q4" sub-headers)
• ✅ Row Span: Explicit row span support in data cells
• ✅ Column Span: Column span support in both headers and data rows
• ✅ Simple API: Easy-to-use API for common use cases with simple data structures
• ✅ Advanced API: Full control with data models for complex scenarios
• ✅ Customizable: Customize cell styles, colors, borders, and more
• ✅ Responsive: Use flex weights to control column sizes

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_grouped_table: ^1.0.1

Then run:

flutter pub get

Usage

Simple API (Recommended for Most Cases)

The simplest way to create a table is using GroupedTable.fromSimpleData():

import 'package:flutter_grouped_table/flutter_grouped_table.dart';

GroupedTable.fromSimpleData(
  headerRows: [
    [
      'Product',
      'Category',
      {'text': 'Sales', 'children': ['Q1', 'Q2', 'Q3', 'Q4']}
    ]
  ],
  dataRows: [
    ['Laptop', 'Electronics', '120', '150', '180', '200'],
    ['Smartphone', null, '250', '280', '300', '320'],
    ['Tablet', null, '80', '90', '100', '110'],
  ],
  rowSpanMap: {
    0: {1: 3}, // Row 0, Column 1 spans 3 rows
  },
  columnFlexWeights: [2, 1, 1, 1, 1, 1],
  // Optional: control the overall table size
  // tableWidth: 900,
  // tableHeight: 500,
  // tableConstraints: const BoxConstraints(minWidth: 900),
)

Key Points:

• Use null in data rows to indicate a cell is merged from the previous row
• Use rowSpanMap to specify which cells span multiple rows: {rowIndex: {colIndex: rowSpan}}
• For grouped headers, use a Map: {'text': 'Header', 'children': ['Sub1', 'Sub2']}

Row Span Example

To create vertically merged cells, use rowSpanMap:

GroupedTable.fromSimpleData(
  headerRows: [
    ['Product', 'Category', 'Q1', 'Q2', 'Q3', 'Q4']
  ],
  dataRows: [
    ['Laptop', 'Electronics', '120', '150', '180', '200'],
    ['Smartphone', null, '250', '280', '300', '320'], // null = merged from row 0
    ['Tablet', null, '80', '90', '100', '110'],       // null = merged from row 0
  ],
  rowSpanMap: {
    0: {1: 3}, // Row 0, Column 1 (Category) spans 3 rows
  },
)

Per-row and Per-cell Heights

You can control row heights per-row using the rowHeights parameter (passed to GroupedTable or fromSimpleData). A null entry falls back to the global rowHeight.

// Make some rows taller than the default 40.0
GroupedTable.fromSimpleData(
  headerRows: [ /* ... */ ],
  dataRows: [ /* ... */ ],
  rowHeight: 40.0,
  rowHeights: const [60.0, 40.0, 50.0, 40.0, 70.0],
);

If you need to override the height of a specific data cell, build the advanced API and set height on a GroupedTableDataCell.

final dataRows = [
  [
    GroupedTableDataCell.text('Laptop'),
    GroupedTableDataCell(
      child: const Text('Electronics'),
      height: 80.0, // cell-specific override
      rowSpan: 1,
    ),
    // ...
  ],
  // ...
];

GroupedTable(
  headerRows: [ /* ... */ ],
  dataRows: dataRows,
  rowHeight: 40.0,
);

Notes:

• GroupedTableDataCell.height takes precedence over rowHeights and rowHeight.
• Row-spanned cell heights are calculated as the sum of the effective heights of the spanned rows plus rowSpacing between rows.

Advanced API (Full Control)

For advanced use cases requiring custom widgets or fine-grained control:

final headerRow = [
  GroupedTableCell.simple('Product'),
  GroupedTableCell.simple('Category'),
  GroupedTableCell.grouped(
    text: 'Sales',
    children: [
      GroupedTableCell.simple('Q1'),
      GroupedTableCell.simple('Q2'),
      GroupedTableCell.simple('Q3'),
      GroupedTableCell.simple('Q4'),
    ],
  ),
];

final dataRows = [
  [
    GroupedTableDataCell.text('Laptop'),
    GroupedTableDataCell.rowSpan(
      child: const Text('Electronics'),
      rowSpan: 3,
    ),
    GroupedTableDataCell.text('120'),
    GroupedTableDataCell.text('150'),
    GroupedTableDataCell.text('180'),
    GroupedTableDataCell.text('200'),
  ],
  [
    GroupedTableDataCell.text('Smartphone'),
    GroupedTableDataCell.text('250'),
    GroupedTableDataCell.text('280'),
    GroupedTableDataCell.text('300'),
    GroupedTableDataCell.text('320'),
  ],
];

GroupedTable(
  headerRows: [headerRow],
  dataRows: dataRows,
  columnFlexWeights: [2, 1, 1, 1, 1, 1],
)

API Reference

GroupedTable.fromSimpleData

Factory constructor for creating tables from simple data structures.

Parameters

• headerRows (required): List of header rows. Each row can contain:
  • String: Simple header text
  • Map: Grouped header with {'text': 'Header', 'children': ['Sub1', 'Sub2']}
• dataRows (required): List of data rows. Each cell can be:
  • String: Text content
  • Widget: Custom widget
  • null: Merged cell (skipped, part of rowSpan from previous row)
  • TableCellData: Advanced cell configuration
• rowSpanMap: Map specifying row spans: {rowIndex: {colIndex: rowSpan}}
• columnFlexWeights: Flex weights for columns
• borderColor: Border color (default: Colors.black)
• borderWidth: Border width (default: 1.0)
• borderRadius: Table border radius
• headerBackgroundColor: Background color for header cells
• dataBackgroundColor: Background color for data cells
• headerTextStyle: Default text style for headers
• dataTextStyle: Default text style for data cells
• defaultHeaderHeight: Default header cell height (default: 40.0)
• rowHeight: Default data row height (default: 40.0)
• rowSpacing: Vertical spacing between rows (default: 0)

GroupedTable

Main table widget (advanced API).

Properties

• headerRows (required): List of header row configurations (List<List<GroupedTableCell>>)
• dataRows (required): List of data rows (List<List<GroupedTableDataCell>>)
• columnFlexWeights: Flex weights for columns
• borderColor: Border color (default: Colors.black)
• borderWidth: Border width (default: 1.0)
• borderRadius: Table border radius
• headerBackgroundColor: Background color for header cells
• dataBackgroundColor: Background color for data cells
• headerTextStyle: Default text style for headers
• dataTextStyle: Default text style for data cells
• defaultHeaderHeight: Default header cell height (default: 40.0)
• rowHeight: Default data row height (default: 40.0)
• rowSpacing: Vertical spacing between rows (default: 0)

GroupedTableCell

Represents a header cell in the table.

Constructors

• GroupedTableCell(): Default constructor
• GroupedTableCell.simple(String text): Simple text cell
• GroupedTableCell.merged(): Merged cell spanning multiple columns/rows
• GroupedTableCell.grouped(): Grouped header with nested children (automatically creates multi-row header)

GroupedTableDataCell

Represents a data cell in the table.

Constructors

• GroupedTableDataCell(): Default constructor with child widget
• GroupedTableDataCell.text(String text): Simple text cell
• GroupedTableDataCell.merged(): Merged cell spanning multiple columns/rows
• GroupedTableDataCell.rowSpan(): Cell with row span

TableCellData

Helper class for advanced cell configuration in simple API.

Constructors

• TableCellData.text(String text): Simple text cell
• TableCellData.rowSpan(dynamic value, int rowSpan): Cell with row span
• TableCellData.empty(): Empty cell (for merged cells)

Example

See the example/ folder for more examples.

cd example
flutter run

License

MIT License

Copyright (c) 2026 JeHee Yu