To add WebView pull to refresh, wrap your WebView in AndroidX SwipeRefreshLayout, call webView.reload() in its refresh listener, and call setRefreshing(false) when the page finishes loading. That takes about ten lines. The part most tutorials skip is stopping the gesture from firing while someone scrolls up inside your page.
Why a WebView app has no pull to refresh by default
A WebView shows web pages, but it doesn’t bring Chrome’s browser controls with it. The pull gesture people expect comes from the browser. Chrome’s overscroll-behavior article describes “Chrome Android’s native pull-to-refresh action” and says it “refreshes the entire page.”
Package a site as an app and users swipe down at the top of a page to no effect. You add the gesture in the Android layer.
What you need before you start
The standard tool for WebView pull to refresh is SwipeRefreshLayout, from AndroidX. Its API reference says it “should be used whenever the user can refresh the contents of a view via a vertical swipe gesture.”
You need a WebView that already loads your site, the AndroidX SwipeRefreshLayout dependency, and a WebViewClient on the WebView so you know when a page finishes.
The official setup guide still shows 1.2.0-alpha01 in its dependency line. The release notes list 1.2.0 as the stable release, from December 3, 2025. Use the stable one:
implementation("androidx.swiperefreshlayout:swiperefreshlayout:1.2.0")
How to add WebView pull to refresh, step by step
Adding the gesture takes three steps: wrap, listen, stop the spinner. Here’s the version I use in Kotlin.
- Wrap the WebView in the layout. SwipeRefreshLayout “can only support one direct child,” so the WebView must be its only child.
<androidx.swiperefreshlayout.widget.SwipeRefreshLayout
android:id="@+id/swipe"
android:layout_width="match_parent"
android:layout_height="match_parent">
<WebView
android:id="@+id/webview"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</androidx.swiperefreshlayout.widget.SwipeRefreshLayout>
- Reload on swipe. Android’s refresh guide says “the onRefresh() method is invoked when the user performs a swipe gesture.” For a WebView, the update is a reload.
val swipe = findViewById<SwipeRefreshLayout>(R.id.swipe)
val webView = findViewById<WebView>(R.id.webview)
swipe.setOnRefreshListener { webView.reload() }
- Stop the spinner when the page is done. The same guide says: “When the update finishes, call setRefreshing(false) to remove the refresh progress indicator.” A WebView tells you it finished in
onPageFinished.
webView.webViewClient = object : WebViewClient() {
override fun onPageFinished(view: WebView, url: String?) {
swipe.isRefreshing = false
}
}
Forget step 3 and the spinner keeps turning after the page has loaded. That’s the most common complaint on forums about this setup.
How to check that it works
Testing pull to refresh takes two minutes on a real phone or emulator.
- Pull down at the very top of a page. The spinner should appear, the page should reload, and the spinner should go away.
- Scroll halfway down, then back up slowly. The page should scroll without refreshing.
- Open a page with a scrollable menu, chat box or table and scroll up inside it. Again, no refresh.
Most setups fail the second and third checks.
Fix pull to refresh firing while scrolling up
A refresh that fires while the user scrolls up happens because SwipeRefreshLayout asks its child whether it can still scroll up. A WebView answers for the whole document. If your site scrolls inside a div (common with app-like layouts, chat widgets and fixed headers), the document sits at the top and the layout grabs the gesture.
The API reference gives you the hook: setOnChildScrollUpCallback will “Set a callback to override canChildScrollUp() method.” The simplest rule allows a refresh only when the WebView itself sits at the top:
swipe.setOnChildScrollUpCallback { _, _ -> webView.scrollY > 0 }
That rule breaks when the page scrolls inside an inner container, because the WebView’s own scroll position stays at zero. Have the page report it instead: add a small JavaScript interface, send the container’s scroll position from a scroll listener, and return that from the callback. It’s the only fix I’ve seen hold up on single-page sites.
Add a refresh menu item for accessibility
A swipe gesture alone isn’t enough, because some users can’t make it. The reference is direct: “The SwipeRefreshLayout does not provide accessibility events; instead, a menu item must be provided to allow refresh of the content wherever this gesture is used.”
The setup guide recommends a menu item with android:showAsAction=never. It explains that “users with accessibility needs can trigger action bar actions using external devices, such as keyboards and D-pads.” When that item is tapped, set isRefreshing = true and call the same reload().
Apps built with my own tool, WebToAPK Free, have a top bar with a refresh icon, added in the October 2026 runtime redesign. The builder has no setting for a pull gesture, so if you need swipe-down, you edit the Android code as shown above.
Styling the spinner and the trigger distance
You can match the spinner to your brand with setColorSchemeResources, which sets “the color resources used in the progress animation.” Skip setColorScheme, which the reference marks deprecated.
If refreshes fire too easily, setDistanceToTriggerSync sets how far the user has to pull, measured in dips. A slightly longer pull cuts down accidental reloads on pages with forms.
Should you use SwipeRefreshLayout or Compose?
SwipeRefreshLayout still works, but it’s in maintenance mode. The release notes say it “will only receive critical fixes; new features are not planned,” and recommend Jetpack Compose.
If your app is already built with Compose, use PullToRefreshBox. It “acts as a container for your scrollable content” and needs isRefreshing and onRefresh parameters. Hosting a WebView inside Compose adds its own wiring, though.
My take: for a classic View-based WebView wrapper, stay on SwipeRefreshLayout. Rewriting a working wrapper in Compose to get one gesture is wasted work.
Common mistakes
The problems I see most often:
- The spinner never stops. You didn’t call
setRefreshing(false)inonPageFinished. - Refresh fires mid-scroll. Your site scrolls inside a container. Use the scroll-up callback.
- Form data disappears. A reload throws away whatever the user typed. Block refresh on checkout and long form pages.
- Offline reload shows an error page. See what a WebView app does without internet.
Pull to refresh pairs well with proper back button handling and opening external links in the browser. They also help with Google Play’s minimum functionality rule.
One limitation: a reload refreshes the whole page. If your site already fetches fresh data in the background, a full reload is slower than it needs to be. Call your JavaScript refresh function instead.
FAQ
Does Android WebView have pull to refresh built in?
No. The pull-to-refresh gesture you know from Chrome is Chrome’s own browser feature. In a WebView app you add it yourself, usually by wrapping the WebView in SwipeRefreshLayout.
Why does pull to refresh fire when I scroll up inside the page?
SwipeRefreshLayout asks its child whether it can scroll up. Pages that scroll inside a div instead of the whole document report that they are at the top, so the layout takes the gesture. Override the check with setOnChildScrollUpCallback.
How do I stop the refresh spinner?
Call setRefreshing(false) when the update finishes. In a WebView app, the natural place is onPageFinished in your WebViewClient.
Is SwipeRefreshLayout deprecated?
Not deprecated, but it is in maintenance mode. Android says it will only receive critical fixes and no new features. Version 1.2.0 is the current stable release, and Compose apps can use PullToRefreshBox instead.
Sources
- Add the swipe-to-refresh interface, Android Developers
- Respond to a refresh request, Android Developers
- SwipeRefreshLayout API reference, Android Developers
- SwipeRefreshLayout release notes, Android Developers
- Pull to refresh in Jetpack Compose, Android Developers
- Take control of your scroll, Chrome for Developers