Photo Library API Reference

API reference for PhotoKit and the system photo pickers: PHPickerViewController, PhotosPicker, PHPhotoLibrary authorization, PHAsset fetching, PHImageManager image requests, asset creation, and the 27-release additions.

When to Use This Reference

Use this reference when:

• Looking up PHPickerConfiguration options and filter syntax
• Checking PhotosPicker modifiers for embedded, inline, or compact styles
• Understanding PHAuthorizationStatus values and access levels
• Fetching assets with PHFetchOptions predicates and sort descriptors
• Requesting images from PHImageManager with delivery modes
• Creating assets with PHAssetCreationRequest, including deferred photo proxies
• Implementing PHPhotoLibraryChangeObserver for library sync, or tracking changes across launches with the iOS 27 persistent change observer
• Editing asset keywords, ratings, and captions (iOS 27)
• Checking which PhotoKit types are Sendable, and how many times requestImage calls its handler

Example Prompts

Questions you can ask your assistant that will draw from this reference:

• "What are all the PHPickerFilter options?"
• "How do I configure PhotosPicker for an inline embedded style?"
• "What's the difference between .authorized and .limited?"
• "How do I fetch the most recent 100 photos?"
• "What are the PHImageRequestOptions delivery modes?"
• "How do I save a deferred photo proxy to the library?"
• "What properties does PHAsset have?"
• "Is PHFetchResult Sendable?"
• "Does requestImage call its handler more than once?"
• "How do I write a PHPhotoLibraryChangeObserver under Swift 6?"
• "How do I strip location metadata from photos the user picks?"
• "How do I present the shared album creation sheet?"
• "How do I find out what changed in the photo library while my app wasn't running?"
• "How do I add keywords or a star rating to a photo?"
• "How do I show an Apple Reference Image in my app?"
• "How do I turn on background photo uploads with Wi-Fi only on macOS 27?"

What's Covered

• PHPickerViewController (iOS 14+): configuration, filters, presentation, delegate, and PHPickerResult
• PhotosPicker (iOS 16+): filters, selection behaviors, embedded styles (presentation, inline, compact; iOS 17+), disabled capabilities, accessory visibility, and HDR preservation
• Picker metadata stripping and search seeding (iOS 27) — PHPickerMetadataOptions, PHPickerSearchText, photosPickerMetadataOptions(_:), photosPickerSearchText(_:)
• Shared album sheets (iOS 27) — photosSharedAlbumCreationSheet / …PostingSheet / …CustomizationSheet, PHSharedAlbumCreationResult, PHSharedAlbumCreationSharingPolicy
• Apple Reference Image (iOS and macOS 27) — PHReferenceImageInfo, imageContainsReferenceImageData, and the four photosReferenceImageViewer(…) modifiers
• PhotosPickerItem loading with Transferable and custom transfer representations
• PHPhotoLibrary authorization statuses, access levels (.readWrite, .addOnly), and the limited library picker
• PHAsset properties, media types, subtypes, and fetch options
• PHAssetCreationRequest from a UIImage, a file URL, resources, and a deferred photo proxy (iOS 17+); custom albums
• PHFetchResult access patterns and enumeration
• PHImageManager image and video requests, delivery modes, and secondary degraded images (iOS 17+)
• PHChange handling with incremental updates for collection views
• Persistent change history observer (iOS 27) — PHPhotoLibraryPersistentChangesObserver, register(_:) / unregisterPersistentChangesObserver(_:), fetchPersistentChanges(since:), PHPhotosError.persistentChangeTokenExpired
• Asset metadata editing (iOS 27) — addKeyword(_:) / removeKeyword(_:), rating (PHAsset.Rating), caption, setLivePhotoVideoPlaybackEnabled(_:), revertAssetContent(to:), originalResourceChoice, PHAssetExtendedMetadata, prefetchAssetExtendedMetadata
• Collections and identifiers (iOS 27) — PHCollectionListSubtype.rootFolder, localIdentifierMappings(forSynced:)
• CloudKit server-side asset export (iOS 27) — PHAssetResourceManager.exportedAssetID(for:), PHAssetResource.dataSize
• Background asset resource upload (iOS and macOS 27) — enableUploadJobExtension(with:), setUploadJobExtensionOptions(_:), disableUploadJobExtension(), PHAssetResourceUploadJobOptions, PHAssetResource.assetResource(forUploadJob:), PHBackgroundResourceUploadJobExtension
• Sendable annotations across PHAsset, PHObject, PHFetchResult, PHChange, and PHPhotoLibrary
• Isolation requirements for photoLibraryDidChange and performChanges change blocks
• requestImage callback order: a degraded image, an optional secondary degraded image, then the final image

Documentation Scope

This page documents the photo-library-ref skill (in the axiom-media suite), the API detail for PhotoKit classes and the photo picker views.

Key APIs

PHAuthorizationStatus

Status	Description
.notDetermined	User hasn't been asked
.restricted	Parental controls limit access
.denied	User denied access
.authorized	Full access granted
.limited	Access to user-selected photos only (iOS 14+)

PhotosPicker Styles (iOS 17+)

Style	Description
.presentation	Modal sheet (default)
.inline	Embedded in view hierarchy
.compact	Single row, minimal vertical space

PHImageManager Delivery Modes

Mode	Description
.opportunistic	Fast thumbnail, then high quality
.highQualityFormat	Only high quality
.fastFormat	Only fast/degraded

PHAsset Media Types

Type	Description
.image	Photos, screenshots, Live Photos
.video	Videos, slo-mo, cinematic, timelapse
.audio	Audio recordings

Related

• photo-library – Implementation patterns for photo picking and library access
• camera-capture-ref – AVFoundation camera API reference
• camera-capture – Custom camera UI patterns
• isolation-inheritance-diag – Diagnosing isolation crashes from PhotoKit callbacks under Swift 6

Resources

Docs: /photosui/phpickerviewcontroller, /photosui/photospicker, /photos/phphotolibrary, /photos/phasset, /photos/phimagemanager