Image Editor Flutter SDK

中文

Overview

Image Editor is an embeddable Flutter component that brings cropping, rotation, and text overlays to your app. It ships with platform-friendly image loading/export helpers and a reactive ImageEditorController, enabling native-like editing workflows in minutes.

Highlights

• Rich toolset: cropping (free, 16:9, 5:4, 1:1), rotation (free angle, ±90°), and text layers.
• Stateful workflow: built-in history stack with undo and reset-to-original.
• Highly configurable: tune tool availability, crop presets, rotation options, and top toolbar copy/colors via ImageEditorConfig.
• Cross-platform loaders: helpers such as loadImageFromAssets, loadImageFromFile, and loadImageFromNetwork hide platform differences.
• Pixel export: convert edited ui.Image instances to PNG/JPEG bytes, optionally apply ImageCompressionConfig scaling, or persist them via saveImageToTempFile when a file path is required.
• Gesture friendly: pinch-to-zoom, drag, and tap to select text layers.

Project Layout

lib/
  image_editor.dart          # Package entry point
  controller/                # Core controller, crop/rotation/text/history handlers
  models/                    # Configurations and data models
  utils/                     # Image loading, exporting, coordinate helpers
  widgets/                   # Main view, toolbars, and painter

See doc/api_reference.md for detailed API descriptions.

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_img_editor: ^0.0.3 # last verions

Run:

flutter pub get

Quick Start

import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import 'package:flutter_img_editor/image_editor.dart';

class AvatarEditorDemo extends StatefulWidget {
  const AvatarEditorDemo({super.key});

  @override
  State<AvatarEditorDemo> createState() => _AvatarEditorDemoState();
}

class _AvatarEditorDemoState extends State<AvatarEditorDemo> {
  ui.Image? _avatar;
  ui.Image? _edited;

  @override
  void initState() {
    super.initState();
    _loadAvatar();
  }

  Future<void> _loadAvatar() async {
    final ui.Image image = await loadImageFromAssets('assets/sample.jpg');
    if (!mounted) return;
    setState(() {
      _avatar = image;
    });
  }

  Future<void> _openEditor() async {
    final ui.Image? avatar = _avatar;
    if (avatar == null) return;
    final ui.Image? result = await Navigator.push<ui.Image?>(
      context,
      MaterialPageRoute(
        builder: (_) => ImageEditor(
          image: avatar,
          config: const ImageEditorConfig(
            // lockToTool: LockToTool.crop1_1, // These parameters will be directly ignored. lockToTool has the highest priority and will immediately perform cropping. 
            enableText: false,
            cropOptions: CropOptionConfig(
              enableFree: false,
              enable16By9: false,
              enable5By4: false,
              enable1By1: true,
            ),
            rotateOptions: RotateOptionConfig(
              enableFree: false,
              enableFixed: true,
            ),
            topToolbar: TopToolbarConfig(
              titleText: 'Edit Avatar',
              confirmText: 'Done',
            ),
            compression: ImageCompressionConfig(
              enabled: true,
              scale: 0.5,
            ),
          ),
        ),
      ),
    );
    if (!mounted || result == null) return;
    setState(() {
      _edited = result;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Avatar Editor Demo')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: _avatar == null ? null : _openEditor,
              child: const Text('Open Editor'),
            ),
            const SizedBox(height: 16),
            if (_edited != null)
              SizedBox(
                height: 180,
                child: RawImage(image: _edited),
              ),
          ],
        ),
      ),
    );
  }
}

1. Load an image resource

final ui.Image image = await loadImageFromAssets('assets/sample.jpg');

Other entry points:

• loadImageFromFile(path): available on IO-capable platforms only.
• loadImageFromNetwork(url): accepts custom http.Client and headers.

2. Embed the editor

Place ImageEditor in your widget tree, passing the ui.Image to edit alongside optional configuration. The controller manages lifecycle, undo/apply operations, and exposes the latest editing state (see API reference).

3. Export the result

final Uint8List? pngBytes = await convertUiImageToBytes(editedImage);
// For workflows that absolutely need a path, use:
final String? tempPath = await saveImageToTempFile(
  editedImage,
  compression: const ImageCompressionConfig(scale: 0.5),
);

Recommendation
Prefer rendering ui.Image directly or sending Uint8List buffers. Converting to a temporary file path blocks on disk IO and may take ~1–2 seconds on mid-range devices.

4. Optional: enable export-time compression

const compression = ImageCompressionConfig(
  enabled: true,
  scale: 0.3, // downscale width/height
  format: ui.ImageByteFormat.png,
);

final ui.Image? result = await Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => ImageEditor(
      image: avatar,
      config: ImageEditorConfig(compression: compression),
    ),
  ),
);

final Uint8List? compressedBytes =
    await convertUiImageToBytes(result!, compression: compression);

Use scale to shrink pixel dimensions and reduce memory/disk footprint. enabled defaults to true, and values in (0,1] take effect. PNG remains lossless; apply custom pipelines if you need additional compression.

Example App

The example/ folder showcases asset, gallery, camera, and network flows. Run it with:

cd example
flutter run

FAQ

• Why is a crop ratio missing? Disable a ratio in ImageEditorConfig.cropOptions and it disappears from the toolbar.
• How do I control rotation options? Use ImageEditorConfig.rotateOptions to enable/disable free rotation (enableFree) and fixed-angle rotation (enableFixed). When disabled, corresponding buttons are hidden.
• loadImageFromFile throws on Web? Web lacks direct file system access; the helper throws UnsupportedError. Use a file picker and manually decode bytes.
• How do I observe editor state? Use ImageEditorController to read active tool, crop rect, text layers, and more.

Contributing

Issues and pull requests are welcome. Please run flutter test and update documentation before submitting changes.

License

Released under the MIT License.

---

Extra API details live in doc/api_reference.md.