### ThumbnailQuality Extension Example

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Demonstrates how to access the size getter from the ThumbnailQualityExtension. Shows how to get the pixel dimension for a quality level.

```dart
final quality = ThumbnailQuality.high;
print(quality.size);  // 400

// Used internally:
final thumbnailSize = ThumbnailSize.square(quality.size);
```

--------------------------------

### GalleryMediaPicker Widget Usage Example

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

An example demonstrating how to instantiate the GalleryMediaPicker widget with a callback for asset selection and an optional leading widget for the app bar.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> assets) {
    setState(() => selectedAssets = assets);
  },
  appBarLeadingWidget: IconButton(
    icon: const Icon(Icons.close),
    onPressed: () => Navigator.pop(context),
  ),
  mediaPickerParams: lightConfig,
)
```

--------------------------------

### Example of using GalleryMediaType and its extension

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Demonstrates how to use the GalleryMediaType enum and its extension to get the corresponding RequestType and fetch media assets. This example shows fetching video assets.

```dart
final mediaType = GalleryMediaType.video;
final requestType = mediaType.type;  // RequestType.video

// Used internally:
final paths = await PhotoManager.getAssetPathList(
  type: mediaType.type,
);
```

--------------------------------

### Basic MediaPickerController Setup

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/04-media-picker-controller.md

Initialize the MediaPickerController, set up callbacks for selection changes and maximum item limits, and dispose of the controller.

```dart
class MyGalleryWidget extends StatefulWidget {
  @override
  State<MyGalleryWidget> createState() => _MyGalleryWidgetState();
}

class _MyGalleryWidgetState extends State<MyGalleryWidget> {
  late final MediaPickerController controller;

  @override
  void initState() {
    super.initState();
    controller = MediaPickerController();
    
    controller.onPickChanged = (picked) {
      print('Selection changed: ${picked.length} items');
    };
    
    controller.onPickMax = () {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Max items reached')),
      );
    };
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // ... build UI
  }
}
```

--------------------------------

### iOS Permissions Setup

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Configure NSPhotoLibraryUsageDescription and NSPhotoLibraryAddUsageDescription keys in your Info.plist for photo library access.

```xml
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to select media.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow access to your gallery</string>
```

--------------------------------

### Install gallery_media_picker Package

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Add the gallery_media_picker dependency to your pubspec.yaml file to include it in your project.

```yaml
dependencies:
  gallery_media_picker: ^0.2.0
```

--------------------------------

### Full Usage in GalleryMediaPicker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

This example demonstrates how to integrate the GalleryMediaProvider and its child widgets within a larger UI structure. It includes handling permission states and displaying the gallery grid.

```dart
@override
Widget build(BuildContext context) {
  return GalleryMediaProvider(
    controller: provider,
    child: Column(
      children: [
        _AlbumSelector(appBarLeadingWidget: widget.appBarLeadingWidget),
        const SizedBox(height: 2),
        Expanded(
          child: ValueListenableBuilder<PermissionState>(
            valueListenable: provider.permitState,
            builder: (_, permit, __) {
              if (!permit.isAuth) {
                return _buildPermissionDeniedUI();
              }

              return NotificationListener<OverscrollIndicatorNotification>(
                onNotification: (overscroll) {
                  overscroll.disallowIndicator();
                  return false;
                },
                child: ValueListenableBuilder<AssetPathEntity?>(
                  valueListenable: provider.currentAlbum,
                  builder: (_, album, _)
                      =>       const _GalleryGridViewWidget(),
                ),
              );
            },
          ),
        ),
      ],
    ),
  );
}
```

--------------------------------

### Android Permissions Setup

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Declare necessary media read permissions in your AndroidManifest.xml for accessing images, videos, and audio.

```xml
<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_AUDIO"/>
```

```xml
>On older Android versions (API < 33), you may also need:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
```

--------------------------------

### iOS Permissions Setup

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Add the NSPhotoLibraryUsageDescription key to your app's Info.plist file to request user permission for accessing the photo library.

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

--------------------------------

### Example Usage of _SelectionWatcher

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/08-selection-watcher.md

Demonstrates how _SelectionWatcher is used to wrap individual asset widgets in a grid, optimizing rebuilds.

```dart
Widget _buildAssetWidget(AssetEntity asset, int index) {
  return _SelectionWatcher(
    key: ValueKey(asset.id),
    asset: asset,
    builder: (_, {required isSelected}) {
      return AnimatedTapWidget(
        onTap: () => provider.pickEntity(asset),
        child: ThumbnailWidget(
          asset: asset,
          isSelected: isSelected,
          params: provider.paramsModel,
        ),
      );
    },
  );
}
```

--------------------------------

### PickedAssetType Usage Example

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Shows how to use a switch statement with the PickedAssetType enum to handle different asset types. This is common when processing a list of picked assets.

```dart
final asset = pickedAssets.first;

switch (asset.type) {
  case PickedAssetType.video:
    playVideo(asset);
  case PickedAssetType.image:
    displayImage(asset);
  case PickedAssetType.other:
    showUnsupportedMessage();
}
```

--------------------------------

### Accessing MediaPickerController in a Widget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Example of how to access the MediaPickerController using GalleryMediaProvider.of(context) within a StatelessWidget. Use the controller to access properties like pickedFile.

```dart
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final controller = GalleryMediaProvider.of(context);
    // Now use controller.pickedFile, controller.currentAlbum, etc.
    return Column(
      children: [
        ValueListenableBuilder(
          valueListenable: controller.pickedFile,
          builder: (_, picked, __) {
            return Text('Selected: ${picked.length}');
          },
        ),
      ],
    );
  }
}
```

--------------------------------

### Access GalleryMediaProvider in a Widget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Use GalleryMediaProvider.of(context) to get the controller instance within your widget's build method. This is useful for triggering media picking actions.

```dart
class MySelectButton extends StatelessWidget {
  const MySelectButton({super.key});

