safe_image

A Flutter plugin for safe image loading from URLs with native downsampling. Prevents OOM crashes and UI jank.

Features

  • Streaming HTTP download — never loads full image body into memory
  • Native downsampling — resizes images on the platform side (Android/iOS) to avoid OOM
  • Disk caching — SHA-1 based cache keys with ETag support
  • Concurrency control — configurable limits for parallel downloads and processing
  • Automatic retry — falls back to reduced resolution on OOM/decode errors

Getting started

Add safe_image to your pubspec.yaml:

dependencies:
  safe_image: ^0.1.0

Usage

Basic usage

import 'package:safe_image/safe_image.dart';

SafeImageWidget(
  url: 'https://example.com/photo.jpg',
  width: 300,
  height: 200,
  fit: BoxFit.cover,
)

Wrap your app with SafeImageScope to share a single pipeline across all SafeImageWidgets:

SafeImageScope(
  config: SafeImageConfig(
    targetMaxSide: 1024,
    quality: 85,
    maxConcurrentDownloads: 6,
  ),
  child: MaterialApp(...),
)

Custom configuration

SafeImageWidget(
  url: imageUrl,
  config: SafeImageConfig(
    hardMaxDownloadBytes: 20 * 1024 * 1024,
    targetMaxSide: 1024,
    quality: 85,
    format: SafeImageFormat.webp,
    connectTimeout: Duration(seconds: 5),
    headers: {'Authorization': 'Bearer token'},
  ),
  placeholder: (context) => CircularProgressIndicator(),
  errorBuilder: (context, error) => Icon(Icons.broken_image),
)

Platform support

Platform Supported
Android Yes
iOS Yes

License

MIT License. See LICENSE for details.

Libraries

safe_image