IGListKit: a data-driven UICollectionView framework for iOS lists

The problem IGListKit solves in a mixed-type feed

A plain UICollectionView wants you to answer three questions yourself: how many sections, how many items per section, and which cell for each index path. That works while every row looks the same. Once a feed mixes a photo post, a suggested account, a header, and an ad, the data source turns into a pile of index arithmetic, and every insert or delete has to be translated into a matching set of index paths for performBatchUpdates(_:, completion:). Get one index wrong and the collection view raises an inconsistency exception.

IGListKit's premise is that the list should be derived from your data, not maintained alongside it. The README states the framework's first selling point plainly: you never call performBatchUpdates(_:, completion:) or reloadData() again. Instead you hand the framework an array of model objects and a way to map each object to a section controller, and it computes the update for you. The README also lists creating collections with multiple data types as a main feature, which is the same problem stated from the other direction.

The intended audience is iOS and tvOS engineers working on feeds, search results, settings screens with heterogeneous rows, or any screen where the content set changes at runtime. The requirements section lists Swift 5.1+, iOS 11.0+, and tvOS 11.0+, with macOS 10.13+ for the diffing algorithm components only. That last qualifier matters: the framework is not a cross-platform list library, it is a UIKit one with a separable diffing core.

How the diffing and section controller model fits together

The repository layout exposes the architecture before you read a line of code. There are three podspecs at the top level: IGListKit.podspec, IGListDiffKit.podspec, and IGListSwiftKit.podspec. The diffing algorithm is packaged separately from the collection view integration, which is what the README means by a decoupled diffing algorithm and by macOS support for the diffing components only. If you want the update computation without the UIKit layer, IGListDiffKit is the piece to look at.

The data flow the README describes is model-first. You supply objects that conform to the framework's model protocol, and a section controller per object type. The section controller owns the cells for its section and reports how many items it has and what each cell should be. When your array of models changes, the framework diffs the old set against the new one and applies the resulting updates to the underlying UICollectionView. That is why the README calls the list data-driven and why it advertises reusable cells and components as an architectural benefit rather than a performance trick.

The README also says diffing behavior is customizable for your models. That is the escape hatch for the common failure mode of identity diffing: two objects that are structurally identical but represent different logical rows. If your models do not carry a stable identity, the default comparison will treat them as interchangeable and you will see cells reused where you expected a replacement. The framework gives you a way to define that identity, but it does not infer one for you.

Installing IGListKit and rendering a first section

The README names CocoaPods as the preferred installation method. Add the pod to your Podfile with the version constraint shown in the README, then run the install command.

pod 'IGListKit', '~> 5.2.0'

After `pod install`, open the generated workspace rather than the project file, which is standard CocoaPods behaviour. Carthage users get an equivalent line in the Cartfile, and Swift Package Manager users add the package by URL through Xcode's File -> Swift Packages -> Add Package Dependency flow, entering https://github.com/Instagram/IGListKit and selecting the latest release. The README points to an Installation Guide on the project's documentation site for advanced usage.

The fastest way to see the framework running is not to write a screen from scratch. The README says to try IGListKit by opening any of the sample apps in the Examples directory, and the repository confirms three: Examples/Examples-iOS/, Examples/Examples-macOS/, and Examples/Examples-tvOS/. Open Examples/Examples-iOS/ in Xcode and run it before you integrate anything into your own target. You will see a collection view whose sections are driven by section controllers rather than a single data source object.

Docs are generated with jazzy and hosted on GitHub Pages. The README gives the regeneration command, which is useful if you want the API reference for the exact commit you are pinned to rather than the published site.

./scripts/build_docs.sh

Run that from the repository root. It writes into the docs directory that the repository already contains.

Where IGListKit is the wrong tool

The framework assumes your list is dynamic. If your screen shows a fixed set of rows that never reorder, never insert, and never delete during the view controller's lifetime, the diffing engine has nothing to compute and you are paying for a section controller abstraction you do not need. A static settings screen with a hand-written data source is less code, not more.

