Implementing Syncfusion Flutter DataGrid

A comprehensive skill for implementing and customizing the Syncfusion Flutter DataGrid (SfDataGrid) control. The DataGrid displays and manipulates data in a tabular format with support for columns, editing, sorting, filtering, grouping, summaries, paging, and export features.

When to Use This Skill

Use this skill when you need to:

Display tabular data in a Flutter application
Bind data sources (List, ObservableList) to a grid
Configure columns (auto-generated or manual)
Implement cell editing and styling
Add sorting, filtering, or searching functionality
Group data and display summaries/aggregates
Implement paging or incremental loading
Enable row operations (drag-drop, swipe, add/delete)
Export grid data to Excel or PDF
Customize grid appearance and behavior
Optimize performance for large datasets
Handle keyboard navigation and accessibility

Component Overview

The Syncfusion Flutter DataGrid (SfDataGrid) is a high-performance data grid control for displaying and manipulating tabular data in Flutter applications. It supports comprehensive data management features including sorting, filtering, grouping, and summarization. The grid is highly customizable and optimized for both small and large datasets with efficient virtualization and paging support.

SfDataGrid excels at:

Displaying structured data in rows and columns
Interactive data exploration with sorting and filtering
Complex data analysis with grouping and summaries
Large dataset handling with virtualization and paging
Data entry and validation with in-cell editing
Data export to Excel and PDF formats
Building responsive data-driven dashboards and reports

Key Capabilities

Data Binding Options: Support for List and ObservableList data sources
Flexible Column Configuration: Manual column definition support
In-Cell Editing: Edit cell content with validation and custom editors
Advanced Sorting: Single and multi-column sorting with custom logic
Powerful Filtering: Built-in and custom filtering predicates
Data Grouping: Group data by one or more columns with expand/collapse
Aggregate Summaries: Group and caption summaries with built-in functions
Selection Modes: Single, multiple, or no selection with event fallbacks
Paging & Virtualization: Efficient handling of large datasets with data virtualization
Export Capabilities: Export to Excel (.xlsx) and PDF formats with customization
Row Operations: Swipe actions, drag-drop, and dynamic row height
Freezing Support: Freeze columns and rows for better navigation
Comprehensive Styling: Cell, row, header styling with conditional formatting
Accessibility: Keyboard navigation and screen reader support

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Installation and pub package setup
Adding dependency to pubspec.yaml
Importing the datagrid package
Creating your first datagrid
Minimal working sample

Data Binding

📄 Read: references/data-binding.md

Basic DataGrid implementation
Creating data models and DataGridSource
Binding with List and ObservableList

Column Types

📄 Read: references/column-types.md

Manually defining columns
Column properties (columnName, label, width)
Column sizing and width options
Column visibility and ordering
Checkbox column and customization
Header icon visiblity

Column Sizing

📄 Read: references/column-sizing.md

Column width configuration modes
Auto-fit and fill modes
Manual column resizing
Width calculation strategies
Dynamic width adjustment

Column Resizing

📄 Read: references/column-resizing.md

Enable/disable column resizing
Resize interaction and UX
Programmatic resizing
Resize events and callbacks
Auto-fit column width

Column Drag and Drop

📄 Read: references/column-drag-and-drop.md

Enable column reordering via drag-drop
Column reorder events
Programmatic column reordering
Drag-drop constraints and behavior

Stacked Headers

📄 Read: references/stacked-headers.md

Multi-level column headers
Stacked header configuration
Spanning columns across headers
Header customization and styling

Freeze Panes

📄 Read: references/freeze-panes.md

Frozen columns (left side)
Frozen rows (top side)
Freeze pane configuration
Scrolling with frozen panes

Scrolling

📄 Read: references/scrolling.md

Horizontal and vertical scrolling
Scroll behavior customization
Programmatic scrolling
Scroll events and callbacks
Virtual scrolling performance

Editing

📄 Read: references/editing.md

Enabling editing
Column-level editing control
Edit triggers and modes
Cell editing events (onBeginEdit, onEndEdit)
Programmatic editing
Enter arrow and Tab key navigation during editing

Sorting

📄 Read: references/sorting.md

Single and multi-column sorting
Custom sorting logic
Programmatic sorting
Sort icons and UI customization
Sort order behavior

Filtering

📄 Read: references/filtering.md

Filtering functionality basics
Filter types and predicates
Programmatic filtering
Custom filter logic
Filter UI customization

Selection

📄 Read: references/selection.md

Selection modes (Single, Multiple, None)
Selection events (onSelectionChanging, onSelectionChanged)
Programmatic selection
Current cell vs selected rows

Grouping

📄 Read: references/grouping.md

