image_overlay_editor 1.0.1

SDKflutter
Platformandroidioswindows

A production-ready Flutter package for creating image editors with overlay functionality. Perfect for apps that need to add stickers, text, or other images on top of photos and upload the result to cloud storage. Features drag & drop positioning, resize, rotate, multiple image sources (gallery/camera/network), extensive theming, and cloud-ready output. Includes required Android/iOS permissions and platform configurations.

image_overlay_editor

A Flutter package that provides a complete image editing solution with overlay functionality. Perfect for apps that need to add stickers, text, or other images on top of photos and upload the result to cloud storage.

Features

  • Drag & Drop: Intuitive positioning of overlay images with smooth interactions
  • Resize: Visual handles to resize overlays with aspect ratio preservation
  • Rotate: Smooth rotation controls for precise overlay positioning
  • Multiple Sources: Gallery, camera, and network images support
  • Cloud Ready: Returns edited image file ready for upload to any storage service
  • Customizable: Extensive theming with custom colors, fonts, and UI elements
  • Responsive: Works perfectly on all screen sizes and orientations
  • Performance Optimized: Efficient memory management and smooth animations
  • Production Ready: Comprehensive error handling and permission management
  • Fully Tested: Complete test coverage for all functionality

Getting started

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

dependencies:
  image_overlay_editor: ^1.0.0

Platform Configuration

⚠️ Important: You must configure platform permissions before using this package.

Android

Add the following permissions to your android/app/src/main/AndroidManifest.xml file:

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

iOS

Add the following keys to your ios/Runner/Info.plist file:

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photo library to pick images for editing</string>
<key>NSCameraUsageDescription</key>
<string>This app needs access to camera to take photos for editing</string>

Web

For web support, add the following to your web/index.html file inside the <head> tag:

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="apple-mobile-web-app-title" content="Image Editor">

Quick Setup

  1. Add the dependency (see above)
  2. Configure platform permissions (see above)
  3. Start using the package:
import 'package:image_overlay_editor/image_overlay_editor.dart';

ImageEditor(
  onSave: (file) => uploadToCloud(file),
)

API Reference

ImageEditor

The main widget that provides the image editing functionality.

Properties

PropertyTypeRequiredDescription
onSaveFunction(File)✅Called with edited image file
onErrorFunction(String)❌Called when error occurs
networkImagesList<String>❌Network images to choose from
configEditorConfig❌Custom theming and behavior
showGallerybool❌Show gallery button (default: true)
showCamerabool❌Show camera button (default: true)
showNetworkbool❌Show network button (default: true)

EditorConfig

Configuration for the editor's appearance and behavior.

Properties

PropertyTypeDefaultDescription
primaryColorColorColors.bluePrimary UI color
secondaryColorColorColors.greySecondary UI color
backgroundColorColorColors.whiteBackground color
textColorColorColors.black87Text color
borderColorColorColors.greyBorder color
maxHeightdouble600.0Maximum editor height
fontFamilyString?nullCustom font family
titleFontSizedouble18.0Title font size
bodyFontSizedouble14.0Body text font size
buttonFontSizedouble16.0Button font size
borderRadiusdouble8.0Border radius
paddingEdgeInsetsEdgeInsets.all(16.0)UI padding
marginEdgeInsetsEdgeInsets.all(8.0)UI margin
showLoadingIndicatorsbooltrueShow loading indicators
loadingTextString'Loading...'Loading text
saveButtonTextString'Save'Save button text
addOverlayTextString'Add Overlay Images'Add overlay text
galleryButtonTextString'Gallery'Gallery button text
cameraButtonTextString'Camera'Camera button text
networkButtonTextString'Network'Network button text

Examples

Custom Theme

ImageEditor(
  config: EditorConfig(
    primaryColor: Colors.green,
    secondaryColor: Colors.orange,
    backgroundColor: Colors.white,
    textColor: Colors.black87,
  ),
  onSave: (file) => uploadToCloud(file),
)

Dark Theme

ImageEditor(
  config: EditorConfig.darkTheme(),
  onSave: (file) => uploadToCloud(file),
)

Brand Theme

ImageEditor(
  config: EditorConfig.brandTheme(
    primaryColor: Colors.purple,
    secondaryColor: Colors.pink,
    fontFamily: 'Poppins',
  ),
  onSave: (file) => uploadToCloud(file),
)

