sheet_mapper

pub package License: MIT

A powerful Flutter package for mapping Excel, CSV, TSV, and PSV files to Dart objects using annotations and code generation, featuring a beautiful drag-and-drop UI widget.

Preview

Sheet Mapper Demo

Author

Abdul Waseem Nihaal

Features

  • Multiple File Formats - Excel (.xlsx, .xls, .xlsm), CSV, TSV, PSV
  • Type-Safe Code Generation - Like json_serializable and freezed
  • Beautiful Drag-Drop UI - Customizable widget for file upload
  • Flexible Annotations - Optional column mapping
  • Default Values - Automatic handling of empty cells
  • Type Conversions - String, int, double, bool, DateTime
  • Error Handling - Comprehensive validation and error messages
  • Zero Dependencies on UI - Use programmatically without the widget
  • Cross-Platform - Android, iOS, Web, Windows, macOS, Linux

Installation

Add to your pubspec.yaml:

dependencies:
  sheet_mapper: ^1.0.0

dev_dependencies:
  build_runner: ^2.4.0
  sheet_mapper_generator: ^1.0.0

Then run:

flutter pub get

Quick Start

1. Define Your Model

import 'package:sheet_mapper/sheet_mapper.dart';

part 'user.g.dart';

@SheetTable()
class User with _$UserSheetMapper {
  @SheetColumn('Full Name', required: true)
  final String name;

  @SheetColumn('Email', required: true)
  final String email;

  @SheetColumn('Age', defaultValue: '0')
  final int age;

  User({
    required this.name,
    required this.email,
    required this.age,
  });
}

2. Generate Code

dart run build_runner build --delete-conflicting-outputs

3. Use the Widget

SheetMapperWidget<User>(
  onResult: (List<User> users) {
    print('Parsed ${users.length} users');
  },
  onError: (String error) {
    print('Error: $error');
  },
)

4. Or Use Programmatically

// Parse directly using generated mixin
final users = _$UserSheetMapper.fromSheet(rows);

// Or parse from file
final file = File('users.xlsx');
final bytes = await file.readAsBytes();
final rows = SheetParser.parseBytes(bytes, SheetType.xlsx);
final users = _$UserSheetMapper.fromSheet(rows);

Annotations

@SheetTable

@SheetTable(
  sheetName: 'Users',      // Excel sheet name (optional)
  sheetIndex: 0,           // Sheet index (default: 0)
  hasHeader: true,         // First row is header (default: true)
  startRow: 0,             // Skip rows (optional)
)
class User with _$UserSheetMapper { ... }

@SheetColumn

@SheetColumn(
  'Column Name',           // Header name
  defaultValue: '0',       // Default if empty (optional)
  dateFormat: 'yyyy-MM-dd',// Date format (optional)
  required: false,         // Throw error if missing (default: false)
  trim: true,              // Trim whitespace (default: true)
)
final String fieldName;

Note: If @SheetColumn is not provided, the field name is used as the column name.

Widget Customization

SheetMapperWidget<User>(
  supportedSheetTypes: [SheetType.xlsx, SheetType.csv],
  height: 250,
  borderColor: Colors.deepPurple,
  borderWidth: 2.0,
  dashPattern: [10, 5],
  backgroundColor: Colors.purple.withOpacity(0.1),
  instructionText: 'Drop your file here',
  icon: Icons.cloud_upload,
  iconSize: 60,
  iconColor: Colors.deepPurple,
  borderRadius: 16,
  onResult: (data) => print('Success'),
  onError: (error) => print('Error: $error'),
)

Supported Types

Type Description Notes
String Direct text Default: "-" if empty
int Integer numbers Nullable by default
double Decimal numbers Nullable by default
bool Boolean Accepts: true/false, 1/0, yes/no
DateTime Date/time ISO8601 or custom format

All types support nullable versions (String?, int?, etc.).

Platform Support

Platform Support
Android ✅
iOS ✅
Web ✅
Windows ✅
macOS ✅
Linux ✅

License

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

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

Libraries

sheet_mapper
sheet_mapper_core
Core sheet_mapper exports without Flutter dependencies