Get Started

Guides

Feature Preview

API Reference

MediaLibrary

expo-media-library provides access to the user's media library, allowing them to access their existing images and videos from your app, as well as save new ones. You can also subscribe to any updates made to the user's media library.

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

expo install expo-media-library

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

Configuration

In managed apps, the permission to access images or videos (Permissions.CAMERA_ROLL) is added automatically.

API

import * as MediaLibrary from 'expo-media-library';

Methods

`MediaLibrary.requestPermissionsAsync()`

Asks the user to grant permissions for accessing media in user's media library. Alias for Permissions.askAsync(Permissions.CAMERA_ROLL).

Returns

A promise that resolves to an object of type CameraRollPermissionResponse.

`MediaLibrary.getPermissionsAsync()`

Checks user's permissions for accessing media library. Alias for Permissions.getAsync(Permissions.CAMERA_ROLL).

Returns

A promise that resolves to an object of type CameraRollPermissionResponse.

`MediaLibrary.createAssetAsync(localUri)`

Creates an asset from existing file. The most common use case is to save a picture taken by Camera. This method requires CAMERA_ROLL permission.

const { uri } = await Camera.takePictureAsync();
const asset = await MediaLibrary.createAssetAsync(uri);

Arguments

localUri (string) -- A URI to the image or video file. It must contain an extension. On Android it must be a local path, so it must start with file:///.

Returns

An object representing an asset.

`MediaLibrary.saveToLibraryAsync(localUri)`

Saves the file at given localUri to the user's media library. Unlike createAssetAsync(), this method doesn't return created asset.

On iOS 11+, it's possible to use this method without asking for CAMERA_ROLL permission, however then yours Info.plist should have NSPhotoLibraryAddUsageDescription key.

Arguments

localUri (string) -- A URI to the image or video file. It must contain an extension. On Android it must be a local path, so it must start with file:///.

`MediaLibrary.getAssetsAsync(options)`

Fetches a page of assets matching the provided criteria.

Arguments

options (object)
- first (number) -- The maximum number of items on a single page. Defaults to 20.
- after (string) -- Asset ID of the last item returned on the previous page.
- album (string | Album) -- Album or its ID to get assets from specific album.
- sortBy (array) -- An array of SortBy keys. By default, all keys are sorted in descending order, however you can also pass a pair [key, ascending] where the second item is a boolean value that means whether to use ascending order. Note that if the SortBy.default key is used, then ascending argument will not matter. Earlier items have higher priority when sorting out the results. If empty, this method will use the default sorting that is provided by the platform.
- mediaType (array) -- An array of MediaType types. By default MediaType.photo is set.
- createdAfter (Date | number) -- Date object or Unix timestamp in milliseconds limiting returned assets only to those that were created after this date.
- createdBefore (Date | number) -- Similarly as createdAfter, but limits assets only to those that were created before specified date.

Returns

A promise that resolves to an object that contains following keys:

assets (array) -- A page of assets fetched by the query.
endCursor (string) -- ID of the last fetched asset. It should be passed as after option in order to get the next page.
hasNextPage (boolean) -- Whether there are more assets to fetch.
totalCount (number) -- Estimated total number of assets that match the query.

`MediaLibrary.getAssetInfoAsync(asset, options)`

Provides more informations about an asset, including GPS location, local URI and EXIF metadata.

Arguments

asset (string | Asset) -- Asset or its ID.
options (object)
- shouldDownloadFromNetwork (boolean) -- Whether allow the asset to be downloaded from network. Only available in iOS with iCloud assets. Defaults to true.

Returns

Asset object extended by additional fields listed in the table.

`MediaLibrary.deleteAssetsAsync(assets)`

Deletes assets from the library. On iOS it deletes assets from all albums they belong to, while on Android it keeps all copies of them (album is strictly connected to the asset). Also, there is additional dialog on iOS that requires user to confirm this action.

Arguments

assets (array) -- An array of assets or their IDs.

Returns

Returns true if the assets were successfully deleted.

`MediaLibrary.getAlbumsAsync()`

Queries for user-created albums in media gallery.

Returns

An array of albums. Depending on Android version, root directory of your storage may be listed as album titled "0" or unlisted at all.

`MediaLibrary.getAlbumAsync(albumName)`

Queries for an album with a specific name.

Arguments

albumName (string) -- Name of the album to look for.

Returns

An object representing an album if album with given name exists, otherwise returns null.

`MediaLibrary.createAlbumAsync(albumName, asset, copyAsset)`

Creates an album with given name and initial asset. The asset parameter is required on Android, since it's not possible to create empty album on this platform. On Android, by default it copies given asset from the current album to the new one, however it's also possible to move it by passing false as copyAsset argument. In case it's copied you should keep in mind that getAssetsAsync will return duplicated asset.

Arguments

albumName (string) -- Name of the album to create.
asset (string | Asset) -- Asset or its ID. Required on Android.
copyAsset (boolean) -- Whether to copy asset to the new album instead of move it. Defaults to true. (Android only)

Returns

Newly created album.

