> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/photo-library.md).

# Photo Library

## What is Photo Library?

The Photo Library feature gives your app broad, persistent access to the user's entire photo library on both iOS and Android - including the Android `READ_MEDIA_IMAGES` and `READ_MEDIA_VIDEO` permissions, and the iOS `NSPhotoLibraryUsageDescription` (Photos) permission. 

{% hint style="danger" %}
Enable it only if your app has a core function that requires this - a **photo editor** or **gallery management** app, for example (e.g. Instagram). 

Google Play has been rejecting apps that request these permissions without this kind of core use case - including marketplace or classifieds apps that only need users to upload a few photos.
{% endhint %}

The device's standard system picker is always available to your app regardless of this setting. If you only need to let users upload a photo - a profile picture, a listing image, an attachment - **you don't need to enable this feature at all**; the system picker handles that without requiring broad permissions.

## Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Photo Library**.
2. Toggle the feature to **Enabled**.
3. Select which Android permissions your app needs: `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`, or both - only check the ones your app actually uses.
4. Enter the **Permission Description**.
5. Click **Save**.
6. Rebuild your app(s).

{% hint style="info" %}
The **Permission Description** is the text shown to users when the OS asks them to grant **photo library** access. Explain clearly why your app needs this permission - for example: "We use your photo library to let you browse and select multiple images for your gallery".
{% endhint %}

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

## How to use

#### Default to the system picker

For most apps - profile pictures, listing photos, message attachments - the standard file input picker covers it without needing this feature enabled at all. Only enable Photo Library if your app's core purpose depends on browsing or managing the user's full photo library.

#### Enable it for gallery and editing apps

If your app lets users browse their camera roll, select multiple photos at once, or manage albums, Photo Library is the right choice - the system picker isn't built for that kind of bulk or repeated access.

#### Only check the Android permissions your app actually uses

If your app only works with photos and never handles video, check `READ_MEDIA_IMAGES` alone rather than both - requesting permissions you don't use increases rejection risk.

#### Write a Permission Description that matches the actual use case

Since this permission grants broad access on both iOS and Android, be specific about why - vague descriptions like "to improve your experience" are a common cause of rejection. Explain the real feature, e.g. "We use your photo library to let you browse and select multiple images for your gallery".

## Troubleshooting

<details>

<summary>App rejected by Google Play Store or Apple App Store</summary>

Both stores may reject apps where the underlying use case doesn't justify persistent, full-library access - marketplace, classifieds, and listing apps are common examples that get rejected even with a valid description. Only enable this feature for apps like photo editors or gallery managers where broad access is core to the app's function; otherwise, use the system picker (default behavior).

</details>