  @override
  Widget build(BuildContext context) {
    final controller = GalleryMediaProvider.of(context);
    
    return ElevatedButton(
      onPressed: () {
        controller.pickEntity(someAsset);
      },
      child: const Text('Select'),
    );
  }
}
```

--------------------------------

### Max Items Picked String Example

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/06-gallery-media-picker-translations.md

Example of how to customize the 'Max items picked' string, which is shown as a toast notification when the selection limit is reached. Use '%s' as a placeholder for the numeric limit.

```dart
const translations = GalleryMediaPickerTranslations(
  maxItemsPicked: 'Límite alcanzado: %s elementos',
);
// Shows: "Límite alcanzado: 5 elementos"
```

--------------------------------

### Filtering Assets by Type

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/03-picked-asset-model.md

Filter a list of assets to get only images or only videos.

```dart
final images = assets.where((a) => a.type == PickedAssetType.image).toList();
final videos = assets.where((a) => a.type == PickedAssetType.video).toList();
```

--------------------------------

### Gallery Media Picker Architecture Overview

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/README.md

Illustrates the architectural flow and component relationships within the gallery_media_picker package. Understanding this helps in debugging and extending the package.

```text
GalleryMediaPicker (StatefulWidget)
    ↓
GalleryMediaProvider (InheritedWidget)
    ↓
MediaPickerController (State Management)
    ↓
_GalleryGridViewWidget (Infinite Scrolling Grid)
    ↓
_SelectionWatcher (O(1) Rebuild Isolation)
    ↓
ThumbnailWidget (Item Rendering)
```

--------------------------------

### Get Pick Index of Asset

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/04-media-picker-controller.md

Returns the zero-based index of an asset in the selection list, or -1 if not selected.

```dart
int pickIndex(AssetEntity entity)
```

```dart
final index = controller.pickIndex(entity);
if (index != -1) {
  print('Asset is selected at position $index');
}
```

--------------------------------

### Basic Gallery Media Picker Usage

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Implement a basic media picker with default settings. The pathList callback receives a list of selected assets.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> paths) {
    // Handle selected media files
    for (final asset in paths) {
      print('Selected: ${asset.path} (${asset.type})');
    }
  },
  appBarLeadingWidget: const Icon(Icons.close, color: Colors.white),
  mediaPickerParams: MediaPickerParamsModel(
    maxPickImages: 5,
    singlePick: false,
    mediaType: GalleryMediaType.all,
    thumbnailQuality: ThumbnailQuality.high,
  ),
)
```

--------------------------------

### Initialize Gallery Media Picker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Use the GalleryMediaPicker widget to display the media picker interface. Provide a callback for handling selected assets and optional parameters.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> assets) { },
  mediaPickerParams: MediaPickerParamsModel(),
)
```

--------------------------------

### Minimal MediaPickerParamsModel Configuration

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/02-media-picker-params-model.md

Shows the simplest way to instantiate MediaPickerParamsModel with default settings.

```dart
const params = MediaPickerParamsModel();
```

--------------------------------

### GalleryMediaProvider Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Initializes a GalleryMediaProvider widget. This widget must be placed above other widgets that need access to the MediaPickerController.

```APIDOC
## GalleryMediaProvider Constructor

### Description
Initializes a GalleryMediaProvider widget, making a MediaPickerController available to its descendants.

### Parameters
#### Required Parameters
- **controller** (MediaPickerController) - The controller instance to provide to descendant widgets.
- **child** (Widget) - The widget tree that will have access to the controller.

#### Optional Parameters
- **key** (Key?) - Optional widget key for Flutter's element tree.
```

--------------------------------

### Main Entry Point Exports

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/MANIFEST.md

Exports from the main entry point of the Gallery Media Picker library. These modules are essential for accessing the library's functionality.

```dart
export 'src/data/enum/media_picker_enums.dart';
export 'src/data/models/gallery_media_picker_translations.dart';
export 'src/data/models/gallery_params_model.dart';
export 'src/data/models/picked_asset_model.dart';
export 'src/views/gallery_media_picker.dart';
```

--------------------------------

### AssetPathEntity Class Definition

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Represents an album or media collection. It includes methods to retrieve assets within a specific range and asynchronously get the total asset count.

```dart
class AssetPathEntity {
  String id;              // Unique album ID
  String name;            // Album name
  
  Future<List<AssetEntity>> getAssetListRange({
    required int start,
    required int end,
  });
  
  Future<int> get assetCountAsync;
  // ... more methods from photo_manager
}
```

--------------------------------

### GalleryMediaPicker Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/01-gallery-media-picker-widget.md

The main entry point widget for displaying a customizable media picker interface. It wraps the internal controller and provider architecture to manage state and handle gallery permissions.

```APIDOC
## GalleryMediaPicker

### Description
The main entry point widget for displaying a customizable media picker interface.

### Constructor
```dart
const GalleryMediaPicker({
  required ValueChanged<List<PickedAssetModel>> pathList,
  required MediaPickerParamsModel mediaPickerParams,
  Widget? appBarLeadingWidget,
  Key? key,
})
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
- **pathList** (ValueChanged<List<PickedAssetModel>>) - Required - Callback invoked whenever the selection changes, returning the current list of picked assets.
- **mediaPickerParams** (MediaPickerParamsModel) - Required - Configuration model containing all appearance, behavior, and filtering parameters.
- **appBarLeadingWidget** (Widget?) - Optional - Optional widget displayed at the leading position of the album selector bar.
- **key** (Key?) - Optional - Optional widget key for Flutter's element tree management.

### Request Example
```dart
GalleryMediaPicker(
  pathList: (pickedAssets) {
    // Handle picked assets
  },
  mediaPickerParams: MediaPickerParamsModel(...),
)
```

### Response
#### Success Response (200)
Returns a `GalleryMediaPicker` widget.

#### Response Example
```dart
// Widget instance
```
```

--------------------------------

### Initialize MediaPickerController

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/04-media-picker-controller.md

Creates a new instance of the MediaPickerController. Initializes state notifiers and sets up listeners for album changes.

```dart
MediaPickerController()
```

--------------------------------

### Handle Max Selection Limit Callback

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/errors.md

Implement a callback to be triggered when the user attempts to pick more items than the maximum allowed. This example shows how to display a SnackBar with a custom message.

```dart
controller.onPickMax = () {
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(
      content: Text(controller.paramsModel.translations.maxItemsPicked
          .replaceAll('%s', '${controller.maxSelection}')),
      duration: const Duration(seconds: 2),
    ),
  );
};
```

--------------------------------

### Import Gallery Media Picker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Import the necessary library to use the Gallery Media Picker functionality.

```dart
import 'package:gallery_media_picker/gallery_media_picker.dart';
```

--------------------------------

### Mobile-First Responsive Configuration

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Configure the media picker for a mobile-first experience with a smaller app bar height, fewer columns, and adjusted aspect ratio for thumbnails.

```dart
final responsiveConfig = MediaPickerParamsModel(
  appBarHeight: 48,
  crossAxisCount: 3,
  childAspectRatio: 0.8,
  gridPadding: const EdgeInsets.all(2),
  gridViewPhysics: const BouncingScrollPhysics(),
  thumbnailQuality: ThumbnailQuality.medium,
);
```

--------------------------------

### Handle Album Loading Errors

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/errors.md

Customize album loading error handling by wrapping the GalleryMediaPicker in a stateful widget. This example demonstrates how to catch exceptions during album fetching and display an error message with a retry option.

```dart
class MyGalleryPicker extends StatefulWidget {
  @override
  State<MyGalleryPicker> createState() => _MyGalleryPickerState();
}

class _MyGalleryPickerState extends State<MyGalleryPicker> {
  bool _hasError = false;
  String _errorMessage = '';

  Future<void> _loadAlbums() async {
    try {
      final result = await PhotoManager.requestPermissionExtend();
      if (!result.isAuth) return;

      final paths = await PhotoManager.getAssetPathList(
        type: GalleryMediaType.all.type,
      );
      
      setState(() => _hasError = false);
    } catch (e) {
      setState(() {
        _hasError = true;
        _errorMessage = e.toString();
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    if (_hasError) {
      return Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Icon(Icons.error_outline, size: 64),
            const SizedBox(height: 16),
            Text('Error loading albums: $_errorMessage'),
            const SizedBox(height: 24),
            ElevatedButton(
              onPressed: _loadAlbums,
              child: const Text('Retry'),
            ),
          ],
        ),
      );
    }

    return GalleryMediaPicker(
      pathList: (_) {}, 
      mediaPickerParams: const MediaPickerParamsModel(),
    );
  }
}
```

--------------------------------

### GalleryMediaProvider

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

An InheritedWidget for providing dependency injection of media picker related services.

```APIDOC
## GalleryMediaProvider

### Description
Provides dependency injection for the media picker's logic, typically used to access controllers and other services up the widget tree.

### Widget
`GalleryMediaProvider extends InheritedWidget`

### Usage
```dart
InheritedWidget { ... }
```
```

--------------------------------

### Light Theme Configuration

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Configure a light theme for the media picker, adjusting colors for the app bar, backgrounds, and text to suit a brighter aesthetic.

```dart
final lightConfig = MediaPickerParamsModel(
  appBarHeight: 56,
  appBarColor: Colors.white,
  gridViewBgColor: Colors.grey[50],
  thumbnailBgColor: Colors.grey[200],
  albumTextColor: Colors.black87,
  albumSelectTextColor: Colors.black87,
  albumSelectIconColor: Colors.black54,
  albumDropDownBgColor: Colors.white,
  selectedAlbumBgColor: Colors.blue[50],
  selectedAlbumTextColor: Colors.blue[600],
  selectedAssetBgColor: Colors.blue[200]?.withOpacity(0.3),
  selectedCheckColor: Colors.blue[600],
  selectedCheckBgColor: Colors.blue[100],
);
```

--------------------------------

### Build Selection Overlay Widget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/07-thumbnail-widget.md

Creates an animated semi-transparent overlay for selected thumbnails. Uses AnimatedContainer for smooth transitions.

```dart
Widget _buildOverlay(Color selectedAssetBg)
```

--------------------------------

### Factory Constructor: fromAssetEntity

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/03-picked-asset-model.md

Asynchronously constructs a PickedAssetModel from a photo_manager AssetEntity. It attempts to load the original file, determines asset type, extracts metadata, and returns a populated model. File loading errors are ignored, resulting in an empty path but intact metadata.

```dart
static Future<PickedAssetModel> fromAssetEntity(
  AssetEntity entity,
  {
    PMCancelToken? cancelToken,
  }
) async
```

--------------------------------

### Handling Asset Files

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Illustrates how to check if a picked asset has an associated File reference and perform operations like uploading it. Requires awaiting asynchronous file operations.

```dart
final asset = pickedAssets.first;
if (asset.file != null) {
  await uploadFile(asset.file!);
}
```

--------------------------------

### Configuration Properties

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/04-media-picker-controller.md

Properties that configure the media picker's behavior and data sources.

```APIDOC
## Configuration Properties

| Property | Type | Description |
|----------|------|-------------|
| `pathList` | `List<AssetPathEntity>` | List of all available albums on the device. Populated by `resetPathList()` |
| `paramsModel` | `MediaPickerParamsModel` | Current picker configuration (layout, colors, text) |
```

--------------------------------

### Building UI for Assets

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/03-picked-asset-model.md

Create a UI widget for displaying an asset, showing its image (if available), title, and dimensions.

```dart
Widget buildAssetTile(PickedAssetModel asset) {
  return Card(
    child: Column(
      children: [
        if (asset.file != null)
          Image.file(asset.file!, width: 150, height: 150),
        Text(asset.title ?? 'Untitled'),
        Text(
          '${asset.orientationWidth}×${asset.orientationHeight}',
          style: const TextStyle(fontSize: 12),
        ),
      ],
    ),
  );
}
```

--------------------------------

### Load Initial Assets

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

Fetches the total asset count and loads the first batch of assets. It includes logic to handle race conditions and ensures the request is still valid before proceeding.

```dart
Future<void> _loadInitialAssets(int changeId)

```

```dart
final album = provider.album;
if (album == null) return;

final count = await album.assetCountAsync;

if (changeId != _albumChangeId) return;  // Request stale
provider.assetCount.value = count;

while (_isLoading) {
  await Future<void>.delayed(const Duration(milliseconds: 10));
  if (changeId != _albumChangeId) return;
}

await _preloadAssets(0, _preloadAmount, changeId);

if (changeId != _albumChangeId) return;
if (mounted) setState(() {});

```

--------------------------------

### Constructor for _GalleryGridViewWidget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

A simple stateful widget with no public parameters. All configuration is accessed via GalleryMediaProvider.of(context).

```dart
const _GalleryGridViewWidget()
```

--------------------------------

### Request Media Permissions in Dart

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Use the permission_handler package to request photo library permissions before initializing the media picker. Handle denied permissions appropriately.

```dart
import 'package:permission_handler/permission_handler.dart';

Future<void> requestPermissions() async {
  final status = await Permission.photos.request();
  if (!status.isGranted) {
    // Optionally show a dialog or redirect to app settings
  }
}
```

--------------------------------

### Use Uint8List for Thumbnails

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Demonstrates how to use the `Uint8List` type to display asset thumbnails. Ensure the asset has a thumbnail before attempting to display it.

```dart
final asset = pickedAssets.first;
if (asset.thumbnail != null) {
  Image.memory(asset.thumbnail!);
}
```

--------------------------------

### GalleryMediaPicker Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/01-gallery-media-picker-widget.md

The constructor for the GalleryMediaPicker widget. It requires a callback for selection changes and media picker parameters, with optional parameters for the app bar leading widget and a widget key.

```dart
const GalleryMediaPicker({
  required ValueChanged<List<PickedAssetModel>> pathList,
  required MediaPickerParamsModel mediaPickerParams,
  Widget? appBarLeadingWidget,
  Key? key,
})
```

--------------------------------

### GalleryMediaProvider Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Constructor for GalleryMediaProvider. Requires a MediaPickerController and a child widget. The controller is provided to descendant widgets.

```dart
const GalleryMediaProvider({
  required MediaPickerController controller,
  required Widget child,
  Key? key,
})
```

--------------------------------

### Runtime Configuration Changes for GalleryMediaPicker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Demonstrates how to dynamically update the configuration of the GalleryMediaPicker widget by changing the MediaPickerParamsModel passed to it. The widget automatically applies these changes.

```dart
class MyGalleryScreen extends StatefulWidget {
  @override
  State<MyGalleryScreen> createState() => _MyGalleryScreenState();
}

class _MyGalleryScreenState extends State<MyGalleryScreen> {
  late MediaPickerParamsModel config;
  bool isDarkMode = false;

  @override
  void initState() {
    super.initState();
    config = _buildConfig();
  }

  void toggleTheme() {
    setState(() {
      isDarkMode = !isDarkMode;
      config = _buildConfig();  // Rebuild with new colors
    });
  }

  MediaPickerParamsModel _buildConfig() {
    return isDarkMode ? darkConfig : lightConfig;
  }

  @override
  Widget build(BuildContext context) {
    return GalleryMediaPicker(
      pathList: (_) {},
      mediaPickerParams: config,  // Updated config
    );
  }
}
```

--------------------------------

### Show Loading Feedback During Asset Selection in Dart

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/errors.md

This snippet demonstrates how to provide visual feedback to the user while asset selection is processing, particularly useful when dealing with potential transcoding delays.

```dart
// Show feedback during selection
controller.onPickChanged = (picked) {
  setState(() => isLoading = true);
  Future.delayed(const Duration(milliseconds: 100), () {
    setState(() => isLoading = false);
  });
};
```

--------------------------------

### Request Permissions Before Opening Gallery

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Use the permission_handler package to request necessary permissions before launching the gallery picker. Navigate to the gallery screen only if permissions are granted.

```dart
import 'package:permission_handler/permission_handler.dart';

Future<void> openGallery() async {
  final status = await Permission.photos.request();
  if (status.isGranted) {
    Navigator.push(context, MaterialPageRoute(builder: (_) => MyGalleryScreen()));
  }
}
```

--------------------------------

### Basic Single Selection

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/01-gallery-media-picker-widget.md

Demonstrates how to use the GalleryMediaPicker for a single asset selection. The `pathList` callback is used to update the selected asset state.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> assets) {
    setState(() {
      selectedAsset = assets.isNotEmpty ? assets.first : null;
    });
  },
  appBarLeadingWidget: const Icon(Icons.close),
  mediaPickerParams: MediaPickerParamsModel(
    singlePick: true,
    maxPickImages: 1,
  ),
)
```

--------------------------------

### Customizing Picker Colors

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Demonstrates how to customize picker colors using Color objects. Null values fallback to theme colors.

```dart
const params = MediaPickerParamsModel(
  appBarColor: Color(0xFF09090B),            // Custom: near-black
  selectedCheckBgColor: Color(0xFF3B82F6),   // Custom: blue
  albumTextColor: null,                      // Fallback to theme
);
```

--------------------------------

### Build Responsive Grid Delegate

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

Creates a responsive column layout for the grid view. The number of columns adjusts based on screen width and the `crossAxisCount` parameter.

```dart
SliverGridDelegateWithMaxCrossAxisExtent _buildGridDelegate(BuildContext context)
```

```dart
final params = provider.paramsModel;
final maxExtent = 360.0 / params.crossAxisCount;  // Scale for phone width

