IGListKit
A data-driven UICollectionView framework for building fast and flexible lists.
Top Related Projects
A React-inspired view framework for iOS.
Epoxy is an Android library for building complex screens in a RecyclerView
A paging view with a highly customizable menu ✨
💻 A fast and flexible O(n) difference algorithm framework for Swift collection.
⛔️**DEPRECATED** ⛔️ A drop-in UIViewController subclass with a growing text input view and other useful messaging features
:octocat: 📃 FoldingCell is an expanding content cell with animation made by @Ramotion
Quick Overview
IGListKit is a data-driven UICollectionView framework for building fast and flexible lists. Developed by Instagram, it aims to make it easier to build complex, performant user interfaces with collection views in iOS applications.
Pros
- Improved performance through diffing and batching of updates
- Simplified architecture with a modular, component-based approach
- Built-in support for common UI patterns like empty states and loading indicators
- Strong type safety and compile-time checks
Cons
- Steeper learning curve compared to traditional UICollectionView implementations
- Requires more setup code for simple use cases
- May be overkill for small projects or simple list views
- Limited customization options for some built-in components
Code Examples
- Creating a section controller:
class PersonSectionController: ListSectionController {
var person: Person!
override func sizeForItem(at index: Int) -> CGSize {
return CGSize(width: collectionContext!.containerSize.width, height: 50)
}
override func cellForItem(at index: Int) -> UICollectionViewCell {
let cell: PersonCell = collectionContext!.dequeueReusableCell(for: self, at: index)
cell.configure(with: person)
return cell
}
override func didUpdate(to object: Any) {
person = object as? Person
}
}
- Setting up an adapter:
let adapter = ListAdapter(updater: ListAdapterUpdater(), viewController: self)
adapter.collectionView = collectionView
adapter.dataSource = self
- Implementing the data source:
extension ViewController: ListAdapterDataSource {
func objects(for listAdapter: ListAdapter) -> [ListDiffable] {
return people
}
func listAdapter(_ listAdapter: ListAdapter, sectionControllerFor object: Any) -> ListSectionController {
return PersonSectionController()
}
func emptyView(for listAdapter: ListAdapter) -> UIView? {
return nil
}
}
Getting Started
-
Install IGListKit using CocoaPods:
pod 'IGListKit', '~> 4.0'
-
Import IGListKit in your Swift file:
import IGListKit
-
Create a UICollectionView and set up the adapter:
let layout = UICollectionViewFlowLayout() let collectionView = UICollectionView(frame: .zero, collectionViewLayout: layout) let adapter = ListAdapter(updater: ListAdapterUpdater(), viewController: self) adapter.collectionView = collectionView adapter.dataSource = self
-
Implement the
ListAdapterDataSource
protocol and create section controllers for your data objects.
Competitor Comparisons
A React-inspired view framework for iOS.
Pros of ComponentKit
- More comprehensive UI framework with a declarative approach
- Better suited for complex, highly dynamic UIs
- Offers more fine-grained control over component lifecycle
Cons of ComponentKit
- Steeper learning curve due to its complexity
- Requires more boilerplate code for simple use cases
- Less flexible for integrating with existing UIKit-based code
Code Comparison
ComponentKit:
CKComponentScope scope(self, [Model class]);
Model *model = scope.state();
return [CKComponent newWithView:{
[UIView class],
{CKComponentViewAttribute(@selector(setBackgroundColor:), [UIColor redColor])}
} size:{}];
IGListKit:
func cellForItem(at index: Int) -> UICollectionViewCell {
let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "cell", for: indexPath)
cell.textLabel.text = items[index]
return cell
}
Summary
ComponentKit offers a more comprehensive UI framework with declarative syntax, making it suitable for complex, dynamic UIs. However, it has a steeper learning curve and requires more boilerplate code. IGListKit, on the other hand, is more lightweight and easier to integrate with existing UIKit code, but may not be as powerful for highly complex UI scenarios.
Epoxy is an Android library for building complex screens in a RecyclerView
Pros of Epoxy
- More flexible architecture, supporting both RecyclerView and ViewPager
- Built-in support for view holders and data binding
- Easier integration with existing Android projects
Cons of Epoxy
- Steeper learning curve due to more complex API
- Less optimized for large lists compared to IGListKit
- Limited to Android platform, while IGListKit supports iOS
Code Comparison
IGListKit (Swift):
class MySection: ListSectionController {
override func sizeForItem(at index: Int) -> CGSize {
return CGSize(width: collectionContext!.containerSize.width, height: 44)
}
}
Epoxy (Kotlin):
@EpoxyModelClass(layout = R.layout.my_item)
abstract class MyItemModel : EpoxyModelWithHolder<MyItemHolder>() {
@EpoxyAttribute lateinit var title: String
override fun bind(holder: MyItemHolder) {
holder.titleView.text = title
}
}
Both libraries aim to simplify the creation of complex, dynamic list UIs, but they target different platforms and have distinct approaches. IGListKit focuses on performance and diffing for iOS, while Epoxy offers a more versatile solution for Android with built-in view holder support and data binding capabilities.
A paging view with a highly customizable menu ✨
Pros of Parchment
- Focused specifically on paging and tab-based interfaces, making it simpler for these use cases
- Highly customizable appearance and behavior of page indicators and menu items
- Lightweight and easy to integrate into existing projects
Cons of Parchment
- Limited in scope compared to IGListKit's broader list management capabilities
- Less active community and fewer contributors
- May require more manual setup for complex list scenarios
Code Comparison
Parchment example:
let pagingViewController = PagingViewController()
pagingViewController.dataSource = self
pagingViewController.delegate = self
addChild(pagingViewController)
view.addSubview(pagingViewController.view)
pagingViewController.didMove(toParent: self)
IGListKit example:
let adapter = ListAdapter(updater: ListAdapterUpdater(), viewController: self)
adapter.dataSource = self
adapter.collectionView = collectionView
Summary
Parchment is a specialized library for paging interfaces, offering easy customization for tabs and page indicators. IGListKit, on the other hand, is a more comprehensive solution for managing complex list-based UIs. While Parchment excels in its niche, IGListKit provides broader functionality for various list management scenarios.
💻 A fast and flexible O(n) difference algorithm framework for Swift collection.
Pros of DifferenceKit
- Lightweight and focused solely on diffing algorithms
- Supports both UIKit and AppKit
- Generally faster performance for simple data structures
Cons of DifferenceKit
- Less comprehensive feature set compared to IGListKit
- Smaller community and fewer resources available
- May require more manual implementation for complex UI scenarios
Code Comparison
DifferenceKit:
let changeset = StagedChangeset(source: oldItems, target: newItems)
tableView.reload(using: changeset) { data in
dataSource = data
}
IGListKit:
let diffResult = ListDiff(oldArray: oldItems, newArray: newItems, option: .equality)
adapter.performUpdates(animated: true, completion: nil)
Both libraries aim to simplify the process of updating collection and table views, but IGListKit provides a more comprehensive solution with additional features like section controllers and display delegates. DifferenceKit focuses primarily on efficient diffing algorithms, offering a lighter-weight option for developers who need only this specific functionality.
While IGListKit is backed by Instagram and has a larger community, DifferenceKit may be preferred for projects requiring a simpler, more focused diffing solution or those targeting both UIKit and AppKit platforms.
⛔️**DEPRECATED** ⛔️ A drop-in UIViewController subclass with a growing text input view and other useful messaging features
Pros of SlackTextViewController
- Focused on text input and messaging UI, providing a more specialized solution for chat-like interfaces
- Includes auto-growing text views and customizable input accessories out of the box
- Offers built-in support for @mentions and #channels, which is particularly useful for messaging apps
Cons of SlackTextViewController
- Less flexible for general-purpose list management compared to IGListKit
- May require more customization for non-messaging use cases
- Not as actively maintained, with fewer recent updates compared to IGListKit
Code Comparison
SlackTextViewController:
let textView = SLKTextView()
textView.placeholder = "Enter a message"
textView.placeholderColor = .lightGray
textView.maxNumberOfLines = 4
IGListKit:
let adapter = ListAdapter(updater: ListAdapterUpdater(), viewController: self)
adapter.dataSource = self
adapter.collectionView = collectionView
While SlackTextViewController focuses on text input and messaging-specific features, IGListKit provides a more general-purpose solution for building complex, data-driven lists. SlackTextViewController is ideal for chat applications, whereas IGListKit offers greater flexibility for various types of list-based interfaces. The code examples highlight the different focus areas, with SlackTextViewController centered on text input configuration and IGListKit on list management.
:octocat: 📃 FoldingCell is an expanding content cell with animation made by @Ramotion
Pros of folding-cell
- Focuses on a specific UI component (expandable cells) with visually appealing animations
- Easier to implement for projects requiring only this particular UI element
- Lightweight and less complex compared to IGListKit
Cons of folding-cell
- Limited in scope, only provides expandable cell functionality
- Less versatile for complex list management and performance optimization
- Smaller community and fewer updates compared to IGListKit
Code Comparison
folding-cell:
let cell = FoldingCell()
cell.itemCount = 2
cell.setup(name: "Cell", duration: 0.5, backViewColor: .blue)
cell.selectedAnimation = .unfold
cell.backgroundView = UIView()
IGListKit:
let adapter = ListAdapter(updater: ListAdapterUpdater(), viewController: self)
adapter.collectionView = collectionView
adapter.dataSource = self
adapter.objects = items
Summary
While folding-cell provides a specific and visually appealing UI component for expandable cells, IGListKit offers a more comprehensive solution for managing complex lists and optimizing performance. folding-cell is easier to implement for projects that only require expandable cells, but IGListKit is more versatile and suitable for larger-scale applications with diverse list management needs.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
A data-driven UICollectionView
framework for building fast and flexible lists.
Main Features | |
---|---|
🙅 | Never call performBatchUpdates(_:, completion:) or reloadData() again |
🏠 | Better architecture with reusable cells and components |
🔠 | Create collections with multiple data types |
🔑 | Decoupled diffing algorithm |
✅ | Fully unit tested |
🔍 | Customize your diffing behavior for your models |
📱 | Simply UICollectionView at its core |
🚀 | Extendable API |
🐦 | Written in Objective-C with full Swift interop support |
IGListKit
is built and maintained with ❤️ by Instagram engineering.
We use the open source version main
branch in the Instagram app.
Multilingual translation
Requirements
- Xcode 11.0+
- iOS 11.0+
- tvOS 11.0+
- macOS 10.13+ (diffing algorithm components only)
- Interoperability with Swift 3.0+
Installation
CocoaPods
The preferred installation method is with CocoaPods. Add the following to your Podfile
:
pod 'IGListKit', '~> 5.0.0'
Carthage
For Carthage, add the following to your Cartfile
:
github "Instagram/IGListKit" ~> 5.0.0
Swift Package Manager
To integrate using Xcode:
File -> Swift Packages -> Add Package Dependency
Enter package URL: https://github.com/Instagram/IGListKit, and select the latest release.
For advanced usage, see our Installation Guide.
Getting Started
Try out IGListKit by opening any of the sample apps available in the Examples
directory.
- Our Getting Started guide
- Ray Wenderlich's IGListKit Tutorial: Better UICollectionViews
- Our example projects
- Ryan Nystrom's talk at try! Swift NYC(Note: this talk was for an earlier version. Some APIs have changed.)
- Migrating an UITableView to IGListCollectionView, by Rodrigo Cavalcante
- Keeping data fresh in Buffer for iOS with AsyncDisplayKit, IGListKit & Pusher, Andy Yates, Buffer
Documentation
You can find the docs here. Documentation is generated with jazzy and hosted on GitHub-Pages.
To regenerate docs, run ./scripts/build_docs.sh
from the root directory in the repo.
Vision
For the long-term goals and "vision" of IGListKit
, please read our Vision doc.
Contributing
Please see the CONTRIBUTING file for how to help. At Instagram, we sync the open source version of IGListKit
daily, so we're always testing the latest changes. But that requires all changes be thoroughly tested and follow our style guide.
We have a set of starter tasks that are great for beginners to jump in on and start contributing.
License
IGListKit
is MIT-licensed.
The files in the /Examples/
directory are licensed under a separate license as specified in each file. Documentation is licensed CC-BY-4.0.
Legal
Copyright © Meta Platforms, Inc • Terms of Use • Privacy Policy
Top Related Projects
A React-inspired view framework for iOS.
Epoxy is an Android library for building complex screens in a RecyclerView
A paging view with a highly customizable menu ✨
💻 A fast and flexible O(n) difference algorithm framework for Swift collection.
⛔️**DEPRECATED** ⛔️ A drop-in UIViewController subclass with a growing text input view and other useful messaging features
:octocat: 📃 FoldingCell is an expanding content cell with animation made by @Ramotion
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot