Photo picker

Stay organized with collections Save and categorize content based on your preferences.
Photo picker dialog appears with media files on your device. Select a photo to share with the app.
Figure 1. Photo picker provides an intuitive UI for sharing photos with your app.

The photo picker provides a browsable, searchable interface that presents the user with their media library, sorted by date from newest to oldest. This tool provides a safe, built-in way for users to select images and videos, without needing to grant your app access to their entire media library.

If you allow the system to configure the photo picker, the tool is available on devices that meet the following criteria, except for Android Go devices:

Furthermore, if you allow the system to configure the photo picker, the tool updates automatically, offering expanded functionality to your app's users over time without requiring any code changes.

Alternatively, you can customize the photo picker launch experience on devices that run Android 13 and higher.

Allow the system to configure the photo picker

The photo picker support library allows you to launch the photo picker from your app using either of the following activity result contracts:

If the photo picker isn't available on a device, the support library automatically invokes the ACTION_OPEN_DOCUMENT intent action instead. This intent is supported on devices that run Android 4.4 (API level 19) or higher. You can verify whether the photo picker is available on a given device by calling isPhotoPickerAvailable().

Select a single media item

To select a single media item, use the PickVisualMedia activity result contract, as shown in the following code snippet:

Kotlin

// Registers a photo picker activity launcher in single-select mode.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: $uri")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// Include only one of the following calls to launch(), depending on the types
// of media that you want to allow the user to choose from.

// Launch the photo picker and allow the user to choose images and videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

// Launch the photo picker and allow the user to choose only images.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageOnly))

// Launch the photo picker and allow the user to choose only videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.VideoOnly))

// Launch the photo picker and allow the user to choose only images/videos of a
// specific MIME type, such as GIFs.
val mimeType = "image/gif"
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.SingleMimeType(mimeType)))

Java

// Registers a photo picker activity launcher in single-select mode.
ActivityResultLauncher<PickVisualMediaRequest> pickMedia = 
        registerForActivityResult(new PickVisualMedia(), uri -> {
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: " + uri);
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// Include only one of the following calls to launch(), depending on the types
// of media that you want to allow the user to choose from.

// Launch the photo picker and allow the user to choose images and videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only images.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageOnly.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly.INSTANCE)
        .build());

// Launch the photo picker and allow the user to choose only images/videos of a
// specific MIME type, such as GIFs.
String mimeType = "image/gif";
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(new PickVisualMedia.SingleMimeType(mimeType))
        .build());

Select multiple media items

To select multiple media items, set a maximum number of selectable media files, as shown in the following code snippet.

Kotlin

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app allows the user to select up to 5 media files.
val pickMultipleMedia =
        registerForActivityResult(PickMultipleVisualMedia(5)) { uris ->
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (uris.isNotEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: ${uris.size}")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// For this example, launch the photo picker and allow the user to choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

Java

// Registering Photo Picker activity launcher with multiple selects (5 max in this example)
ActivityResultLauncher<PickVisualMediaRequest> pickMultipleMedia =
        registerForActivityResult(new PickMultipleVisualMedia(5), uris -> {
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (!uris.isEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: " + uris.size());
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// For this example, launch the photo picker and allow the user to choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

Customize the photo picker launch experience

The following sections describe how you can use a framework library to customize the intents that launch the photo picker.

Check whether the photo picker is available

To check whether the photo picker is available on a given device, include the logic shown in the following code snippet:

Kotlin

import android.os.ext.SdkExtensions.getExtensionVersion

fun isPhotoPickerAvailable(): Boolean {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        true
    } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        getExtensionVersion(Build.VERSION_CODES.R) >= 2
    } else {
        false
    }
}

Java

import android.os.ext.SdkExtensions.getExtensionVersion;

private boolean isPhotoPickerAvailable() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        return true;
    } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        return getExtensionVersion(Build.VERSION_CODES.R) >= 2;
    } else
        return false;
    }
}

Define sharing limitations

Apps can declare a value for EXTRA_PICK_IMAGES_MAX, which indicates the maximum number of media files that appear in the photo picker when shown to the user. For instance, if you prompt a user to select a required profile picture for their account, set one photo as a maximum sharing requirement.

Select a single media item

To launch photo picker in single-select mode, do the following:

Kotlin