Control Button Visibility

// Gallery only
ImageEditor(
  showGallery: true,
  showCamera: false,
  showNetwork: false,
  onSave: (file) => uploadToCloud(file),
)

// Camera only
ImageEditor(
  showGallery: false,
  showCamera: true,
  showNetwork: false,
  onSave: (file) => uploadToCloud(file),
)

// All options enabled (default)
ImageEditor(
  showGallery: true,
  showCamera: true,
  showNetwork: true,
  onSave: (file) => uploadToCloud(file),
)

Upload Examples

Firebase Storage

import 'package:firebase_storage/firebase_storage.dart';

void uploadToFirebase(File imageFile) async {
  final storageRef = FirebaseStorage.instance.ref();
  final imageRef = storageRef.child('edited_images/${DateTime.now().millisecondsSinceEpoch}.png');
  
  await imageRef.putFile(imageFile);
  final downloadUrl = await imageRef.getDownloadURL();
  print('Uploaded to Firebase: $downloadUrl');
}

HTTP Upload

import 'package:http/http.dart' as http;

void uploadToServer(File imageFile) async {
  final bytes = await imageFile.readAsBytes();
  final response = await http.post(
    Uri.parse('https://your-server.com/upload'),
    body: bytes,
    headers: {'Content-Type': 'image/png'},
  );
  print('Uploaded to server: ${response.statusCode}');
}

Local Database

import 'package:sqflite/sqflite.dart';

void saveToDatabase(File imageFile) async {
  final bytes = await imageFile.readAsBytes();
  final database = await openDatabase('my_database.db');
  
  await database.insert('images', {
    'data': bytes,
    'timestamp': DateTime.now().millisecondsSinceEpoch,
  });
  print('Saved to database');
}

Dependencies

This package uses the following dependencies:

  • flutter (>=3.0.0)
  • image_picker (^1.0.0) - For picking images from gallery/camera
  • screenshot (^2.1.0) - For capturing the edited image
  • path_provider (^2.1.0) - For temporary file management
  • permission_handler (^11.0.0) - For handling permissions

Usage

Basic Usage

import 'package:image_overlay_editor/image_overlay_editor.dart';

ImageEditor(
  onSave: (file) => uploadToCloud(file),
)

Complete Example

import 'package:flutter/material.dart';
import 'package:image_overlay_editor/image_overlay_editor.dart';
import 'dart:io';

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('My App')),
        body: Center(
          child: ElevatedButton(
            onPressed: () => _openEditor(context),
            child: const Text('Edit Image'),
          ),
        ),
      ),
    );
  }

  void _openEditor(BuildContext context) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => ImageEditor(
          networkImages: [
            'https://example.com/sticker1.png',
            'https://example.com/sticker2.png',
          ],
          onSave: (File editedImage) {
            uploadToFirebase(editedImage);
          },
          onError: (String error) {
            print('Error: $error');
          },
        ),
      ),
    );
  }

  void uploadToFirebase(File imageFile) async {
    // Your upload logic here
    print('Uploading: ${imageFile.path}');
  }
}

## Platform Support

- ✅ iOS (iOS 11.0+)
- ✅ Android (API level 21+)
- ✅ Web (Flutter 3.0+)
- ✅ macOS (macOS 10.14+)
- ✅ Windows (Windows 10+)
- ✅ Linux (Ubuntu 18.04+)

## Testing

The package includes comprehensive tests covering:

- Widget rendering and interactions
- Configuration options
- Image processing utilities
- Error handling scenarios
- Performance optimizations

Run tests with:
```bash
flutter test

Performance Features

  • Memory Efficient: Optimized image loading and processing
  • Smooth Animations: 60fps drag, resize, and rotate operations
  • Fast Rendering: Efficient widget tree and state management
  • Minimal Dependencies: Only essential packages included
  • Production Optimized: No debug prints or development code

Security & Permissions

  • Permission Handling: Automatic camera and gallery permission requests
  • Error Recovery: Graceful handling of permission denials
  • File Security: Secure temporary file creation and cleanup
  • Network Safety: Safe network image loading with error handling

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please:

  1. Check the documentation
  2. Search existing issues
  3. Create a new issue with detailed information