`MediaLibrary.deleteAlbumsAsync(albums, deleteAssets)`

Deletes given albums from the library.

On Android by default it deletes assets belonging to given albums from the library. On iOS it doesn't delete these assets, however it's possible to do by passing true as deleteAssets.

Arguments

albums (array) -- Array of albums or their IDs, that will be removed from the library.
deleteAssets (boolean) -- Whether to also delete assets belonging to given albums. Defaults to false. (iOS only)

Returns

Returns a promise resolving to true if the albums were successfully deleted from the library.

`MediaLibrary.addAssetsToAlbumAsync(assets, album, copyAssets)`

Adds array of assets to the album.

On Android, by default it copies assets from the current album to provided one, however it's also possible to move them by passing false as copyAssets argument. In case they're copied you should keep in mind that getAssetsAsync will return duplicated assets.

Arguments

assets (array) -- Array of assets to add.
album (string | Album) -- Album or its ID, to which the assets will be added.
copyAssets (boolean) -- Whether to copy assets to the new album instead of move them. Defaults to true. (Android only)

Returns

Resolves to true if the assets were successfully added to the album.

`MediaLibrary.removeAssetsFromAlbumAsync(assets, album)`

Removes given assets from album.

On Android, album will be automatically deleted if there are no more assets inside.

Arguments

assets (array) -- Array of assets to remove from album.
album (string | Album) -- Album or its ID, from which the assets will be removed.

Returns

Returns true if the assets were successfully removed from the album.

`MediaLibrary.getMomentsAsync()`

Available on iOS only. Fetches a list of moments, which is a group of assets taken around the same place and time.

Returns

An array of albums whose type is moment.

`MediaLibrary.addListener(listener)`

Subscribes for updates in user's media library.

Arguments

listener (function) -- A callback that is called when any assets have been inserted or deleted from the library. On Android it's invoked with an empty object. On iOS it's invoked with an object that contains following keys:
- insertedAssets (array) -- Array of assets that have been inserted to the library.
- deletedAssets (array) -- Array of assets that have been deleted from the library.
- updatedAssets (array) -- Array of assets that have been updated or completed downloading from network storage (iCloud in iOS).

accessPrivileges (string) - Indicates if your app has access to the whole or only part of the photo library. Possible values are:
- all if the user granted your app access to the whole photo library
- limited if the user granted your app access only to selected photos (only available on iOS 14.0+)
- none if user denied or hasn't yet granted the permission

`Asset`

Field name	Type	Platforms	Description	Possible values
id	string	both	Internal ID that represents an asset
filename	string	both	Filename of the asset
uri	string	both	URI that points to the asset	`assets://` (iOS), `file://` (Android)
mediaType	string	both	Media type	`MediaType.audio`, `MediaType.photo`, `MediaType.video`, `MediaType.unknown`
width	number	both	Width of the image or video
height	number	both	Height of the image or video
creationTime	number	both	File creation timestamp
modificationTime	number	both	Last modification timestamp
duration	number	both	Duration of the video or audio asset in seconds
mediaSubtypes	array	iOS	An array of media subtypes	`hdr`, `panorama`, `stream`, `timelapse`, `screenshot`, `highFrameRate`, `livePhoto`, `depthEffect`
albumId	string	Android	Album ID that the asset belongs to
localUri *	string	both	Local URI for the asset
location *	object	both	GPS location if available	`latitude: number, longitude: number` or `null`
exif *	object	both	EXIF metadata associated with the image
orientation *	number	iOS	Display orientation of the image. Orientation is available only for assets whose mediaType is MediaType.photo	Numbers 1-8, see EXIF orientation specification
isFavorite *	boolean	iOS	Whether the asset is marked as favorite	`true`, `false`
isNetworkAsset **	boolean	iOS	Whether the asset is stored on the network (iCloud on iOS)	`true`, `false`

* These fields can be obtained only by calling getAssetInfoAsync method

** This field is available only if flag shouldDownloadFromNetwork is set to false

`Album`

Field name	Type	Platforms	Description	Possible values
id	string	both
title	string	both
assetCount	number	both	Estimated number of assets in the album
folderName	string	iOS	Name of folder that the album belongs to. Can be null if the album is in the root directory
type	string	iOS	The type of the assets album	`album`, `moment`, `smartAlbum`
startTime *	number	iOS	Earliest creation timestamp of all assets in the moment
endTime *	number	iOS	Latest creation timestamp of all assets in the moment
approximateLocation *	object	iOS	Approximated location of all assets in the moment	`latitude: number, longitude: number` or `null`
locationNames *	array	iOS	Names of locations grouped in the moment

* These fields apply only to albums whose type is moment

Constants

`MediaLibrary.MediaType`

Possible media types:

MediaType.photo
MediaType.video
MediaType.audio
MediaType.unknown

`MediaLibrary.SortBy`

Supported keys that can be used to sort getAssetsAsync results:

SortBy.default
SortBy.creationTime
SortBy.modificationTime
SortBy.mediaType
SortBy.width
SortBy.height
SortBy.duration