Photo Library

Save, browse, edit, and export photos and videos on iOS and Android

One.PhotoLibrary is the full read and write API for the system photo library: save captures, browse asset metadata page by page, organize albums, mark favorites, replace content in place, and export originals to files. Reach for it when your app manages the library itself; for a one-shot attachment, the system pickers on the image picker page are simpler.

On iOS it drives PHPhotoLibrary from the Photos framework. On Android it queries MediaStore through the content resolver. On web there is no library, so permissions read denied, lists come back empty, and calls that return a value reject.

Usage

import { One } from 'one'

async function saveCapture(imageFileUri: string) {
  const permission = await One.PhotoLibrary.requestAddPermission()
  if (permission === 'authorized') {
    const assetId = await One.PhotoLibrary.saveImage(imageFileUri)
    console.log('Saved Photos asset', assetId)
  }
}

Saving needs only add permission, which never prompts on current Android. The save resolves with the new asset identifier once the library commits the change.

How it works

Two permissions split the API. Add-only covers saveImage and saveVideo. Read/write covers everything else: listing, albums, favorites, deletion, replacement, and export. Declare the messages your app uses in native.app.photoLibrary before prebuild: addOnly becomes NSPhotoLibraryAddUsageDescription and readWrite becomes NSPhotoLibraryUsageDescription on iOS, plus a flag that stops the system from showing the limited-access alert on its own, so your app chooses when to call presentLimitedLibraryPicker. On Android the same config stamps the READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, and legacy storage permissions into the manifest. Calls without their message reject with E_PHOTO_LIBRARY_MANIFEST before touching the library.

Reads fetch newest first in bounded pages: integer offset from 0 to 1,000,000 and integer limit from 1 to 100, defaulting to the first 50. Each asset carries its identifier, media type, pixel size, duration, optional creation date, and favorite and Live Photo flags. Metadata only; no call returns image or video bytes. On iOS fetches run on a background queue and writes commit through performChanges, resolving only after Photos accepts the change. On Android queries run on a worker thread against MediaStore, and albums are media buckets, listed but never edited: renaming, membership changes, deletion, and content replace and revert resolve without doing anything, and creating an album rejects. Deleting an asset removes it from the whole library and may show a system confirmation; Photos can retain the item in Recently Deleted.

Saves accept local file:// URIs produced by the file system, image picker, or document picker, never network URLs, and resolve with the new identifier. An app with read/write access can save without requesting add-only access. Exports write to a unique temporary file and return its file:// URI: the untouched original, the visible edited image, or the visible edited video. Each takes an allowNetwork flag, default false, that permits an iCloud download; without it, a cloud-only asset fails rather than using data. Content replacement keeps the asset identifier and the original, so revertAssetContent restores it; Photos may ask the user to confirm either edit. On web, permissions read denied, lists and the picker return empty results, void writes resolve silently, and every call that returns an asset, album, file, or identifier rejects.

API reference

Platform differences

Limits and gotchas

• Album edits and replaces are silent on Android. Rename, membership, album deletion, and content replace and revert resolve without changing anything there; only creating an album rejects. Gate editing UI on iOS.
• Saves take files, not URLs. The save methods accept local file:// URIs only. Anything else rejects with E_PHOTO_LIBRARY_URI.
• Pages shift as the library changes. Offsets count positions in the current newest-first order, so an insert or delete between requests moves later pages. Re-read from the start after a change.
• The limited picker returns only new picks. The promise resolves with the ids added in that session, possibly none. Read the library again for the full visible set.
• Exports are temp files you own. Every export writes a file yours to keep, move, or delete. Delete it when finished.
• Deletion may confirm and may linger. The system can ask the user to confirm a delete, and Photos can keep the item in Recently Deleted.

Examples

import { useState } from 'react'
import { Button, Text } from 'react-native'
import { One } from 'one'

function SavePhoto({ fileUri }: { fileUri: string }) {
  const [saved, setSaved] = useState(false)

  async function save() {
    const permission = await One.PhotoLibrary.requestAddPermission()
    if (permission !== 'authorized') return
    await One.PhotoLibrary.saveImage(fileUri)
    setSaved(true)
  }

  return (
    <>
      <Button title="Save to library" onPress={save} />
      {saved ? <Text>Saved.</Text> : null}
    </>
  )
}

Add-only permission is the cheapest grant that can save, and on current Android it resolves authorized without a prompt. The button stays usable after a deny, so the user can retry once they grant access in Settings.

import { useEffect, useState } from 'react'
import { Text } from 'react-native'
import { One } from 'one'

type LibraryAsset = Awaited<ReturnType<typeof One.PhotoLibrary.listAssets>>['assets'][number]

function NewestPhotos() {
  const [assets, setAssets] = useState<LibraryAsset[]>([])

  useEffect(() => {
    async function load() {
      const permission = await One.PhotoLibrary.requestReadPermission()
      if (permission !== 'authorized' && permission !== 'limited') return
      const page = await One.PhotoLibrary.listAssets(0, 50)
      setAssets(page.assets)
    }
    load()
  }, [])

  return (
    <>
      {assets.map((asset) => (
        <Text key={asset.identifier}>
          {asset.mediaType} {asset.width}x{asset.height}
          {asset.isLivePhoto ? ' live' : ''}
        </Text>
      ))}
    </>
  )
}

Limited access still returns a page, restricted to the user’s selection, so both grants share the same listing path. An asset flagged live can be shown with One.iOS.LivePhotoView.

import { One } from 'one'

async function copyOriginal(identifier: string, share: (uri: string) => Promise<void>) {
  const uri = await One.PhotoLibrary.exportOriginalAsset(identifier)
  try {
    const info = await One.FileSystem.getInfo(uri)
    console.log('Exported bytes:', info.size)
    await share(uri)
  } finally {
    await One.FileSystem.delete(uri)
  }
}

The export lands in a temporary file outside the library, so reading it needs no further permission. The finally deletes it once the share finishes, keeping the temp directory from filling with exports.