A library that provides access to the device's media library.
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.
-
npx expo install expo-media-library
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
You can configure expo-media-library
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-media-library
repository.
{
"expo": {
"plugins": [
[
"expo-media-library",
{
"photosPermission": "Allow $(PRODUCT_NAME) to access your photos.",
"savePhotosPermission": "Allow $(PRODUCT_NAME) to save photos.",
"isAccessMediaLocationEnabled": true
}
]
]
}
}
Name | Default | Description |
---|---|---|
photosPermission | "Allow $(PRODUCT_NAME) to access your photos." | Only for: iOS Sets the iOS |
savePhotosPermission | "Allow $(PRODUCT_NAME) to save photos." | Only for: iOS Sets the iOS |
isAccessMediaLocationEnabled | false | Only for: Android Sets whether or not to request the |
import { useState, useEffect } from 'react';
import { Button, Text, SafeAreaView, ScrollView, StyleSheet, Image, View, Platform } from 'react-native';
import * as MediaLibrary from 'expo-media-library';
export default function App() {
const [albums, setAlbums] = useState(null);
const [permissionResponse, requestPermission] = MediaLibrary.usePermissions();
async function getAlbums() {
if (permissionResponse.status !== 'granted') {
await requestPermission();
}
const fetchedAlbums = await MediaLibrary.getAlbumsAsync({
includeSmartAlbums: true,
});
setAlbums(fetchedAlbums);
}
return (
<SafeAreaView style={styles.container}>
<Button onPress={getAlbums} title="Get albums" />
<ScrollView>
{albums && albums.map((album) => <AlbumEntry album={album} />)}
</ScrollView>
</SafeAreaView>
);
}
function AlbumEntry({ album }) {
const [assets, setAssets] = useState([]);
useEffect(() => {
async function getAlbumAssets() {
const albumAssets = await MediaLibrary.getAssetsAsync({ album });
setAssets(albumAssets.assets);
}
getAlbumAssets();
}, [album]);
return (
<View key={album.id} style={styles.albumContainer}>
<Text>
{album.title} - {album.assetCount ?? 'no'} assets
</Text>
<View style={styles.albumAssetsContainer}>
{assets && assets.map((asset) => (
<Image source={{ uri: asset.uri }} width={50} height={50} />
))}
</View>
</View>
);
}
%%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({
container: {
flex: 1,
gap: 8,
justifyContent: 'center',
...Platform.select({
android: {
paddingTop: 40,
},
}),
},
albumContainer: {
paddingHorizontal: 20,
marginBottom: 12,
gap: 4,
},
albumAssetsContainer: {
flexDirection: 'row',
flexWrap: 'wrap',
},
});
import * as MediaLibrary from 'expo-media-library';
MediaLibrary.SortBy
Type: SortByObject
Supported keys that can be used to sort getAssetsAsync
results.
usePermissions(options)
Parameter | Type |
---|---|
options (optional) | PermissionHookOptions<{
granularPermissions: GranularPermission[],
writeOnly: boolean
}> |
Check or request permissions to access the media library.
This uses both requestPermissionsAsync
and getPermissionsAsync
to interact with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]
Example
const [permissionResponse, requestPermission] = MediaLibrary.usePermissions();
MediaLibrary.addAssetsToAlbumAsync(assets, album, copy)
Parameter | Type | Description |
---|---|---|
assets | AssetRef | AssetRef[] | An array of Asset or their IDs. |
album | AlbumRef | An Album or its ID. |
copy (optional) | boolean | Android only. Whether to copy assets to the new album instead of move them.
Defaults to Default: true |
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.
Promise<boolean>
Returns promise which fulfils with true
if the assets were successfully added to
the album.
MediaLibrary.albumNeedsMigrationAsync(album)
Checks if the album should be migrated to a different location. In other words, it checks if the
application has the write permission to the album folder. If not, it returns true
, otherwise false
.
Note: For Android below R, web or iOS, this function always returns
false
.
Promise<boolean>
Returns a promise which fulfils with true
if the album should be migrated.
MediaLibrary.createAlbumAsync(albumName, asset, copyAsset)
Parameter | Type | Description |
---|---|---|
albumName | string | Name of the album to create. |
asset (optional) | AssetRef | An Asset or its ID (required on Android). |
copyAsset (optional) | boolean | Android Only. Whether to copy asset to the new album instead of move it.
Defaults to Default: true |
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.
Newly created Album
.
MediaLibrary.createAssetAsync(localUri)
Parameter | Type | Description |
---|---|---|
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 |
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.
A promise which fulfils with an object representing an Asset
.
Example
const { uri } = await Camera.takePictureAsync();
const asset = await MediaLibrary.createAssetAsync(uri);
MediaLibrary.deleteAlbumsAsync(albums, assetRemove)
Parameter | Type | Description |
---|---|---|
albums | AlbumRef | AlbumRef[] | An array of |
assetRemove (optional) | boolean | iOS Only. Whether to also delete assets belonging to given albums.
Defaults to Default: false |
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
.
Promise<boolean>
Returns a promise which fulfils with true
if the albums were successfully deleted from
the library.
MediaLibrary.deleteAssetsAsync(assets)
Parameter | Type | Description |
---|---|---|
assets | AssetRef | AssetRef[] | An array of Asset or their IDs. |
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.
Promise<boolean>
Returns promise which fulfils with true
if the assets were successfully deleted.
MediaLibrary.getAlbumAsync(title)
Parameter | Type | Description |
---|---|---|
title | string | Name of the album to look for. |
Queries for an album with a specific name.
An object representing an Album
, if album with given name exists, otherwise
returns null
.
MediaLibrary.getAlbumsAsync(namedParameters)
Parameter | Type |
---|---|
namedParameters (optional) | AlbumsOptions |
Queries for user-created albums in media gallery.
A promise which fulfils with an array of Album
s. Depending on Android version,
root directory of your storage may be listed as album titled "0"
or unlisted at all.
MediaLibrary.getAssetInfoAsync(asset, options)
Parameter | Type | Description |
---|---|---|
asset | AssetRef | An Asset or its ID. |
options (optional) | MediaLibraryAssetInfoQueryOptions | - |
Provides more information about an asset, including GPS location, local URI and EXIF metadata.
An AssetInfo object, which is an Asset
extended by an additional fields.
MediaLibrary.getAssetsAsync(assetsOptions)
Parameter | Type |
---|---|
assetsOptions (optional) | AssetsOptions |
Fetches a page of assets matching the provided criteria.
MediaLibrary.getMomentsAsync()
Fetches a list of moments, which is a group of assets taken around the same place and time.
Promise<any>
An array of albums whose type is moment
.
MediaLibrary.getPermissionsAsync(writeOnly, granularPermissions)
Parameter | Type | Description |
---|---|---|
writeOnly (optional) | boolean | - |
granularPermissions (optional) | GranularPermission[] | A list of |
Checks user's permissions for accessing media library.
A promise that fulfils with PermissionResponse
object.
MediaLibrary.isAvailableAsync()
Returns whether the Media Library API is enabled on the current device.
Promise<boolean>
A promise which fulfils with a boolean
, indicating whether the Media Library API is
available on the current device.
MediaLibrary.migrateAlbumIfNeededAsync(album)
Moves album content to the special media directories on Android R or above if needed.
Those new locations are in line with the Android scoped storage
- so your application won't
lose write permission to those directories in the future.
This method does nothing if:
The migration is possible when the album contains only compatible files types.
For instance, movies and pictures are compatible with each other, but music and pictures are not.
If automatic migration isn't possible, the function will be rejected.
In that case, you can use methods from the expo-file-system
to migrate all your files manually.
Android R introduced a lot of changes in the storage system. Now applications can't save
anything to the root directory. The only available locations are from the MediaStore
API.
Unfortunately, the media library stored albums in folders for which, because of those changes,
the application doesn't have permissions anymore. However, it doesn't mean you need to migrate
all your albums. If your application doesn't add assets to albums, you don't have to migrate.
Everything will work as it used to. You can read more about scoped storage in the Android documentation.
Promise<void>
A promise which fulfils to void
.
MediaLibrary.presentPermissionsPickerAsync()
Available only on iOS >= 14. Allows the user to update the assets that your app has access to.
The system modal is only displayed if the user originally allowed only limited
access to their
media library, otherwise this method is a no-op.
Promise<void>
A promise that either rejects if the method is unavailable (meaning the device is not
running iOS >= 14), or resolves to void
.
Note: This method doesn't inform you if the user changes which assets your app has access to. For that information, you need to subscribe for updates to the user's media library using addListener(listener). If
hasIncrementalChanges
isfalse
, the user changed their permissions.
MediaLibrary.removeAssetsFromAlbumAsync(assets, album)
Parameter | Type | Description |
---|---|---|
assets | AssetRef | AssetRef[] | An array of Asset or their IDs. |
album | AlbumRef | An Album or its ID. |
Removes given assets from album.
On Android, album will be automatically deleted if there are no more assets inside.
Promise<boolean>
Returns promise which fulfils with true
if the assets were successfully removed from
the album.
MediaLibrary.requestPermissionsAsync(writeOnly, granularPermissions)
Parameter | Type | Description |
---|---|---|
writeOnly (optional) | boolean | - |
granularPermissions (optional) | GranularPermission[] | A list of |
Asks the user to grant permissions for accessing media in user's media library.
A promise that fulfils with PermissionResponse
object.
MediaLibrary.saveToLibraryAsync(localUri)
Parameter | Type | Description |
---|---|---|
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 |
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.
Promise<void>
MediaLibrary.addListener(listener)
Parameter | Type | Description |
---|---|---|
listener | (event: MediaLibraryAssetsChangeEvent) => void | A callback that is fired when any assets have been inserted or deleted from the
library, or when the user changes which assets they're allowing access to. On Android it's
invoked with an empty object. On iOS it's invoked with |
Subscribes for updates in user's media library.
An Subscription
object that you can call remove()
on when you would
like to unsubscribe the listener.
EXPermissionResponse
An object obtained by permissions get and request functions.
EXPermissionResponse 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. |
Album
Name | Type | Description |
---|---|---|
approximateLocation (optional) | Location | Only for: iOS Apply only to albums whose type is |
assetCount | number | Estimated number of assets in the album. |
endTime | number | Only for: iOS Apply only to albums whose type is |
id | string | Album ID. |
locationNames (optional) | string[] | Only for: iOS Apply only to albums whose type is |
startTime | number | Only for: iOS Apply only to albums whose type is |
title | string | Album title. |
type (optional) | AlbumType | Only for: iOS The type of the assets album. |
AlbumsOptions
Name | Type | Description |
---|---|---|
includeSmartAlbums (optional) | boolean | - |
Asset
Name | Type | Description |
---|---|---|
albumId (optional) | string | Only for: Android Album ID that the asset belongs to. |
creationTime | number | File creation timestamp. |
duration | number | Duration of the video or audio asset in seconds. |
filename | string | Filename of the asset. |
height | number | Height of the image or video. |
id | string | Internal ID that represents an asset. |
mediaSubtypes (optional) | MediaSubtype[] | Only for: iOS An array of media subtypes. |
mediaType | MediaTypeValue | Media type. |
modificationTime | number | Last modification timestamp. |
uri | string | URI that points to the asset. |
width | number | Width of the image or video. |
AssetInfo
Type: Asset
extended by:
Name | Type | Description |
---|---|---|
exif (optional) | object | EXIF metadata associated with the image. |
isFavorite (optional) | boolean | Only for: iOS Whether the asset is marked as favorite. |
isNetworkAsset (optional) | boolean | Only for: iOS This field is available only if flag |
localUri (optional) | string | Local URI for the asset. |
location (optional) | Location | GPS location if available. |
orientation (optional) | number | Only for: iOS Display orientation of the image. Orientation is available only for assets whose
|
AssetsOptions
Name | Type | Description |
---|---|---|
after (optional) | AssetRef | Asset ID of the last item returned on the previous page. To get the ID of the next page,
pass |
album (optional) | AlbumRef | Album or its ID to get assets from specific album. |
createdAfter (optional) | Date | number |
|
createdBefore (optional) | Date | number | Similarly as |
first (optional) | number | The maximum number of items on a single page. Default: 20 |
mediaType (optional) | MediaTypeValue[] | MediaTypeValue | An array of MediaTypeValues or a single Default: MediaType.photo |
sortBy (optional) | SortByValue[] | SortByValue | An array of |
GranularPermission
Literal Type: string
Determines the type of media that the app will ask the OS to get access to.
Acceptable values are: 'audio'
| 'photo'
| 'video'
Location
Name | Type | Description |
---|---|---|
latitude | number | - |
longitude | number | - |
MediaLibraryAssetInfoQueryOptions
Name | Type | Description |
---|---|---|
shouldDownloadFromNetwork (optional) | boolean | Whether allow the asset to be downloaded from network. Only available in iOS with iCloud assets. Default: true |
MediaLibraryAssetsChangeEvent
Name | Type | Description |
---|---|---|
deletedAssets (optional) | Asset[] | Available only if |
hasIncrementalChanges | boolean | Whether the media library's changes could be described as "incremental changes".
|
insertedAssets (optional) | Asset[] | Available only if |
updatedAssets (optional) | Asset[] | Available only if |
MediaSubtype
Literal Type: string
Acceptable values are: 'depthEffect'
| 'hdr'
| 'highFrameRate'
| 'livePhoto'
| 'panorama'
| 'screenshot'
| 'stream'
| 'timelapse'
MediaTypeObject
Name | Type | Description |
---|---|---|
audio | 'audio' | - |
photo | 'photo' | - |
unknown | 'unknown' | - |
video | 'video' | - |
PagedInfo
Name | Type | Description |
---|---|---|
assets | T[] | A page of |
endCursor | string | ID of the last fetched asset. It should be passed as |
hasNextPage | boolean | Whether there are more assets to fetch. |
totalCount | number | Estimated total number of assets that match the query. |
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
PermissionResponse
Type: EXPermissionResponse
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:
|
SortByKey
Literal Type: string
Acceptable values are: 'default'
| 'mediaType'
| 'width'
| 'height'
| 'creationTime'
| 'modificationTime'
| 'duration'
SortByObject
Name | Type | Description |
---|---|---|
creationTime | 'creationTime' | - |
default | 'default' | - |
duration | 'duration' | - |
height | 'height' | - |
mediaType | 'mediaType' | - |
modificationTime | 'modificationTime' | - |
width | 'width' | - |
Subscription
Name | Type | Description |
---|---|---|
remove | () => void | A method to unsubscribe the listener. |
PermissionStatus
PermissionStatus Values
UNDETERMINED
PermissionStatus.UNDETERMINED = "undetermined"
User hasn't granted or denied the permission yet.
The following permissions are added automatically through this library's AndroidManifest.xml:
Android Permission | Description |
---|---|
Allows an application to read from external storage. | |
Allows an application to write to external storage. |
The following usage description keys are used by this library:
Info.plist Key | Description |
---|---|
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 add-only access to the user’s photo library. |