Awesome Open Source
Awesome Open Source

expandable-collection-view-kit Awesome

Build Platform Platform Language SPM License

Last Update: 04/February/2020.

If you like the project, please give it a star ⭐ It will show the creator your appreciation and help others to discover the repo.

✍️ About

πŸ—‚ Expandable, hierarchical, flexible, declarative UICollectionView with diffable data sources & SwiftUI-like tree items builder [Swift 5.1, iOS & iPadOS 13].

πŸ“Ί Demo

Please wait while the .gif files are loading...

🍱 Features

  • Ease of use
    • Instantiate ExpandableCollectionViewManager class, provide its parent view controller and specify the Folders and Items.
  • Flexible API
    • There are many customization points that can be used to adjust: Folders, Items, Navigation, appeareances and also custom animations.
    • Swift's Function Builders make it very easy to create a tree of interconnected items
  • Autolayout
    • You don't need to do anything related to autolayout - the component properly handles all the changes. The only thing you need to do is to instantiate the ExpandableCollectionViewManager and fill it in with items.
  • Performant
    • The under-the-hood implementation uses Swift's Diffable Data Sources and Collection View Compositional Layout which provides high performance and tested backing APi.
  • Extendable
    • The component can be further extended with new types of items, Function Builder types (such as For Each that applies a group of modifiers to a set of items, rather than copy-pasting the same modifiers or managing boilerplate configuration), decoratable content views for items and the list goes on.

πŸ“š Usage



Create a property that will hold the ExpandableCollectionViewManager reference and the instantiate it via one of the designated initializers:

let expVCManager = ExpandableCollectionViewManager(parentViewController: self)

Here self is the reference to the UIViewController where the property is used.


To pre-fill the collection view, you may use the trailing closure syntax for one of the designated initializers:

let expVCManager = ExpandableCollectionViewManager(parentViewController: self) {
    Folder(title: "ToDo") {
        Item(title: "Compose Email")
            .setImage(systemName: "paperplane")
        Item(title: "Watch Netflix")

    Item(title: "Buy new iPhone")
    Item(title: "Cleanup")


Adding More Items

You can add more items by using appendItems method:

expVCManager.appendItems {
    Folder(title: "Marvel") {
        Item(title: "Spider-Man")
        Item(title: "Iron Man")
        Item(title: "Black Widow")
    Folder(title: "DC") {
        Item(title: "Batman")
        Item(title: "Batgirl")
        Item(title: "Nightwing")

Item Modifiers

There are a number of item modifiers that can be applied to them to change their behaviour or appearance:

expVCManager.appendItems {
    Folder(title: "Marvel") {
        Item(title: "Spider-Man")
            .setImage(systemName: "tray.full.fill") // 1
        Item(title: "Iron Man")
        Item(title: "Black Widow")
    .setTintColor(.systemOrange) // 2
    .isExpanded(true) // 3
    .isItemsCountVisible(true) // 4

    Folder(title: "DC") {
        Item(title: "Batman")
        Item(title: "Batgirl")
        Item(title: "Nightwing")
    .isChevronVisible(false) // 5

Let's break down the API's line by line:

  1. Changes the default image icon for either Item and/or Folder
  2. Changes tint color of a Folder's icon
  3. Determines whether a Folder is automatically expanded
  4. Displays a Folder's item counter label that
  5. Changes the visibility of chevron icon


Actions allow to specify a closure that will be executed on item tap action:

Item(title: "Spider-Man")
    .setImage(systemName: "spider.fill")
    .setAction { [weak self] indexPath, title in
        self?.showWarning("Item \(title) that is at \(indexPath) index path has been tapped.")

Actions have two input parameters an item's index path and title. That should make the API more or less flexible for action handling use cases.


You can specify cells' unfold animation. It's expressed as enum type, where the default is .simple, which is the default diffing animation (hide/show). However, there is a an another option that you to use one of the pre-built animations or implement and inject your own.

expVCManager.unfoldAnimation = .custom(AnimationFactory.moveDown(duration: 0.415)) // 1
expVCManager.unfoldAnimation = .custom(AnimationFactory.verticalUnfold(duration: 0.435)) // 2

Let's break the sample code down. The AnimationFactory is a built-in type that has a number of pre-implemented animations.

  1. The moveDown animation simply moves each unfolded item to the direction of unfolding with the specified duration.
  2. The verticalUnfold animation is a bit more complicated: it applies a series of affine transformations to each unfolded cell.

To define an inject your own animations, you need to use the following typealias that defines the required closure's signature for the .custom unfold animation type:

let delayFactor = 0.015

let slideOutAnimation: ExpandableItem.Animation = { cell, indexPath, collectionView, completion in
        withDuration: duration,
        delay: delayFactor * Double(indexPath.row),
        options: [.curveEaseInOut],
        animations: {
         cell.transform = CGAffineTransform(translationX: collectionView.bounds.width, y: 0)
    }, completion: completion)

expVCManager.unfoldAnimation = .custom(slideOutAnimation)

Here we used the ExpandalbeItem.Animation typealias to get the right closure’s signature and then we implemented our custom cell animation. The final step is that we injected it via the .custom(slideOutAnimation) type.

Transition Handling

The component also supports custom handler for view controller transitioning. It can be specified via the following property:

expVCManager.onCellTapHandler = { _, destinationViewController in
    // 1. Prepare presentation part of the destination view controller
    let navController = UINavigationController(rootViewController: destinationViewController)
    // 2. Present the view controller
    self.present(navController, animated: true)

That makes different kinds of view controller navigation logic to work on a per-item basis. Which means for one view controller bound item we can use UINavigationController to present its view controller, wheres for some other item we can use modal view controller presentation style.

View Controller Configuration

There is yet an another modifier for Item type that allows to specify a UIViewController type:

Item(title: "Spider-Man")
    .setImage(systemName: "spider.fill")
    .setViewControllerType(IssuesViewController.self) { [weak self] viewController in
    viewController.comics = self?.endpoint(\.latest.spiderman.comics)

Here we specified the target view controller type that needs to be transitioned when the Spider-Man cell is tapped and its configuration code, where we, for example can inject data, perform any other operation or simply omit.

πŸ— Installation

Swift Package Manager

Xcode 11+

  1. Open MenuBar β†’ File β†’ Swift Packages β†’ Add Package Dependency...
  2. Paste the package repository url and hit Next.
  3. Select the installment rules.

After specifying which version do you want to install, the package will be downloaded and attached to your project.


If you already have a Package.swift or you are building your own package simply add a new dependency:

dependencies: [
    .package(url: "", from: "1.0.0")


You can always use copy-paste the sources method πŸ˜„. Or you can compile the framework and include it with your project.

πŸ™‹β€β™€οΈπŸ™‹β€β™‚οΈ Contributing

Your contributions are always appreciated. There are many ways how you help with the project:

  • You can suggest something
  • You can write additional documentation or sample codes
  • Implement a new feature
  • Fix a bug
  • Help to maintain by answering to the questions (if any) that other folks have
  • etc.

Overall guidelies are:

  • Please, discuss a feature or a major source change/addition before spending time and creating a pool requested via issues.
  • Create a separate branch and make sure that your code compiles and does not produce errors and warnings.
  • Please, don't be upset if it takes a while to review your code or receive an answer.

πŸ‘¨β€πŸ’» Author

Astemir Eleev

πŸ”– Licence

The project is available under MIT Licence

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
swift (7,441)Β 
ios (3,432)Β 
framework (1,048)Β 
package (255)Β 
swift-package-manager (114)Β 
uicollectionview (88)Β 
spm (35)Β 
kit (32)Β 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising πŸ“¦Β 10
All Projects
Application Programming Interfaces πŸ“¦Β 124
Applications πŸ“¦Β 192
Artificial Intelligence πŸ“¦Β 78
Blockchain πŸ“¦Β 73
Build Tools πŸ“¦Β 113
Cloud Computing πŸ“¦Β 80
Code Quality πŸ“¦Β 28
Collaboration πŸ“¦Β 32
Command Line Interface πŸ“¦Β 49
Community πŸ“¦Β 83
Companies πŸ“¦Β 60
Compilers πŸ“¦Β 63
Computer Science πŸ“¦Β 80
Configuration Management πŸ“¦Β 42
Content Management πŸ“¦Β 175
Control Flow πŸ“¦Β 213
Data Formats πŸ“¦Β 78
Data Processing πŸ“¦Β 276
Data Storage πŸ“¦Β 135
Economics πŸ“¦Β 64
Frameworks πŸ“¦Β 215
Games πŸ“¦Β 129
Graphics πŸ“¦Β 110
Hardware πŸ“¦Β 152
Integrated Development Environments πŸ“¦Β 49
Learning Resources πŸ“¦Β 166
Legal πŸ“¦Β 29
Libraries πŸ“¦Β 129
Lists Of Projects πŸ“¦Β 22
Machine Learning πŸ“¦Β 347
Mapping πŸ“¦Β 64
Marketing πŸ“¦Β 15
Mathematics πŸ“¦Β 55
Media πŸ“¦Β 239
Messaging πŸ“¦Β 98
Networking πŸ“¦Β 315
Operating Systems πŸ“¦Β 89
Operations πŸ“¦Β 121
Package Managers πŸ“¦Β 55
Programming Languages πŸ“¦Β 245
Runtime Environments πŸ“¦Β 100
Science πŸ“¦Β 42
Security πŸ“¦Β 396
Social Media πŸ“¦Β 27
Software Architecture πŸ“¦Β 72
Software Development πŸ“¦Β 72
Software Performance πŸ“¦Β 58
Software Quality πŸ“¦Β 133
Text Editors πŸ“¦Β 49
Text Processing πŸ“¦Β 136
User Interface πŸ“¦Β 330
User Interface Components πŸ“¦Β 514
Version Control πŸ“¦Β 30
Virtualization πŸ“¦Β 71
Web Browsers πŸ“¦Β 42
Web Servers πŸ“¦Β 26
Web User Interface πŸ“¦Β 210