ZLPhotoBrowser: a WeChat-style picker for iOS that also edits images and crops video

What ZLPhotoBrowser is for, and who ends up using it

The README describes ZLPhotoBrowser as a WeChat-like image picker: select normal photos, videos, gif and livePhoto, edit images, crop video. That sentence is the scope. The target is an iOS app that needs a full asset flow rather than a single screen: browse the system library, preview, select in order, optionally edit, then hand the results back to app code.

The feature list shows how far past a picker it goes. Portrait and landscape, iPad multi-window, SwiftUI, a custom camera, a configurable column count, maximum and minimum video duration, and an image editor with draw, crop, image sticker, text sticker, mosaic, filter and adjustments for brightness, contrast and saturation. A separate video editor and a customizable camera are listed too. For a team building a chat app, a social feed or a marketplace listing flow, that is most of the media pipeline in one dependency.

The audience is therefore narrower than the feature list suggests. This is not a utility you call once. It is a UI subsystem with its own colors, fonts, images and localized strings, and the README presents the picker as the entry point through ZLPhotoPicker and its showPreview and showPhotoLibrary methods. If you only need to read a few assets, the surface area is larger than the problem.

How the picker, the editors and the asset results fit together

The mechanism visible in the README is block-based. You create a ZLPhotoPicker, assign a selectImageBlock closure, then call one of two entry methods. showPreview opens the big-picture preview flow; showPhotoLibrary opens the album grid. The closure receives results and an isOriginal flag, which is where your code takes over.

That single callback shape means the editing and selection state stay inside the component until the user confirms. The README does not document a delegate protocol or a step-by-step data flow, so the exact internal pipeline is not something this article can describe. What the repository layout does show is a Sources directory, a Tests directory, an Example Xcode project and a separate SwiftUIExample, which suggests the library is meant to be read alongside a running sample rather than from the README alone.

The 5.0.0 changelog adds detail about the configuration surface. A supportLandscape attribute was added, enableWideCameras now defaults to true, and there is a thumbVCAllowPanToDismiss property. Two fixes in the same release are worth noting for anyone integrating: the selection limit prompt was wrong when only videos were allowed, and selection state did not sync after deselecting in preview. Those are the kinds of defects that show up only when you combine editing, preview and a restricted media type, which is precisely the combination this library encourages.

Installing ZLPhotoBrowser with CocoaPods and a first selection flow

The README lists four installation routes: CocoaPods, Carthage, Swift Package Manager, and a manual install by building frameworks or embedding the Xcode project. Requirements are iOS 10.0, Swift 5.x and Xcode 14.x.

For CocoaPods, the README gives this Podfile shape. Note the platform line and use_frameworks!, both of which come from the README rather than from guesswork.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target 'MyApp' do
  pod 'ZLPhotoBrowser'
end

Then run the install command. If the latest version does not resolve, the README says to run pod repo update first.

pod install

For Swift Package Manager the README gives three steps in Xcode: File > Add Packages, enter the repository URL, and set the version resolving rule to Up to Next Major with 5.0.0 as the earliest version. Carthage users add a Cartfile line and run carthage update; the README warns that universal frameworks with common architectures can fail and points to the Xcode 12 workaround document, which is a real constraint for anyone still using that route.

Once the dependency is in place, a minimal library selection looks like this. The closure is where you receive the chosen assets and the original-versus-edited flag.

let picker = ZLPhotoPicker()
picker.selectImageBlock = { [weak self] results, isOriginal in
    // your code
}
picker.showPhotoLibrary(sender: self)

Before any of this runs, the README is explicit about Info.plist. You need Privacy - Photo Library Usage Description, Privacy - Camera Usage Description and Privacy - Microphone Usage Description. It also lists a Localized resources can be mixed key set to YES, and states that without it multiple languages are not supported and the album name falls back to English. That last point is easy to miss and only surfaces in a non-English build.

Where ZLPhotoBrowser is the wrong dependency

