Archive Expo Snack Discord Forums Changelog

Expo ImagePicker
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.

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

Terminal

- npx expo install expo-image-picker

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Configuration in app.json/app.config.js

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.

Are you using this library in a bare React Native app?

Learn how to configure the native projects in the installation instructions in the expo-image-picker repository.

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-image-picker",
        {
          "photosPermission": "The app accesses your photos to let you share them with your friends."
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`photosPermission`	`"Allow $(PRODUCT_NAME) to access your photos"`	Only for: iOS A string to set the `NSPhotoLibraryUsageDescription` permission message.
`cameraPermission`	`"Allow $(PRODUCT_NAME) to access your camera"`	Only for: iOS A string to set the `NSCameraUsageDescription` permission message.
`microphonePermission`	`"Allow $(PRODUCT_NAME) to access your microphone"`	Only for: iOS A string to set the `NSMicrophoneUsageDescription` permission message.

Usage

Image Picker

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.canceled) {
      setImage(result.assets[0].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>
  );
}

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,
  "cancelled": false
}

Using with AWS S3

Refer the with-aws-storage-upload example. Follow Amplify docs to set your project up correctly.

Using with Firebase

Refer the with-firebase-storage-upload example. Make sure you follow the Using Firebase guide to set your project up correctly.

API

import * as ImagePicker from 'expo-image-picker';

Hooks

`useCameraPermissions(options)`

Name	Type	Description
options (optional)	`PermissionHookOptions<object>`	-

Check or request permissions to access the camera. This uses both requestCameraPermissionsAsync and getCameraPermissionsAsync to interact with the permissions.

Example

const [status, requestPermission] = ImagePicker.useCameraPermissions();

Returns

[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

`useMediaLibraryPermissions(options)`

Name	Type	Description
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.

Example

const [status, requestPermission] = ImagePicker.useMediaLibraryPermissions();

Returns

[null | MediaLibraryPermissionResponse, RequestPermissionMethod<MediaLibraryPermissionResponse>, GetPermissionMethod<MediaLibraryPermissionResponse>]

Methods

`ImagePicker.getCameraPermissionsAsync()`

Checks user's permissions for accessing camera.

Returns

Promise<CameraPermissionResponse>

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 `false` Default: `false`

Checks user's permissions for accessing photos.

Returns

Promise<MediaLibraryPermissionResponse>

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.

Returns

Promise<(ImagePickerResult | ImagePickerErrorResult)[]>

On Android: a promise that resolves to an array of objects of exactly same type as in ImagePicker.launchImageLibraryAsync or ImagePicker.launchCameraAsync if the ImagePicker finished successfully. Otherwise, to the array of ImagePickerErrorResult.
On other platforms: an empty array.

`ImagePicker.launchCameraAsync(options)`

Name	Type	Description
options (optional)	`ImagePickerOptions`	An `ImagePickerOptions` object. 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. a Button 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.

Returns

Promise<ImagePickerResult>

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 `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: 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, 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.

Returns

Promise<ImagePickerResult>

`ImagePicker.requestCameraPermissionsAsync()`

Asks the user to grant permissions for accessing camera. This does nothing on web because the browser camera is not used.

Returns

Promise<CameraPermissionResponse>

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 `false` Default: `false`

Asks the user to grant permissions for accessing user's photo. This method does nothing on web.

Returns

Promise<MediaLibraryPermissionResponse>

A promise that fulfills with an object of type MediaLibraryPermissionResponse.

Interfaces

`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.

Types

`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. This might be `null` when the ID is unavailable or the user gave limited permission to access the media library. On Android, the ID is unavailable when the user selects a photo by directly browsing file system.
base64 (optional)	`string \| null`	When the `base64` option is truthy, it is a Base64-encoded string of the selected image's JPEG data, otherwise `null`. 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: `<Image source={{ uri: 'data:image/jpeg;base64,' + asset.base64 }} style={{ width: 200, height: 200 }} />`
duration (optional)	`number \| null`	Length of the video in milliseconds or `null` if the asset is not a video.
exif (optional)	`Record<string, any> \| null`	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.
fileName (optional)	`string \| null`	Only for: iOS Preferred filename to use when saving this item. This might be `null` when the name is unavailable or user gave limited permission to access the media library.
fileSize (optional)	`number`	Only for: iOS File size of the picked image or video, in bytes.
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.

`ImagePickerCanceledResult`

Type representing canceled pick result.

Name	Type	Description
assets	`null`	`null` signifying that the request was canceled.
canceled	`true`	Boolean flag set to `true` showing that the request was canceled.

`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. Cropping multiple images is not supported - this option is mutually exclusive with `allowsMultipleSelection`. On iOS, this option is ignored if `allowsMultipleSelection` is enabled. Default: `false`
allowsMultipleSelection (optional)	`boolean`	Only for: iOS 14+ Android Web Whether or not to allow selecting multiple media files at once. Cropping multiple images is not supported - this option is mutually exclusive with `allowsEditing`. If this option is enabled, then `allowsEditing` is ignored. Default: `false`
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`
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. Assets should be returned in the selection order regardless of this option, but there is no guarantee that it is always true when this option is disabled. Default: `false`
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 `0` to `1`. `0` means compress for small size, `1` means compress for maximum quality. Note: If the selected image has been compressed before, the size of the output file may be bigger than the size of the original image. Note: On iOS, if a `.bmp` or `.png` image is selected from the library, this option is ignored. Default: `0.2`
selectionLimit (optional)	`number`	Only for: iOS 14+ The maximum number of items that user can select. Applicable when `allowsMultipleSelection` is enabled. Setting the value to `0` sets the selection limit to the maximum that the system supports. Default: `0`
videoExportPreset (optional)	`VideoExportPreset`	Deprecated. See `videoExportPreset` in Apple documentation. 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 `0` disables the limit. Defaults to `0` (no limit). On iOS, when `allowsEditing` is set to `true`, maximum duration is limited to 10 minutes. This limit is applied automatically, if `0` or no value is specified. On Android, effect of this option depends on support of installed camera app. On Web this option has no effect - the limit is browser-dependant.
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`

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 `false` showing that the request was successful.

`MediaLibraryPermissionResponse`

Extends PermissionResponse type exported by expo-modules-core, containing additional iOS-specific field.

PermissionResponse extended by:

Name	Type	Description
accessPrivileges (optional)	`'all' \| 'limited' \| 'none'`	-

`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`

Only for:

iOS

`UIImagePickerPresentationStyle`

Picker presentation style. Its values are directly mapped to the UIModalPresentationStyle.

Only for:

iOS 13+

Android Permission	Description
`CAMERA`	Required to be able to access the camera device.
`READ_EXTERNAL_STORAGE`	Allows an application to read from external storage.
`WRITE_EXTERNAL_STORAGE`	Allows an application to write to external storage.

iOS

The following usage description keys are used by the APIs in this library.

Info.plist Key	Description
`NSMicrophoneUsageDescription`	A message that tells the user why the app is requesting access to the device’s microphone.
`NSPhotoLibraryUsageDescription`	A message that tells the user why the app is requesting access to the user’s photo library.
`NSCameraUsageDescription`	A message that tells the user why the app is requesting access to the device’s camera.