Flutter Basic Table #

A comprehensive and high-performance table widget for Flutter with Map-based column management, advanced sorting, selection, theming, and interactive features.

🚀 What's New in v2.0.0 #

⚡ Revolutionary Map-Based Architecture #

• 80% faster column reordering - No more row data reorganization
• ID-based column management - Direct access, no index confusion
• Persistent sort states - Sorting survives column reordering
• Enhanced type safety - Compile-time column validation

🎯 Key Improvements #

• Performance: Dramatically improved column operations
• Maintainability: Cleaner, more intuitive API
• Developer Experience: Advanced debugging and visualization
• Flexibility: Runtime column management made easy

⚠️ Breaking Changes: v2.0.0 introduces significant API changes. See our Migration Guide for upgrading from v1.x.

✨ Features #

🏗️ Core Architecture #

• Map-based column system with ID-based identification
• Order-driven rendering with automatic sorting
• Type-safe cell mapping with automatic fallbacks
• Intelligent state management with data validation

📊 Table Functionality #

• Advanced sorting with persistent state across reordering
• Drag-and-drop column reordering with order management
• Row selection with individual and bulk operations
• Cell interactions (tap, double-tap, right-click)
• Variable row heights with custom height support

🎨 Visual & Theming #

• Comprehensive theming system for all components
• Custom tooltips with overflow detection and formatters
• Status indicators with generic enum support
• Responsive design with flexible column widths
• Synchronized scrollbars with smooth interactions

🛠️ Developer Tools #

• Debug visualization with column order display
• Data validation with integrity checking
• Performance monitoring with built-in benchmarks
• Statistics generation for data analysis

📦 Installation #

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

dependencies:
  flutter_basic_table: ^2.0.0

Then run:

flutter pub get

🚀 Quick Start #

Basic Usage #

import 'package:flutter_basic_table/flutter_basic_table.dart';

class MyTableWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BasicTable(
      // Map-based column definition
      columns: {
        'id': BasicTableColumn(
          id: 'id',
          name: 'ID',
          order: 0,
          minWidth: 60,
        ),
        'name': BasicTableColumn(
          id: 'name',
          name: 'Name', 
          order: 1,
          minWidth: 120,
        ),
        'email': BasicTableColumn(
          id: 'email',
          name: 'Email',
          order: 2,
          minWidth: 200,
          tooltipFormatter: (value) => 'Email: $value',
        ),
      },
      
      // Map-based row data
      rows: [
        BasicTableRow(
          cells: {
            'id': BasicTableCell.text('1'),
            'name': BasicTableCell.text('John Doe'),
            'email': BasicTableCell.text('john@example.com'),
          },
          index: 0,
        ),
        BasicTableRow(
          cells: {
            'id': BasicTableCell.text('2'),
            'name': BasicTableCell.text('Jane Smith'),
            'email': BasicTableCell.text('jane@example.com'),
          },
          index: 1,
        ),
      ],
      
      // Enhanced features
      theme: MyCustomTheme.table,
      selectedRows: selectedRows,
      onRowSelectionChanged: (index, selected) {
        // Handle row selection
      },
      onColumnReorder: (columnId, newOrder) {
        // Handle column reordering with new signature
      },
      onColumnSortById: (columnId, sortState) {
        // Handle sorting with ID-based approach
      },
    );
  }
}

Advanced Features #

Custom Cell Types

// Status indicator cells
BasicTableCell.status(
  UserStatus.active,
  StatusConfig.simple(color: Colors.green, text: 'Active'),
)

// Custom widget cells
BasicTableCell.widget(
  IconButton(
    icon: Icon(Icons.edit),
    onPressed: () => editUser(userId),
  ),
)

// Rich text cells with custom styling
BasicTableCell.text(
  'Important',
  style: TextStyle(fontWeight: FontWeight.bold, color: Colors.red),
  backgroundColor: Colors.yellow.withOpacity(0.2),
)

Column Management

// Create columns with order management
final columns = {
  'id': BasicTableColumn.simple(name: 'ID', order: 0),
  'name': BasicTableColumn.simple(name: 'Name', order: 1),
  'status': BasicTableColumn(
    id: 'status',
    name: 'Status',
    order: 2,
    forceTooltip: true,
    tooltipFormatter: (value) => 'Current status: $value',
  ),
};

// Reorder columns programmatically
final reorderedColumns = BasicTableColumn.reorderColumn(
  columns, 
  'status', 
  0, // Move to first position
);

// Normalize orders if needed
final normalizedColumns = BasicTableColumn.normalizeOrders(columns);

State Management with ColumnSortManager

class TableController extends ChangeNotifier {
  final ColumnSortManager sortManager = ColumnSortManager();
  Map<String, BasicTableColumn> columns = {...};
  List<BasicTableRow> rows = [...];
  
