SmartRefreshLayout — Intelligent Pull-to-Refresh for Android

Introduction

SmartRefreshLayout is a pull-to-refresh framework for Android that goes beyond the standard SwipeRefreshLayout. It offers a modular header and footer system with over 20 built-in refresh styles, support for both pull-down refresh and pull-up load-more, and works with any scrollable view including RecyclerView, ListView, WebView, and ScrollView.

What SmartRefreshLayout Does

• Wraps any scrollable content view to add pull-down refresh and pull-up load-more behaviors
• Provides over 20 built-in animated header and footer styles out of the box
• Supports nested scrolling for seamless integration with CoordinatorLayout and AppBarLayout
• Handles automatic detection of whether the content view can scroll further
• Enables global default header and footer configuration across the entire application

Architecture Overview

The library uses a kernel-plus-extension architecture. The kernel module handles gesture interception, scroll physics, and the state machine governing idle, pulling, refreshing, and completing states. Header and footer modules are separate artifacts that implement the RefreshHeader or RefreshFooter interface, keeping the core small and letting developers include only the styles they need.

Setup & Configuration

• Add the kernel dependency plus one or more header/footer style artifacts to your Gradle file
• Wrap your scrollable content inside a SmartRefreshLayout in XML or programmatically
• Set a refresh listener with setOnRefreshListener and call finishRefresh when data loading completes
• Configure load-more via setOnLoadMoreListener for infinite scroll pagination patterns
• Set global defaults in Application.onCreate using SmartRefreshLayout.setDefaultRefreshHeaderCreator

Key Features

• Modular design allowing developers to include only needed header and footer styles
• Works with RecyclerView, ListView, ScrollView, WebView, and NestedScrollView
• Supports both vertical and horizontal refresh orientations
• Configurable drag rate, max drag distance, rebound animations, and auto-refresh triggers
• Two-level refresh support for secondary content panels below the main content

Comparison with Similar Tools

• SwipeRefreshLayout — official Jetpack component but limited to a single material spinner style; SmartRefreshLayout offers 20+ headers
• Ultra Pull-to-Refresh — similar concept but no longer actively maintained; SmartRefreshLayout has continued development
• PullToRefresh by Chris Banes — legacy library that predates AndroidX; SmartRefreshLayout supports modern AndroidX layouts
• Lottie + SwipeRefreshLayout — custom animation approach but requires manual implementation; SmartRefreshLayout bundles animated headers natively
• Jetpack Compose pull-refresh — Compose-native modifier; SmartRefreshLayout targets the View system with richer animation options

FAQ

Q: Can I create custom header animations? A: Yes. Implement the RefreshHeader interface and override onMoving to drive your custom animation based on the drag percentage.

Q: Does it work with Jetpack Compose? A: It targets the traditional View system. For Compose projects, use the built-in Compose pull-refresh modifier or wrap SmartRefreshLayout in an AndroidView.

Q: How do I disable load-more? A: Call setEnableLoadMore(false) on the SmartRefreshLayout instance or set it in XML.

Q: Is the library compatible with ViewPager2? A: Yes. It handles nested horizontal scrolling correctly when wrapping ViewPager2 content.

Sources

• https://github.com/scwang90/SmartRefreshLayout
• https://github.com/scwang90/SmartRefreshLayout/blob/main/art/md_property.md