The clearest limitation is reach. The library is iOS only, with a minimum of iOS 10.0, and every installation route in the README is an Apple toolchain route. There is no Android, web or cross-platform path here, and no server component. If your product ships on more than one platform, this is a per-platform decision, not a shared one.

The second limitation is API stability across major versions. The 5.0.0 changelog says partial APIs were updated for iOS 26 and iOS 27 compatibility, and that enableWideCameras now defaults to true. A changed default is a behavior change you inherit on upgrade, not an opt-in. The 4.7.4 release also changed the license from MIT to Apache-2.0, which is a different set of obligations for anyone who pinned an older version and assumed the earlier terms still applied.

The third is scope. If you want the image editor alone, the README points you elsewhere: it says that if you only want the image edit feature, move to ZLImageEditor, a separate repository. That is a direct statement that this package is not the right unit for editing-only use. Similarly, an app that needs to display a handful of remote images and never touches the system library gains nothing from a component built around album selection, a camera and a cropper.

How ZLPhotoBrowser differs from a bare PhotosUI picker

The obvious alternative on iOS is the system picker exposed through PhotosUI, which hands back selected items and leaves presentation and editing to the system. The difference in approach is where the UI lives. PhotosUI gives you a sheet you do not style; ZLPhotoBrowser gives you a picker you configure, and the README's feature list is largely a list of things you can change: column count, maximum previews and selections, video duration bounds, fonts, per-part colors with dynamic color support for light and dark mode, and custom images.

That configurability is the trade. With the system picker you inherit Apple's behavior and accessibility for free and write almost no code. With ZLPhotoBrowser you get the WeChat-style grid, drag-and-drop preview selection, sliding selection in the library, a selected index display, drag-to-sort of chosen photos, and the bundled editors, but you also own the integration and the upgrade path.

The related searches for this project include Ypimagepicker, Skphotobrowser and Jxphotobrowser, names in the same family of iOS image picker components. The README gives no detail about those projects, so the honest comparison is structural: they occupy the same slot in an app, and the choice comes down to which feature set and which license you can live with. One constraint that is specific to this project: the README states iOS 10.0 as the floor, so a codebase targeting something newer still carries that compatibility surface.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-28, which is recent. The release history shows 5.0.0 on 2026-06-25, 4.7.4 on 2026-01-23 and 4.7.3 on 2025-10-17. That cadence suggests a maintainer who batches changes rather than shipping continuously, and the 5.0.0 entry is a large one: iPad multitasking and custom window sizes, iOS 26 and iOS 27 API updates, a new camera-dismiss parameter, a new landscape attribute, a new pan-to-dismiss property, sticker and doodling rework, and changed album filtering logic.

For upgrade planning, the changelog is the only reliable source, and the CHANGELOG.md file sits at the repository root. The changed album filtering logic is the item most likely to surprise you: if your app depends on which system albums appear, that behavior moved in 5.0.0. The selection-limit fix for video-only configurations and the transparent PNG rendering fix are the kind of bugs you may have worked around locally, in which case those workarounds should be removed on upgrade.

On licensing, the project is Apache-2.0, and the 4.7.4 changelog records the move from MIT. Apache-2.0 includes an explicit patent grant and requires that notices be preserved; MIT is shorter and permissive in a different way. This article is not legal advice. The practical step is to read the LICENSE file at the repository root and confirm which terms apply to the specific version you pin, since the two licenses coexisted across releases.

Editorial conclusion

Use ZLPhotoBrowser if you need a complete picker with editing already assembled, on an iOS 10 or later deployment target, and you accept that the picker is the integration surface. Do not adopt it for a single screen of thumbnails, and do not expect a stable API across the 4.x to 5.0 step. Before committing, open the Wiki usage page for Swift and OC, confirm your Info.plist keys, and decide whether the Apache-2.0 terms fit your distribution.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. longitachi/ZLPhotoBrowser on GitHub
4. README
5. Releases