Named Media Picker #

Flutter gallery media picker for Android and iOS that returns upload-ready files with real display names — not temporary image_picker cache filenames.

final files = await NamedMediaPicker.pick(context);

print(files.first.displayName);   // IMG_1222.PNG
print(files.first.uploadFilename); // same — ready for multipart

Why this package? #

Most gallery / image pickers give you a path. Uploads need a filename.

Positioning: use this when the picked media will be uploaded (Dio, http, CMS, chat attachments). If you mainly need an Instagram-style embedded gallery UI with album browsing, compare with packages like gallery_media_picker.

Features #

• Single or multi-select images and videos
• Upload-ready NamedMedia.displayName / uploadFilename
• iOS filename sanitization (UUID, _o_, _L0_ noise)
• Built-in photo library permission + settings / retry UI
• Paged thumbnail grid with selection checkmarks
• Theme + translations (i18n-ready strings)
• Optional origin-file preference for higher quality exports
• Android & iOS (no web / desktop)

Installation #

dependencies:
  named_media_picker: ^0.0.1

Platform setup #

Android (AndroidManifest.xml) #

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<!-- API < 33 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<!-- Optional: read GPS from photo metadata on Android 10+ -->
<uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION"/>

iOS (Info.plist) #

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to select media.</string>

Usage #

import 'package:named_media_picker/named_media_picker.dart';

final files = await NamedMediaPicker.pick(
  context,
  config: const NamedMediaPickerConfig(
    maxCount: 10,
    filter: NamedMediaFilter.all,
  ),
);

for (final file in files) {
  print('Path: ${file.path}');
  print('Display name: ${file.displayName}');
  print('Upload as: ${file.uploadFilename}');
  if (file.hasLocation) {
    print('Location: ${file.latitude}, ${file.longitude}');
  }
}

Returns an empty list when the user cancels or permission is denied.

Upload with Dio #

import 'package:dio/dio.dart';

final form = FormData();

for (final media in files) {
  form.files.add(
    MapEntry(
      'media',
      await MultipartFile.fromFile(
        media.path,
        filename: media.uploadFilename,
      ),
    ),
  );
}

Theming & translations #

NamedMediaPickerConfig(
  theme: NamedMediaPickerTheme(
    appBarBackgroundColor: Colors.teal,
    selectedCheckBackgroundColor: Colors.teal,
  ),
  translations: NamedMediaPickerTranslations(
    selectMediaTitle: 'Choose files',
    done: 'Confirm',
  ),
)

Config reference #

Filters #

API #

NamedMedia fields #

Example #

See the example/ app:

cd example
flutter pub get
flutter run

Limitations #

• iOS Photos custom renames are not exposed by Apple; only import/camera filenames are available.
• Simulator screenshots may still need sanitization (handled automatically).
• Android & iOS only (no web/desktop).
• No album browser yet — shows the device “all photos” library.
• No audio picking.
• Location is often null (privacy, stripped metadata, or missing ACCESS_MEDIA_LOCATION on Android 10+).

License #

MIT — see LICENSE.