react-native-image-crop-picker

# react-native-image-crop-picker [![Backers on Open Collective](https://opencollective.com/react-native-image-crop-picker/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/react-native-image-crop-picker/sponsors/badge.svg)](#sponsors) <img src="svg.svg" width="50%" height="50%" /> iOS/Android image picker with support for camera, video, configurable compression, multiple images and cropping ## Result <p align="left"> <img width=200 title="iOS Single Pick" src="https://github.com/ivpusic/react-native-image-crop-picker/blob/master/images/ios_single_pick_v2.png"> <img width=200 title="iOS Multiple Pick" src="https://github.com/ivpusic/react-native-image-crop-picker/blob/master/images/ios_multiple_pick_v2.png"> <img width=200 title="iOS Crop Normal" src="https://github.com/ivpusic/react-native-image-crop-picker/blob/master/images/ios_normal_crop.png"> <img width=200 title="iOS Crop Circular" src="https://github.com/ivpusic/react-native-image-crop-picker/blob/master/images/ios_circular_crop.png"> </p> ## Important notes - If you are using react-native new architecture, you have to use react-native-image-crop-picker version >= 0.50.0 ## Usage Import library ```javascript import ImagePicker from "react-native-image-crop-picker"; ``` ### Select from gallery Call single image picker with cropping ```javascript ImagePicker.openPicker({ width: 300, height: 400, cropping: true, }).then((image) => { console.log(image); }); ``` Call multiple image picker ```javascript ImagePicker.openPicker({ multiple: true, }).then((images) => { console.log(images); }); ``` Select video only from gallery ```javascript ImagePicker.openPicker({ mediaType: "video", }).then((video) => { console.log(video); }); ``` **Android: The prop 'cropping' has been known to cause videos not to be displayed in the gallery on Android. Please do not set cropping to true when selecting videos.** ### Select from camera #### Image ```javascript ImagePicker.openCamera({ width: 300, height: 400, cropping: true, }).then((image) => { console.log(image); }); ``` #### Video ```javascript ImagePicker.openCamera({ mediaType: "video", }).then((image) => { console.log(image); }); ``` ### Crop picture ```javascript ImagePicker.openCropper({ path: "my-file-path.jpg", width: 300, height: 400, }).then((image) => { console.log(image); }); ``` ### Optional cleanup Module is creating tmp images which are going to be cleaned up automatically somewhere in the future. If you want to force cleanup, you can use `clean` to clean all tmp files, or `cleanSingle(path)` to clean single tmp file. ```javascript ImagePicker.clean() .then(() => { console.log("removed all tmp images from tmp directory"); }) .catch((e) => { alert(e); }); ``` ### Request Object | Property | Type | Description | | ----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | cropping | bool (default false) | Enable or disable cropping | | width | number | Width of result image when used with `cropping` option | | height | number | Height of result image when used with `cropping` option | | multiple | bool (default false) | Enable or disable multiple image selection | | writeTempFile (ios only) | bool (default true) | When set to false, does not write temporary files for the selected images. This is useful to improve performance when you are retrieving file contents with the `includeBase64` option and don't need to read files from disk. | | includeBase64 | bool (default false) | When set to true, the image file content will be available as a base64-encoded string in the `data` property. Hint: To use this string as an image source, use it like: ``<Image source={{uri: `data:${image.mime};base64,${image.data}`}} />`` | | includeExif | bool (default false) | Include image exif data in the response | | avoidEmptySpaceAroundImage (ios only) | bool (default true) | When set to true, the image will always fill the mask space. | | cropperActiveWidgetColor (android only) | string (default `"#424242"`) | When cropping image, determines ActiveWidget color. | | cropperStatusBarColor (android only) | string (default `#424242`) | When cropping image, determines the color of StatusBar. | | cropperToolbarColor (android only) | string (default `#424242`) | When cropping image, determines the color of Toolbar. | | cropperToolbarWidgetColor (android only) | string (default `darker orange`) | When cropping image, determines the color of Toolbar text and buttons. | | freeStyleCropEnabled | bool (default false) | Enables user to apply custom rectangle area for cropping | | cropperToolbarTitle | string (default `Edit Photo`) | When cropping image, determines the title of Toolbar. | | cropperCircleOverlay | bool (default false) | Enable or disable circular cropping mask. | | disableCropperColorSetters (android only) | bool (default false) | When cropping image, disables the color setters for cropping library. | | minFiles (ios only) | number (default 1) | Min number of files to select when using `multiple` option | | maxFiles | number (default 5) | Max number of files to select when using `multiple` option | | waitAnimationEnd (ios only) | bool (default true) | Promise will resolve/reject once ViewController `completion` block is called | | smartAlbums (ios only) | array ([supported values](https://github.com/ivpusic/react-native-image-crop-picker/blob/master/README.md#smart-album-types-ios)) (default ['UserLibrary', 'PhotoStream', 'Panoramas', 'Videos', 'Bursts']) | List of smart albums to choose from | | useFrontCamera | bool (default false) | Whether to default to the front/'selfie' camera when opened. Please note that not all Android devices handle this parameter, see [issue #1058](https://github.com/ivpusic/react-native-image-crop-picker/issues/1058) | | compressVideoPreset (ios only) | string (default MediumQuality) | Choose which preset will be used for video compression | | compressImageMaxWidth | number (default none) | Compress image with maximum width | | compressImageMaxHeight | number (default none) | Compress image with maximum height | | compressImageQuality | number (default 1 (Android)/0.8 (iOS)) | Compress image with quality (from 0 to 1, where 1 is best quality). On iOS, values larger than 0.8 don't produce a noticeable quality increase in most images, while a value of 0.8 will reduce the file size by about half or less compared to a value of 1. | | loadingLabelText (ios only) | string (default "Processing assets...") | Text displayed while photo is loading in picker | | mediaType | string (default any) | Accepted mediaType for image selection, can be one of: 'photo', 'video', or 'any' | | showsSelectedCount (ios only) | bool (default true) | Whether to show the number of selected assets | | sortOrder (ios only) | string (default 'none', supported values: 'asc', 'desc', 'none') | Applies a sort order on the creation date on how media is displayed within the albums/detail photo views when opening the image picker | | forceJpg (ios only) | bool (default false) | Whether to convert photos to JPG. This will also convert any Live Photo into its JPG representation | | showCropGuidelines (android only) | bool (default true) | Whether to show the 3x3 grid on top of the image during cropping | | showCropFrame (android only) | bool (default true) | Whether to show crop frame during cropping | | hideBottomControls (android only) | bool (default false) | Whether to display bottom controls | | enableRotationGesture (android only) | bool (default false) | Whether to enable rotating the image by hand gesture | | cropperChooseText (ios only) | string (default choose) | Choose button text | | cropperChooseColor (ios only) | string (default `#FFCC00`) | HEX format color for the Choose button. [Default color is controlled by TOCropViewController](https://github.com/TimOliver/TOCropViewController/blob/a942414508012b13102f776eb65dac655f31cabb/Objective-C/TOCropViewController/Views/TOCropToolbar.m#L444). | | cropperCancelText (ios only) | string (default Cancel) | Cancel button text | | cropperCancelColor (ios only) | string (default tint `iOS` color ) | HEX format color for the Cancel button. Default value is the default tint iOS color [controlled by TOCropViewController](https://github.com/TimOliver/TOCropViewController/blob/a942414508012b13102f776eb65dac655f31cabb/Objective-C/TOCropViewController/Views/TOCropToolbar.m#L433) | | cropperRotateButtonsHidden (ios only) | bool (default false) | Enable or disable cropper rotate buttons | #### Smart Album Types (ios) NOTE: Some of these types may not be available on all iOS versions. Be sure to check this to avoid issues. ``` ['PhotoStream', 'Generic', 'Panoramas', 'Videos', 'Favorites', 'Timelapses', 'AllHidden', 'RecentlyAdded', 'Bursts', 'SlomoVideos', 'UserLibrary', 'SelfPortraits', 'Screenshots', 'DepthEffect', 'LivePhotos', 'Animated', 'LongExposure'] ``` ### Response Object | Property | Type | Description | | ------------------------- | :----: | :------------------------------------------------------------------------------------- | | path | string | Selected image location. This is null when the `writeTempFile` option is set to false. | | localIdentifier(ios only) | string | Selected images' localidentifier, used for PHAsset searching | | sourceURL(ios only) | string | Selected images' source path, do not have write access | | filename | string | Selected images' filename | | width | number | Selected image width | | height | number | Selected image height | | mime | string | Selected image MIME type (image/jpeg, image/png) | | size | number | Selected image size in bytes | | duration | number | Video duration time in milliseconds | | data | base64 | Optional base64 selected file representation | | exif | object | Extracted exif data from image. Response format is platform specific | | cropRect | object | Cropped image rectangle (width, height, x, y) | | creationDate (ios only) | string | UNIX timestamp when image was created | | modificationDate | string | UNIX timestamp when image was last modified | # Install ## Step 1 ```bash npm i react-native-image-crop-picker --save ``` ## Step 2 ### iOS ```bash cd ios pod install ``` ## Step 3 ### iOS #### Step 1 In Xcode open Info.plist and add string key `NSPhotoLibraryUsageDescription` with value that describes why you need access to user photos. More info here https://forums.developer.apple.com/thread/62229. Depending on what features you use, you also may need `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` keys. #### (Optional) Step 2 - To localize the camera / gallery / cropper text buttons - Open your Xcode project - Go to your project settings by opening the project name on the Navigation (left side) - Select your project in the project list - Should be into the Info tab and add in Localizations the language your app was missing throughout the + - Rebuild and you should now have your app camera and gallery with the classic ios text in the language you added. ### Android - [Optional] If you want to use camera picker in your project, add following to `app/src/main/AndroidManifest.xml` - `<uses-permission android:name="android.permission.CAMERA"/>` - [Optional] If you want to use front camera, also add following to `app/src/main/ AndroidManifest.xml` - `<uses-feature android:name="android.hardware.camera" android:required="false" />` - `<uses-feature android:name="android.hardware.camera.front" android:required="false" />` ## TO DO - [ ] [Android] Standardize multiple select - [ ] [Android] Video compression ## Contributors This project exists thanks to all the people who contribute. [[Contribute]](CONTRIBUTING.md). <a href="graphs/contributors"><img src="https://opencollective.com/react-native-image-crop-picker/contributors.svg?width=890" /></a> ## Backers Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/react-native-image-crop-picker#backer)] <a href="https://opencollective.com/react-native-image-crop-picker#backers" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/backers.svg?width=890"></a> ## Sponsors Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/react-native-image-crop-picker#sponsor)] <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/0/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/0/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/1/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/1/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/2/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/2/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/3/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/3/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/4/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/4/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/5/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/5/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/6/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/6/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/7/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/7/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/8/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/8/avatar.svg"></a> <a href="https://opencollective.com/react-native-image-crop-picker/sponsor/9/website" target="_blank"><img src="https://opencollective.com/react-native-image-crop-picker/sponsor/9/avatar.svg"></a> ## License _MIT_