Data grouping (single and multi-column)
Group expand/collapse behavior
Custom grouping logic
Group header customization

Summaries

📄 Read: references/summaries.md

Summary rows (Group and Caption summaries)
Built-in aggregate functions (Sum, Average, Count, Min, Max)
Custom summary calculations
Summary display formatting
Summary footer configuration

Paging

📄 Read: references/paging.md

Paging setup and configuration
Page size and page navigation
Custom paging UI
Programmatic page navigation
Page change events

Load More

📄 Read: references/load-more.md

Incremental loading setup
Load More row handling
Load More triggers and events
Programmatic load more control
Large dataset pagination strategies

Pull to Refresh

📄 Read: references/pull-to-refresh.md

Pull to refresh gestures
Refresh event handling
Custom refresh UI
Loading state management
Data refresh patterns

Row Height Customization

📄 Read: references/row-height-customization.md

Row height configuration
Auto row height based on content
QueryRowHeight event usage
Dynamic row height adjustment
Header row height customization

Swiping

📄 Read: references/swiping.md

Row swiping gestures
Swipe actions and commands
Swipe event handling
Custom swipe action UI
Swipe extent configuration

Styles

📄 Read: references/styles.md

Grid styling basics
Cell styling (DataGridCellStyle)
Conditional cell styling
Row styling and alternating row colors
Header styling
Theme customization

Conditional Styling

📄 Read: references/conditional-styling.md

Apply styles based on cell/row data
Dynamic styling logic
Style builders and callbacks
Performance optimization for conditional styles

Placeholder

📄 Read: references/placeholder.md

Empty DataGrid view
Custom placeholder widgets
Loading state display
No data message customization

Export to Excel

📄 Read: references/export-to-excel.md

Export DataGrid to Excel
Excel export customization (columns, rows, styling)
Excel export options and events
File save and sharing

Export to PDF

📄 Read: references/export-to-pdf.md

Export DataGrid to PDF
PDF export customization
Page orientation and sizing
PDF export events
File save and sharing

Footer

📄 Read: references/footer.md

Footer row configuration
Summary display in footer
Custom footer content
Footer styling

Accessibility

📄 Read: references/accessibility.md

Keyboard navigation
Screen reader support
Accessibility best practices

Localization

📄 Read: references/localization.md

Localization setup
Multi-language support

Right-to-Left

📄 Read: references/right-to-left.md

RTL (Right-to-Left) support
Text direction customization

Quick Start Example

Step 1: Add Package

bash

# Always installs the latest compatible version automatically
flutter pub add syncfusion_flutter_datagrid

Always install the package via terminal — do not edit
pubspec.yaml
directly. Run this command from the Flutter project root and wait for it to complete successfully before proceeding.

Step 2: Create Data Model

dart

class OrderInfo {
  int orderId;
  String customerId;
  String shipCountry;
  double freight;
  DateTime orderDate;

  OrderInfo({
    required this.orderId,
    required this.customerId,
    required this.shipCountry,
    required this.freight,
    required this.orderDate,
  });
}

Step 3: Create DataGridSource

dart

import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class OrderDataSource extends DataGridSource {
  late List<OrderInfo> _orders;

  OrderDataSource(List<OrderInfo> orders) {
    _orders = orders;
    buildDataGridRows();
  }

  List<DataGridRow> dataGridRows = [];

  @override
  List<DataGridRow> get rows => dataGridRows;

  void buildDataGridRows() {
    dataGridRows = _orders
        .map<DataGridRow>((order) => DataGridRow(cells: [
              DataGridCell<int>(columnName: 'orderId', value: order.orderId),
              DataGridCell<String>(columnName: 'customerId', value: order.customerId),
              DataGridCell<String>(columnName: 'shipCountry', value: order.shipCountry),
              DataGridCell<double>(columnName: 'freight', value: order.freight),
              DataGridCell<DateTime>(columnName: 'orderDate', value: order.orderDate),
            ]))
        .toList();
  }

  @override
  DataGridRowAdapter? buildRow(DataGridRow row) {
    return DataGridRowAdapter(cells: [
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[0].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[1].value.toString()),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[2].value.toString()),
      ),
      Container(
        alignment: Alignment.centerRight,
        padding: const EdgeInsets.all(8.0),
        child: Text('\$${row.getCells()[3].value.toStringAsFixed(2)}'),
      ),
      Container(
        alignment: Alignment.centerLeft,
        padding: const EdgeInsets.all(8.0),
        child: Text(row.getCells()[4].value.toString().split(' ')[0]),
      ),
    ]);
  }
}

Step 4: Add DataGrid to View

dart

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_datagrid/datagrid.dart';

