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.Android Device | Android Emulator | iOS Device | iOS Simulator | Web |
---|---|---|---|---|
→
expo install expo-image-picker
If you're installing this in a bare React Native app, you should also follow these additional installation instructions.
expo-image-picker
using its built-in config plugin if you use config plugins in your project (EAS Build or 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.expo build:[android|ios]
)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" | iOS only A string to set the NSPhotoLibraryUsageDescription permission message. |
cameraPermission | "Allow $(PRODUCT_NAME) to access your camera" | iOS only A string to set the NSCameraUsageDescription permission message. |
microphonePermission | "Allow $(PRODUCT_NAME) to access your microphone" | iOS only A string to set the NSMicrophoneUsageDescription permission message. |
import React, { useState, useEffect } from 'react'; import { Button, Image, View, Platform } from 'react-native'; import * as ImagePicker from 'expo-image-picker'; export default function ImagePickerExample() { const [image, setImage] = useState(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.cancelled) { setImage(result.uri); } }; return ( <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}> <Button title="Pick an image from camera roll" onPress={pickImage} /> {image && <Image source={{ uri: image }} style={{ width: 200, height: 200 }} />} </View> ); }
{ "cancelled":false, "height":1611, "width":2148, "uri":"file:///data/user/0/host.exp.exponent/cache/cropped1814158652.jpg" }
import * as ImagePicker from 'expo-image-picker';
PermissionHookOptions<object>
)Check or request permissions to access the camera.
This uses both requestCameraPermissionsAsync
and getCameraPermissionsAsync
to interact with the permissions.
const [status, requestPermission] = ImagePicker.useCameraPermissions();
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]
PermissionHookOptions<{ writeOnly: boolean }>
)Check or request permissions to access the media library.
This uses both requestMediaLibraryPermissionsAsync
and getMediaLibraryPermissionsAsync
to interact with the permissions.
const [status, requestPermission] = ImagePicker.useMediaLibraryPermissions();
[null | MediaLibraryPermissionResponse, RequestPermissionMethod<MediaLibraryPermissionResponse>, GetPermissionMethod<MediaLibraryPermissionResponse>]
Checks user's permissions for accessing camera.
A promise that fulfills with an object of type CameraPermissionResponse.
Deprecated. UsegetMediaLibraryPermissionsAsync()
instead.
boolean
) - Whether to request write or read and write permissions. Defaults to false
Checks user's permissions for accessing photos.
A promise that fulfills with an object of type MediaLibraryPermissionResponse.
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
.ImagePickerOptions
) - An ImagePickerOptions
object.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 bloc
the request without a warning.
Note: Make sure that you handleMainActivity
destruction on Android. See ImagePicker.getPendingResultAsync. Notes for Web: The system UI can only be shown after user activation (e.g. aButton
press).
Therefore, calling launchCameraAsync
in componentDidMount
, for example, will not work as
intended. The cancelled
event will not be returned in the browser due to platform restrictions
and inconsistencies across browsers.
If the user cancelled the action, the method returns { cancelled: true }
. Otherwise,
this method returns information about the selected media item. When the chosen item is an image,
this method returns { cancelled: false, type: 'image', uri, width, height, exif, base64 }
;
when the item is a video, this method returns { cancelled: false, type: 'video', uri, width, height, duration }
.
T
) - An object extended by ImagePickerOptions
.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 If the selected image is an animated GIF, the result image will be an
animated GIF too if and only if quality
is set to undefined
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 — GIF).
Notes for Web: The system UI can only be shown after user activation (e.g. aButton
press).
Therefore, calling launchImageLibraryAsync
in componentDidMount
, for example, will not
work as intended. The cancelled
event will not be returned in the browser due to platform
restrictions and inconsistencies across browsers.
If the user cancelled the action, the method returns { cancelled: true }
. Otherwise,
this method returns information about the selected media item. When the chosen item is an image,
this method returns { cancelled: false, type: 'image', uri, width, height, exif, base64 }
;
when the item is a video, this method returns { cancelled: false, type: 'video', uri, width, height, duration }
.
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.
Deprecated. UserequestMediaLibraryPermissionsAsync()
instead.
boolean
) - Whether to request write or read and write permissions. Defaults to 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.
Alias for PermissionResponse
type exported by expo-modules-core
.
Deprecated. UseImagePicker.MediaLibraryPermissionResponse
instead.
An alias for the MediaLibraryPermissionResponse
object.
T extends ImagePickerOptions | OpenFileBrowserOptions
T extends { allowsMultipleSelection: true } ? ImagePickerMultipleResult : ImagePickerResult
Name | Type | Description |
---|---|---|
base64 (optional) | string | Included if the base64 option is truthy, and is a Base64-encoded string of the selected
image's JPEG data. If you prepend this with 'data:image/jpeg;base64,' to create a data URI,
you can use it as the source of an Image element; for example:
|
cancelled | boolean | Boolean flag which shows if request was cancelled. If asset data have been returned this should
always be false . |
duration (optional) | number | Length of the video in milliseconds. |
exif (optional) | Record<string, any> | The exif field is included if the exif option is truthy, and is an object containing the
image's EXIF data. The names of this object's properties are EXIF tags and the values are the
respective EXIF values for those tags. |
height | number | Height of the image or video. |
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 Image element, in the case of
an image) and width and height specify the dimensions of the media. |
width | number | Width of the image or video. |
An object returned when the pick action has been cancelled by the user.
Name | Type | Description |
---|---|---|
cancelled | true | - |
Name | Type | Description |
---|---|---|
code | string | The error code. |
exception (optional) | string | The exception which caused the error. |
message | string | The error message. |
Name | Type | Description |
---|---|---|
cancelled | false | - |
selected | ImageInfo[] | - |
Name | Type | Description |
---|---|---|
allowsEditing (optional) | boolean | 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 | Web
Only Whether or not to allow selecting multiple media files at once. |
aspect (optional) | [number, number] | An array with two entries [x, y] specifying the aspect ratio to maintain if the user is
allowed to edit the image (by passing allowsEditing: true ). This is only applicable on
Android, since on iOS the crop rectangle is always a square. |
base64 (optional) | boolean | Whether to also include the image data in Base64 format. |
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. |
mediaTypes (optional) | MediaTypeOptions | Choose what type of media to pick. Default: ImagePicker.MediaTypeOptions.Images
|
presentationStyle (optional) | UIImagePickerPresentationStyle | iOS Only Choose presentation style to customize view during taking photo/video. Default: ImagePicker.UIImagePickerPresentationStyle.Automatic |
quality (optional) | number | Specify the quality of compression, from 0 to 1 . 0 means compress for small size,
1 means compress for maximum quality.
|
videoExportPreset (optional) | VideoExportPreset |
iOS 11+ Only 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 0 disables the limit.
Defaults to 0 (no limit).
|
videoQuality (optional) | UIImagePickerControllerQualityType | iOS Only Specify the quality of recorded videos. Defaults to the highest quality available for the device. Default: ImagePicker.UIImagePickerControllerQualityType.High |
Acceptable values are: ImagePickerCancelledResult
, ImageInfo
.
Extends PermissionResponse
type exported by expo-modules-core
and contains additional iOS-specific field.
PermissionResponse
extended by:
Name | Type | Description |
---|---|---|
accessPrivileges (optional) | 'all' | 'limited' | 'none' | iOS Only |
Name | Type | Description |
---|---|---|
allowsMultipleSelection | boolean | Web
Only 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 | MediaTypeOptions | Choose what type of media to pick. Default: ImagePicker.MediaTypeOptions.Images
|
Acceptable values are: 'never'
, number
.
Acceptable values are: PermissionHookBehavior
, Options
.
Name | Type | Description |
---|---|---|
canAskAgain | boolean | - |
expires | PermissionExpiration | - |
granted | boolean | - |
status | PermissionStatus | - |
All
- Images and videos.MediaTypeOptions.All = "All"
Images
- Only images.MediaTypeOptions.Images = "Images"
Videos
- Only videos.MediaTypeOptions.Videos = "Videos"
DENIED
PermissionStatus.DENIED = "denied"
GRANTED
PermissionStatus.GRANTED = "granted"
UNDETERMINED
PermissionStatus.UNDETERMINED = "undetermined"
High
- Highest available resolution.UIImagePickerControllerQualityType.High = 0
Medium
- Depends on the device.UIImagePickerControllerQualityType.Medium = 1
Low
- Depends on the device.UIImagePickerControllerQualityType.Low = 2
VGA640x480
- 640 × 480UIImagePickerControllerQualityType.VGA640x480 = 3
IFrame1280x720
- 1280 × 720UIImagePickerControllerQualityType.IFrame1280x720 = 4
IFrame960x540
- 960 × 540UIImagePickerControllerQualityType.IFrame960x540 = 5
Picker presentation style. Its values are directly mapped to the UIModalPresentationStyle
.
AUTOMATIC
- WebBrowserPresentationStyle.FullScreen
.UIImagePickerPresentationStyle.AUTOMATIC = "automatic"
Automatic
Deprecated. UseUIImagePickerPresentationStyle.AUTOMATIC
instead.
UIImagePickerPresentationStyle.Automatic = "automatic"
CURRENT_CONTEXT
- A presentation style where the picker is displayed over the app's content.UIImagePickerPresentationStyle.CURRENT_CONTEXT = "currentContext"
CurrentContext
Deprecated. UseUIImagePickerPresentationStyle.CURRENT_CONTEXT
instead.
UIImagePickerPresentationStyle.CurrentContext = "currentContext"
FORM_SHEET
- A presentation style that displays the picker centered in the screen.UIImagePickerPresentationStyle.FORM_SHEET = "formSheet"
FULL_SCREEN
- A presentation style in which the presented picker covers the screen.UIImagePickerPresentationStyle.FULL_SCREEN = "fullScreen"
FormSheet
Deprecated. UseUIImagePickerPresentationStyle.FORM_SHEET
instead.
UIImagePickerPresentationStyle.FormSheet = "formSheet"
FullScreen
Deprecated. UseUIImagePickerPresentationStyle.FULL_SCREEN
instead.
UIImagePickerPresentationStyle.FullScreen = "fullScreen"
OVER_CURRENT_CONTEXT
- A presentation style where the picker is displayed over the app's content.UIImagePickerPresentationStyle.OVER_CURRENT_CONTEXT = "overCurrentContext"
OVER_FULL_SCREEN
- A presentation style in which the picker view covers the screen.UIImagePickerPresentationStyle.OVER_FULL_SCREEN = "overFullScreen"
OverCurrentContext
Deprecated. UseUIImagePickerPresentationStyle.OVER_CURRENT_CONTEXT
instead.
UIImagePickerPresentationStyle.OverCurrentContext = "overCurrentContext"
OverFullScreen
Deprecated. UseUIImagePickerPresentationStyle.OVER_FULL_SCREEN
instead.
UIImagePickerPresentationStyle.OverFullScreen = "overFullScreen"
PAGE_SHEET
- A presentation style that partially covers the underlying content.UIImagePickerPresentationStyle.PAGE_SHEET = "pageSheet"
POPOVER
- A presentation style where the picker is displayed in a popover view.UIImagePickerPresentationStyle.POPOVER = "popover"
PageSheet
Deprecated. UseUIImagePickerPresentationStyle.PAGE_SHEET
instead.
UIImagePickerPresentationStyle.PageSheet = "pageSheet"
Popover
Deprecated. UseUIImagePickerPresentationStyle.POPOVER
instead.
UIImagePickerPresentationStyle.Popover = "popover"
Passthrough
- Resolution: Unchanged •
Video compression: None •
Audio compression: NoneVideoExportPreset.Passthrough = 0
LowQuality
- Resolution: Depends on the device •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.LowQuality = 1
MediumQuality
- Resolution: Depends on the device •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.MediumQuality = 2
HighestQuality
- Resolution: Depends on the device •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.HighestQuality = 3
H264_640x480
- Resolution: 640 × 480 •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.H264_640x480 = 4
H264_960x540
- Resolution: 960 × 540 •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.H264_960x540 = 5
H264_1280x720
- Resolution: 1280 × 720 •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.H264_1280x720 = 6
H264_1920x1080
- Resolution: 1920 × 1080 •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.H264_1920x1080 = 7
H264_3840x2160
- Resolution: 3840 × 2160 •
Video compression: H.264 •
Audio compression: AACVideoExportPreset.H264_3840x2160 = 8
HEVC_1920x1080
- Resolution: 1920 × 1080 •
Video compression: HEVC •
Audio compression: AACVideoExportPreset.HEVC_1920x1080 = 9
HEVC_3840x2160
- Resolution: 3840 × 2160 •
Video compression: HEVC •
Audio compression: AACVideoExportPreset.HEVC_3840x2160 = 10
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. |
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. |