Upload files

Upload File

To upload to S3 from a file, specify the key and the localFile to be uploaded, where the localFile can be an instance of AWSFile created from either an OS platform File instance or the result of Flutter file picker plugins such as file_picker.

Upload platform `File`

Note: To use AWSFilePlatform, add aws_common package to your Flutter project by running: flutter pub add aws_common

1import 'dart:io' as io;
2
3import 'package:amplify_storage_s3/amplify_storage_s3.dart';
4import 'package:aws_common/vm.dart';
5
6Future<void> uploadIOFile(io.File file) async {
7  final awsFile = AWSFilePlatform.fromFile(file);
8  try {
9    final uploadResult = await Amplify.Storage.uploadFile(
10      localFile: awsFile,
11      key: 'upload/file.png',
12    ).result;
13    safePrint('Uploaded file: ${uploadResult.uploadedItem.key}');
14  } on StorageException catch (e) {
15    safePrint('Error uploading file: ${e.message}');
16    rethrow;
17  }
18}

Upload with Flutter file_picker plugin

The file_picker plugin can be used to retrieve arbitrary file types from the user's device.

1import 'package:amplify_flutter/amplify_flutter.dart';
2import 'package:file_picker/file_picker.dart';
3
4Future<void> uploadImage() async {
5  // Select a file from the device
6  final result = await FilePicker.platform.pickFiles(
7    type: FileType.custom,
8    withData: false,
9    // Ensure to get file stream for better performance
10    withReadStream: true,
11    allowedExtensions: ['jpg', 'png', 'gif'],
12  );
13
14  if (result == null) {
15    safePrint('No file selected');
16    return;
17  }
18
19  // Upload file with its filename as the key
20  final platformFile = result.files.single;
21  try {
22    final result = await Amplify.Storage.uploadFile(
23      localFile: AWSFile.fromStream(
24        platformFile.readStream!,
25        size: platformFile.size,
26      ),
27      key: platformFile.name,
28      onProgress: (progress) {
29        safePrint('Fraction completed: ${progress.fractionCompleted}');
30      },
31    ).result;
32    safePrint('Successfully uploaded file: ${result.uploadedItem.key}');
33  } on StorageException catch (e) {
34    safePrint('Error uploading file: $e');
35    rethrow;
36  }
37}

Upload Data

To upload to S3 from a data object, specify the key and data, where data is an instance of S3DataPayload created from various data formats.

1import 'package:amplify_flutter/amplify_flutter.dart';
2import 'package:amplify_storage_s3/amplify_storage_s3.dart';
3
4Future<void> uploadStringData({
5  required String dataString,
6  required String key,
7}) async {
8  try {
9    final result = await Amplify.Storage.uploadData(
10      data: S3DataPayload.string(
11        dataString,
12        contentType: 'text/plain',
13      ),
14      key: key,
15    ).result;
16
17    safePrint('Uploaded data: ${result.uploadedItem.key}');
18  } on StorageException catch (e) {
19    safePrint('Error uploading data: ${e.message}');
20    rethrow;
21  }
22}

Upload Options

You can attach metadata while uploading data or a file by specifying the metadata property in options. If you want the metadata to be included in the upload result, you can set the getProperties flag to true in options.

1Future<void> uploadWithOptions() async {
2  // When uploading data, use `StorageUploadDataOptions`
3  final uploadDataOperation = Amplify.Storage.uploadData(
4    data: S3DataPayload.string(
5      'example',
6      contentType: 'text/plain',
7    ),
8    key: 'example.txt',
9    options: const StorageUploadDataOptions(
10      metadata: {
11        'project': 'ExampleProject',
12      },
13      pluginOptions: S3UploadDataPluginOptions(
14        getProperties: true,
15      ),
16    ),
17  );
18  final uploadDataResult = await uploadDataOperation.result;
19  safePrint(
20    'Uploaded data with metadata: ${uploadDataResult.uploadedItem.metadata}',
21  );
22
23  // When uploading a file, use `StorageUploadFileOptions`
24  final uploadFileOperation = Amplify.Storage.uploadFile(
25    localFile: AWSFile.fromPath('path/to/example.txt'),
26    key: 'example.txt',
27    options: const StorageUploadFileOptions(
28      metadata: {
29        'project': 'ExampleProject',
30      },
31      pluginOptions: S3UploadFilePluginOptions(
32        getProperties: true,
33      ),
34    ),
35  );
36  final uploadFileResult = await uploadFileOperation.result;
37  safePrint(
38    'Uploaded file with metadata: ${uploadFileResult.uploadedItem.metadata}',
39  );
40}

The Amplify.Storage.getProperties API allows you to retrieve metadata without downloading the file.

In S3 console, you should see the metadata attached to your file as the following.

Screenshot of the metadata properties in S3 console, defined from above, showing two rows of data. The first row is a system defined key value pair where the key is Content-Type with the value is text/plain. The second row is user defined key value pair where the key is x-amz-meta-project and the value is ExampleProject

Control of Upload Operations

A call to Amplify.Storage.uploadFile or Amplify.Storage.uploadData returns a reference to the operation that is performing the upload.

To cancel the upload (for example, in response to the user pressing a Cancel button), simply call .cancel() on the returned upload operation.

1import 'package:amplify_flutter/amplify_flutter.dart';
2import 'package:amplify_storage_s3/amplify_storage_s3.dart';
3
4S3UploadFileOperation? uploadOperation;
5
6Future<void> uploadFile(String path) async {
7  try {
8    final storagePlugin = Amplify.Storage.getPlugin(AmplifyStorageS3.pluginKey);
9    uploadOperation = storagePlugin.uploadFile(
10      localFile: AWSFile.fromPath(path),
11      key: 'example_file.txt',
12    );
13
14    final result = await uploadOperation!.result;
15    safePrint('Uploaded ${result.uploadedItem.key}');
16  } on StorageException catch (e) {
17    safePrint('Error uploading file: ${e.message}');
18  }
19}
20
21void cancelUpload() {
22  uploadOperation?.cancel();
23  uploadOperation = null;
24}

Multipart Upload

Amplify will automatically perform a S3 multipart upload for files larger than 5MB. For more information about S3's multipart upload support, see Uploading and copying objects using multipart upload.

Set up Amplify Storage

Download files