class DataGridPage extends StatefulWidget {
  const DataGridPage({Key? key}) : super(key: key);

  @override
  State<DataGridPage> createState() => _DataGridPageState();
}

class _DataGridPageState extends State<DataGridPage> {
  late List<OrderInfo> _orders;
  late OrderDataSource _orderDataSource;

  @override
  void initState() {
    super.initState();
    _orders = getOrders();
    _orderDataSource = OrderDataSource(_orders);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('DataGrid'),
      ),
      body: SfDataGrid(
        source: _orderDataSource,
        columns: [
          GridColumn(
            columnName: 'orderId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Order ID'),
            ),
          ),
          GridColumn(
            columnName: 'customerId',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Customer Name'),
            ),
          ),
          GridColumn(
            columnName: 'shipCountry',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Ship Country'),
            ),
          ),
          GridColumn(
            columnName: 'freight',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerRight,
              child: const Text('Freight'),
            ),
          ),
          GridColumn(
            columnName: 'orderDate',
            label: Container(
              padding: const EdgeInsets.all(16.0),
              alignment: Alignment.centerLeft,
              child: const Text('Order Date'),
            ),
          ),
        ],
      ),
    );
  }

  List<OrderInfo> getOrders() {
    return [
      OrderInfo(
        orderId: 1001,
        customerId: 'ALFKI',
        shipCountry: 'Germany',
        freight: 32.38,
        orderDate: DateTime(2024, 01, 15),
      ),
      OrderInfo(
        orderId: 1002,
        customerId: 'FRANS',
        shipCountry: 'Mexico',
        freight: 11.61,
        orderDate: DateTime(2024, 01, 14),
      ),
      OrderInfo(
        orderId: 1003,
        customerId: 'MEREP',
        shipCountry: 'Canada',
        freight: 45.34,
        orderDate: DateTime(2024, 01, 13),
      ),
    ];
  }
}

Key Properties and Configuration

Property	Type	Description
`source`	DataGridSource	Data source for the grid (required)
`columns`	List<GridColumn>	Column definitions (required)
`rowHeight`	double	Default row height
`headerRowHeight`	double	Height of header row
`allowSorting`	bool	Enable sorting
`allowMultiColumnSorting`	bool	Enable multi-column sorting
`allowFiltering`	bool	Enable filtering
`allowEditing`	bool	Enable cell editing
`navigationMode`	GridNavigationMode	Row or Cell navigation
`selectionMode`	SelectionMode	None, Single, or Multiple
`frozenColumnsCount`	int	Number of frozen columns from left
`frozenRowsCount`	int	Number of frozen rows from top
`columnWidthMode`	ColumnWidthMode	Auto, Fill, None

Common Patterns

Pattern 1: Sorting with Multi-Column Support

Enable single and multi-column sorting with visual indicators:

dart

SfDataGrid(
  source: _employeeDataSource,
  allowSorting: true,
  allowMultiColumnSorting: true,
  allowTriStateSorting: true,
  showSortNumbers: true,
  columns: _columns,
)

Add programmatic sorting:

dart

_employeeDataSource.sortedColumns.add(
  SortColumnDetails(
    name: 'name',
    sortDirection: DataGridSortDirection.ascending,
  ),
);
_employeeDataSource.sort();

Pattern 2: Filtering with Programmatic and UI Support

Enable both programmatic and UI-based filtering:

dart

SfDataGrid(
  source: _employeeDataSource,
  allowFiltering: true,
  columns: _columns,
  onFilterChanging: (DataGridFilterChangeDetails details) {
    // Optional: validate before applying filter
    return true;
  },
  onFilterChanged: (DataGridFilterChangeDetails details) {
    // Optional: handle post-filter notification
    print('Filtered column: ${details.column.columnName}');
  },
)

Add programmatic filters:

dart

// Add single condition
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    type: FilterType.greaterThanOrEqual,
    value: 50000,
  ),
);

// Add multiple conditions (AND operator)
_employeeDataSource.addFilter(
  'salary',
  FilterCondition(
    value: 100000,
    type: FilterType.lessThanOrEqual,
    filterOperator: FilterOperator.and,
  ),
);

// Clear filters
_employeeDataSource.clearFilters('salary');

Pattern 3: Grouping with Custom Captions and Expand/Collapse

Implement hierarchical data grouping with expand/collapse functionality:

dart

// In initState
_employeeDataSource.addColumnGroup(
  ColumnGroup(name: 'city', sortGroupRows: true),
);

