react-native-image-picker
Version:
A React Native module that allows you to use native UI to select media from the device library or directly from the camera
173 lines (119 loc) • 15.3 kB
Markdown
# react-native-image-picker 🎆
A React Native module that allows you to select a photo/video from the device library or camera.
[](https://img.shields.io/npm/dw/react-native-image-picker)
[](https://img.shields.io/npm/v/react-native-image-picker?color=red)
[](https://github.com/react-native-image-picker/react-native-image-picker/blob/main/LICENSE.md)
## Installation
```bash
yarn add react-native-image-picker
```
### New Architecture
To take advantage of the new architecture run-
#### iOS
```bash
RCT_NEW_ARCH_ENABLED=1 npx pod-install ios
```
#### Android
Set `newArchEnabled` to `true` inside `android/gradle.properties`
### Pre-Fabric (AKA not using the new architecture)
```bash
npx pod-install ios
```
## Post-install Steps
### iOS
Add the appropriate keys to your `Info.plist` depending on your requirement:
| Requirement | Key |
| ------------------------------ | ------------------------------------------------------- |
| Select image/video from photos | NSPhotoLibraryUsageDescription |
| Capture Image | NSCameraUsageDescription |
| Capture Video | NSCameraUsageDescription & NSMicrophoneUsageDescription |
### Android
No permissions required (`saveToPhotos` requires permission [check](#note-on-file-storage)).
Note: This library does not require `Manifest.permission.CAMERA`, if your app declares as using this permission in manifest then you have to obtain the permission before using `launchCamera`.
#### Targeting Android API Levels Below 30
If your app's `minSdkVersion` is set to below 30 and it does not already include or depend on `androidx.activity:activity:1.9.+` or a newer version, you'll need to add the following line to the dependencies section of your `app/build.gradle` file to ensure support for the backported AndroidX Photo Picker:
```groovy
dependencies {
...
implementation("androidx.activity:activity:1.9.+")
...
}
```
Additionally, you may need to update your `AndroidManifest.xml` to trigger the installation of the backported Photo Picker. For reference, you can check the example app's configuration in `example/android/app/src/main/AndroidManifest.xml` and `example/android/app/build.gradle`.
For more details, consult the Android documentation on AndroidX Photo Picker: [https://developer.android.com/training/data-storage/shared/photopicker](https://developer.android.com/training/data-storage/shared/photopicker)
## API Reference
## Methods
```js
import {launchCamera, launchImageLibrary} from 'react-native-image-picker';
```
### `launchCamera()`
Launch camera to take photo or video.
```js
launchCamera(options?, callback);
// You can also use as a promise without 'callback':
const result = await launchCamera(options?);
```
See [Options](#options) for further information on `options`.
The `callback` will be called with a response object, refer to [The Response Object](#the-response-object).
### `launchImageLibrary`
Launch gallery to pick image or video.
```js
launchImageLibrary(options?, callback)
// You can also use as a promise without 'callback':
const result = await launchImageLibrary(options?);
```
See [Options](#options) for further information on `options`.
The `callback` will be called with a response object, refer to [The Response Object](#the-response-object).
## Options
| Option | iOS | Android | Web | Description |
| ----------------------- | --- | ------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mediaType | OK | OK | OK | `photo` or `video` or `mixed`(`launchCamera` on Android does not support 'mixed'). Web only supports 'photo' for now. |
| restrictMimeTypes | NO | OK | NO | Array containing the mime-types allowed to be picked. Default is empty (everything). |
| maxWidth | OK | OK | NO | To resize the image. |
| maxHeight | OK | OK | NO | To resize the image. |
| videoQuality | OK | OK | NO | `low`, `medium`, or `high` on iOS, `low` or `high` on Android. |
| durationLimit | OK | OK | NO | Video max duration (in seconds). |
| quality | OK | OK | NO | 0 to 1, photos. |
| conversionQuality | NO | OK | NO | For conversion from HEIC/HEIF to JPEG, 0 to 1. Default is `0.92` |
| cameraType | OK | OK | NO | 'back' or 'front' (May not be supported in few android devices). |
| includeBase64 | OK | OK | OK | If `true`, creates base64 string of the image (Avoid using on large image files due to performance). |
| includeExtra | OK | OK | NO | If `true`, will include extra data which requires library permissions to be requested (i.e. exif data). |
| saveToPhotos | OK | OK | NO | (Boolean) Only for `launchCamera`, saves the image/video file captured to public photo. |
| selectionLimit | OK | OK | OK | Supports providing any integer value. Use `0` to allow any number of files on iOS version >= 14 & Android version >= 13. Default is `1`. |
| presentationStyle | OK | NO | NO | Controls how the picker is presented. `currentContext`, `pageSheet`, `fullScreen`, `formSheet`, `popover`, `overFullScreen`, `overCurrentContext`. Default is `currentContext`. |
| formatAsMp4 | OK | NO | NO | Converts the selected video to MP4 (iOS Only). |
| assetRepresentationMode | OK | OK | NO | A mode that determines which representation to use if an asset contains more than one on iOS or disables HEIC/HEIF to JPEG conversion on Android if set to 'current'. Possible values: 'auto', 'current', 'compatible'. Default is 'auto'. |
|
## The Response Object
| key | iOS | Android | Web | Description |
| ------------ | --- | ------- | --- | ------------------------------------------------------------------- |
| didCancel | OK | OK | OK | `true` if the user cancelled the process |
| errorCode | OK | OK | OK | Check [ErrorCode](#ErrorCode) for all error codes |
| errorMessage | OK | OK | OK | Description of the error, use it for debug purpose only |
| assets | OK | OK | OK | Array of the selected media, [refer to Asset Object](#Asset-Object) |
## Asset Object
| key | iOS | Android | Web | Photo/Video | Requires Permissions | Description |
| ------------ | --- | ------- | --- | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| base64 | OK | OK | OK | PHOTO ONLY | NO | The base64 string of the image (photos only) |
| uri | OK | OK | OK | BOTH | NO | The file uri in app specific cache storage. Except when picking **video from Android gallery** where you will get read only content uri, to get file uri in this case copy the file to app specific storage using any react-native library. For web it uses the base64 as uri. |
| originalPath | NO | OK | NO | BOTH | NO | The original file path. |
| width | OK | OK | OK | BOTH | NO | Asset dimensions |
| height | OK | OK | OK | BOTH | NO | Asset dimensions |
| fileSize | OK | OK | NO | BOTH | NO | The file size |
| type | OK | OK | NO | BOTH | NO | The file type |
| fileName | OK | OK | NO | BOTH | NO | The file name |
| duration | OK | OK | NO | VIDEO ONLY | NO | The selected video duration in seconds |
| bitrate | --- | OK | NO | VIDEO ONLY | NO | The average bitrate (in bits/sec) of the selected video, if available. (Android only) |
| timestamp | OK | OK | NO | BOTH | YES | Timestamp of the asset. Only included if 'includeExtra' is true |
| id | OK | OK | NO | BOTH | YES | local identifier of the photo or video. On Android, this is the same as fileName |
## Note on file storage
Image/video captured via camera will be stored in temporary folder allowing it to be deleted any time, so don't expect it to persist. Use `saveToPhotos: true` (default is `false`) to save the file in the public photos. `saveToPhotos` requires `WRITE_EXTERNAL_STORAGE` permission on Android 28 and below (The permission has to obtained by the App manually as the library does not handle that).
For web, this doesn't work.
## ErrorCode
| Code | Description |
| ------------------ | ------------------------------------------------- |
| camera_unavailable | Camera not available on device |
| permission | Permission not satisfied |
| others | Other errors (check errorMessage for description) |
## License
[MIT](LICENSE.md)