PhotoKit
Build media selection, camera capture, photo library queries, and image caching workflows with PhotosUI (PhotosPicker), PhotoKit (PHPhotoLibrary), and AVFoundation. Targets Swift 6.4 / iOS 26+.
Contents
Picker Selection Strategy
| Approach |
UI Framework |
Permissions Needed |
Use Case |
PhotosPicker |
SwiftUI |
None (runs out-of-process) |
User selects photos/videos for import |
PHPickerViewController |
UIKit |
None (runs out-of-process) |
UIKit equivalent of PhotosPicker |
PHPhotoLibrary |
Direct API |
NSPhotoLibraryUsageDescription |
Custom gallery, background sync, asset deletion |
AVCaptureSession |
Custom UI |
NSCameraUsageDescription |
Real-time camera viewfinder, photo/video capture |
Prefer PhotosPicker for standard media selection. It preserves user privacy and eliminates permission friction.
Privacy and Permissions
When accessing PHPhotoLibrary directly, request authorization and handle .limited access:
let status = await PHPhotoLibrary.requestAuthorization(for: .readWrite)
switch status {
case .authorized:
// Full photo library access granted
case .limited:
// User selected specific photos (present PHPhotoLibrary.shared().presentLimitedLibraryPicker)
case .denied, .restricted:
// Direct user to Settings
case .notDetermined:
break
@unknown default:
break
}
Include NSPhotoLibraryUsageDescription (read/write) or NSPhotoLibraryAddUsageDescription (write-only save) in Info.plist.
Image Loading and Caching
Use PHCachingImageManager for fast grid thumbnail generation:
- Prepare caching: Call
startCachingImages(for:targetSize:contentMode:options:) when scrolling into view.
- Reuse options: Use
PHImageRequestOptions with deliveryMode = .opportunistic for quick thumbnails followed by high-res data.
- Cancel obsolete requests: Cancel pending request IDs when cells scroll out of viewport.
Camera Capture Boundaries
For custom camera viewfinders using AVCaptureSession:
- Configure sessions on a dedicated serial background queue, never on
@MainActor.
- Balance every transaction with
session.beginConfiguration() and defer { session.commitConfiguration() }.
- Embed viewfinders in SwiftUI using
UIViewRepresentable backed by AVCaptureVideoPreviewLayer.
Route by Task
- For SwiftUI
PhotosPicker single/multi-selection and media filtering recipes, read PhotosPicker Recipes.
- For complete camera controllers, photo capture, video recording, and barcode scanning, read Camera Capture Patterns.
- For asset fetching, thumbnail caching with
PHCachingImageManager, and memory management, read Image Loading and Caching. For format conversion and compression, read Image Formats and Compression.
- For video playback, custom player UI, and AVPlayer integration, read AV Playback Reference.
iOS 27 Updates
PHAssetResource.originalFilename is incorrectly non-nullable. Use the new nullable filename property and handle nil.
Sources: https://sosumi.ai/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes
Common Mistakes
- Requesting full photo library permissions when
PhotosPicker would suffice without any permissions.
- Hardcoding
.highQualityFormat on PHImageRequestOptions for fast-scrolling grids, causing dropped frames.
- Running
AVCaptureSession.startRunning() or configuration changes on @MainActor.
- Forgetting to handle
.limited photo library access on iOS 14+.
- Loading full-resolution
UIImage into memory for multiple items simultaneously without downsampling.
Review Checklist
References
- PhotoKit patterns and picker recipes
- Camera capture and AVCaptureSession reference
- Image loading, caching, and downsampling
- Image formats and compression
- AV Playback reference
- PhotoKit documentation
- PhotosUI documentation
1---2name: photokit3description: "Builds or reviews photo-library picking, image loading, camera capture, and video recording with PhotoKit, PhotosPicker/PHPicker, and AVFoundation. Use for photo or camera permissions, media selection, capture sessions, library changes, caching, or media export."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/photokit6---78# PhotoKit910Build media selection, camera capture, photo library queries, and image caching workflows with `PhotosUI` (`PhotosPicker`), `PhotoKit` (`PHPhotoLibrary`), and `AVFoundation`. Targets Swift 6.4 / iOS 26+.1112## Contents1314- [Picker Selection Strategy](#picker-selection-strategy)15- [Privacy and Permissions](#privacy-and-permissions)16- [Image Loading and Caching](#image-loading-and-caching)17- [Camera Capture Boundaries](#camera-capture-boundaries)18- [Route by Task](#route-by-task)19- [iOS 27 Updates](#ios-27-updates)20- [Common Mistakes](#common-mistakes)21- [Review Checklist](#review-checklist)22- [References](#references)2324## Picker Selection Strategy2526| Approach | UI Framework | Permissions Needed | Use Case |27|---|---|---|---|28| `PhotosPicker` | SwiftUI | **None** (runs out-of-process) | User selects photos/videos for import |29| `PHPickerViewController` | UIKit | **None** (runs out-of-process) | UIKit equivalent of PhotosPicker |30| `PHPhotoLibrary` | Direct API | `NSPhotoLibraryUsageDescription` | Custom gallery, background sync, asset deletion |31| `AVCaptureSession` | Custom UI | `NSCameraUsageDescription` | Real-time camera viewfinder, photo/video capture |3233Prefer `PhotosPicker` for standard media selection. It preserves user privacy and eliminates permission friction.3435## Privacy and Permissions3637When accessing `PHPhotoLibrary` directly, request authorization and handle `.limited` access:3839```swift40let status = await PHPhotoLibrary.requestAuthorization(for: .readWrite)41switch status {42case .authorized:43 // Full photo library access granted44case .limited:45 // User selected specific photos (present PHPhotoLibrary.shared().presentLimitedLibraryPicker)46case .denied, .restricted:47 // Direct user to Settings48case .notDetermined:49 break50@unknown default:51 break52}53```5455Include `NSPhotoLibraryUsageDescription` (read/write) or `NSPhotoLibraryAddUsageDescription` (write-only save) in `Info.plist`.5657## Image Loading and Caching5859Use `PHCachingImageManager` for fast grid thumbnail generation:601. **Prepare caching**: Call `startCachingImages(for:targetSize:contentMode:options:)` when scrolling into view.612. **Reuse options**: Use `PHImageRequestOptions` with `deliveryMode = .opportunistic` for quick thumbnails followed by high-res data.623. **Cancel obsolete requests**: Cancel pending request IDs when cells scroll out of viewport.6364## Camera Capture Boundaries6566For custom camera viewfinders using `AVCaptureSession`:67- Configure sessions on a dedicated serial background queue, never on `@MainActor`.68- Balance every transaction with `session.beginConfiguration()` and `defer { session.commitConfiguration() }`.69- Embed viewfinders in SwiftUI using `UIViewRepresentable` backed by `AVCaptureVideoPreviewLayer`.7071## Route by Task7273- For SwiftUI `PhotosPicker` single/multi-selection and media filtering recipes, read [PhotosPicker Recipes](references/photokit-patterns.md).74- For complete camera controllers, photo capture, video recording, and barcode scanning, read [Camera Capture Patterns](references/camera-capture.md).75- For asset fetching, thumbnail caching with `PHCachingImageManager`, and memory management, read [Image Loading and Caching](references/image-loading-caching.md). For format conversion and compression, read [Image Formats and Compression](references/image-formats-compression.md).76- For video playback, custom player UI, and AVPlayer integration, read [AV Playback Reference](references/av-playback.md).7778## iOS 27 Updates7980- `PHAssetResource.originalFilename` is incorrectly non-nullable. Use the new nullable `filename` property and handle `nil`.8182Sources: https://sosumi.ai/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes8384## Common Mistakes8586- Requesting full photo library permissions when `PhotosPicker` would suffice without any permissions.87- Hardcoding `.highQualityFormat` on `PHImageRequestOptions` for fast-scrolling grids, causing dropped frames.88- Running `AVCaptureSession.startRunning()` or configuration changes on `@MainActor`.89- Forgetting to handle `.limited` photo library access on iOS 14+.90- Loading full-resolution `UIImage` into memory for multiple items simultaneously without downsampling.9192## Review Checklist9394- [ ] `PhotosPicker` preferred over custom library enumeration where appropriate95- [ ] `NSPhotoLibraryUsageDescription` provided when using `PHPhotoLibrary`96- [ ] `NSCameraUsageDescription` provided when using `AVCaptureSession`97- [ ] `.limited` photo library authorization handled gracefully98- [ ] `PHCachingImageManager` used with preheating for asset collections99- [ ] `AVCaptureSession` configured and started on a serial background queue100- [ ] Photo picker item loading handles cancellation and errors asynchronously101- [ ] Image assets downsampled to target display size to prevent memory spikes102103## References104105- [PhotoKit patterns and picker recipes](references/photokit-patterns.md)106- [Camera capture and AVCaptureSession reference](references/camera-capture.md)107- [Image loading, caching, and downsampling](references/image-loading-caching.md)108- [Image formats and compression](references/image-formats-compression.md)109- [AV Playback reference](references/av-playback.md)110- [PhotoKit documentation](https://sosumi.ai/documentation/photokit)111- [PhotosUI documentation](https://sosumi.ai/documentation/photosui)