A library that provides access to the system's UI for selecting images and videos from the phone's library or taking a photo with the camera.
GitHub
npm
expo-image-picker
provides access to the system's UI for selecting images and videos from the phone's library or taking a photo with the camera.
-
npx expo install expo-image-picker
If you are installing this in an existing React Native app (bare workflow), start by installing expo
in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.
On iOS, when an image (usually of a higher resolution) is picked from the camera roll, the result of the cropped image gives the wrong value for the cropped rectangle in some cases. Unfortunately, this issue is with the underlying UIImagePickerController
due to a bug in the closed-source tools built into iOS.
You can configure expo-image-picker
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
Learn how to configure the native projects in the installation instructions in the expo-image-picker
repository.
{
"expo": {
"plugins": [
[
"expo-image-picker",
{
"photosPermission": "The app accesses your photos to let you share them with your friends."
}
]
]
}
}
Name | Default | Description |
---|---|---|
photosPermission | "Allow $(PRODUCT_NAME) to access your photos" | Only for: iOS A string to set the |
cameraPermission | "Allow $(PRODUCT_NAME) to access your camera" | Only for: iOS A string to set the |
microphonePermission | "Allow $(PRODUCT_NAME) to access your microphone" | Only for: iOS A string to set the |
import { useState } from 'react';
import { Button, Image, View, StyleSheet } from 'react-native';
import * as ImagePicker from 'expo-image-picker';
export default function ImagePickerExample() {
const [image, setImage] = useState<string | null>(null);
const pickImage = async () => {
// No permissions request is necessary for launching the image library
let result = await ImagePicker.launchImageLibraryAsync({
mediaTypes: ImagePicker.MediaTypeOptions.All,
allowsEditing: true,
aspect: [4, 3],
quality: 1,
});
console.log(result);
if (!result.canceled) {
setImage(result.assets[0].uri);
}
};
return (
<View style={styles.container}>
<Button title="Pick an image from camera roll" onPress={pickImage} />
{image && <Image source={{ uri: image }} style={styles.image} />}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
image: {
width: 200,
height: 200,
},
});
When you run this example and pick an image, you will see the image that you picked show up in your app, and a similar log will be shown in the console:
{
"assets": [
{
"assetId": "C166F9F5-B5FE-4501-9531",
"base64": null,
"duration": null,
"exif": null,
"fileName": "IMG.HEIC",
"fileSize": 6018901,
"height": 3025,
"type": "image",
"uri": "file:///data/user/0/host.exp.exponent/cache/cropped1814158652.jpg"
"width": 3024
}
],
"canceled": false
}
An example of how to use AWS storage can be found in with-aws-storage-upload.
See Amplify documentation guide to set up your project correctly.
An example of how to use Firebase storage can be found in with-firebase-storage-upload.
See Using Firebase guide to set up your project correctly.
import * as ImagePicker from 'expo-image-picker';
useCameraPermissions(options)
Name | Type |
---|---|
options (optional) | PermissionHookOptions<object> |
Check or request permissions to access the camera.
This uses both requestCameraPermissionsAsync
and getCameraPermissionsAsync
to interact with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]
Example
const [status, requestPermission] = ImagePicker.useCameraPermissions();
useMediaLibraryPermissions(options)
Name | Type |
---|---|
options (optional) | PermissionHookOptions<{
writeOnly: boolean
}> |
Check or request permissions to access the media library.
This uses both requestMediaLibraryPermissionsAsync
and getMediaLibraryPermissionsAsync
to interact with the permissions.
[null | MediaLibraryPermissionResponse, RequestPermissionMethod<MediaLibraryPermissionResponse>, GetPermissionMethod<MediaLibraryPermissionResponse>]
Example
const [status, requestPermission] = ImagePicker.useMediaLibraryPermissions();
ImagePicker.getCameraPermissionsAsync()
Checks user's permissions for accessing camera.
A promise that fulfills with an object of type CameraPermissionResponse.
ImagePicker.getMediaLibraryPermissionsAsync(writeOnly)
Name | Type | Description |
---|---|---|
writeOnly (optional) | boolean | Whether to request write or read and write permissions. Defaults to Default: false |
Checks user's permissions for accessing photos.
A promise that fulfills with an object of type MediaLibraryPermissionResponse.
ImagePicker.getPendingResultAsync()
Android system sometimes kills the MainActivity
after the ImagePicker
finishes. When this
happens, we lost the data selected from the ImagePicker
. However, you can retrieve the lost
data by calling getPendingResultAsync
. You can test this functionality by turning on
Don't keep activities
in the developer options.
ImagePicker.launchImageLibraryAsync
or ImagePicker.launchCameraAsync
if the ImagePicker
finished successfully. Otherwise, to the array of ImagePickerErrorResult
.ImagePicker.launchCameraAsync(options)
Name | Type | Description |
---|---|---|
options (optional) | ImagePickerOptions | An Default: {} |
Display the system UI for taking a photo with the camera. Requires Permissions.CAMERA
.
On Android and iOS 10 Permissions.CAMERA_ROLL
is also required. On mobile web, this must be
called immediately in a user interaction like a button press, otherwise the browser will block
the request without a warning.
Note: Make sure that you handle
MainActivity
destruction on Android. See ImagePicker.getPendingResultAsync. Notes for Web: The system UI can only be shown after user activation (e.g. aButton
press). Therefore, callinglaunchCameraAsync
incomponentDidMount
, for example, will not work as intended. Thecancelled
event will not be returned in the browser due to platform restrictions and inconsistencies across browsers.
A promise that resolves to an object with canceled
and assets
fields.
When the user canceled the action the assets
is always null
, otherwise it's an array of
the selected media assets which have a form of ImagePickerAsset
.
ImagePicker.launchImageLibraryAsync(options)
Name | Type | Description |
---|---|---|
options (optional) | ImagePickerOptions | An object extended by |
Display the system UI for choosing an image or a video from the phone's library.
Requires Permissions.MEDIA_LIBRARY
on iOS 10 only. On mobile web, this must be called
immediately in a user interaction like a button press, otherwise the browser will block the
request without a warning.
Animated GIFs support: On Android, if the selected image is an animated GIF, the result image will be an
animated GIF too if and only if quality
is explicitly set to 1.0
and allowsEditing
is set to false
.
Otherwise compression and/or cropper will pick the first frame of the GIF and return it as the
result (on Android the result will be a PNG). On iOS, both quality and cropping are supported.
Notes for Web: The system UI can only be shown after user activation (e.g. a
Button
press). Therefore, callinglaunchImageLibraryAsync
incomponentDidMount
, for example, will not work as intended. Thecancelled
event will not be returned in the browser due to platform restrictions and inconsistencies across browsers.
A promise that resolves to an object with canceled
and assets
fields.
When the user canceled the action the assets
is always null
, otherwise it's an array of
the selected media assets which have a form of ImagePickerAsset
.
ImagePicker.requestCameraPermissionsAsync()
Asks the user to grant permissions for accessing camera. This does nothing on web because the browser camera is not used.
A promise that fulfills with an object of type CameraPermissionResponse.
ImagePicker.requestMediaLibraryPermissionsAsync(writeOnly)
Name | Type | Description |
---|---|---|
writeOnly (optional) | boolean | Whether to request write or read and write permissions. Defaults to Default: false |
Asks the user to grant permissions for accessing user's photo. This method does nothing on web.
A promise that fulfills with an object of type MediaLibraryPermissionResponse.
PermissionResponse
An object obtained by permissions get and request functions.
PermissionResponse Properties
Name | Type | Description |
---|---|---|
canAskAgain | boolean | Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission. |
expires | PermissionExpiration | Determines time when the permission expires. |
granted | boolean | A convenience boolean that indicates if the permission is granted. |
status | PermissionStatus | Determines the status of the permission. |
CameraPermissionResponse
Type: PermissionResponse
Alias for PermissionResponse
type exported by expo-modules-core
.
ImagePickerAsset
Represents an asset (image or video) returned by the image picker or camera.
Name | Type | Description |
---|---|---|
assetId (optional) | string | null | Only for: iOS Android The unique ID that represents the picked image or video, if picked from the library. It can be used by expo-media-library to manage the picked asset.
|
base64 (optional) | string | null | When the
|
duration (optional) | number | null | Length of the video in milliseconds or |
exif (optional) | Record<string, any> | null | The |
fileName (optional) | string | null | Preferred filename to use when saving this item. This might be |
fileSize (optional) | number | File size of the picked image or video, in bytes. |
height | number | Height of the image or video. |
mimeType (optional) | string | The MIME type of the selected asset or |
type (optional) | 'image' | 'video' | The type of the asset. |
uri | string | URI to the local image or video file (usable as the source of an |
width | number | Width of the image or video. |
ImagePickerCanceledResult
Type representing canceled pick result.
Name | Type | Description |
---|---|---|
assets | null |
|
canceled | true | Boolean flag set to |
ImagePickerErrorResult
Name | Type | Description |
---|---|---|
code | string | The error code. |
exception (optional) | string | The exception which caused the error. |
message | string | The error message. |
ImagePickerOptions
Name | Type | Description |
---|---|---|
allowsEditing (optional) | boolean | Only for: iOS Android Whether to show a UI to edit the image after it is picked. On Android the user can crop and rotate the image and on iOS simply crop it.
Default: false |
allowsMultipleSelection (optional) | boolean | Only for: iOS 14+ Android Web Whether or not to allow selecting multiple media files at once.
Default: false |
aspect (optional) | [number, number] | An array with two entries |
base64 (optional) | boolean | Whether to also include the image data in Base64 format. |
cameraType (optional) | CameraType | Only for: iOS Android Selects the camera-facing type. The
Default: CameraType.back |
exif (optional) | boolean | Whether to also include the EXIF data for the image. On iOS the EXIF data does not include GPS tags in the camera case. |
legacy (optional) | boolean | Only for: Android Uses the legacy image picker on Android. This will allow media to be selected from outside the users photo library. Default: false |
mediaTypes (optional) | MediaTypeOptions | Choose what type of media to pick. Default: ImagePicker.MediaTypeOptions.Images |
orderedSelection (optional) | boolean | Only for: iOS 15+ Whether to display number badges when assets are selected. The badges are numbered in selection order. Assets are then returned in the exact same order they were selected.
Default: false |
preferredAssetRepresentationMode (optional) | UIImagePickerPreferredAssetRepresentationMode | Only for: iOS 14+ Choose preferred asset representation mode to use when loading assets. Default: ImagePicker.UIImagePickerPreferredAssetRepresentationMode.Automatic |
presentationStyle (optional) | UIImagePickerPresentationStyle | Only for: iOS Choose presentation style to customize view during taking photo/video. Default: ImagePicker.UIImagePickerPresentationStyle.Automatic |
quality (optional) | number | Only for: iOS Android Specify the quality of compression, from
Default: 0.2 |
selectionLimit (optional) | number | Only for: iOS 14+ Android The maximum number of items that user can select. Applicable when Default: 0 |
videoExportPreset (optional) | VideoExportPreset |
Only for: iOS 11+ Specify preset which will be used to compress selected video. Default: ImagePicker.VideoExportPreset.Passthrough |
videoMaxDuration (optional) | number | Maximum duration, in seconds, for video recording. Setting this to
|
videoQuality (optional) | UIImagePickerControllerQualityType | Only for: iOS Specify the quality of recorded videos. Defaults to the highest quality available for the device. Default: ImagePicker.UIImagePickerControllerQualityType.High |
ImagePickerResult
Literal Type: multiple types
Type representing successful and canceled pick result.
Acceptable values are: ImagePickerSuccessResult
| ImagePickerCanceledResult
ImagePickerSuccessResult
Type representing successful pick result.
Name | Type | Description |
---|---|---|
assets | ImagePickerAsset[] | An array of picked assets. |
canceled | false | Boolean flag set to |
MediaLibraryPermissionResponse
Extends PermissionResponse
type exported by expo-modules-core
, containing additional iOS-specific field.
Type: PermissionResponse
extended by:
Name | Type | Description |
---|---|---|
accessPrivileges (optional) | 'all' | 'limited' | 'none' | Indicates if your app has access to the whole or only part of the photo library. Possible values are:
|
OpenFileBrowserOptions
Name | Type | Description |
---|---|---|
allowsMultipleSelection | boolean | Only for: Web Whether or not to allow selecting multiple media files at once. |
base64 | boolean | Whether to also include the image data in Base64 format. |
capture (optional) | boolean | - |
mediaTypes (optional) | MediaTypeOptions | Choose what type of media to pick. Default: ImagePicker.MediaTypeOptions.Images |
PermissionExpiration
Literal Type: multiple types
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never'
| number
PermissionHookOptions
Literal Type: multiple types
Acceptable values are: PermissionHookBehavior
| Options
CameraType
CameraType Values
MediaTypeOptions
MediaTypeOptions Values
PermissionStatus
PermissionStatus Values
UNDETERMINED
PermissionStatus.UNDETERMINED = "undetermined"
User hasn't granted or denied the permission yet.
UIImagePickerControllerQualityType
UIImagePickerControllerQualityType Values
UIImagePickerPreferredAssetRepresentationMode
Picker preferred asset representation mode. Its values are directly mapped to the PHPickerConfigurationAssetRepresentationMode
.
UIImagePickerPreferredAssetRepresentationMode Values
Automatic
UIImagePickerPreferredAssetRepresentationMode.Automatic = "automatic"
A mode that indicates that the system chooses the appropriate asset representation.
Compatible
UIImagePickerPreferredAssetRepresentationMode.Compatible = "compatible"
A mode that uses the most compatible asset representation.
Current
UIImagePickerPreferredAssetRepresentationMode.Current = "current"
A mode that uses the current representation to avoid transcoding, if possible.
UIImagePickerPresentationStyle
Picker presentation style. Its values are directly mapped to the UIModalPresentationStyle
.
UIImagePickerPresentationStyle Values
AUTOMATIC
UIImagePickerPresentationStyle.AUTOMATIC = "automatic"
The default presentation style chosen by the system.
On older iOS versions, falls back to WebBrowserPresentationStyle.FullScreen
.
CURRENT_CONTEXT
UIImagePickerPresentationStyle.CURRENT_CONTEXT = "currentContext"
A presentation style where the picker is displayed over the app's content.
FORM_SHEET
UIImagePickerPresentationStyle.FORM_SHEET = "formSheet"
A presentation style that displays the picker centered in the screen.
FULL_SCREEN
UIImagePickerPresentationStyle.FULL_SCREEN = "fullScreen"
A presentation style in which the presented picker covers the screen.
OVER_CURRENT_CONTEXT
UIImagePickerPresentationStyle.OVER_CURRENT_CONTEXT = "overCurrentContext"
A presentation style where the picker is displayed over the app's content.
OVER_FULL_SCREEN
UIImagePickerPresentationStyle.OVER_FULL_SCREEN = "overFullScreen"
A presentation style in which the picker view covers the screen.
PAGE_SHEET
UIImagePickerPresentationStyle.PAGE_SHEET = "pageSheet"
A presentation style that partially covers the underlying content.
POPOVER
UIImagePickerPresentationStyle.POPOVER = "popover"
A presentation style where the picker is displayed in a popover view.
VideoExportPreset
VideoExportPreset Values
Passthrough
VideoExportPreset.Passthrough = 0
Resolution: Unchanged • Video compression: None • Audio compression: None
LowQuality
VideoExportPreset.LowQuality = 1
Resolution: Depends on the device • Video compression: H.264 • Audio compression: AAC
MediumQuality
VideoExportPreset.MediumQuality = 2
Resolution: Depends on the device • Video compression: H.264 • Audio compression: AAC
HighestQuality
VideoExportPreset.HighestQuality = 3
Resolution: Depends on the device • Video compression: H.264 • Audio compression: AAC
H264_640x480
VideoExportPreset.H264_640x480 = 4
Resolution: 640 × 480 • Video compression: H.264 • Audio compression: AAC
H264_960x540
VideoExportPreset.H264_960x540 = 5
Resolution: 960 × 540 • Video compression: H.264 • Audio compression: AAC
H264_1280x720
VideoExportPreset.H264_1280x720 = 6
Resolution: 1280 × 720 • Video compression: H.264 • Audio compression: AAC
H264_1920x1080
VideoExportPreset.H264_1920x1080 = 7
Resolution: 1920 × 1080 • Video compression: H.264 • Audio compression: AAC
H264_3840x2160
VideoExportPreset.H264_3840x2160 = 8
Resolution: 3840 × 2160 • Video compression: H.264 • Audio compression: AAC
HEVC_1920x1080
VideoExportPreset.HEVC_1920x1080 = 9
Resolution: 1920 × 1080 • Video compression: HEVC • Audio compression: AAC
HEVC_3840x2160
VideoExportPreset.HEVC_3840x2160 = 10
Resolution: 3840 × 2160 • Video compression: HEVC • Audio compression: AAC
The following permissions are added automatically through the library AndroidManifest.xml.
Android Permission | Description |
---|---|
Required to be able to access the camera device. | |
Allows an application to read from external storage. | |
Allows an application to write to external storage. |
The following usage description keys are used by the APIs in this library.
Info.plist Key | Description |
---|---|
A message that tells the user why the app is requesting access to the device’s microphone. | |
A message that tells the user why the app is requesting access to the user’s photo library. | |
A message that tells the user why the app is requesting access to the device’s camera. |