flutter_native_gallery #

A native photo and video gallery picker for Flutter with album browsing, pagination, ordered multiple selection, Live Photo detection, image optimization, and media metadata extraction.

Features #

• Requests native photo library permissions.
• Reads albums, photos, videos, and available native metadata.
• Presents a responsive, draggable gallery bottom sheet.
• Opens album selection in a full-height page with safe-area handling.
• Loads large galleries incrementally.
• Supports image-only, video-only, or combined media requests.
• Preserves the order of multiple selections.
• Limits selection to 30 items by default with a configurable maximum.
• Detects Live Photos on supported Apple platforms.
• Shows video duration and Live Photo indicators.
• Provides a configurable HD selection control.
• Adapts the HD control to light, dark, and custom application color schemes.
• Optimizes non-HD images with configurable quality and dimensions.
• Preserves EXIF data when supported.
• Extracts dimensions, dates, duration, MIME type, location, camera, exposure, favorite state, Live Photo state, and serializable EXIF values.
• Exposes configurable labels for localization.
• Provides both a ready-to-use picker and a lower-level gallery controller.

Platform Requirements #

iOS #

Photo library access requires NSPhotoLibraryUsageDescription in Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is used to select media.</string>

NSPhotoLibraryAddUsageDescription is only required when selected media can also be written back to the library:

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Photo library access is used to save media.</string>

Android #

Gallery access uses the media permissions supported by each Android version:

<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.ACCESS_MEDIA_LOCATION" />
<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

ACCESS_MEDIA_LOCATION allows coordinates to be read when they are present and the operating system grants access.

Basic Usage #

import 'dart:io';
import 'dart:typed_data';

import 'package:flutter_native_gallery/flutter_native_gallery.dart';

Open the picker and receive the selected assets in selection order:

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

A null result means the picker was dismissed. An empty gallery, denied permission, and limited-library access are handled by the picker UI.

Export Selected Media #

Resolve an asset to a file together with its normalized metadata:

for (final FlutterNativeGalleryAsset asset
    in selectedAssets ?? const <FlutterNativeGalleryAsset>[]) {
  final FlutterNativeGalleryAssetExport? exported = await asset.export();
  if (exported == null) continue;

  final File file = exported.file;
  final Map<String, dynamic> metadata = exported.toJson();
}

Videos and HD images use their original file. Non-HD images use the default 1920 x 1920 bounds at quality 82. An original file is retained when optimization would produce a larger result.

A Live Photo is a paired still image and motion resource. The single-file export contains the still image only, so its serialized metadata reports isLivePhoto: false and preserves the native source state as originalIsLivePhoto: true. This prevents consumers from treating a static JPEG or HEIF export as playable Live Photo media.

Customize non-HD image export with FlutterNativeGalleryImageExportOptions:

final FlutterNativeGalleryAssetExport? exported = await asset.export(
  imageOptions: const FlutterNativeGalleryImageExportOptions(
    quality: 76,
    maxWidth: 1600,
    maxHeight: 1600,
    format: FlutterNativeGalleryImageFormat.automatic,
    preserveExif: true,
    useOriginalWhenOptimizedFileIsLarger: true,
  ),
);

The highQuality argument overrides the value selected in the picker for an individual export:

final FlutterNativeGalleryAssetExport? original = await asset.export(
  highQuality: true,
);

Asset Metadata #

Read metadata without exporting or optimizing the file:

final FlutterNativeGalleryAssetMetadata metadata = await asset.metadata();

final bool hasCoordinates = metadata.hasCoordinates;
final String? device = metadata.device;
final String? format = metadata.format;
final Map<String, dynamic> json = metadata.toJson();

Metadata is best effort. Values unavailable from the operating system or source file remain null or are omitted from toJson().

Available metadata includes:

Asset API #

Each FlutterNativeGalleryAsset provides:

Request thumbnail bytes directly:

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

Picker Configuration #

FlutterNativeGalleryPickerConfig controls selection, presentation, and every visible label.

Controller API #

FlutterNativeGalleryController exposes gallery access without the picker UI:

const FlutterNativeGalleryController controller =
    FlutterNativeGalleryController();

final FlutterNativeGalleryPermissionStatus permission =
    await controller.requestPermission();

if (permission.canReadGallery) {
  final List<FlutterNativeGalleryAlbum> albums = await controller.albums();
}

Albums expose their native count, cover, and paginated assets. The controller also provides limited-library management, settings access, and cache clearing.

Platform Behavior #

Live Photo detection uses the native asset subtype available on iOS and macOS. Android does not expose the same subtype, so isLivePhoto remains false. Detection describes the native library asset; it does not imply that a single-file export contains the paired motion resource.

Limited photo access can restrict albums, files, and metadata. Coordinates and EXIF values can also be absent even when permission is granted.

License #

MIT License. See LICENSE.