The second boundary is platform. The requirements list macOS 10.13+ for the diffing algorithm components only, which means you cannot build a macOS collection view on IGListKit. If your product ships an AppKit list, look at the diffing component alone or elsewhere.

The third is language posture. The README says the framework is written in Objective-C with full Swift interop support, and the repository carries both an IGListKit.podspec and an IGListSwiftKit.podspec. Interop is not the same as idiomatic. A team that has standardized on Swift-only dependencies will be adding an Objective-C module and its headers to their build, and the README does not claim the API surface has been redesigned for Swift.

Finally, there is a maintenance question the README does not answer. The last push to the repository was on 2026-08-19, and the most recent release is 5.2.0 from 2026-02-17. The README states that Instagram syncs the open source version daily and uses the main branch in the Instagram app, which is a strong signal about internal use but not a published support commitment. There is no stated deprecation policy, and the README does not document a rollback path if an upgrade breaks your build.

IGListKit versus a plain UICollectionView data source

The real alternative is not another library. It is the UICollectionViewDataSource you already have, plus UICollectionViewDiffableDataSource if you are on a recent enough deployment target.

The difference in approach is where identity lives. With a hand-written data source, you own the array, you own the index paths, and you own the batch update. With IGListKit, you own the model objects and their identity, and the framework owns the index paths. That trade is favourable exactly when the update logic is the part that keeps breaking. It is unfavourable when the model objects are trivial and the update logic is three lines.

IGListKit's section controller abstraction is the other half of the difference. A section controller is a per-section object with its own lifecycle, which lets you keep the cell configuration for a photo post separate from the cell configuration for a suggested account. A single data source with a switch statement over item types achieves the same visual result, but the state for each section stays in the view controller. The README frames this as better architecture with reusable cells and components, and for a feed with a dozen section types that framing holds up.

The cost is indirection. To render one row you now touch a model, a section controller, and a cell, and debugging a missing row means checking which of the three dropped it. Teams that have been burned by over-abstracted list layers should weigh that before adopting.

Licence, upgrade cost and what the repository actually ships

IGListKit is MIT-licensed, and the README links to LICENSE.md at the repository root. MIT is permissive, so the usual obligations apply: keep the copyright notice and the licence text with your distribution. The README adds two carve-outs worth reading carefully. Files under the Examples directory are licensed under a separate licence as specified in each file, and the documentation is licensed CC-BY-4.0. If you copy sample code out of Examples into your app, you are not necessarily under MIT anymore. That is a factual distinction in the repository, not legal advice; your counsel should read LICENSE.md and the per-file headers.

Upgrade cost is visible in the release history. The jump from 5.0.0 in May 2024 to 5.1.0 in October 2025 to 5.2.0 in February 2026 is a minor-version cadence, and the README's installation snippets pin to the 5.2.0 line with a tilde constraint, which allows patch updates within 5.2. The repository ships a CHANGELOG.md at the top level, so the diff between releases is documented rather than implied. It also ships a Package.swift and an spm directory, so Swift Package Manager consumers get a manifest rather than a wrapper.

Two repository files hint at the contribution bar. There is a Dangerfile and a .swiftlint.yml at the root, and the README says changes must be thoroughly tested and follow the project's style guide. If you plan to carry a local fork, expect to satisfy those checks. The README also notes that the open source version is synced daily from Instagram's internal copy, which means upstream changes can arrive faster than a fork's patch set can be rebased.

Editorial conclusion

Adopt IGListKit if you maintain an iOS or tvOS collection view whose sections mix cell types and you are tired of computing index paths by hand; the CocoaPods line pod 'IGListKit', '~> 5.2.0' is the documented entry point. Skip it if your list is a single fixed cell type, if you need macOS collection views (only the diffing components are documented for macOS 10.13+), or if you cannot accept Objective-C headers in a Swift-only codebase. Before committing, check that your deployment target is iOS 11.0+ or tvOS 11.0+, confirm the MIT licence text in LICENSE.md against your distribution model, and read the Examples directory in the repository to see how a section controller is actually wired.

Frequently asked questions

Official sources

1. Instagram/IGListKit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases