/ReactiveLists

React-like API for UITableView & UICollectionView

Primary LanguageSwiftMIT LicenseMIT

React-like API for UITableView & UICollectionView

Build Status Version Status license MIT codecov Platform

ReactiveLists provides a React-like API for UITableView and UICollectionView that makes it easy to write stateless code that generates user interfaces.

In our experience this can make UI code significantly easier to read and maintain. Instead of spreading the definition of your content over various data source methods, you can define the content concisely. The table or collection content and layout are immediately obvious by scanning over the source code.

You can read more about the origins of this library in our announcement blog post.

Features

  • React-like declarative API for UITableView and UICollectionView
  • Automatic UI updates, whenever your models change

Example

// Given a view controller with a table view

// 1. create cell models
let cell0 = ExampleTableCellModel(...)
let cell1 = ExampleTableCellModel(...)
let cell2 = ExampleTableCellModel(...)

// 2. create section models
let section0 = ExampleTableSectionViewModel(cellViewModels: [cell0, cell1, cell2])

// 3. create table model
let tableModel = TableViewModel(sectionModels: [section0])

// 4. create driver
self.driver = TableViewDriver(tableView: self.tableView, tableViewModel: tableModel)

// 5. update driver with new table model as it changes
let updatedTableModel = self.doSomethingToChangeModels()
self.driver.tableViewModel = updatedTableModel

// self.tableView will update automatically

Project Status

An early version of the UITableView support has been shipping in the PlanGrid app since late 2015 and is now used accross wide parts of the app. The support for UICollectionView is less mature as we only use UICollectionView in very few places.

Feature Status
UITableView support ✅
UICollectionView support ⚠️ Experimental

Vision

For long-term goals and direction, please see VISION.md.

Getting Started

Read our Getting Started Guide to learn how to use ReactiveLists.

Documentation

Read our documentation here. Generated with jazzy. Hosted by GitHub Pages.

Generating docs

$ ./scripts/gen_docs.sh

Requirements

  • Xcode 10.2+
  • Swift 4.2 or 5.0
  • iOS 11+

Installation

CocoaPods (recommended)

use_frameworks!

# For latest release in CocoaPods
pod 'ReactiveLists'

# Latest on master branch
pod 'ReactiveLists', :git => 'https://github.com/plangrid/ReactiveLists.git', :branch => 'master'

Swift Package Manager

Select Xcode menu File > Swift Packages > Add Package Dependency... and enter repository URL with GUI.

Repository: https://github.com/plangrid/ReactiveLists

Contribute

Please read and follow our Contributing Guide and our Code of Conduct.

License

ReactiveLists is released under an MIT License. See LICENSE for details.

Copyright © 2018-present PlanGrid, Inc.