TLPhotoPicker Documentation

For common use cases, TLPhotosPickerConfigure provides several built-in presets that you can apply directly to your view controller's configure property:

• .singlePhoto: Configures the picker for selecting only one photo.
• .videoOnly: Configures the picker to allow only video recording/selection.
• .compactGrid: Configures an Instagram-style compact grid layout.

// Single photo selection with a custom color
viewController.configure = .singlePhoto
    .selectedColor(.systemPurple)

// Video only configuration
viewController.configure = .videoOnly
    .numberOfColumns(3)
    .allowPhotograph(false)
    .allowVideoRecording(true)

// Compact grid configuration
viewController.configure = .compactGrid
    .maxSelection(10)
    .selectedColor(.systemBlue)

TLPHAsset is a wrapper around PHAsset that provides convenient helper methods for accessing image data, file sizes, and exporting media. It includes properties for the underlying phAsset, selection order, AssetType (.photo, .video, or .livePhoto), original filename, and whether it was captured via camera.

public struct TLPHAsset {
    public var phAsset: PHAsset?
    public var selectedOrder: Int
    public var type: AssetType
    public var originalFileName: String?
    public var isSelectedFromCamera: Bool
    public var fullResolutionImage: UIImage?
}

TLPhotoPicker supports two ways to handle events:

1. Delegate Pattern: Best for complex logic or when your controller needs to conform to a protocol. Implement TLPhotosPickerViewControllerDelegate to handle methods like dismissPhotoPicker(withTLPHAssets:).
2. Closure Pattern: Best for simple, one-off event handling. Use closures for properties like didExceedMaximumNumberOfSelection.

// Delegate approach
class ViewController: TLPhotosPickerViewControllerDelegate {
    func dismissPhotoPicker(withTLPHAssets: [TLPHAsset]) {
        // Handle selection
    }
}

// Closure approach
picker.didExceedMaximumNumberOfSelection = { picker in
    // Handle max selection
}

CocoaPods

Add the following to your Podfile:

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"))
]

The recommended way to configure TLPhotosPickerViewController is using the modern Builder Pattern on a TLPhotosPickerConfigure object. This allows for a fluent API to set properties like column count and selection limits.

Commonly used methods include:

• .numberOfColumns(_:)
• .maxSelection(_:)
• .selectedColor(_:)
• .groupBy(_:) (e.g., .day)
• .allowPhotograph(_:)
• .allowVideoRecording(_:)

viewController.configure = TLPhotosPickerConfigure()
    .numberOfColumns(3)
    .maxSelection(20)

In version 2.x, most delegate methods in TLPhotosPickerViewControllerDelegate are now optional with default implementations. You no longer need to implement every method to satisfy the protocol; you only need to implement the ones required for your specific logic (typically dismissPhotoPicker(withTLPHAssets:)).

// In 2.x, you only implement what you need
extension ViewController: TLPhotosPickerViewControllerDelegate {
    func dismissPhotoPicker(withTLPHAssets: [TLPHAsset]) {
        self.selectedAssets = withTLPHAssets
    }
}

To use TLPhotoPicker, you must add the following keys to your Info.plist to request access to the photo library and camera:

• NSPhotoLibraryUsageDescription: Required to select images.
• NSCameraUsageDescription: Required to take photos.

iOS 14+ Limited Photo Access: To suppress the automatic prompting for limited photo access, add the following key:

• PHPhotoLibraryPreventAutomaticLimitedAccessAlert: Set to <true/>.

<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>
<key>PHPhotoLibraryPreventAutomaticLimitedAccessAlert</key>
<true/>

You can configure the picker by creating an instance of TLPhotosPickerConfigure and assigning it to the configure property of your TLPhotosPickerViewController. This style uses direct property assignment.

let viewController = TLPhotosPickerViewController()
var configure = TLPhotosPickerConfigure()
configure.numberOfColumn = 3
configure.maxSelectedAssets = 20
viewController.configure = configure

By setting the didCaptureMediaURL closure, camera captures are returned as temporary file URLs instead of being saved to the Photo Library.

Important: When this closure fires, both the camera picker and the TLPhotosPickerViewController have already been fully dismissed. You should not call dismiss on the presenting view controller; instead, simply present your next screen (e.g., an upload screen) directly.

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)
}