flutter_native_gallery 0.1.1

Native photo and video gallery reader with a reusable Flutter picker sheet.

flutter_native_gallery

A native gallery reader and picker UI for Flutter apps.

flutter_native_gallery wraps photo_manager behind small SI7ES-friendly models and a reusable media picker bottom sheet. It can read native albums, paginate photos and videos, show thumbnails, detect iOS Live Photos, select multiple assets, expose an HD preference, and resolve selected assets to local files for upload.

The package only reads and selects media. It does not upload files, send chat messages, or depend on any chat composer or SI7ES app feature.

Features

• Requests photo and video library permission.
• Reads native albums from the device gallery.
• Opens an album picker with a normal Scaffold and AppBar.
• Loads gallery assets page by page.
• Renders image and video thumbnails in a grid.
• Shows video durations.
• Shows a Live Photo indicator for iOS/macOS Live Photos.
• Supports ordered multiple selection.
• Limits selection to 30 assets by default.
• Allows the max selection count to be configured.
• Exposes an HD toggle choice through each selected asset.
• Resolves selected assets to local File instances for app-level upload.
• Keeps all labels app-provided, so they can be localized by the host app.

Platform Setup

iOS

Add the photo library usage description to the host app:

<key>NSPhotoLibraryUsageDescription</key>
<string>Your app uses the photo library so you can select media.</string>

If your app supports adding assets to the library, also add:

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Your app saves media to your photo library.</string>

Android

Add gallery permissions to the host app:

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />
<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

Basic Usage

final selectedAssets = await FlutterNativeGalleryPicker.show(
  context,
  config: const FlutterNativeGalleryPickerConfig(
    title: 'Recents',
    albumPickerTitle: 'Select an album',
    cancelLabel: 'Cancel',
    highQualityLabel: 'HD',
    highQualityTooltip: 'High quality',
    sendLabel: 'Send',
    requestType: FlutterNativeGalleryRequestType.imagesAndVideos,
    maxSelection: 30,
    showHighQualityToggle: true,
    highQualityInitiallySelected: false,
  ),
);

for (final asset in selectedAssets ?? const <FlutterNativeGalleryAsset>[]) {
  final file = await asset.file(original: asset.highQualitySelected);
  if (file == null) continue;

  // Upload or send the file in your app layer.
}

Configuration

FlutterNativeGalleryPickerConfig controls the picker behavior and all user-facing labels.

Option	Default	Description
requestType	imagesAndVideos	Controls whether the picker loads images, videos, or both.
maxSelection	30	Maximum number of photos, videos, or Live Photos the user can select.
pageSize	80	Number of assets loaded per page.
initialHeightFactor	0.58	Initial height of the main gallery sheet.
minHeightFactor	0.34	Minimum height before the main sheet can close while dragging down.
maxHeightFactor	0.96	Maximum expanded height of the main gallery sheet.
showHighQualityToggle	true	Shows or hides the HD toggle.
highQualityInitiallySelected	false	Initial state of the HD toggle.
title	Select attachments	Main picker title when no album is available.
albumPickerTitle	Select an album	Album picker title.
cancelLabel	Cancel	Tooltip/accessibility label for close actions.
highQualityLabel	HD	Visible HD label.
highQualityTooltip	High quality	Tooltip/accessibility label for the HD toggle.
sendLabel	Send	Send button label.
recentsLabel	Recents	Fallback label for recents/all-media UI.
emptyLabel	No media found	Empty state label.
permissionTitle	Gallery access needed	Permission view title.
permissionMessage	Allow photo library access to choose media.	Permission view message.
openSettingsLabel	Open settings	Button label for opening app settings.
limitedAccessLabel	Manage selected photos	Button label for iOS limited library access.

Selected Assets

Each selected item is returned as a FlutterNativeGalleryAsset.

Useful fields:

Field	Description
id	Native asset identifier.
title	Asset title or id fallback.
type	image, video, audio, or other.
width / height	Oriented media dimensions.
duration	Video duration.
mimeType	Native MIME type when available.
isLivePhoto	true for iOS/macOS Live Photos detected by the native asset subtype.
highQualitySelected	The HD toggle value captured when the picker returns.

Resolve a selected asset to a local file:

final file = await asset.file(original: asset.highQualitySelected);

Request a thumbnail:

final bytes = await asset.thumbnail(width: 320, height: 320, quality: 80);

Example

Run the example app:

cd example
flutter pub get
flutter run

The example opens the picker, prints selected asset details, and resolves selected files so you can see the upload-ready paths.

Platform Notes

Live Photo detection depends on the native subtype exposed by photo_manager. It is available on iOS/macOS when the asset is a Live Photo. Android does not expose the same Live Photo subtype, so isLivePhoto remains false.

The package intentionally keeps upload and messaging outside its API. Host apps should use the returned files and metadata to build their own send, upload, compression, or CDN flow.