Swiftpack.co -  GuillemEspejo/StatefulCollections as Swift Package
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
Simple stateful UITableView and UICollectionView for iOS
.package(url: "https://github.com/GuillemEspejo/StatefulCollections.git", from: "1.0.2")

Simple stateful collection views for iOS in Swift.

Swift Version Build Status License Cocoapods Compatible Platform PRs Welcome

StatefulCollections is a small and lightweight Swift framework that allows to create UITableviews and UICollectionViews that support empty, loading and error states as easy as possible.

It can be partially customized to allow greater flexibility while keeping things simple. It has a nice balance between view customization and ease of use.


  • ☑ Simple to use
  • ☑ Customizable
  • ☑ Supports empty, loading and error states


  • iOS 13.0+
  • Xcode 11.3



CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate StatefulCollections into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'StatefulCollections'

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding StatefulCollections as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/GuillemEspejo/StatefulCollections.git", .upToNextMajor(from: "1.0.2"))

Basic Usage

Import StatefulCollections module wherever you have a reference to a UITableView or UICollectionView that will be used as stateful. Set your collection style view classes to its matching subclass, StatefulTableView or StatefulCollectionView

import StatefulCollections
// Other imports ...

class ViewController: UIViewController {

    @IBOutlet weak var tableview: StatefulTableView!
    @IBOutlet weak var collectionview: StatefulCollectionView!

// ...


Set the class and the import module in storyboard if needed.

When you want to set the state of the view, set it using setStateTo:

tableview.setState(to: .loading)
collectionview.setState(to: .empty)

Both views support four different states:

State View Image Text Use
.normal Standard view appearance. N/A N/A Used as default state, when there is content to show.
.loading Removes cell separator, shows activity indicator and the default text. N/A 'Loading...' Used when loading or processing data (Core Data, networking, file parsing, etc).
.emtpy Removes cell separator, shows SF Image and the default text. 'text.badge.xmark' 'No results' Used when there are no results to show.
.error Removes cell separator, shows SF Image and the default text. 'xmark.octagon' 'There was an unknown error' Used when the process of obtaining data for the collection has failed (I/O errors, networking,etc).


StatefulCollections allow a certain degree of customization but tries to keep things as simple as possible.

Although you can't add or remove the basic view components of each state, the ones shown can be customized. Images, labels and separator styles can be freely modified.

For example:

tableview.setState(to: .error)

will give your tableview the following appearance:

However, you can set the image and the text to another values:

let errorImage = UIImage(systemName: "clear")
tableview.setImage(to: errorImage, forState: .error)
tableview.setText(to: "Network error", forState: .error)

// ...

tableview.setState(to: .error)

Besides setting custom images and text, you can also set custom tints and colors. The colors are applied to the views itself and are not dependant on the state.

tableview.setImageTint(to: .red)
tableview.setTextColor(to: .blue)

Reset states and colors

If you want to reset any state appearance to its original settings, just use resetState or resetAllStates:

tableview.setText(to: "Server error", forState: .error)
tableview.setText(to: "Loading data from disk...", forState: .loading)
tableview.setText(to: "There were no results for your query", forState: .empty)

// ...

tableview.reset(state: .error) // Only error state will be reset

// ...
tableview.resetAllStates() // Every state will be reset to default values

Due to the colors being independent of the state, when you need custom colors for a single one, you must set them every time you set that state, and reset them when another one is shown.

tableview.setImageTint(to: .red)
tableview.setTextColor(to: .yellow)
tableview.setState(to: .error)

// ...

tableview.setState(to: .empty)


If you want to contribute to StatefulCollections, check the LICENSE file for more info.


Guillem Espejo – g.espejogarcia@gmail.com

Distributed under the MIT license. See LICENSE for more information.



Stars: 1
Last commit: 2 weeks ago

Ad: Job Offers

iOS Software Engineer @ Perry Street Software
Perry Street Software is Jack’d and SCRUFF. We are two of the world’s largest gay, bi, trans and queer social dating apps on iOS and Android. Our brands reach more than 20 million members worldwide so members can connect, meet and express themselves on a platform that prioritizes privacy and security. We invest heavily into SwiftUI and using Swift Packages to modularize the codebase.

Release Notes

1 year ago

Added full version of code after refactoring. Added example project to repository.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API