📦 image_picker_adapter

A highly customizable, cross-platform image picking, cropping, and compression toolkit built on top of Flutter's image_picker, image_cropper, and flutter_image_compress. This adapter provides a modular, testable, and UI-agnostic solution for seamless image selection and preprocessing in your apps.

🚀 Features

  • ✅ Platform-aware image selection from camera or gallery
  • ✂️ Optional image cropping (with customizable UI)
  • 🗜️ Optional image compression
  • 🧩 Modular architecture (SOLID principles)
  • 🔄 Supports Cubit for state-driven image picking
  • 🖼️ Custom UI builders for both avatar and image pickers
  • 📦 Easy to plug into any Flutter app via DI and BlocProvider

📦 Installation

Add the following to your pubspec.yaml:

dependencies:
  image_picker_adapter: latest_version

Then run:

flutter pub get

🧱 Architecture Overview

┌──────────────────────────┐
│    AppImagePicker        │ ◄── Customizable Widget
├──────────────────────────┤
│  ↳ ImagePickerCubit      │ ◄── Handles image picking states
│  ↳ ImagePickerManager    │ ◄── Coordinates services
│     ↳ AppImagePickerService
│     ↳ IImageCropperService
│     ↳ IImageCompressorService
└──────────────────────────┘

🛠️ Getting Started

1. ✅ Register Dependencies

void registerImagePickerAdapterDependencies() {
  sl.registerLazySingleton<AppImagePickerService>(() => AppImagePickerService());
  sl.registerLazySingleton<IImageCropperService>(() => AppImageCropperService());
  sl.registerLazySingleton<IImageCompressorService>(() => AppImageCompressorService());

  sl.registerLazySingleton<ImagePickerManager>(
    () => ImagePickerManager(
      pickerService: sl<AppImagePickerService>(),
      cropperService: sl<IImageCropperService>(),
      compressorService: sl<IImageCompressorService>(),
    ),
  );

  sl.registerFactory(
    () => ImagePickerCubit(imagePickerManager: sl<ImagePickerManager>()),
  );
}

2. 🧠 Provide Bloc

List<SingleChildWidget> imagePickerAdapterBlocProviders = [
  BlocProvider<ImagePickerCubit>(create: (_) => sl<ImagePickerCubit>()),
];

3. 🎨 Use AppImagePicker Widget

AppImagePicker(
  imageQuality: 80,
  crop: true,
  compress: true,
  onChanged: (file) {
    // Do something with XFile
  },
  builder: (file) => CircleAvatar(
    backgroundImage: file != null ? FileImage(File(file.path)) : null,
  ),
)

👤 Avatar Picker Example

AvatarImagePicker(
  imageSource: user.avatarUrl,
  radius: 40,
  crop: true,
  compress: true,
  onChanged: (file) => print('Picked: ${file?.path}'),
)

🧪 Extension Utilities

extension XFileParserExtension on XFile {
  Future<T?> parseAs<T>() async {
    if (T == File) return File(path) as T;
    if (T == Uint8List) return await readAsBytes() as T;
    if (T == String) return path as T;
    if (T == XFile) return this as T;
    throw UnsupportedError('Unsupported type conversion: $T');
  }
}

🧭 Source Selector Modes

  • bottomSheet (default)
  • alertDialog
  • custom

You can inject your own selector widget or use built-in ones like SourceSelectorDialog or ImageSourceSelector.

🧩 Customization

  • Build your own image viewer UI with builder in AppImagePicker
  • Customize source selection UI via IImageSourceSelectorService
  • Provide your own crop/compress service by implementing IImageCropperService, IImageCompressorService

📄 License

MIT License

🙌 Contributions

Feel free to open issues, pull requests or contribute ideas to enhance the image_picker_adapter.

🧠 Credits

👨‍💼 Author

image_picker_adapter Developed with ❤️ by Shohidul Islam

Libraries

application/managers/image_picker_manager
config/bloc_provider/register_reusable_image_widget_bloc_provider
config/dependency_injection/register_reusable_image_widget_dependencies
enums/source_selector_style
extensions/xfile_parser_extension
image_picker_adapter
services/app_image_compressor_service
services/app_image_cropper_service
services/app_image_picker_service
services/crop_aspect_ratio_preset_custom
services/i_services/i_image_compressor_service
services/i_services/i_image_cropper_service
services/i_services/i_image_source_selector_service
services/source_selector/image_source_selector_service
services/source_selector/present_source_selector_ui
typedefs/typedefs
view_models/image_picker_cubit/image_picker_cubit
views/image_picker/app_image_picker
views/image_picker/app_image_picker_error_widget
views/image_picker/avatar_image_picker
views/source_selector/image_source_selector
views/source_selector/selector_list_tile
views/source_selector/source_selector_dialog