{"id":32284379,"url":"https://github.com/mahmoudelsayed7/image-builder","last_synced_at":"2026-05-15T08:31:35.349Z","repository":{"id":319175879,"uuid":"1065293190","full_name":"MAHMOUDELSAYED7/Image-Builder","owner":"MAHMOUDELSAYED7","description":"ImageBuilder is a production-ready Flutter package that unifies image handling across network, assets, files, memory, and SVGs. It features built-in caching, adaptive loaders, flexible customization, and robust error handling. With extensive testing and reliable performance, it simplifies image rendering for scalable, production-grade Flutter apps.","archived":false,"fork":false,"pushed_at":"2025-10-16T21:52:03.000Z","size":33023,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-18T01:09:35.882Z","etag":null,"topics":["dart","dart-package","dependencies","flutter","flutter-package","flutter-plugin","image-builder","open-source","package","pubdev"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/image_builder","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MAHMOUDELSAYED7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T12:35:56.000Z","updated_at":"2025-10-16T21:52:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MAHMOUDELSAYED7/Image-Builder","commit_stats":null,"previous_names":["mahmoudelsayed7/image-builder"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/MAHMOUDELSAYED7/Image-Builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FImage-Builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FImage-Builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FImage-Builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FImage-Builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MAHMOUDELSAYED7","download_url":"https://codeload.github.com/MAHMOUDELSAYED7/Image-Builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MAHMOUDELSAYED7%2FImage-Builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280546390,"owners_count":26348719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","dart-package","dependencies","flutter","flutter-package","flutter-plugin","image-builder","open-source","package","pubdev"],"created_at":"2025-10-23T01:31:00.017Z","updated_at":"2025-10-23T01:31:58.727Z","avatar_url":"https://github.com/MAHMOUDELSAYED7.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ImageBuilder\n\nA comprehensive Flutter package for handling various image types including network images, SVGs, local assets, file images, and memory images with advanced caching, platform-adaptive loading indicators, and robust error handling.\n\n\nhttps://github.com/user-attachments/assets/7de0525a-c655-4fcd-8745-21d941465fb1\n\n\n## ✨ Features\n\n- 🖼️ **Multi-format support**: PNG, JPG, JPEG, WEBP, SVG\n- 🌐 **Network image loading**: Built-in caching with CachedNetworkImage\n- 📱 **Local asset support**: Seamless integration with Flutter assets\n- 📁 **File image support**: Load images directly from device files\n- 💾 **Memory image support**: Display images from Uint8List byte data\n- 🎨 **SVG customization**: Color tinting and scaling for vector graphics\n- ⚡ **Robust error handling**: Graceful fallbacks and custom error widgets\n- 🔄 **Platform-adaptive loading**: \n  - iOS/macOS: Native `CupertinoActivityIndicator`\n  - Android/Web: Material Design `CircularProgressIndicator`\n- 🎯 **Loading color customization**: Custom colors for loading indicators\n- 📏 **Flexible sizing**: Individual width/height or unified size parameter\n- 🛡️ **Production-ready**: Comprehensive error handling prevents crashes\n- 🧪 **Well-tested**: Extensive test suite with 25+ test cases covering all functionality\n\n## 📦 Installation\n\nAdd this to your package's `pubspec.yaml` file:\n\n```yaml\ndependencies:\n  image_builder: ^1.2.0\n```\n\nThen run:\n\n```bash\nflutter pub get\n```\n\n## 🚀 Quick Start\n\nImport the package:\n\n```dart\nimport 'package:image_builder/image_builder.dart';\n```\n\n### Basic Usage\n\n```dart\n// Display any type of image (network, asset, SVG)\nImageBuilder('assets/images/logo.png')\n\n// Display a network image with adaptive loading\nImageBuilder('https://example.com/image.jpg')\n```\n\n### 📐 Custom Sizing\n\n```dart\n// Using individual width and height\nImageBuilder(\n  'assets/images/logo.svg',\n  width: 100,\n  height: 100,\n  fit: BoxFit.cover,\n)\n\n// Using unified size (sets both width and height)\nImageBuilder(\n  'assets/images/icon.png',\n  size: 50,\n)\n```\n\n### 🎨 SVG Color Customization\n\n```dart\n// Tint SVG with custom colors\nImageBuilder(\n  'assets/icons/heart.svg',\n  size: 24,\n  color: Colors.red, // Apply red tint to SVG\n)\n```\n\n### 📁 File Images\n\n```dart\nimport 'dart:io';\n\n// Display image from device file\nfinal File imageFile = File('/path/to/image.jpg');\nImageBuilder(\n  imageFile,\n  width: 200,\n  height: 150,\n  fit: BoxFit.cover,\n)\n```\n\n### 💾 Memory Images\n\n```dart\nimport 'dart:typed_data';\n\n// Display image from memory bytes\nfinal Uint8List imageBytes = await getImageBytes();\nImageBuilder(\n  imageBytes,\n  width: 200,\n  height: 150,\n  fit: BoxFit.cover,\n)\n```\n\n### 🔄 Platform-Adaptive Loading\n\nThe package automatically uses platform-appropriate loading indicators:\n\n```dart\n// Automatic platform detection\nImageBuilder(\n  'https://example.com/image.jpg',\n  width: 200,\n  height: 200,\n  useAdaptiveLoading: true, // Default: true\n)\n\n// Force Material Design loading (all platforms)\nImageBuilder(\n  'https://example.com/image.jpg',\n  width: 200,\n  height: 200,\n  useAdaptiveLoading: false,\n)\n```\n\n**Platform Behavior:**\n- **iOS/macOS**: Uses `CupertinoActivityIndicator` for native look\n- **Android/Web/Others**: Uses `CircularProgressIndicator` for Material Design\n\n### 🎯 Custom Loading Colors\n\nPersonalize your loading indicators with custom colors:\n\n```dart\n// Blue loading indicator\nImageBuilder(\n  'https://example.com/large-image.jpg',\n  width: 200,\n  height: 200,\n  useAdaptiveLoading: true,\n  loadingColor: Colors.blue, // Works on both Cupertino and Material indicators\n)\n\n// Custom color with hex value\nImageBuilder(\n  'https://example.com/image.jpg',\n  width: 200,\n  height: 200,\n  loadingColor: Color(0xFF6B46C1), // Custom purple\n)\n```\n\n### 🛡️ Advanced Error Handling\n\n```dart\nImageBuilder(\n  'https://example.com/image.jpg',\n  width: 200,\n  height: 200,\n  placeholder: Container(\n    color: Colors.grey[200],\n    child: const CircularProgressIndicator(),\n  ),\n  errorWidget: Container(\n    color: Colors.red[100],\n    child: Column(\n      mainAxisAlignment: MainAxisAlignment.center,\n      children: [\n        Icon(Icons.error, color: Colors.red),\n        Text('Failed to load image'),\n      ],\n    ),\n  ),\n)\n```\n\n## 📚 Complete Example\n\nHere's a comprehensive example showcasing all major features:\n\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:image_builder/image_builder.dart';\n\nclass ImageGallery extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: Text('ImageBuilder Examples')),\n      body: SingleChildScrollView(\n        padding: EdgeInsets.all(16),\n        child: Column(\n          children: [\n            // Network image with adaptive loading\n            ImageBuilder(\n              'https://picsum.photos/300/200',\n              width: 300,\n              height: 200,\n              fit: BoxFit.cover,\n              loadingColor: Colors.blue,\n            ),\n            \n            SizedBox(height: 20),\n            \n            // SVG with custom color\n            ImageBuilder(\n              'assets/icons/star.svg',\n              size: 60,\n              color: Colors.amber,\n            ),\n            \n            SizedBox(height: 20),\n            \n            // Local image with error handling\n            ImageBuilder(\n              'assets/images/photo.png',\n              width: 200,\n              height: 150,\n              fit: BoxFit.cover,\n              errorWidget: Container(\n                width: 200,\n                height: 150,\n                color: Colors.grey[200],\n                child: Icon(Icons.broken_image, size: 50),\n              ),\n            ),\n\n            SizedBox(height: 20),\n            \n            // File image\n            ImageBuilder(\n              File('/path/to/device/image.jpg'),\n              width: 200,\n              height: 150,\n              fit: BoxFit.cover,\n            ),\n\n            SizedBox(height: 20),\n            \n            // Memory image\n            ImageBuilder(\n              imageBytes, // Uint8List\n              width: 200,\n              height: 150,\n              fit: BoxFit.cover,\n            ),\n          ],\n        ),\n      ),\n    );\n  }\n}\n```\n\n## 🎮 Interactive Example App\n\nThe package includes a comprehensive example app that demonstrates all features including **device image upload functionality**:\n\n- **Gallery Selection**: Pick images from your device's photo library\n- **Camera Capture**: Take new photos directly from the camera\n- **Cross-Platform**: Works on iOS, Android, macOS, and other Flutter-supported platforms\n- **Real-time Preview**: See ImageBuilder in action with your own images\n\nTo run the example app:\n\n```bash\ncd example\nflutter run\n```\n\nThe example app showcases:\n- Network image loading with adaptive indicators\n- SVG rendering with color customization  \n- Memory image display from asset bytes (using `photo.jpg`)\n- **Cross-platform file picker** (works on Mobile, Desktop \u0026 Web)\n- **Device image upload** (gallery/camera selection for mobile)\n- Error handling and fallback widgets\n- All supported image formats\n\n**Platform Support**:\n- **Mobile (iOS/Android)**: Gallery selection with device files\n- **Desktop (macOS/Windows/Linux)**: Native file picker with local files\n- **Web**: File selection with automatic fallback to memory bytes\n\n**Smart Platform Detection**: The example app automatically shows the appropriate UI based on your platform - file picker on desktop/web or gallery selection on mobile.\n\nPerfect for testing the package capabilities and understanding implementation patterns!\n\n## 📖 API Reference\n\n### ImageBuilder Constructor\n\nThe ImageBuilder widget provides a single unified constructor that accepts different image sources.\n\n#### Constructor (Recommended)\n```dart\nImageBuilder(\n  Object source, {\n  Key? key,\n  double? width,\n  double? height,\n  double? size,\n  Color? color,\n  BoxFit fit = BoxFit.contain,\n  Widget? placeholder,\n  Widget? errorWidget,\n  Duration? maxCacheAge,\n  int? maxCacheSizeBytes,\n  bool useAdaptiveLoading = true,\n  Color? loadingColor,\n})\n```\n\nThe `source` parameter accepts:\n- **String**: Network URL, asset path, or local file path\n- **File**: Device file object (from dart:io)\n- **Uint8List**: Image data as bytes in memory\n\n#### Deprecated Constructors\n\n\u003e ⚠️ **Note**: `ImageBuilder.file()` and `ImageBuilder.memory()` are deprecated as of v1.2.0 and will be removed in v2.0.0. Please use the unified constructor `ImageBuilder()` instead.\n\n```dart\n// ❌ Deprecated (still works but shows warnings)\nImageBuilder.file(myFile, ...)\nImageBuilder.memory(myBytes, ...)\n\n// ✅ Recommended (new way)\nImageBuilder(myFile, ...)\nImageBuilder(myBytes, ...)\n```\n\n### Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|---------|\n| `source` | `Object` | **Required.** Image source - can be String (path/URL), File object, or Uint8List (bytes) | - |\n| `width` | `double?` | Image width in logical pixels (ignored if `size` provided) | `null` |\n| `height` | `double?` | Image height in logical pixels (ignored if `size` provided) | `null` |\n| `size` | `double?` | Sets both width and height to same value | `null` |\n| `color` | `Color?` | Tint color for SVG images | `null` |\n| `fit` | `BoxFit` | How image should be inscribed into layout space | `BoxFit.contain` |\n| `placeholder` | `Widget?` | Custom widget shown while loading (overrides adaptive loading) | `null` |\n| `errorWidget` | `Widget?` | Custom widget shown when loading fails | `null` |\n| `maxCacheAge` | `Duration?` | Maximum cache duration for network images | `null` |\n| `maxCacheSizeBytes` | `int?` | Maximum cache size in bytes | `null` |\n| `useAdaptiveLoading` | `bool` | Enable platform-adaptive loading indicators | `true` |\n| `loadingColor` | `Color?` | Custom color for adaptive loading indicators | `null` |\n\n## 🎯 Supported Image Formats\n\n### Network Images\n- **All formats** supported by Flutter's network image loading\n- **HTTPS/HTTP** protocols supported\n- **Automatic caching** with `CachedNetworkImage`\n- **Custom cache duration** and size limits\n\n### Local Assets  \n- **PNG, JPG, JPEG**: Standard raster formats\n- **WEBP**: Modern efficient format\n- **Assets folder** integration with `pubspec.yaml`\n\n### Vector Graphics\n- **SVG**: Scalable vector graphics with color customization\n- **Color tinting**: Apply any color to SVG elements\n- **Perfect scaling**: No quality loss at any size\n\n## 🔧 Platform Support\n\n| Platform | Adaptive Loading | Network Images | Local Assets | SVG Support |\n|----------|------------------|----------------|--------------|-------------|\n| **iOS** | ✅ Cupertino | ✅ | ✅ | ✅ |\n| **macOS** | ✅ Cupertino | ✅ | ✅ | ✅ |\n| **Android** | ✅ Material | ✅ | ✅ | ✅ |\n| **Web** | ✅ Material | ✅ | ✅ | ✅ |\n| **Windows** | ✅ Material | ✅ | ✅ | ✅ |\n| **Linux** | ✅ Material | ✅ | ✅ | ✅ |\n\n*_macOS requires network entitlements for network images_\n\n## 🔗 Dependencies\n\nThis package uses these well-maintained dependencies:\n\n- **[cached_network_image](https://pub.dev/packages/cached_network_image)** `^3.3.0` - Network image caching and loading\n- **[flutter_svg](https://pub.dev/packages/flutter_svg)** `^2.0.9` - SVG rendering and color customization\n\n## 🧪 Testing\n\nThe package includes comprehensive tests covering:\n\n- ✅ **Platform-adaptive loading** behavior across all platforms\n- ✅ **Loading color customization** functionality\n- ✅ **Network error handling** and recovery\n- ✅ **File image loading** with proper error handling\n- ✅ **Memory image display** from Uint8List data\n- ✅ **Graceful error states** without crashes\n- ✅ **Cross-platform compatibility** testing\n- ✅ **SVG color tinting** and rendering\n- ✅ **Robust widget construction** for all image types\n\nRun tests with:\n```bash\nflutter test\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. \n\nFor major changes, please open an issue first to discuss what you would like to change.\n\n## 📄 License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelsayed7%2Fimage-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahmoudelsayed7%2Fimage-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahmoudelsayed7%2Fimage-builder/lists"}