Skip to content
Get packs

Guide · Open source

How to use MJRefresh: install and add pull-to-refresh in iOS

Updated · written with AI from the project's own documentation and checked against our catalogue data

MJRefresh is an open-source Objective-C library for iOS apps that adds 'pull down to refresh' and 'load more' controls to scrolling screens such as table views, collection views and web views. This guide shows how to install it and attach a refresh control to a scroll view, based on the project's README. After reading it, you will know which install methods the README covers, which control classes exist, and where the library fits and does not fit.

MJRefreshCoderMJLee/MJRefresh · ★ 13.8k · MIT

Quick start

  1. 1Install the library. Add pod 'MJRefresh' to your Podfile, or add github "CoderMJLee/MJRefresh" to your Cartfile, or use Swift Package Manager.
  2. 2Import the header. Import MJRefresh in the file that owns your scroll view. If you installed manually, import MJRefresh.h.
  3. 3Create a header. Use MJRefreshNormalHeader with a closure or a target and action to create a pull-to-refresh control.
  4. 4Load your data. Inside the refreshing block, fetch or reload your data for the table or collection view.
  5. 5Link the control to the scroll view. Call link(to:) with your table, collection or web view so the control is attached.
  6. 6End the refresh. Call endRefreshing once the new data is ready so the control returns to its normal state.
  7. 7Set language if needed. Set MJRefreshConfig.default.language or the i18n file and bundle if your app needs localized refresh text.

What MJRefresh does and who it is for

MJRefresh is meant for developers who need standard loading gestures and animations without building them from scratch. The README says it works with UIScrollView, UITableView, UICollectionView and WKWebView.

It suits iOS developers who need standard pull-to-refresh behavior, teams maintaining Objective-C iOS apps, and developers who want to customize refresh animations or text. It is not a fit for SwiftUI-only projects, since the README focuses on UIKit scroll views and does not mention SwiftUI, and it is not for Android or web projects.

  • Supported controls: UIScrollView, UITableView, UICollectionView, WKWebView
  • Header types: MJRefreshNormalHeader, MJRefreshGifHeader
  • Footer types: MJRefreshAutoNormalFooter, MJRefreshAutoGifFooter, MJRefreshBackNormalFooter, MJRefreshBackGifFooter

Install MJRefresh with CocoaPods, Carthage or Swift Package Manager

You need Xcode and one of the supported dependency managers. The README lists CocoaPods, Carthage and Swift Package Manager. The README badges mark SPM and Carthage as supported, and the SPM support was released from version 3.7.1.

For CocoaPods, add the pod to your Podfile and run the install from your project folder. For Carthage, add the GitHub entry to your Cartfile.

  • CocoaPods: add pod 'MJRefresh' to your Podfile
  • Carthage: add github "CoderMJLee/MJRefresh" to your Cartfile
  • Swift Package Manager: supported according to the README badges
pod 'MJRefresh' github "CoderMJLee/MJRefresh"

Add MJRefresh manually without a package manager

If you do not use a package manager, the README describes copying the library files into your project. Drag all files in the MJRefresh folder into your project, then import the main header file.

The README lists the files included in the library, including the MJRefresh.bundle resource and the extension files for UIScrollView and UIView.

  • Drag all files in the MJRefresh folder into your project
  • Import the main file in your code
#import "MJRefresh.h"

Attach a pull-to-refresh header to a table or collection view

Refresh controls are created with a class method that takes a refreshing block or a target and action. The base class MJRefreshComponent provides beginRefreshing, endRefreshing and isRefreshing methods to control the state. The header class MJRefreshHeader also exposes lastUpdatedTimeKey and lastUpdatedTime for the last successful drop-down refresh.

The README's Swift chaining example creates a MJRefreshNormalHeader with a closure, sets automaticallyChangeTransparency-style options, and links it to a table view. Load your data inside the closure, then call endRefreshing when the data arrives.

  • Use headerWithRefreshingBlock: or headerWithRefreshingTarget:refreshingAction: to create a header
  • Call beginRefreshing to start refreshing and endRefreshing to stop
  • Use isRefreshing to check the current state
MJRefreshNormalHeader { [weak self] in // load some data }.autoChangeTransparency(true) .link(to: tableView)

Customize refresh text and localization

The README describes dynamic language switching. Set MJRefreshConfig.default.language to change the language, and set i18nFilename or i18nBundle to point to your own strings. Components rerender automatically when the language setting changes.

To customize a DIY component, override i18nDidChange, reset your texts, and call super afterwards so the layout is updated. The README also says you can receive the MJRefreshDidChangeLanguageNotification notification instead.

  • Language: MJRefreshConfig.default.language
  • File name: MJRefreshConfig.default.i18nFilename (without the .strings extension)
  • Bundle: MJRefreshConfig.default.i18nBundle
MJRefreshConfig.default.language = "zh-hans"

Build a custom refresh control

The README says the classes marked as usable can be used directly, while the other classes in the chart are meant for inheritance. To make your own control, subclass the base header, footer or component class and override the relevant methods.

The README's examples section lists 6 drop-down refresh examples, 10 pull-to-refresh examples and UICollectionView and WKWebView examples. Use those as reference when you need custom behavior.

  • Subclass MJRefreshComponent, MJRefreshHeader or MJRefreshFooter for custom controls
  • Check the README examples list for the drop-down, pull-to-refresh, UICollectionView and WKWebView cases

What people use it for

  • Adding pull-to-refresh to a UITableView that loads a feed from a server
  • Adding a load-more footer at the bottom of a UICollectionView
  • Adding a refresh header to a WKWebView
  • Customizing refresh text for several languages in an Objective-C iOS app
  • Creating a custom refresh control by subclassing the base component classes

Frequently asked questions

Is MJRefresh free to use?

MJRefresh is released under the MIT licence, according to the project metadata. The MIT licence allows use, copying and modification under its terms, so check the licence text before using it in your product.

How do I install MJRefresh?

The README lists three package-manager options: CocoaPods with pod 'MJRefresh', Carthage with github "CoderMJLee/MJRefresh", and Swift Package Manager. You can also copy the files from the MJRefresh folder into your project manually.

Does MJRefresh work with SwiftUI?

The README does not mention SwiftUI and focuses on UIKit scroll views. If your project is SwiftUI-only, this library is not described as a fit for it.

What do I need before using MJRefresh?

The README lists Xcode plus one of CocoaPods, Carthage or Swift Package Manager. The library is for iOS apps, and the setup and customization assume familiarity with Xcode and UIKit.

Can MJRefresh show localized refresh text?

Yes. The README describes dynamic i18n switching through MJRefreshConfig.default.language, plus settings for an i18n file name and bundle.

What are the alternatives to MJRefresh?

Projects comparable to MJRefresh are SVPullToRefresh, DZNEmptyDataSet, PullToRefresh and UIRefreshControl. Apple's UIRefreshControl is the built-in option for basic refresh in UIKit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MJRefresh is a good choice for iOS developers who use UIKit table, collection or web views and want standard pull-to-refresh and load-more controls with customizable text and animations. If your project is SwiftUI-only, targets Android or web, or your team has no iOS or Xcode experience, pick another option such as Apple's UIRefreshControl or a SwiftUI-native approach.

Install options & downloads