return SliverGridDelegateWithMaxCrossAxisExtent(
  maxCrossAxisExtent: maxExtent,
  mainAxisSpacing: 1.5,
  crossAxisSpacing: 1.5,
  childAspectRatio: params.childAspectRatio,
);
```

--------------------------------

### Accessing Controller via Dependency Injection

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Shows how child widgets can access the controller provided by GalleryMediaProvider without explicit prop drilling, using the static `of` method.

```dart
// No need to pass controller through all intermediate widgets
Widget _buildGridItem(BuildContext context) {
  final controller = GalleryMediaProvider.of(context);
  // Use controller here
}
```

--------------------------------

### Grid With _SelectionWatcher (O(1) rebuilds)

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/08-selection-watcher.md

Shows the optimized approach using _SelectionWatcher, where each watcher caches its own selection state, resulting in O(1) rebuilds.

```dart
_SelectionWatcher(
  asset: asset,
  builder: (_, {required isSelected}) {
    return ThumbnailWidget(asset: asset, isSelected: isSelected);
  },
)
```

--------------------------------

### GalleryMediaPickerTranslations Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/06-gallery-media-picker-translations.md

Defines the constructor for GalleryMediaPickerTranslations, initializing all customizable text strings for the media picker.

```dart
const GalleryMediaPickerTranslations({
  String noMediaFound = 'No media found.',
  String recent = 'Recent',
  String tapToOpenSettings = 'Tap to open settings',
  String permissionDenied = 'Permissions denied. Please grant access to your gallery.',
  String maxItemsPicked = 'You have already picked %s items.',
  String videoLabel = 'Video',
  String imageLabel = 'Image',
  String gifLabel = 'GIF',
  String selectedLabel = 'Selected',
  String notSelectedLabel = 'Not selected',
})
```

--------------------------------

### Accessing GalleryMediaProvider Controller

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Demonstrates how to access the GalleryMediaProvider controller from any descendant widget using `GalleryMediaProvider.of(context)`. This is useful for triggering actions like picking an entity.

```dart
class ThumbnailWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Access controller from anywhere in the tree
    final controller = GalleryMediaProvider.of(context);
    
    return GestureDetector(
      onTap: () => controller.pickEntity(asset),
      child: Container(...),
    );
  }
}
```

--------------------------------

### Tap to Open Settings String

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/06-gallery-media-picker-translations.md

A button label shown on the permission-denied screen, allowing users to open app settings to grant gallery access. Default: 'Tap to open settings'.

```dart
final String tapToOpenSettings;
```

--------------------------------

### GalleryMediaPicker Widget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

The main widget for picking media from the device gallery. It requires a callback for selection changes and a configuration model.

```APIDOC
## GalleryMediaPicker Widget

### Description
This widget provides an interface for users to select media assets from their device's gallery. It requires a callback function to handle asset selection events and a configuration object to customize its behavior and appearance.

### Properties
- **`pathList`** (Function(List<PickedAssetModel>)) - Required. Callback triggered when the selection of assets changes.
- **`appBarLeadingWidget`** (Widget?) - Optional. A widget to display at the leading position of the AppBar.
- **`mediaPickerParams`** (MediaPickerParamsModel) - Required. Configuration model that defines all picker behaviors and styling options.
```

--------------------------------

### High-Performance Large Gallery Configuration

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Optimize the media picker for large galleries by setting a higher `crossAxisCount`, using `ThumbnailQuality.low`, and applying `ClampingScrollPhysics` for performance.

```dart
final performanceConfig = MediaPickerParamsModel(
  crossAxisCount: 4,
  thumbnailQuality: ThumbnailQuality.low,
  maxPickImages: 50,
  gridViewPhysics: const ClampingScrollPhysics(),
  childAspectRatio: 1.0,
);
```

--------------------------------

### Full Grid Implementation with SelectionWatcher

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/08-selection-watcher.md

Demonstrates integrating _SelectionWatcher within a GridView.builder to efficiently handle item selections. Only the tapped item's watcher triggers a rebuild, ensuring smooth user experience even with thousands of items.

```dart
GridView.builder(
  itemCount: assetCount,
  itemBuilder: (context, index) {
    final asset = _assetCache[index];
    return _SelectionWatcher(
      key: ValueKey(asset.id),
      asset: asset,
      builder: (_, {required isSelected}) {
        return AnimatedTapWidget(
          onTap: () => provider.pickEntity(asset),
          child: ThumbnailWidget(
            asset: asset,
            isSelected: isSelected,
            params: provider.paramsModel,
          ),
        );
      },
    );
  },
)
```

--------------------------------

### Key Exports in Gallery Media Picker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/README.md

Lists the main widgets, controllers, data models, and enums exported by the gallery_media_picker package. These are the primary components you will interact with when using the library.

```dart
import 'package:gallery_media_picker/gallery_media_picker.dart';

// Widgets
GalleryMediaPicker          // Main picker widget
GalleryMediaProvider        // Dependency injection (InheritedWidget)
ThumbnailWidget             // Individual thumbnail (internal)

// Controllers
MediaPickerController       // Selection and album state management

// Data Models
PickedAssetModel            // Selected asset with metadata
MediaPickerParamsModel      // Configuration options
GalleryMediaPickerTranslations  // Localization strings