  void sortColumn(String columnId, ColumnSortState state) {
    sortManager.setSortState(columnId, state);
    
    if (state != ColumnSortState.none) {
      rows.sort((a, b) {
        final valueA = a.getComparableValue(columnId);
        final valueB = b.getComparableValue(columnId);
        final comparison = valueA.compareTo(valueB);
        return state == ColumnSortState.ascending ? comparison : -comparison;
      });
    }
    
    notifyListeners();
  }
  
  void reorderColumn(String columnId, int newOrder) {
    columns = BasicTableColumn.reorderColumn(columns, columnId, newOrder);
    notifyListeners();
  }
}

🎨 Theming #

Create beautiful, consistent table designs:

final myTheme = BasicTableThemeData(
  headerTheme: BasicTableHeaderCellTheme(
    backgroundColor: Colors.blue[50],
    textStyle: TextStyle(fontWeight: FontWeight.bold, color: Colors.blue[800]),
    enableReorder: true,
    enableSorting: true,
  ),
  dataRowTheme: BasicTableDataRowTheme(
    backgroundColor: Colors.white,
    border: BorderSide(color: Colors.grey[300]!, width: 0.5),
  ),
  selectionTheme: BasicTableSelectionTheme(
    selectedRowColor: Colors.blue.withOpacity(0.1),
    hoverRowColor: Colors.grey.withOpacity(0.05),
  ),
  // ... more theme options
);

📱 Platform Support #

• ✅ Android
• ✅ iOS
• ✅ Web
• ✅ Windows
• ✅ macOS
• ✅ Linux

🔧 Migration from v1.x #

If you're upgrading from v1.x, please follow our comprehensive Migration Guide which includes:

• Step-by-step conversion instructions
• Before/after code examples
• Common gotchas and solutions
• Performance optimization tips

Quick Migration Example #

// Before (v1.x)
final columns = [
  BasicTableColumn(name: 'ID', minWidth: 60),
  BasicTableColumn(name: 'Name', minWidth: 120),
];

final rows = [
  BasicTableRow(
    cells: [
      BasicTableCell.text('1'),
      BasicTableCell.text('John'),
    ],
    index: 0,
  ),
];

// After (v2.0)
final columns = {
  'id': BasicTableColumn(id: 'id', name: 'ID', order: 0, minWidth: 60),
  'name': BasicTableColumn(id: 'name', name: 'Name', order: 1, minWidth: 120),
};

final rows = [
  BasicTableRow(
    cells: {
      'id': BasicTableCell.text('1'),
      'name': BasicTableCell.text('John'),
    },
    index: 0,
  ),
];

📊 Performance #

Benchmarks (v2.0 vs v1.x) #

Performance Tips #

// Cache sorted columns for multiple renders
final sortedColumns = BasicTableColumn.mapToSortedList(columns);

// Use batch operations for multiple changes
final updatedRow = row.updateCells({
  'name': BasicTableCell.text('New Name'),
  'status': BasicTableCell.text('Updated'),
});

// Validate data integrity periodically
if (!validateTableData(columns, rows)['is_valid']) {
  // Handle validation errors
}

🧪 Examples #

Check out the comprehensive example application that demonstrates:

• Basic table setup with Map-based columns
• Advanced sorting with persistent states
• Column reordering with visual feedback
• Row selection with bulk operations
• Custom theming with multiple presets
• Debug features for development
• Performance monitoring tools

Run the example:

cd example
flutter run

🤝 Contributing #

We welcome contributions! Please see our Contributing Guide for details.

Development Setup #

# Clone the repository
git clone https://github.com/kihyun1998/flutter_basic_table.git

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run example
cd example && flutter run

📝 API Documentation #

Comprehensive API documentation is available at pub.flutter-io.cn/documentation/flutter_basic_table.

Key Classes #

• BasicTable: Main table widget with Map-based architecture
• BasicTableColumn: Column definition with ID and order management
• BasicTableRow: Row data with Map-based cell structure
• ColumnSortManager: Advanced sort state management
• BasicTableThemeData: Comprehensive theming system
• StatusConfig: Generic status indicator configuration

🐛 Issues and Feedback #

Please file issues, bugs, and feature requests on our GitHub Issues page.

When reporting issues, please include:

• Flutter version
• Package version
• Platform (iOS, Android, Web, etc.)
• Minimal reproduction code
• Expected vs actual behavior

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Thanks to all contributors who helped make this library better
• Inspired by modern data table implementations across platforms
• Built with ❤️ for the Flutter community

Made with ❤️ by KiHyun Park

⭐ Star this repo if you found it helpful! ⭐