TLPhotoPicker

A modern, flexible photo and video picker for iOS applications. TLPhotoPicker enables selecting media from multiple smart albums with an interface similar to Facebook's photo picker.

Demo 🙉

Features

• ✅ Smart Album Support - Camera roll, selfies, panoramas, favorites, videos, and custom albums
• 📱 Selection Order - Visual order indicators for selected media
• ▶️ Media Playback - Preview videos and Live Photos directly in the picker
• ⏱️ Video Duration - Display video length on thumbnails
• ⚡ High Performance - Async asset loading with excellent scrolling performance
• 🎨 Customizable - Custom cells, selection rules, and UI elements
• 🔄 Live Updates - Automatic reload when Photos library changes
• ☁️ iCloud Support - Seamless iCloud Photo Library integration

Custom Camera Cell

Requirements

• iOS 13.0+
• Swift 5.0+
• Xcode 14.0+

Installation

CocoaPods

platform :ios, '13.0'
pod "TLPhotoPicker"

Swift Package Manager

Add TLPhotoPicker as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/tilltue/TLPhotoPicker.git", .upToNextMajor(from: "2.1.0"))
]

Privacy Configuration

Add the following keys to your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Access to photos is required to select images</string>
<key>NSCameraUsageDescription</key>
<string>Camera access is required to take photos</string>

iOS 14+ Limited Photo Access

To suppress automatic prompting, add this to Info.plist:

<key>PHPhotoLibraryPreventAutomaticLimitedAccessAlert</key>
<true/>

Learn more

Quick Start

Basic Usage

import TLPhotoPicker

class ViewController: UIViewController {
    @IBAction func openPhotoPicker() {
        let picker = TLPhotosPickerViewController()
        picker.delegate = self
        present(picker, animated: true)
    }
}

extension ViewController: TLPhotosPickerViewControllerDelegate {
    func dismissPhotoPicker(withTLPHAssets: [TLPHAsset]) {
        // Handle selected assets
        for asset in withTLPHAssets {
            print("Selected: \(asset.originalFileName ?? "Unknown")")
        }
    }
}

Modern Async/Await (iOS 13+)

// Load images asynchronously
Task {
    if let image = await selectedAssets.first?.fullResolutionImage() {
        await MainActor.run {
            self.imageView.image = image
        }
    }
}

// Load multiple images concurrently
Task {
    let images = await withTaskGroup(of: UIImage?.self) { group in
        for asset in selectedAssets {
            group.addTask { await asset.fullResolutionImage() }
        }

        var results: [UIImage] = []
        for await image in group {
            if let image = image { results.append(image) }
        }
        return results
    }

    await MainActor.run {
        self.displayImages(images)
    }
}

Configuration with Builder Pattern

let picker = TLPhotosPickerViewController()

// Use presets
picker.configure = .singlePhoto
picker.configure = .videoOnly
picker.configure = .compactGrid

// Or build custom configuration
picker.configure = TLPhotosPickerConfigure()
    .numberOfColumns(3)
    .maxSelection(20)
    .allowVideo(true)
    .allowLivePhotos(true)
    .selectedColor(.systemPink)
    .useCameraButton(true)

// Extend presets
picker.configure = .videoOnly
    .numberOfColumns(4)
    .selectedColor(.systemBlue)

present(picker, animated: true)

Documentation

For detailed information, see:

• Configuration Guide - Complete configuration options
• Advanced Usage - Custom cells, delegates, and rules
• API Reference - TLPHAsset and helper methods
• Migration Guide - Upgrading from older versions

Common Use Cases

Single Photo Selection

picker.configure = .singlePhoto
    .selectedColor(.systemPurple)

Video Recording Only

picker.configure = TLPhotosPickerConfigure()
    .mediaType(.video)
    .allowPhotograph(false)
    .allowVideoRecording(true)

Instagram-style Grid

picker.configure = .compactGrid
    .maxSelection(10)
    .selectedColor(UIColor(red: 0/255, green: 122/255, blue: 255/255, alpha: 1.0))

Custom Selection Rules

picker.canSelectAsset = { asset in
    // Only allow images larger than 300x300
    return asset.pixelWidth >= 300 && asset.pixelHeight >= 300
}

picker.didExceedMaximumNumberOfSelection = { picker in
    // Show alert when limit reached
}

Capture Camera Media URL

let picker = TLPhotosPickerViewController()
picker.didCaptureMediaURL = { url in
    // Both the camera picker and TLPhotosPickerViewController are already
    // dismissed at this point. Just present your next screen.
    let uploadVC = MyUploadViewController(fileURL: url)
    presentingViewController.present(uploadVC, animated: true)
}

present(picker, animated: true)

When set, camera captures are returned as temporary file URLs instead of being saved to the Photo Library. By the time the closure fires, the camera picker and TLPhotosPickerViewController have both been fully dismissed — the caller only needs to present their next view controller, never dismiss.

Delegate Methods

protocol TLPhotosPickerViewControllerDelegate {
    func shouldDismissPhotoPicker(withTLPHAssets: [TLPHAsset]) -> Bool
    func dismissPhotoPicker(withTLPHAssets: [TLPHAsset])
    func dismissPhotoPicker(withPHAssets: [PHAsset])
    func photoPickerDidCancel()
    func dismissComplete()
    func canSelectAsset(phAsset: PHAsset) -> Bool
    func didExceedMaximumNumberOfSelection(picker: TLPhotosPickerViewController)
    func handleNoAlbumPermissions(picker: TLPhotosPickerViewController)
    func handleNoCameraPermissions(picker: TLPhotosPickerViewController)
}

TLPHAsset

The library provides TLPHAsset, a wrapper around PHAsset with convenient helper methods:

public struct TLPHAsset {
    public var phAsset: PHAsset?
    public var selectedOrder: Int
    public var type: AssetType // .photo, .video, .livePhoto
    public var originalFileName: String?
    public var isSelectedFromCamera: Bool

    // Async image loading
    public func fullResolutionImage() async -> UIImage?

    // iCloud download
    public func cloudImageDownload(
        progressBlock: @escaping (Double) -> Void,
        completionBlock: @escaping (UIImage?) -> Void
    ) -> PHImageRequestID?

    // Export to file
    public func tempCopyMediaFile(
        convertLivePhotosToJPG: Bool = false,
        progressBlock: ((Double) -> Void)? = nil,
        completionBlock: @escaping ((URL, String) -> Void)
    ) -> PHImageRequestID?

    // File size
    public func photoSize(completion: @escaping (Int) -> Void)
    public func videoSize(completion: @escaping (Int) -> Void)

    // Static method
    public static func asset(with localIdentifier: String) -> TLPHAsset?
}

See API Reference for complete documentation.

Contributing

Issues and pull requests are welcome! Please check existing issues before creating new ones.

💖 Support This Project

TLPhotoPicker is an open-source project maintained in my free time. If you find it useful, please consider supporting its development:

Your support helps me:

• 🐛 Fix bugs and maintain compatibility with latest iOS versions
• ✨ Develop new features and improvements
• 📚 Improve documentation and examples
• ⚡ Performance optimizations and code quality

Every contribution is appreciated! 🙏

Author

wade.hawk - junhyi.park@gmail.com

Does your organization use TLPhotoPicker? Let me know!

License

TLPhotoPicker is available under the MIT license. See the LICENSE file for details.