Adaptive Image Loader πŸ–ΌοΈ

Pub Version Pub Points Pub Likes License: MIT Platform

A high-performance, drop-in replacement for Image.network that automatically resolves and loads images from Google Drive (Edge CDN), Dropbox, GitHub, GitLab, Box, OneDrive, and standard public URLs β€” with built-in disk caching, on-the-fly server-side resizing, and programmatic cache eviction.

No more broken preview links, 302 redirect lags, manual URL conversions, or rate-limit warning walls.

βš–οΈ Why AdaptiveImage vs Image.network?

Feature Standard Image.network AdaptiveImage ⚑
Google Drive Links ❌ Fails / 302 redirects / Rate limits βœ… Instant Google Edge CDN (0 Redirects)
Server-Side Downscaling ❌ Downloads full 15MB file βœ… Scales on CDN (=s400) β€” Saves 95% RAM
Dropbox Share Links ❌ Broken HTML preview page βœ… Direct media stream (?dl=1)
GitHub / GitLab Blob Links ❌ Broken HTML viewer βœ… Direct raw content stream
Box / OneDrive Links ❌ Web redirect walls βœ… Auto-converted direct stream
Offline Disk Caching ❌ None (Re-downloads every time) βœ… Built-in caching with 1 boolean
Programmatic Cache Eviction ❌ Complex boilerplate βœ… AdaptiveImage.evict(url)
Container Fit Behavior ⚠️ Can distort βœ… Preserves natural aspect ratio & bounds

✨ Features

  • ⚑ Google Edge CDN Acceleration: Resolves Google Drive links to Google's Edge CDN endpoint (https://lh3.googleusercontent.com/d/{FILE_ID}) for 0 HTTP redirects and ultra-low Time-To-First-Byte (TTFB).
  • πŸ“ On-The-Fly Server-Side Resizing: Scale huge images directly on Google's Edge servers (size: 400 $\to$ =s400) before downloading to mobile devices.
  • 🌐 Multi-Cloud & Git Repository Support:
    • Google Drive: /file/d/, open?id=, uc?id=, thumbnail?id=, docs.google.com
    • Dropbox: Shared links converted to direct streams (?dl=1)
    • GitHub: github.com/.../blob/... $\to$ raw.githubusercontent.com/...
    • GitLab: gitlab.com/.../-/blob/... $\to$ gitlab.com/.../-/raw/...
    • Box.com: app.box.com/s/... $\to$ app.box.com/shared/static/...
    • Microsoft OneDrive: onedrive.live.com & 1drv.ms links
  • 🧹 Programmatic Cache Eviction: Instantly purge outdated images from memory and disk caches with AdaptiveImage.evict(url).
  • πŸš€ Optional Disk Caching: Powered by cached_network_image and flutter_cache_manager.
  • 🎨 Full Image.network Parity: Supports fit, alignment, headers, colorBlendMode, placeholderColor, fadeInDuration, memCacheWidth, and memCacheHeight.
  • πŸ’™ Null-safe & Flutter 3.x+ ready.

πŸ“¦ Installation

Add this to your package's pubspec.yaml file:

dependencies:
  adaptive_image_loader: ^1.0.4

Then run:

flutter pub get

πŸš€ Quick Start & Code Examples

Automatically detects and resolves any cloud or web image link:

import 'package:adaptive_image_loader/adaptive_image_loader.dart';

AdaptiveImage.image(
  'https://drive.google.com/file/d/1a2B3c4D5e6F7g8H9i0J_k-L/view',
  width: double.infinity,
  height: 200,
  fit: BoxFit.cover,
  useCache: true,
)

2. Google Drive with Server-Side CDN Resizing

Save 95% bandwidth and memory by downscaling on Google's Edge servers:

AdaptiveImage.driveImage(
  'https://drive.google.com/file/d/FILE_ID/view',
  size: 400, // Transforms to https://lh3.googleusercontent.com/d/{ID}=s400
  width: 300,
  height: 200,
  fit: BoxFit.contain,
  placeholderColor: Colors.grey.shade200,
)

3. GitHub & GitLab Repository Raw Images

Display images directly from repository branches:

AdaptiveImage.gitHubImage(
  'https://github.com/flutter/flutter/blob/master/packages/flutter/assets/logo.png',
  width: 250,
  height: 120,
  fit: BoxFit.contain,
)

4. Background Images (CircleAvatar & DecorationImage)

Use AdaptiveImageProvider wherever an ImageProvider is accepted:

CircleAvatar(
  radius: 50,
  backgroundImage: AdaptiveImageProvider(
    'https://drive.google.com/file/d/FILE_ID/view',
    driveImageSize: 300,
    useCache: true,
  ),
)

5. Programmatic Cache Eviction

Force-refresh cached images (e.g. after a user changes their profile avatar):

await AdaptiveImage.evict('https://drive.google.com/file/d/FILE_ID/view');

πŸ” FAQ & Common Issues Solved

Why do Google Drive images fail in standard Image.network? Google Drive share links (like drive.google.com/file/d/...) lead to an HTML preview page rather than the raw image bytes. Even legacy download links (drive.google.com/uc?id=...) issue 302 redirects and frequently fail with rate-limit / virus-scan warning pages. AdaptiveImage resolves directly to Google's Edge CDN (lh3.googleusercontent.com/d/...), eliminating redirects and rate-limit walls completely.
How does server-side resizing save memory? When loading a 12MB (4000x3000px) photo in a 100x100 avatar, standard loaders download all 12MB and decode a massive bitmap into RAM. By specifying size: 200, Google's Edge CDN resizes the file on the server to ~20KB before transmitting it, dramatically speeding up rendering and preventing Out-Of-Memory (OOM) crashes.
Does it support offline caching? Yes! Setting useCache: true enables persistent disk caching via cached_network_image and flutter_cache_manager.

πŸ› οΈ Complete Example App

import 'package:flutter/material.dart';
import 'package:adaptive_image_loader/adaptive_image_loader.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Adaptive Image Loader Example')),
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            AdaptiveImage.driveImage(
              'https://drive.google.com/file/d/FILE_ID/view',
              size: 400,
              width: double.infinity,
              height: 200,
              fit: BoxFit.cover,
            ),
            const SizedBox(height: 16),
            AdaptiveImage.gitHubImage(
              'https://github.com/flutter/flutter/blob/master/packages/flutter/assets/logo.png',
              width: 200,
              height: 100,
            ),
          ],
        ),
      ),
    );
  }
}

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

adaptive_image_loader