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

Add the dependency (see above)
Configure platform permissions (see above)
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

Property	Type	Required	Description
`onSave`	`Function(File)`	✅	Called with edited image file
`onError`	`Function(String)`	❌	Called when error occurs
`networkImages`	`List<String>`	❌	Network images to choose from
`config`	`EditorConfig`	❌	Custom theming and behavior
`showGallery`	`bool`	❌	Show gallery button (default: true)
`showCamera`	`bool`	❌	Show camera button (default: true)
`showNetwork`	`bool`	❌	Show network button (default: true)

EditorConfig

Configuration for the editor's appearance and behavior.

Properties

Property	Type	Default	Description
`primaryColor`	`Color`	`Colors.blue`	Primary UI color
`secondaryColor`	`Color`	`Colors.grey`	Secondary UI color
`backgroundColor`	`Color`	`Colors.white`	Background color
`textColor`	`Color`	`Colors.black87`	Text color
`borderColor`	`Color`	`Colors.grey`	Border color
`maxHeight`	`double`	`600.0`	Maximum editor height
`fontFamily`	`String?`	`null`	Custom font family
`titleFontSize`	`double`	`18.0`	Title font size
`bodyFontSize`	`double`	`14.0`	Body text font size
`buttonFontSize`	`double`	`16.0`	Button font size
`borderRadius`	`double`	`8.0`	Border radius
`padding`	`EdgeInsets`	`EdgeInsets.all(16.0)`	UI padding
`margin`	`EdgeInsets`	`EdgeInsets.all(8.0)`	UI margin
`showLoadingIndicators`	`bool`	`true`	Show loading indicators
`loadingText`	`String`	`'Loading...'`	Loading text
`saveButtonText`	`String`	`'Save'`	Save button text
`addOverlayText`	`String`	`'Add Overlay Images'`	Add overlay text
`galleryButtonText`	`String`	`'Gallery'`	Gallery button text
`cameraButtonText`	`String`	`'Camera'`	Camera button text
`networkButtonText`	`String`	`'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:

Check the documentation
Search existing issues
Create a new issue with detailed information

image_overlay_editor

Features

Getting started

Platform Configuration

Android

iOS

Web

Quick Setup

API Reference

ImageEditor

Properties

EditorConfig

Properties

Examples

Custom Theme

Dark Theme

Brand Theme

Control Button Visibility

Upload Examples

Firebase Storage

HTTP Upload

Local Database

Dependencies

Usage

Basic Usage

Complete Example

Performance Features

Security & Permissions

License

Contributing

Support

Libraries

image_overlay_editor package