image_cropper

Image Cropper

A Flutter plugin for Android, iOS and Web supports cropping images. This plugin is based on three different native libraries so it comes with different UI between these platforms.

Introduction

Image Cropper doesn't manipulate images in Dart codes directly, instead, the plugin uses Platform Channel to expose Dart APIs that Flutter application can use to communicate with three very powerful native libraries (uCrop, TOCropViewController and Cropper.js) to crop and rotate images. Because of that, all credits belong to these libraries.

uCrop - Yalantis

This project aims to provide an ultimate and flexible image cropping experience. Made in Yalantis

TOCropViewController - Tim Oliver

TOCropViewController is an open-source UIViewController subclass to crop out sections of UIImage objects, as well as perform basic rotations. It is excellent for things like editing profile pictures, or sharing parts of a photo online. It has been designed with the iOS Photos app editor in mind, and as such, behaves in a way that should already feel familiar to users of iOS.

Cropper.js - Fengyuan Chen

JavaScript image cropper.

How to install

Android

• Add UCropActivity into your AndroidManifest.xml

<activity
  android:name="com.yalantis.ucrop.UCropActivity"
  android:screenOrientation="portrait"
  android:theme="@style/Theme.AppCompat.Light.NoActionBar"/>

Note:

• From v1.2.0, you need to migrate your android project to v2 embedding (detail)

iOS

• No configuration required

Web

• Add following codes inside <head> tag in file web/index.html:

<head>
  ....

  <!-- cropperjs -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.css" />
  <script src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"></script>

  ....
</head>

Usage

Required parameters

• sourcePath: the absolute path of an image file.

Optional parameters

• maxWidth: maximum cropped image width.

• maxHeight: maximum cropped image height.

• aspectRatio: controls the aspect ratio of crop bounds. If this values is set, the cropper is locked and user can't change the aspect ratio of crop bounds.

• compressFormat: the format of result image, png or jpg (default is ImageCompressFormat.jpg).

• compressQuality: number between 0 and 100 to control the quality of image compression. Note: this field is ignored on Web.

• uiSettings: controls UI customization on specific platform (android, ios, web,...)

  • Android: see Android customization.

  • iOS: see iOS customization.

  • Web: see Web customization.

Note

• The result file is saved in NSTemporaryDirectory on iOS and application Cache directory on Android, so it can be lost later, you are responsible for storing it somewhere permanent (if needed).

• The implementation on Web is much different compared to the implementation on mobile app. It causes some configuration fields not working (compressQuality) on Web.

• WebUiSettings is required for Web.

Customization

Android

iOS

Web

  class CropperDialog extends StatefulWidget {
    ...
  }  

  class _CropperDialogState extends State<CropperDialog> {
    @override
    void initState() {
      super.initState();
      /// IMPORTANT: must to call this function
      widget.initCropper();
    }

    @override
    Widget build(BuildContext context) {
      Dialog(
        child: Column(
          children: [
            ...
            cropper,
            ...
            TextButton(
              onPressed: () async {
                /// IMPORTANT: to call crop() function and return
                /// result data to plugin, for example:
                final result = await crop();
                Navigator.of(context).pop(result);
              },
              child: Text('Crop'),
            )
          ]
        ),
      );
    }
  }

  WebUiSettings(
    ...
    customDialogBuilder: (cropper, initCropper, crop, rotate, scale) {
      return CropperDialog(
        cropper: cropper,
        initCropper: initCropper,
        crop: crop,
        rotate: rotate,
        scale: scale,
      );
    },
    ...
  )

Example

import 'package:image_cropper/image_cropper.dart';

CroppedFile croppedFile = await ImageCropper().cropImage(
    sourcePath: imageFile.path,
    uiSettings: [
      AndroidUiSettings(
        toolbarTitle: 'Cropper',
        toolbarColor: Colors.deepOrange,
        toolbarWidgetColor: Colors.white,
        aspectRatioPresets: [
          CropAspectRatioPreset.original,
          CropAspectRatioPreset.square,
          CropAspectRatioPresetCustom(),
        ],
      ),
      IOSUiSettings(
        title: 'Cropper',
        aspectRatioPresets: [
          CropAspectRatioPreset.original,
          CropAspectRatioPreset.square,
          CropAspectRatioPresetCustom(), // IMPORTANT: iOS supports only one custom aspect ratio in preset list
        ],
      ),
      WebUiSettings(
        context: context,
      ),
    ],
  );

class CropAspectRatioPresetCustom implements CropAspectRatioPresetData {
  @override
  (int, int)? get data => (2, 3);

  @override
  String get name => '2x3 (customized)';
}
    

Credits

• Android: uCrop created by Yalantis
• iOS: TOCropViewController created by Tim Oliver
• Web: Cropper.js created by Fengyuan Chen