CHTCollectionViewWaterfallLayout: a Pinterest-style UICollectionView layout

The staggered grid UICollectionViewFlowLayout cannot express

UICollectionViewFlowLayout arranges cells in rows whose height is set by the tallest item, so a grid of images with mixed aspect ratios ends up with visible gaps under the shorter cells. CHTCollectionViewWaterfallLayout exists to remove those gaps. It is a subclass of UICollectionViewLayout that places each item into the shortest available column, producing the staggered grid the README describes as inspired by Pinterest. The audience is iOS and tvOS developers building image feeds, card walls, or any collection where items have differing heights and the layout should stay tight. The README states the layout tries to imitate UICollectionViewFlowLayout's usage as much as possible, which matters if you already know that API: the customization surface is a set of layout properties plus an optional delegate, not a new layout language. The requirements are iOS 13+ or tvOS 13+, and either Swift 5.0+ or Objective-C.

How the layout places items and where the delegate fits

The mechanism is column packing. You set columnCount, and the layout assigns each item to the shortest column at the time it is placed, which is what produces the waterfall shape. The itemRenderDirection property controls the order in which items are rendered in subsequent rows: left-to-right, right-to-left, or shortest column first. Spacing is controlled separately for columns and rows through minimumColumnSpacing and minimumInteritemSpacing, and the README notes that different sections can use different column counts, so a single collection view can mix a two-column band with a three-column one. Per-item sizing and per-section metrics come from a delegate rather than from the layout object itself: the delegate supplies item sizes, header and footer heights, section insets, and column counts. In 1.0.0 the Swift implementation added insetsForHeaderIn:, insetsForFooterIn: and minimumColumnSpacingFor: as delegate methods, plus the headerInset, footerInset and minimumContentHeight properties. The README says these have sensible defaults and do not require adoption. One detail worth reading twice: layoutAttributesForElements(in:) returns attributes whose supplementary element kind carries the CHT prefix, so any filtering by representedElementKind has to match that string.

Installing via Swift Package Manager and rendering a two-column feed

Swift Package Manager is the recommended path in the README. Add the package to the dependencies array of your Package.swift, pinned from 1.0.0. Two library products are published: CHTCollectionViewWaterfallLayout for the Swift implementation and CHTCollectionViewWaterfallLayoutObjC for the Objective-C one, so pick the product that matches the language of the code that will import it.

dependencies: [
  .package(url: "https://github.com/chiahsien/CHTCollectionViewWaterfallLayout.git", from: "1.0.0")
]

If you use CocoaPods instead, the README gives the pod name directly, and a subspec for the Objective-C variant. Note the README's own warning that CocoaPods trunk becomes read-only on December 2, 2026 and no new versions will be published after that date, with migration to Swift Package Manager recommended.

pod 'CHTCollectionViewWaterfallLayout'           # Swift (default)
pod 'CHTCollectionViewWaterfallLayout/ObjC'      # Objective-C

For a first real use, configure the layout before handing it to the collection view. The README's example sets a column count of 2, a column spacing of 10, an item spacing of 10, and zero header and footer heights. It also says that although every property has a default, setting at least columnCount is strongly recommended.

let layout = CHTCollectionViewWaterfallLayout()
layout.columnCount = 2
layout.minimumColumnSpacing = 10
layout.minimumInteritemSpacing = 10
layout.headerHeight = 0
layout.footerHeight = 0

After that, implement the delegate to return each item's size. The sizes are what make the waterfall visible: uniform sizes produce a plain grid, and varied heights produce the staggered effect. Both a Swift and an Objective-C demo project live in the Demo/ directory, and the README points there and to the source headers rather than walking through a full view controller.

The 1.0.0 upgrade is the real adoption cost

The README is explicit that v1.0.0 includes a full rewrite of the Swift implementation and lists the breaking changes. The minimum deployment target moved from iOS 9 and tvOS 9 to iOS 13 and tvOS 13, so a project that still supports older systems cannot take this release at all. The swift-tools-version moved from 5.0 to 5.9, and Xcode 15 or newer is required to resolve the package through SPM. Headers and footers are now created with custom element kind strings, CHTCollectionElementKindSectionHeader and CHTCollectionElementKindSectionFooter, where 0.9.x redirected those constants to the UIKit element kinds. Registration calls must be updated. The README adds a caveat that layoutAttributesForSupplementaryView(ofKind:at:) accepts both variants, so layout queries work either way, but layoutAttributesForElements(in:) returns the CHT-prefixed kind, which means filtering code has to match it. layoutAttributesForSupplementaryView(ofKind:at:) also changed to return an optional and now returns nil for unknown element kinds instead of an empty attributes object. The public delegate property became private, and the 0.9.x migration shims are gone, so old selector names such as sizeForItemAtIndexPath:, heightForHeaderInSection:, insetForSectionAtIndex: and columnCountForSection: must be renamed to their replacements. The Objective-C implementation is unchanged. If you are on 0.9.10 and staying there, note that the last push to the repository was on 2026-03-18 and release 1.0.1 followed the same day.

When a compositional layout or a flow layout is the better choice

The honest limitation is that this is a single-purpose layout. It does not do orthogonal scrolling, sticky headers, or per-section layout switching beyond column count, and the README documents no section-level layout composition. If your screen mixes a carousel with a grid, or needs estimated self-sizing cells with a custom arrangement, UICollectionViewCompositionalLayout covers more ground and is maintained by Apple alongside the SDK. The trade-off is verbosity: a compositional layout describes its structure through group and item definitions, while this layout stays close to the flow layout model of properties plus a delegate. UICollectionViewFlowLayout remains the right answer when every cell in a row can share a height; the waterfall only earns its place when item heights differ enough that row-based packing leaves gaps. The README's performance claim is that you should try 10,000+ items and see the smoothness for yourself, which is an invitation to measure on your own data rather than a published benchmark. Treat the layout as a rendering component with no data layer: it computes attributes and nothing else.

Licence, maintenance and what an upgrade actually costs

The project is MIT licensed, which permits use in closed-source applications; the LICENSE file is at the repository root. That is a permissive licence, and nothing documented suggests additional terms. On maintenance: the repository is not archived, and the most recent push was on 2026-03-18, so it has been touched within the last six months. The release history shows a long gap between 0.9.10 in December 2021 and 1.0.0 in March 2026, which is worth knowing if you are deciding how much to depend on future releases. The upgrade cost is concentrated in one event: the 0.9.x to 1.0.0 Swift migration. If you adopt 1.0.0 fresh, that cost does not apply to you, and the additive properties and delegate methods in 1.0.0 need no adoption. If you are on 0.9.x, budget for the deployment target bump, the Xcode 15 requirement, the element kind rename in registrations, the optional return type, and the removed selector shims. Objective-C users skip all of it, since the README states that implementation is unchanged.

Editorial conclusion

Adopt it if you need a staggered grid on iOS 13 or tvOS 13 and want a layout whose API mirrors UICollectionViewFlowLayout, with both Swift and Objective-C products available. Do not adopt it if you are pinned below iOS 13, or if your existing Swift code still references the 0.9.x delegate names and element kind constants. Before upgrading, verify your supplementary view registrations use CHTCollectionElementKindSectionHeader and CHTCollectionElementKindSectionFooter, and check whether any code filters layout attributes by representedElementKind.

Frequently asked questions

Official sources

1. chiahsien/CHTCollectionViewWaterfallLayout on GitHub
2. Issues
3. License: MIT
4. README
5. Releases