// Launches photo picker in single-select mode.
// This means that the user can select one photo or video.
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
startActivityForResult(intent, PHOTO_PICKER_REQUEST_CODE)

Java

// Launches photo picker in single-select mode.
// This means that the user can select one photo or video.
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
startActivityForResult(intent, PHOTO_PICKER_REQUEST_CODE);

Select multiple media items

If your app’s use case requires that the user select multiple photos or videos, you can specify the maximum number of images that should appear in the photo picker using the EXTRA_PICK_IMAGES_MAX extra, as shown in the following code snippet:

Kotlin

// Launches photo picker in multi-select mode.
// This means that user can select multiple photos/videos, up to the limit
// specified by the app in the extra (10 in this example).
val maxNumPhotosAndVideos = 10
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
intent.putExtra(MediaStore.EXTRA_PICK_IMAGES_MAX, maxNumPhotosAndVideos)
startActivityForResult(intent, PHOTO_PICKER_MULTI_SELECT_REQUEST_CODE)

Java

// Launches photo picker in multi-select mode.
// This means that user can select multiple photos/videos, up to the limit
// specified by the app in the extra (10 in this example).
final int maxNumPhotosAndVideos = 10;
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
intent.putExtra(MediaStore.EXTRA_PICK_IMAGES_MAX, maxNumPhotosAndVideos);
startActivityForResult(intent, PHOTO_PICKER_MULTI_SELECT_REQUEST_CODE);

Keep in mind that there is a platform limit on the largest number you can specify as a maximum number of files. To access this limit, call getPickImagesMaxLimit().

Handle the photo picker results

After the photo picker launches, use the ACTION_PICK_IMAGES intent action to handle the results. The picker returns a set of URIs:

Kotlin

// onActivityResult() handles callbacks from the photo picker.
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    super.onActivityResult(requestCode, resultCode, data)
    if (resultCode != Activity.RESULT_OK) {
        // Handle error
        return
    }
    when (requestCode) {
        REQUEST_PHOTO_PICKER_SINGLE_SELECT -> {
            // Get photo picker response for single select.
            val currentUri: Uri = data.data!!

            // Do stuff with the photo/video URI.
            return
    }
        REQUEST_PHOTO_PICKER_MULTI_SELECT -> {
            // Get photo picker response for multi select.
            var i = 0
            var currentUri: Uri

            while (i < data.clipData!!.itemCount) {
                currentUri = data.clipData!!.getItemAt(i).uri
                // Do stuff with each photo/video URI.
                i++
            }
            return
    }
}

Java

// onActivityResult() handles callbacks from the photo picker.
@Override
protected void onActivityResult(
    int requestCode, int resultCode, final Intent data) {

    if (resultCode != Activity.RESULT_OK) {
        // Handle error
        return;
    }

    switch(requestCode) {
        case REQUEST_PHOTO_PICKER_SINGLE_SELECT:
            // Get photo picker response for single select.
            Uri currentUri = data.getData();

            // Do stuff with the photo/video URI.
            return;
        case REQUEST_PHOTO_PICKER_MULTI_SELECT:
            // Get photo picker response for multi select
            for (int i = 0; i < data.getClipData().getItemCount(); i++) {
                Uri currentUri = data.getClipData().getItemAt(i).getUri();

                // Do stuff with each photo/video URI.
            }
            return;
    }
}

By default, the photo picker shows both photos and videos. You can also filter by only photos or only videos by setting a MIME type in the setType() method. For example, to show only videos in the photo picker, pass video/* into setType():

Kotlin

// Launches photo picker for videos only in single select mode.
val intent = Intent(MediaStore.ACTION_PICK_IMAGES)
intent.type = "video/*"
startActivityForResult(intent, PHOTO_PICKER_VIDEO_SINGLE_SELECT_REQUEST_CODE)

// Apps can also change the mimeType to allow users to select
// images only - intent.type = "images/*"

Java

// Launches photo picker for videos only in single select mode.
Intent intent = new Intent(MediaStore.ACTION_PICK_IMAGES);
intent.setType("video/*");
startActivityForResult(intent, PHOTO_PICKER_VIDEO_SINGLE_SELECT_REQUEST_CODE);

// Apps can also change the mimeType to allow users to select
// images only - intent.setType("image/*");
// or a specific mimeType - intent.setType("image/gif");