Skip to content
tamimattafiPublic
forked from mr0xf00/easycrop
Β 
Β 

Latest commit

Β 

History

95 Commits

Folders and files

Repository files navigation


Krop for Kotlin and Compose Multiplatform

Easy to use image cropping library for Kotlin and Compose Multiplatform, with support for shapes, aspect-ratios, transformations, large images, auto zoom...

Krop Release Kotlin License Apache 2.0

Demo

Krop supports the following targets: android, ios, jvm/desktop, js/browser, wasmJs

Getting Started

1. Add Dependencies

Version:

Krop Release

Compatibility:

Krop version Kotlin version Compose version
0.3.0-alpha01 2.2.20 1.9.0
0.2.0 2.1.21 1.8.0
0.1.4 2.0 1.7
0.1.2 2.0 1.6
0.1.0 1.9 1.6

Option 1: Add the ui module to use the crop dialog out of the box:

commonMain.dependencies {
    implementation("com.attafitamim.krop:ui:$version")
    
    // Optional: use extensions for different 3rd party libraries
    implementation("com.attafitamim.krop:extensions-filekit:$version")
}

Option 2: If you are looking for a custom design, use the core module instead:

commonMain.dependencies {
    implementation("com.attafitamim.krop:core:$version")
}

For hints on how to use core logic for a custom design, check sources of the ui module.

2. Create an ImageCropper instance

Option 1 : inside the composition

val imageCropper = rememberImageCropper()

Option 2 : outside the composition (eg. ViewModel)

class MyViewModel : ViewModel {
    val imageCropper = ImageCropper()
}

3. Trigger crop action through imageCropper

scope.launch {
    val result = imageCropper.crop(bitmap) // Suspends until user accepts or cancels cropping
    when (result) {
        CropResult.Cancelled -> { }
        is CropError -> { }
        is CropResult.Success -> { result.bitmap }
    }
}

4. Use the state from imageCropper to open the crop dialog

val cropState = imageCropper.cropState 
if(cropState != null) ImageCropperDialog(state = cropState)

That's it !

Customization

To customize the ui of the image cropper you can provide a different implementation of CropperStyle to the cropper dialog. You can also use the cropperStyle factory function. example :

ImageCropperDialog(
    state = cropState,
    style = cropperStyle(
        overlay = Color.Red.copy(alpha = .5f),
        autoZoom = false,
        guidelines = null,
    )
)

Use different image sources

Krop makes it possible to use different image sources depending on the platform.

Common πŸ‘₯πŸ”΅

The crop function provides overloads for ImageBitmap, but it is also possible to use a custom implementation of ImageSrc.

Available implementations for ImageSrc in common code are:

  • ImageBitmapSrc - takes ImageBitmap as a source.

Android πŸ“±πŸŸ’

For android, crop function provides overloads for File, Uri and ImageStream.

Available implementations for ImageSrc in android are:

  • ImageStreamSrc - takes ImageStream as a source.

Available implementations for ImageStream:

  • UriImageStream - takes Uri and Context as sources.
  • FileImageStream - takes File as a source.

iOS 🍎🟠

For ios, crop function provides overloads for UIImage, NSURL and PHAsset. You can also use cropPHAssetLocalIdentifier and cropPath to pass string values.

Available implementations for ImageSrc in ios are:

  • UIImageSrc - takes UIImage as a source.
  • NSURLImageSrc - takes NSURL or path: String as sources.
  • PHAssetImageSrc - takes PHAsset or localIdentifier: String as sources.

Desktop πŸ’»πŸ”΅

For desktop, crop function provides overloads for File and ImageStream.

Available implementations for ImageSrc in desktop are:

  • ImageStreamSrc - takes ImageStream as a source.

Available implementations for ImageStream:

  • FileImageStream - takes File as a source.

Use extensions

Krop also makes it possible to use different 3rd party libraries using extension modules.

FileKit

Step 1: Add FileKit extension to your project:

commonMain.dependencies {
    implementation("com.attafitamim.krop:extensions-filekit:$version")
}

Step 2: Use helper functions to load and save images:

val imagePicker = rememberFilePickerLauncher(type = FileKitType.Image) { image ->
    image?.let {
        scope.launch {
            // Convert the selected image to ImageSrc
            val imageSrc = image.toImageSrc()
            
            // Crop the image
            when (val result = imageCropper.cropSrc(imageSrc)) {
                CropResult.Cancelled -> {}
                is CropError -> { /* Handle error */ }
                is CropResult.Success -> {
                    // Convert the cropped image to bytes
                    val bitmap = result.bitmap
                    val bytes = bitmap.encodeToByteArray()
                    
                    // Save the cropped image
                    val file = FileKit.filesDir / "cropped_image.jpg"
                    file.write(bytes)
                }
            }
        }
    }
}

Releases

Used by

Contributors

Languages