// Enums
ThumbnailQuality            // low, medium, high
PickedAssetType             // image, video, other
GalleryMediaType            // all, image, video, audio
```

--------------------------------

### Build Responsive Grid View

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

Constructs the responsive grid with nested ValueListenableBuilders for reactive updates. Handles different states like no album, no assets, or available assets.

```dart
@override
Widget build(BuildContext context)
```

```dart
ValueListenableBuilder<AssetPathEntity?>(
  valueListenable: provider.currentAlbum,
  builder: (_, album, _) {
    if (album == null) {
      return const Center(child: CircularProgressIndicator());
    }

    return ValueListenableBuilder<int>(
      valueListenable: provider.assetCount,
      builder: (_, count, _) {
        if (count == 0) {
          return Center(child: Text(provider.paramsModel.translations.noMediaFound));
        }

        return Container(
          decoration: BoxDecoration(
            color: provider.paramsModel.gridViewBgColor ??
                Theme.of(context).colorScheme.surface,
          ),
          child: GridView.builder(...),
        );
      },
    );
  },
)
```

--------------------------------

### setAlbum

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/04-media-picker-controller.md

Switch the current album to a new one and update the asset counts accordingly.

```APIDOC
## setAlbum

### Description
Switch the current album to a new one and update the asset counts accordingly.

### Method
```dart
void setAlbum(AssetPathEntity album)
```

### Parameters
#### Path Parameters
- **album** (AssetPathEntity) - Required - The album to switch to.

### Example

```dart
controller.setAlbum(newAlbum);
```
```

--------------------------------

### Conditionally Build Video Overlay

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/07-thumbnail-widget.md

Builds an overlay specifically for video assets.

```dart
if (asset.type == AssetType.video) ...;
```

--------------------------------

### Checking Gallery Permission State

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Demonstrates how to check the current gallery permission state. The `.isAuth` shorthand is useful for quickly determining if access is denied or restricted.

```dart
final permit = controller.permitState.value;

if (permit == PermissionState.authorized) {
  // Picker is functional
} else if (permit.isAuth) {
  // Shorthand: checks if denied OR restricted
  showErrorUI();
}
```

--------------------------------

### Configure Multi-Selection with Limit

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Set up multi-selection with a specified limit on the number of images that can be picked. Useful for scenarios requiring multiple selections up to a certain count.

```dart
const params = MediaPickerParamsModel(
  singlePick: false,
  maxPickImages: 10,
);
```

--------------------------------

### GalleryMediaProvider Controller

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Provides access to the controller for managing media picker state, including listening to selections and checking permissions.

```APIDOC
## GalleryMediaProvider Controller

### Description

Provides access to the controller for managing media picker state, including listening to selections and checking permissions.

### Method

`GalleryMediaProvider.of(context)`

### Endpoint

N/A (SDK method)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Usage

```dart
final controller = GalleryMediaProvider.of(context);

// Listen to selection changes:
ValueListenableBuilder<List<PickedAssetModel>>(
  valueListenable: controller.pickedFile,
  builder: (_, assets, __) {
    // Update UI with selected assets
    return Container(); 
  },
)

// Check permission state:
if (controller.permitState.value == PermissionState.authorized) {
  // Picker is functional
}
```

### Properties

- **pickedFile** (ValueListenable<List<PickedAssetModel>>): A listenable that emits the list of currently picked assets.
- **permitState** (ValueNotifier<PermissionState>): A notifiable value indicating the current permission state.
```

--------------------------------

### Advanced Gallery Media Picker Usage (Dark Theme)

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/README.md

Configure a dark theme for the media picker with custom parameters for appearance, behavior, and internationalization.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> paths) {
    context.read<MediaProvider>().setPickedFiles(paths);
  },
  mediaPickerParams: MediaPickerParamsModel(
    appBarHeight: 50,
    maxPickImages: 10,
    crossAxisCount: 4,
    childAspectRatio: 1,
    singlePick: false,
    appBarColor: Colors.transparent,
    gridViewBgColor: const Color(0xFF09090B),
    albumTextColor: Colors.white,
    gridPadding: const EdgeInsets.all(2),
    thumbnailBgColor: const Color(0xFF181818),
    thumbnailBoxFix: BoxFit.cover,
    selectedAlbumIcon: Icons.check_circle_rounded,
    mediaType: GalleryMediaType.image,
    selectedCheckColor: Colors.white,
    albumSelectIconColor: Colors.white,
    selectedCheckBgColor: const Color(0xFF3B82F6),
    selectedAlbumBgColor: Colors.white10,
    albumDropDownBgColor: const Color(0xFF18181B),
    albumSelectTextColor: Colors.white,
    selectedAssetBgColor: const Color(0xFF3B82F6).withOpacity(0.2),
    selectedAlbumTextColor: const Color(0xFF3B82F6),
    gridViewController: _scrollController, // Use a persistent controller!
    thumbnailQuality: ThumbnailQuality.high,
    gridViewPhysics: const BouncingScrollPhysics(),
    translations: const GalleryMediaPickerTranslations(
      noMediaFound: 'No hay archivos multimedia.',
      permissionDenied: 'Permisos denegados.',
    ),
  ),
)
```

--------------------------------

### Key Exports

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/README.md

This section highlights the main API components that are directly exportable and usable by developers. It includes essential widgets, controllers, data models, and enums for interacting with the media picker functionality.

```APIDOC
## Key Exports

### Main API
```dart
import 'package:gallery_media_picker/gallery_media_picker.dart';

// Widgets
GalleryMediaPicker          // Main picker widget
GalleryMediaProvider        // Dependency injection (InheritedWidget)
ThumbnailWidget             // Individual thumbnail (internal)

// Controllers
MediaPickerController       // Selection and album state management

// Data Models
PickedAssetModel            // Selected asset with metadata
MediaPickerParamsModel      // Configuration options
GalleryMediaPickerTranslations  // Localization strings

// Enums
ThumbnailQuality            // low, medium, high
PickedAssetType             // image, video, other
GalleryMediaType            // all, image, video, audio
```
```

