Form Upload

Estimated reading: 5 minutes 25 views

FlutKit provides a set of flexible and reusable file upload components designed to handle common upload scenarios such as drag-and-drop uploads, form-based file selection, preview uploads, and avatar uploads.
Each component is optimized for clarity, validation, and ease of integration into form workflows.

Drag & Drop Upload

DragDropUpload is designed for modern drag-and-drop file uploads, especially suitable for dashboard and web-based interfaces.

Constructor

Dart

DragDropUpload({
  Key? key,
  void Function(List<String>, List<Map<String, dynamic>>)? onFilesChanged,
  String? instructionText,
  IconData? icon,
  String? Function(List<String>, List<Map<String, dynamic>>)? validator,
})

DragDropUpload({
  Key? key,
  void Function(List<String>, List<Map<String, dynamic>>)? onFilesChanged,
  String? instructionText,
  IconData? icon,
  String? Function(List<String>, List<Map<String, dynamic>>)? validator,
})

Parameter	Description
`key`	Widget key untuk Flutter tree management.
`onFilesChanged`	Callback yang dipanggil setiap kali file ditambahkan atau dihapus. Mengembalikan `fileNames` dan `webFiles` (metadata file untuk Web).
`instructionText`	Teks instruksi yang ditampilkan pada area upload (misalnya: “Drag files here or click to upload”).
`icon`	Icon opsional yang ditampilkan di area upload untuk meningkatkan visual cue.
`validator`	Fungsi validasi kustom untuk memeriksa file sebelum dianggap valid (misalnya ukuran atau tipe file).

Example

Dart

DragDropUpload(
  onFilesChanged: (fileNames, webFiles) {
    // handle uploaded files
  },
),

DragDropUpload(
  onFilesChanged: (fileNames, webFiles) {
    // handle uploaded files
  },
),

Use cases

Drag-and-drop document upload
Media uploads with validation
Web-based file handling

File Upload Form

FileUploadForm is a form-integrated file picker that supports single and multiple file uploads, validation, and size variants.

Constructor

Dart

FileUploadForm({
  Key? key,
  bool allowMultiple = false,
  bool enabled = true,
  FormSize size = FormSize.medium,
  String? buttonText,
  String? fieldText,
  String? Function(List<PlatformFile>?)? validator,
  void Function(List<PlatformFile>?)? onSaved,
  dynamic Function(List<PlatformFile>)? onFilesSelected,
  List<PlatformFile>? initialValue,
  String? successMessage,
})

FileUploadForm({
  Key? key,
  bool allowMultiple = false,
  bool enabled = true,
  FormSize size = FormSize.medium,
  String? buttonText,
  String? fieldText,
  String? Function(List<PlatformFile>?)? validator,
  void Function(List<PlatformFile>?)? onSaved,
  dynamic Function(List<PlatformFile>)? onFilesSelected,
  List<PlatformFile>? initialValue,
  String? successMessage,
})

Parameter	Description
`key`	Widget identifier dalam Flutter widget tree.
`allowMultiple`	Menentukan apakah pengguna boleh memilih lebih dari satu file.
`enabled`	Jika `false`, tombol upload akan dinonaktifkan.
`size`	Mengontrol ukuran UI komponen (`small`, `medium`, `large`).
`buttonText`	Teks pada tombol upload.
`fieldText`	Placeholder atau label pada field upload.
`validator`	Fungsi validasi form untuk memeriksa file yang dipilih.
`onSaved`	Callback yang dipanggil saat form disimpan (`FormState.save()`).
`onFilesSelected`	Callback utama saat file berhasil dipilih oleh user.
`initialValue`	File awal yang sudah terpilih (misalnya saat edit form).
`successMessage`	Pesan sukses yang ditampilkan setelah upload berhasil.

Single File Upload

Dart

FileUploadForm(
  onFilesSelected: (files) {
    for (var file in files) {
      // handle file
    }
  },
),

FileUploadForm(
  onFilesSelected: (files) {
    for (var file in files) {
      // handle file
    }
  },
),

Multiple Files Upload

Dart

FileUploadForm(
  allowMultiple: true,
  onFilesSelected: (files) {
    for (var file in files) {
      // handle files
    }
  },
),

FileUploadForm(
  allowMultiple: true,
  onFilesSelected: (files) {
    for (var file in files) {
      // handle files
    }
  },
),

Custom Text

Dart

FileUploadForm(
  buttonText: 'Upload File',
  fieldText: 'Select document',
  onFilesSelected: (files) {
    for (var file in files) {
      // handle file
    }
  },
),