// In widget build
SfDataGrid(
  source: _employeeDataSource,
  controller: _dataGridController,
  allowExpandCollapseGroup: true,
  autoExpandGroups: false,
  groupCaptionTitleFormat: '{ColumnName}: {Key} ({ItemsCount} records)',
  groupExpanded: (DataGridGroupChangedDetails group) {
    print('Group expanded: ${group.key}');
  },
  groupCollapsed: (DataGridGroupChangedDetails group) {
    print('Group collapsed: ${group.key}');
  },
  columns: _columns,
)

Programmatic expand/collapse:

dart

// Expand all groups
_dataGridController.expandAllGroup();

// Collapse groups at specific level
_dataGridController.collapseGroupsAtLevel(1);

Common Use Cases

Use Case	Key Features	Reference Files
Basic data display	Data binding, columns	getting-started.md, column-types.md
Editable grid	Cell editing, validation	editing.md, data-binding.md
Sortable/filterable table	Sorting, filtering	sorting.md, filtering.md
Grouped data with totals	Grouping, summaries	grouping.md, summaries.md
Large dataset	Paging, Load More	paging.md, load-more.md
Data export	Excel/PDF export	export-to-excel.md, export-to-pdf.md
Responsive layout	Column sizing, scrolling	column-sizing.md, scrolling.md
Custom cell layouts	Templates, styling	styles.md, conditional-styling.md

Troubleshooting

DataGrid not showing data:

Verify
```
source
```
is set with a valid DataGridSource
Check that
```
columns
```
are defined
Ensure
```
buildDataGridRows()
```
is called in DataGridSource constructor
Verify data model is not empty

Editing not working:

Set
```
allowEditing=true
```
Set
```
navigationMode
```
to
```
GridNavigationMode.cell
```
Set
```
selectionMode
```
to Single or Multiple
Check column's
```
allowEditing
```
property

Sorting not working:

Enable
```
allowSorting=true
```
on the SfDataGrid
Verify column header is tappable (check
```
GridColumn.allowSorting
```
is not
```
false
```
)
Check that custom
```
compare()
```
method is implemented correctly in DataGridSource if using custom sorting
For async sorting, override
```
performSorting()
```
in DataGridSource

Filtering not working:

Enable
```
allowFiltering=true
```
on the SfDataGrid
Verify column header has filter icon visible (check
```
GridColumn.allowFiltering
```
is not
```
false
```
)
For programmatic filters, ensure column name in
```
addFilter()
```
matches exact
```
GridColumn.columnName
```
Check
```
FilterCondition.type
```
is appropriate for the data type
Verify
```
effectiveRows
```
returns filtered results; use
```
clearFilters()
```
to reset all filters

Grouping not showing:

Ensure
```
addColumnGroup()
```
is called before building the grid
Verify
```
ColumnGroup.name
```
exactly matches a
```
GridColumn.columnName
```
Check that grouping column contains non-null values
Enable
```
allowExpandCollapseGroup=true
```
to show expand/collapse UI
Use
```
DataGridController
```
with
```
expandAllGroup()
```
to verify grouping is working

Multi-Column Sorting not working:

Set
```
allowMultiColumnSorting=true
```
on the SfDataGrid
For web/desktop: hold Ctrl while clicking column headers to add additional sort columns
Check
```
sortedColumns
```
list to verify multiple sort entries exist
Call
```
sort()
```
after modifying
```
sortedColumns
```
programmatically

Custom Grouping Logic not applied:

Override
```
performGrouping()
```
in DataGridSource
Return the custom group key as a String
Ensure the method returns non-null values for proper grouping

Next Steps

Start with references/getting-started.md for basic setup
Configure columns using references/column-types.md
Add interactivity with editing, sorting, and filtering
Optimize for your data size using paging or virtualization
Customize appearance with styling and templates

syncfusion-flutter-datagrid

NPX Install

Tags

SKILL.md Content

Implementing Syncfusion Flutter DataGrid

When to Use This Skill

Component Overview

Key Capabilities

Documentation and Navigation Guide

Getting Started

Data Binding

Column Types

Column Sizing

Column Resizing

Column Drag and Drop

Stacked Headers

Freeze Panes

Scrolling

Editing

Sorting

Filtering

Selection

Grouping

Summaries

Paging

Load More

Pull to Refresh

Row Height Customization

Swiping

Styles

Conditional Styling

Placeholder

Export to Excel

Export to PDF

Footer

Accessibility

Localization

Right-to-Left

Quick Start Example

Step 1: Add Package

Step 2: Create Data Model

Step 3: Create DataGridSource

Step 4: Add DataGrid to View

Key Properties and Configuration

Common Patterns

Pattern 1: Sorting with Multi-Column Support

Pattern 2: Filtering with Programmatic and UI Support

Pattern 3: Grouping with Custom Captions and Expand/Collapse

Common Use Cases

Troubleshooting

Next Steps