Skip to content
Get packs

Guide · Open source

How to use IGListKit: install and build data-driven lists

Updated · written with AI from the project's own documentation and checked against our catalogue data

IGListKit is an open-source framework from Instagram engineering that builds UICollectionView-based lists from your data. You supply the data, and it works out what changed so your screens update without manual batch-update or reloadData calls. This guide covers what you need, how to install it, and how the pieces fit together so you can start on a list or feed screen.

IGListKitInstagram/IGListKit · ★ 13.1k · MIT

Quick start

  1. 1Confirm requirements. Check that you have Xcode, Swift 5.1+, and an iOS 11.0+ or tvOS 11.0+ target.
  2. 2Pick a dependency manager. Choose CocoaPods, Carthage, or Swift Package Manager, as listed in the README.
  3. 3Add IGListKit. Add the pod line to your Podfile or the GitHub line to your Cartfile, or add the package URL in Xcode.
  4. 4Run a sample app. Open one of the sample apps in the Examples directory to see the framework in use.
  5. 5Read the Getting Started guide. Follow the official guide on the project homepage to build your first data-driven list.
  6. 6Build your screen. Supply your data to IGListKit and let it compute changes instead of calling reloadData manually.

What IGListKit does and who it is for

IGListKit is a data-driven UICollectionView framework for building fast and flexible lists. It is written in Objective-C and has full Swift interop, so it works in Swift projects too.

The README positions it for iOS developers building list or feed screens with UICollectionView, teams that want a reusable, decoupled diffing approach for their models, and apps that mix several data types in one collection. It assumes familiarity with UICollectionView.

  • Never call performBatchUpdates(_:, completion:) or reloadData() again, according to the README's feature list.
  • Create collections with multiple data types.
  • Customize diffing behavior for your models.
  • Extendable API.

Check the requirements before you install

The README lists Swift 5.1+ and Interoperability with Swift 3.0+. It also lists minimum platform versions: iOS 11.0+, tvOS 11.0+, and macOS 10.13+, where macOS support covers the diffing algorithm components only.

You need Xcode and one of three dependency managers: CocoaPods, Carthage, or Swift Package Manager. The README covers only Apple platforms, so it is not a fit for Android or web projects.

  • Xcode with Swift 5.1+
  • iOS 11.0+ or tvOS 11.0+ targets
  • macOS 10.13+ (diffing algorithm components only)
  • CocoaPods, Carthage, or Swift Package Manager

Install IGListKit with CocoaPods, Carthage or Swift Package Manager

CocoaPods is the README's preferred method. Add the pod line to your Podfile, then install your pods as you normally would.

For Carthage, add the GitHub line to your Cartfile. For Swift Package Manager, the README says to use Xcode: choose File, then Swift Packages, then Add Package Dependency, enter the package URL, and select the latest release. The README links to an Installation Guide for advanced usage.

  • CocoaPods: add the line to your Podfile.
  • Carthage: add the line to your Cartfile.
  • Swift Package Manager: File > Swift Packages > Add Package Dependency, then enter https://github.com/Instagram/IGListKit.
pod 'IGListKit', '~> 5.2.0' github "Instagram/IGListKit" ~> 5.2.0

Try the examples and guides before writing your own screen

The fastest way to see the framework work is to open one of the sample apps in the Examples directory. The README also links an official Getting Started guide, the example projects, and a third-party tutorial from Ray Wenderlich.

The docs are generated with jazzy and hosted on GitHub Pages at the homepage. The README also explains how to regenerate them with ./scripts/build_docs.sh from the repository root.

  • Open a sample app in the Examples directory.
  • Read the Getting Started guide on the project homepage.
  • Browse the API docs at https://instagram.github.io/IGListKit.
./scripts/build_docs.sh

Know when IGListKit is not the right choice

If you need a SwiftUI-only solution, IGListKit may not fit, because the README describes a UICollectionView framework and does not mention SwiftUI. Beginners with no iOS background will also find it hard going, since the README assumes UICollectionView knowledge.

Comparable projects named in this directory include DifferenceKit, IGListDiffKit, and UICollectionViewDiffableDataSource. Compare them against your own requirements before committing.

What people use it for

  • Building a feed or timeline screen in an iOS app with UICollectionView.
  • Showing several data types, such as text, images and headers, in one collection.
  • Customizing how a model's changes are diffed for a list of items.
  • Migrating a UITableView-based list to a collection-based layout, as described in a third-party guide linked from the README.

Frequently asked questions

Is IGListKit free to use?

Yes. The README states that IGListKit is MIT-licensed. The Examples directory uses a separate license noted in each file, and documentation is licensed CC-BY-4.0.

How do I install IGListKit?

The README's preferred method is CocoaPods: add pod 'IGListKit', '~> 5.2.0' to your Podfile. You can also use Carthage with a Cartfile line or Swift Package Manager through Xcode's Add Package Dependency option.

What are the IGListKit requirements?

The README lists Swift 5.1+, iOS 11.0+, tvOS 11.0+, and macOS 10.13+ for the diffing algorithm components only. You also need Xcode and one of CocoaPods, Carthage, or Swift Package Manager.

Does IGListKit work with Swift?

Yes. The README says it is written in Objective-C with full Swift interop support and lists Interoperability with Swift 3.0+.

Can IGListKit be used with SwiftUI?

The README does not mention SwiftUI and describes IGListKit as a UICollectionView framework, so it does not claim SwiftUI support.

What are alternatives to IGListKit?

This directory lists DifferenceKit, IGListDiffKit, and UICollectionViewDiffableDataSource as comparable projects. The README itself does not compare them, so check each against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

IGListKit suits iOS developers who build list or feed screens with UICollectionView and want diffing handled for them, especially with several data types in one collection. Skip it if you need SwiftUI, Android or web support, or if you are new to iOS and UICollectionView.

Install options & downloads