LoadControl

A standard control that can initiate the loading of a scroll view’s contents.

Features

• Footer loading indicator.
• Scroll, pull up to load with paging behavior (and haptic feedback).
• Horizontal loading for collection views.
• Customizable insets, offsets, margins and directions.
• Customizable activity indicator.
• SwiftUI support.

Refresh Control	Load Control

The reversed refresh control

Similar to the behaviors and implementation of the UIRefreshControl:

self.tableView.refreshControl = UIRefreshControl()
self.tableView.refreshControl?.addTarget(self, action: #selector(refresh), for: .valueChanged)

@objc
private func refresh()

The load control is the reversed version of a refresh control, use to load more items from a list of contents. The simplest use-case is adding an action selector to a target with the UIScrollView extension:

import LoadControl

self.tableView.loadControl = LoadControl()
self.tableView.loadControl?.addTarget(self, action: #selector(load), for: .valueChanged)

@objc
private func load()

Swizzling

Be aware that this extension swizzles the setters of .contentOffset and .contentSize on UIScrollView.

Customizable indicator & SwiftUI support

Currently, the LoadControl does not permit customizing the loading animation; instead, it simply displays the default UIActivityIndicatorView. Additionally, a SwiftUI version is missing. Both of these features will be available soon.

Example

This component comes with example app written in Swift. To run the example project, if you use CocoaPods, you can try it by running:

$ pod try LoadControl

Basics

In order to enable infinite load control you have to provide an action handler as target selector using addTarget(_:action:for:). The block you provide is executed each time the load control detects that more data needs to be provided. The handler's function is to do asynchronous tasks, such as networking or database fetch, and update your scroll view or it's subclass.

The block is called from the main queue, so make sure to send any long-running jobs to the background queue. Once you have received fresh data, update the table view by adding new rows and sections, and then use endLoading() to end the animations and reset the state of the control's components. viewDidLoad() is a nice location to add the target selector.

Ensure that any interactions with UIKit or methods supplied by LoadControl occur on the main queue. In Swift, use async(group:qos:flags:execute:) to conduct UI-related calls on DispatchQueue.main. Many people make the mistake of utilizing an external reference to a table or collection view within the action handler. Do not do this since it causes a cyclic retention. Instead, send the instance of scroll view or scroll view subclass as the first parameter to the block.

To access the associated container scroll view of the load control, make a call to the property .scrollView:

if self.loadControl?.scrollView is UITableView

Collection view quirks

UICollectionView's reloadData() resets the .contentOffset value. Instead use performBatchUpdates(_:completion:) if possible.

self.collectionView.loadControl?.endLoading(completion: { scrollView in
    let collectionView = scrollView as? UICollectionView
    
    collectionView?.performBatchUpdates({ () -> Void in
        // Update collection view
    })
})

If you want your collection view to load contents horizontally, set the .direction value to .horizontal:

self.collectionView.loadControl?.direction = .horizontal

Begin loading programmatically

You can utilize the infinite loading flow to load initial data or use beginLoading(_:) to retrieve additional. viewDidLoad() is an excellent spot to load initial data, but the decision is entirely up to you. When thescrollToBottom option is set to true (and it is true by default), the load control will try to scroll down to display the activity indicator view. Keep in mind that scrolling does not occur if the user interacts with the scroll view.

self.tableView.loadControl?.beginLoading(true)

To check if the load control is currently loading or not, access the property .isLoading:

/// Is currently in a middle of a loading event.
print(self.tableView.loadControl?.isLoading)

Prevent infinite scroll

Sometimes you need to stop the infinite loading from continuing. For example, if your search API returns no further results, it makes no sense to continue sending calls or displaying the activity indicator.

/// Change the flag value just before a load more event occurs.
self.tableView.loadControl?.shouldShowActivityIndicator = self.currentPage < 5

/// Or set ``true`` to allow or ``false`` to prevent it from triggering.
self.tableView.loadControl?.shouldShowActivityIndicator = self.viewModel.isEnded

Seamlessly preload content

Perhaps you want your content to flow without ever displaying an activity indicator. LoadControl allows you to provide an offset in points that will be utilized to start the preloader before the user reaches the bottom of the scroll view. A proper balance between the number of results loaded each time and a large enough offset should provide your users with a satisfactory experience. Most likely, you will have to develop your own method for combining those based on the type of content and device size.

/// Preload additional data 200 screen points prior to hitting the bottom of the scroll view.
self.tableView.loadControl?.triggerOffset = 200

Adjust layout attributes

Some layout attributes of the LoadControl is adjustable, including insets, offsets and margins. Try adjusting these settings to find what best meets your demands:

/// Indicator view inset. Essentially `is equal to indicator view height`.
self.tableView.loadControl?.indicatorInset = 50
    
/// `Extra padding` to push indicator view outside view bounds.
/// Used in case `when content size` is `smaller than view bounds`.
self.tableView.loadControl?.extraEndInset = 0
    
/// Flag `used to return user back to start` of scroll view when loading initial content.
self.tableView.loadControl?.scrollToStartWhenFinished = false
    
/// Indicator view margin: `top & bottom for vertical`
/// direction or `left & right for horizontal` direction.
self.tableView.loadControl?.indicatorMargin = 25

Haptic feedback

For example, suppose you have ran out of data and are at the end of the list. LoadControl mimics the UIRefreshControl's auto shrinking and disappearing behaviour. It includes some haptic feedback (UIImpactFeedbackGenerator), similar to that of the refresh control.

This haptic feedback is not activated by default while scrolling across the middle of the list. When you reach the end of the data in the list, enable it by following the below example:

self.viewModel.load(completion: { [weak self] in
    guard let `self` = self else { return }
    
    /// If you've run out of data, enable `haptic feedback`.
    self.tableView.loadControl?.isHapticEnabled = self.viewModel.isEnded
    
    DispatchQueue.main.async {
        self.tableView.reloadData()
        self.tableView.loadControl?.endLoading()
    }
})

I'm still unsure whether I should give it the ability to adjust the intensity of the feedback. Currently, it is the same as the UIRefreshControl, which has the FeedbackStyle set to .medium.

Requirements

• Swift 5.1+
• Xcode 11.0+

Platform	Installation	Status
iOS 13.0+ (UIKit)	CocoaPods, Carthage, Swift Package Manager, Manual	Fully tested
macOS 11.0+ (AppKit)	CocoaPods, Carthage, Swift Package Manager, Manual	Testing

Installation

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 LoadControl as a dependency is as easy as adding it to the dependencies value of your Package.swift or the package list in Xcode.

1. File → Swift Packages → Add Package Dependency.
2. Add https://github.com/verny-tran/LoadControl.git.
3. Select "Branch" with main.

dependencies: [
    .package(url: "https://github.com/verny-tran/LoadControl.git", .upToNextMajor(from: "1.0.0"))
]

Normally you'll want to depend on the LoadControl target:

.product(name: "LoadControl", package: "LoadControl")

CocoaPods

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

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '13.0'
use_frameworks!

target 'App' do
  pod 'LoadControl', '~> 1.0.0'
end

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate LoadControl into your Xcode project using Carthage, specify it in your Cartfile:

github "verny-tran/LoadControl"

Manually

If you prefer not to use any of the aforementioned dependency managers, you can integrate LoadControl into your project manually.

Embedded Framework

1. Open up Terminal, cd into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:

$ git init

2. Add LoadControl as a git submodule by running the following command:

$ git submodule add https://github.com/verny-tran/LoadControl.git

3. Open the new LoadControl folder, and drag the LoadControl.xcodeproj into the Project Navigator of your application's Xcode project.

It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.

4. Select the LoadControl.xcodeproj in the Project Navigator and verify the deployment target matches that of your application target.

5. Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.

6. In the tab bar at the top of that window, open the "General" panel.

7. Click on the + button under the "Embedded Binaries" section.

8. Select the LoadControl.framework for iOS.

You can verify which one you selected by inspecting the build log for your project. The build target for LoadControl will be listed as LoadControlKit.

9. And that's it!

The LoadControl.framework is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.

Inspiration

The features of LoadControl is heavily inspired by, and is a totally Swifted alternative of the component UIScrollView-InfiniteScroll by Andrej Mihajlov (pronebird). Now you don't need the following line in your Bridging-Header.h file anymore.

#import <LoadControl/LoadControl.h>

Authors

• Trần T. Dũng (Verny), [email protected]
• Võ C. Kha (Zach), [email protected]

Contact

Follow and contact me on LinkedIn or Medium. If you find an issue, open a ticket. Pull requests are warmly welcome as well.

License

LoadControl is available under the MIT license. See the LICENSE file for more info.