FileUploadForm(
  buttonText: 'Upload File',
  fieldText: 'Select document',
  onFilesSelected: (files) {
    for (var file in files) {
      // handle file
    }
  },
),

Disabled State

Dart

FileUploadForm(
  enabled: false,
  onFilesSelected: (files) {
    for (var file in files) {
      // disabled upload
    }
  },
),

FileUploadForm(
  enabled: false,
  onFilesSelected: (files) {
    for (var file in files) {
      // disabled upload
    }
  },
),

Size Variants

Small

Dart

FileUploadForm(
  size: FormSize.small,
  onFilesSelected: (files) {},
),

FileUploadForm(
  size: FormSize.small,
  onFilesSelected: (files) {},
),

Medium

Dart

FileUploadForm(
  size: FormSize.medium,
  onFilesSelected: (files) {},
),

FileUploadForm(
  size: FormSize.medium,
  onFilesSelected: (files) {},
),

Large

Dart

FileUploadForm(
  size: FormSize.large,
  onFilesSelected: (files) {},
),

FileUploadForm(
  size: FormSize.large,
  onFilesSelected: (files) {},
),

Upload with Preview

UploadPreview extends the drag-and-drop experience by displaying a preview of uploaded files.

Constructor

Dart

UploadPreview({
  Key? key,
  void Function(List<String>, List<Map<String, dynamic>>)? onFilesChanged,
  String? instructionText,
  IconData? icon,
  String? Function(List<String>, List<Map<String, dynamic>>)? validator,
})

UploadPreview({
  Key? key,
  void Function(List<String>, List<Map<String, dynamic>>)? onFilesChanged,
  String? instructionText,
  IconData? icon,
  String? Function(List<String>, List<Map<String, dynamic>>)? validator,
})

Parameter	Description
`key`	Widget key untuk kontrol widget tree.
`onFilesChanged`	Callback untuk mengelola file dan preview-nya.
`instructionText`	Instruksi teks pada area upload.
`icon`	Icon visual pendukung pada UI.
`validator`	Validasi custom terhadap file sebelum ditampilkan sebagai preview.

Example

Dart

UploadPreview(
  onFilesChanged: (fileNames, webFiles) {
    // handle preview files
  },
),

UploadPreview(
  onFilesChanged: (fileNames, webFiles) {
    // handle preview files
  },
),

Use cases

Image uploads
Media previews before submission
UX-focused upload flows

Avatar Upload

AvatarUpload is optimized for profile image uploads with built-in size and file type validation.

Constructor

Dart

AvatarUpload({
  Key? key,
  required double maxSizeBytes,
  required List<String> allowedExtensions,
  required void Function(PlatformFile?) onChanged,
  String? instructionText,
  String? disableText,
  bool enabled = true,
  double radius = 80,
})

AvatarUpload({
  Key? key,
  required double maxSizeBytes,
  required List<String> allowedExtensions,
  required void Function(PlatformFile?) onChanged,
  String? instructionText,
  String? disableText,
  bool enabled = true,
  double radius = 80,
})

Parameter	Description
`key`	Widget identifier.
`maxSizeBytes`	Ukuran maksimum file dalam bytes (misalnya 2 MB).
`allowedExtensions`	Daftar ekstensi file yang diizinkan (`jpg`, `png`, dll).
`onChanged`	Callback saat file dipilih atau dihapus (`null` jika dihapus).
`instructionText`	Teks instruksi upload avatar.
`disableText`	Teks yang ditampilkan saat komponen dalam keadaan disabled.
`enabled`	Mengaktifkan atau menonaktifkan upload.
`radius`	Radius avatar (mengontrol ukuran visual avatar).

Example

Dart

AvatarUpload(
  instructionText: "Drop or browse image (JPG, PNG)",
  maxSizeBytes: 2 * 1024 * 1024, // 2 MB
  allowedExtensions: ['jpg', 'jpeg', 'png'],
  radius: 80,
  enabled: true,
  onChanged: (file) {
    if (file != null) {
      debugPrint("Selected file: ${file.name}");
    } else {
      debugPrint("File removed");
    }
  },
),

AvatarUpload(
  instructionText: "Drop or browse image (JPG, PNG)",
  maxSizeBytes: 2 * 1024 * 1024, // 2 MB
  allowedExtensions: ['jpg', 'jpeg', 'png'],
  radius: 80,
  enabled: true,
  onChanged: (file) {
    if (file != null) {
      debugPrint("Selected file: ${file.name}");
    } else {
      debugPrint("File removed");
    }
  },
),

Use cases

Profile picture upload
User account settings
Avatar replacement with validation

Demo

To see this component in action, please refer to the demo available under Forms → File Upload