--------------------------------

### Build Thumbnail Widget Structure

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/07-thumbnail-widget.md

Constructs a semantically-labeled, visually-layered thumbnail with conditional overlays for selection state, video duration, and GIF badges. Use this for the main widget structure.

```dart
Semantics(
  label: _getSemanticLabel(),  // Screen reader text
  selected: isSelected,         // Selection state for accessibility
  child: ClipRRect(
    child: DecoratedBox(
      decoration: BoxDecoration(color: thumbnailBg),
      child: Stack(
        fit: StackFit.expand,
        children: [
          _buildImage(thumbnailBg),
          if (isSelected) _buildOverlay(selectedAssetBg),
          if (isSelected) _buildCheckmark(selectedCheckBg, selectedCheck),
          if (asset.type == AssetType.video) _buildVideoDuration(),
          if (_isGif) _buildGifBadge(),
        ],
      ),
    ),
  ),
)
```

--------------------------------

### Request Permissions Before Opening Picker

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Ensure you request necessary permissions, such as photo access, before navigating to the media picker. This prevents runtime errors and ensures a smooth user flow.

```dart
final status = await Permission.photos.request();
if (status.isGranted) {
  Navigator.push(...);
}
```

--------------------------------

### Image Rendering with Fade-in Animation

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/07-thumbnail-widget.md

Loads and displays the media thumbnail with a fade-in animation. Handles synchronous loading, animated opacity, and provides a fallback on error. Use this for displaying the actual image content within the thumbnail.

```dart
frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
  if (wasSynchronouslyLoaded) return child;
  return AnimatedOpacity(
    opacity: frame == null ? 0 : 1,
    duration: const Duration(milliseconds: 200),
    curve: Curves.easeOut,
    child: child,
  );
}
```

--------------------------------

### MediaPickerController

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Controller for managing the selection and album state within the media picker.

```APIDOC
## MediaPickerController

### Description
Manages the selection state and album state for the media picker. It extends `ChangeNotifier` to allow for state updates.

### Class
`MediaPickerController extends ChangeNotifier`

### Usage
```dart
ChangeNotifier { ... }
```
```

--------------------------------

### GalleryMediaPicker Widget

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

The main widget for the Gallery Media Picker. It takes a callback for selected assets and optional media picker parameters.

```APIDOC
## GalleryMediaPicker Widget

### Description

The main widget for the Gallery Media Picker. It takes a callback for selected assets and optional media picker parameters.

### Widget Signature

```dart
GalleryMediaPicker({
  required void Function(List<PickedAssetModel> assets) pathList,
  MediaPickerParamsModel? mediaPickerParams,
})
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> assets) { 
    // Handle selected assets
  },
  mediaPickerParams: MediaPickerParamsModel(),
)
```

### Response

This widget does not directly return a value but invokes the `pathList` callback with selected assets.
```

--------------------------------

### GalleryMediaPicker Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Defines the constructor for the GalleryMediaPicker widget, specifying required parameters like pathList and mediaPickerParams, and an optional appBarLeadingWidget.

```dart
GalleryMediaPicker(
  required ValueChanged<List<PickedAssetModel>> pathList,
  required MediaPickerParamsModel mediaPickerParams,
  Widget? appBarLeadingWidget,
)
```

--------------------------------

### Building UI Based on Permission State

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/types.md

Shows how to conditionally render UI elements based on the gallery permission state using ValueListenableBuilder. Displays a loading indicator, permission denied UI, or the picker UI.

```dart
ValueListenableBuilder<PermissionState>(
  valueListenable: controller.permitState,
  builder: (_, state, __) {
    if (state == PermissionState.notDetermined) {
      return const Center(child: CircularProgressIndicator());
    }
    if (!state.isAuth) {
      return _buildPermissionDeniedUI();
    }
    return _buildPickerUI();
  },
)
```

--------------------------------

### General UI Strings

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/06-gallery-media-picker-translations.md

This section details the individual string properties available for customization within the GalleryMediaPickerTranslations model, including their default values and usage contexts.

```APIDOC
## General UI Strings

### No Media Found

#### Description
Text displayed when the selected album is empty or contains no assets matching the media type filter.

#### Default Value
`'No media found.'`

#### Usage
- Shown in the center of the grid when `assetCount` is 0.

### Recent Album Label

#### Description
Label for the OS-provided "Recents" or "Recent" album.

#### Default Value
`'Recent'`

#### Usage
- Album selector dropdown when the recents album is detected.

### Tap to Open Settings

#### Description
Button label shown when gallery permissions are denied, allowing the user to open app settings to grant access.

#### Default Value
`'Tap to open settings'`

#### Usage
- Permission-denied error screen.

### Permission Denied

#### Description
Error message displayed when the user has not granted photo library access.

#### Default Value
`'Permissions denied. Please grant access to your gallery.'`

#### Usage
- Permission-denied error screen above the settings button.

### Max Items Picked

#### Description
Toast notification shown when the user attempts to select more items than `maxPickImages` allows. Use `%s` as a placeholder for the numeric limit.

#### Default Value
`'You have already picked %s items.'`

#### Usage
- Toast notification when selection limit is reached.

#### Placeholder
- `%s`: Replaced with the actual numeric limit.
```

--------------------------------

### Configure Thumbnail and Grid Colors

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Define the background colors for thumbnails and the main grid view. This helps in setting the overall aesthetic of the media grid.

```dart
MediaPickerParamsModel(
  thumbnailBgColor: Color?,         // Thumbnail placeholder
  gridViewBgColor: Color?,          // Grid background
)
```

```dart
const darkConfig = MediaPickerParamsModel(
  thumbnailBgColor: Color(0xFF18181B),
  gridViewBgColor: Color(0xFF09090B),
);
```

--------------------------------

### Multi-Selection with Custom Styling

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/01-gallery-media-picker-widget.md

