Skip to main content

antd_upload 1.0.0 copy "antd_upload: ^1.0.0" to clipboard
antd_upload: ^1.0.0 copied to clipboard

Ant Design v6 Upload component for Flutter. File selection upload with file list display, upload progress, preview and remove, aligned with antd React Upload API.

antd_upload - Flutter upload list with custom file types #

English | 简体中文

Positioning & design #

antd_upload is the file-list and upload-state layer of an upload flow, not a transport. It owns the trigger button, the selected-file list with progress, thumbnails, per-item status, and removal/preview affordances, while your code decides how files are picked and how bytes reach the server. AntUpload<T> is generic in the payload stored on each file record, so a row can carry a domain object (a parsed response, a document entity, a media descriptor) instead of a raw map.

Design rules:

  • Files are values. AntUploadFile<T> is immutable; progress updates go through copyWith, so state transitions are explicit and testable.
  • Picking and transport are separate hooks. onSelectFiles returns the rows to add (after your own picker or a synthetic source), and customRequest receives one row plus a progress callback, which is where HTTP, signing, or chunking lives.
  • Controlled and uncontrolled lists coexist. fileList is the source of truth when supplied; otherwise defaultFileList seeds internal state and onChange reports every mutation.
  • The list is the visual contract. listType switches between text rows and picture cards, and showUploadList can hide the list while keeping selection active for custom layouts.

Installation #

Requires Dart >=3.0.0 and Flutter >=3.10.0.

dependencies:
  antd_upload: ^1.0.0

Wrap the subtree in AntTheme so triggers, borders, and status colors come from the design tokens:

AntTheme(
  data: AntThemeData.light(),
  child: MaterialApp(home: YourPage()),
)

Quick start #

import 'package:antd_theme/antd_theme.dart';
import 'package:antd_upload/antd_upload.dart';
import 'package:material_ui/material_ui.dart';

class Attachment {
  const Attachment({required this.id, required this.name});

  final String id;
  final String name;
}

Future<List<AntUploadFile<Attachment>>> pickDocuments() async {
  final stamp = DateTime.now().microsecondsSinceEpoch;
  return <AntUploadFile<Attachment>>[
    AntUploadFile<Attachment>(
      uid: 'doc-$stamp',
      name: 'report.pdf',
      size: 20480,
      extra: Attachment(id: 'doc-$stamp', name: 'report.pdf'),
    ),
  ];
}

void main() => runApp(
      AntTheme(
        data: AntThemeData.light(),
        child: MaterialApp(
          home: Scaffold(
            body: Padding(
              padding: const EdgeInsets.all(16),
              child: AntUpload<Attachment>(
                multiple: true,
                uploadButtonText: 'Select files',
                onSelectFiles: pickDocuments,
                onChange: (file, list) {
                  debugPrint('${list.length} rows, last ${file.status}');
                },
              ),
            ),
          ),
        ),
      ),
    );

onSelectFiles returns the rows to add — in a real app that is where you invoke a platform picker. Each returned row enters the list as uploading; with no customRequest the widget marks it done, so this example is self-contained.

API #

API reference

1. Picture-card list with an owned list #

class GalleryUpload extends StatefulWidget {
  const GalleryUpload({super.key});

  @override
  State<GalleryUpload> createState() => _GalleryUploadState();
}

class _GalleryUploadState extends State<GalleryUpload> {
  List<AntUploadFile<Attachment>> _files = <AntUploadFile<Attachment>>[];

  void _apply(
    AntUploadFile<Attachment> file,
    List<AntUploadFile<Attachment>> list,
  ) {
    setState(() => _files = list);
  }

  @override
  Widget build(BuildContext context) {
    return AntUpload<Attachment>(
      fileList: _files,
      listType: AntUploadListType.pictureCard,
      accept: 'image/*',
      maxCount: 8,
      multiple: true,
      uploadButtonText: 'Add images',
      onSelectFiles: () async {
        final stamp = DateTime.now().microsecondsSinceEpoch;
        return <AntUploadFile<Attachment>>[
          AntUploadFile<Attachment>(
            uid: 'image-$stamp',
            name: 'photo.png',
            size: 4096,
          ),
        ];
      },
      onChange: _apply,
      onRemove: (file) async {
        debugPrint('removed ${file.uid}');
        return true;
      },
      onPreview: (file) => debugPrint('preview ${file.name}'),
    );
  }
}

Passing fileList makes the widget controlled: the new list from onChange must be stored, as _apply does, or removed rows reappear. onRemove returns a Future<bool>; returning false keeps the row.

2. Simulated transport with progress #

Future<void> uploadToServer(
  AntUploadFile<Attachment> file,
  void Function(AntUploadFile<Attachment> next) update,
) async {
  for (var percent = 0; percent <= 100; percent += 20) {
    await Future<void>.delayed(const Duration(milliseconds: 150));
    update(
      file.copyWith(
        status: AntUploadStatus.uploading,
        percent: percent,
      ),
    );
  }
  update(
    file.copyWith(
      status: AntUploadStatus.done,
      percent: 100,
      url: 'https://example.com/files/${file.uid}',
    ),
  );
}

AntUpload<Attachment>(
  uploadButtonText: 'Upload',
  customRequest: uploadToServer,
  onSelectFiles: () async => <AntUploadFile<Attachment>>[
    AntUploadFile<Attachment>(
      uid: 'doc-1',
      name: 'contract.pdf',
      size: 8192,
    ),
  ],
  onChange: (file, list) => debugPrint('${file.uid}: ${file.status} ${file.percent}%'),
)

update replaces the row with the new value; call it repeatedly for progress and finish with AntUploadStatus.done or AntUploadStatus.error. Reporting a failure this way renders the row's error state instead of leaving the uploading spinner on.

3. Text list with rejected rows #

AntUpload<Attachment>(
  listType: AntUploadListType.text,
  maxCount: 3,
  accept: '.pdf,.docx',
  onSelectFiles: () async => <AntUploadFile<Attachment>>[
    const AntUploadFile<Attachment>(
      uid: 'ok',
      name: 'summary.pdf',
      size: 1024,
    ),
    const AntUploadFile<Attachment>(
      uid: 'bad',
      name: 'notes.txt',
      status: AntUploadStatus.error,
    ),
  ],
  onChange: (file, list) => debugPrint('${list.length} files'),
  onRemove: (file) async => true,
)

A row returned with AntUploadStatus.error stays visible in its failed state, so an unsupported file is shown with its reason instead of being silently dropped.

Demo #

Project structure #

packages/antd_upload/
├── lib/
│   ├── antd_upload.dart                 # barrel export
│   └── src/upload/
│       ├── ant_upload.dart              # trigger, list, remove and preview
│       └── ant_upload_types.dart        # file record, enums, callbacks
├── example/lib/main.dart                # runnable gallery
├── docs/api-index.md                    # generated API index
└── README.md

License #

MIT. See the repository LICENSE.

☕ Buy Me a Coffee #

If this project has been helpful to you, you are welcome to buy me a coffee. Thank you for your support!

Alipay WeChat
Alipay QR code WeChat QR code
1
likes
0
points
0
downloads

Publisher

unverified uploader

Weekly Downloads

Ant Design v6 Upload component for Flutter. File selection upload with file list display, upload progress, preview and remove, aligned with antd React Upload API.

Homepage
Repository (GitHub)
View/report issues

Topics

#ui #components #design-system #ant-design #upload

License

unknown (license)

Dependencies

antd_icons_flutter, antd_theme, flutter, material_ui

More

Packages that depend on antd_upload