Shows how to configure the GalleryMediaPicker for multi-asset selection with custom UI elements like app bar color and text color. It also allows setting the number of columns and thumbnail quality.

```dart
GalleryMediaPicker(
  pathList: (List<PickedAssetModel> assets) {
    context.read<PhotoProvider>().setSelectedPhotos(assets);
  },
  mediaPickerParams: MediaPickerParamsModel(
    maxPickImages: 10,
    singlePick: false,
    appBarHeight: 60,
    appBarColor: Colors.black,
    albumTextColor: Colors.white,
    gridViewBgColor: Colors.black,
    crossAxisCount: 4,
    thumbnailQuality: ThumbnailQuality.high,
    gridViewController: _scrollController,
  ),
)
```

--------------------------------

### Build Asset Widget with Selection

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

Wraps the asset display in a `_SelectionWatcher` for efficient selection updates and an `AnimatedTapWidget` for tap interactions. It uses a `ThumbnailWidget` to display the asset.

```dart
Widget _buildAssetWidget(AssetEntity asset, int index)
```

```dart
return _SelectionWatcher(
  key: ValueKey(asset.id),
  asset: asset,
  builder: (_, {required isSelected}) {
    return AnimatedTapWidget(
      onTap: () => provider.pickEntity(asset),
      child: ThumbnailWidget(
        asset: asset,
        isSelected: isSelected,
        params: provider.paramsModel,
      ),
    );
  },
);
```

--------------------------------

### Scoped State with Independent Pickers

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/05-gallery-media-provider.md

Demonstrates how to create two independent gallery pickers, each with its own isolated controller by wrapping them in separate GalleryMediaProvider instances.

```dart
// Two completely independent pickers with separate controllers
Column(
  children: [
    GalleryMediaProvider(
      controller: _pickerController1,
      child: const GalleryMediaPicker(...),
    ),
    GalleryMediaProvider(
      controller: _pickerController2,
      child: const GalleryMediaPicker(...),
    ),
  ],
)
```

--------------------------------

### Handle Thumbnail Generation Errors

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/errors.md

Displays a black placeholder when thumbnail generation fails due to platform errors or unsupported formats. No user action is required.

```dart
Image(
  image: AssetEntityImageProvider(asset, thumbnailSize: ...),
  errorBuilder: (_, __, ___) => const ColoredBox(color: Colors.black),
)
```

--------------------------------

### Handle Album Change

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/09-gallery-grid-view-widget.md

Callback executed when the user switches albums. It invalidates preloads, clears the cache, and loads the initial assets for the new album.

```dart
void _onAlbumChanged() {
  _albumChangeId++;
  _assetCache.clear();
  unawaited(_loadInitialAssets(_albumChangeId));
}
```

--------------------------------

### GalleryMediaPickerTranslations Constructor

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/06-gallery-media-picker-translations.md

The constructor for GalleryMediaPickerTranslations allows for the customization of all user-facing strings and accessibility labels. Each parameter has a default value that can be overridden.

```APIDOC
## Constructor GalleryMediaPickerTranslations

### Description
Initializes a new instance of the GalleryMediaPickerTranslations class with customizable text for various UI elements and messages.

### Parameters
- **noMediaFound** (string) - Optional - Default: 'No media found.' - Text displayed when no media is found in the selected album.
- **recent** (string) - Optional - Default: 'Recent' - Label for the OS-provided 'Recent' album.
- **tapToOpenSettings** (string) - Optional - Default: 'Tap to open settings' - Button label to open app settings when permissions are denied.
- **permissionDenied** (string) - Optional - Default: 'Permissions denied. Please grant access to your gallery.' - Error message shown when gallery permissions are denied.
- **maxItemsPicked** (string) - Optional - Default: 'You have already picked %s items.' - Toast message when the maximum number of items is picked. Use `%s` as a placeholder for the item count.
- **videoLabel** (string) - Optional - Default: 'Video' - Label for video media type.
- **imageLabel** (string) - Optional - Default: 'Image' - Label for image media type.
- **gifLabel** (string) - Optional - Default: 'GIF' - Label for GIF media type.
- **selectedLabel** (string) - Optional - Default: 'Selected' - Accessibility label indicating an item is selected.
- **notSelectedLabel** (string) - Optional - Default: 'Not selected' - Accessibility label indicating an item is not selected.
```

--------------------------------

### Check Media Picker Permission State

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Verify if the application has the necessary permissions to access the media library before enabling picker functionality.

```dart
if (controller.permitState.value == PermissionState.authorized) {
  // Picker is functional
}
```

--------------------------------

### Optimize for High-Quality Display

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Configure settings for displaying media with high quality. This involves setting higher thumbnail quality and adjusting item aspect ratio and spacing.

```dart
const params = MediaPickerParamsModel(
  thumbnailQuality: ThumbnailQuality.high,     // 400×400 pixels
  childAspectRatio: 1.0,                       // Square items
  gridPadding: EdgeInsets.all(4),              // Better spacing
);
```

--------------------------------

### Single Image Selection Configuration

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/configuration.md

Set up the media picker for selecting only one image by configuring `singlePick: true`, `maxPickImages: 1`, and `mediaType: GalleryMediaType.image`.

```dart
final singleImageConfig = MediaPickerParamsModel(
  singlePick: true,
  maxPickImages: 1,
  mediaType: GalleryMediaType.image,
  appBarHeight: 50,
  crossAxisCount: 4,
);
```

--------------------------------

### Listen to Media Selection Changes

Source: https://github.com/camilo1498/gallery_media_picker/blob/master/_autodocs/INDEX.md

Use ValueListenableBuilder to reactively update your UI when the user selects or deselects media assets.

```dart
ValueListenableBuilder<List<PickedAssetModel>>(
  valueListenable: controller.pickedFile,
  builder: (_, assets, __) { },
)
```