How Pull-to-Refresh Works in Safari on iOS and iPadOS

This article provides a complete breakdown of the pull-to-refresh gesture in the mobile Safari web browser on iOS and iPadOS. It covers how users physically trigger the gesture, the history of its implementation, the underlying technical mechanics within Apple's WebKit engine, and how web developers can manage or disable this behavior on their websites using CSS.

Performing the Gesture

The pull-to-refresh gesture allows users to reload the current webpage without reaching for the small reload icon in the address bar. To use it, a user must follow three simple steps:

  1. Scroll to the very top of the current webpage.
  2. Place a finger on the screen and swipe downward.
  3. Release the finger once the spinning loading indicator fully appears at the top of the screen.

If the user stops pulling and scrolls back up before releasing their finger, the refresh is canceled, and the page remains in its current state.

The History of Pull-to-Refresh in Safari

While the pull-to-refresh gesture was invented in 2008 and quickly became a standard across native iOS applications, Apple did not include it in mobile Safari for over a decade. The feature was finally introduced in 2021 with the release of iOS 15 and iPadOS 15. Apple added this gesture primarily because iOS 15 moved Safari's address bar to the bottom of the screen, changing how users interacted with navigation controls.

How the Mechanics Work Under the Hood

Mobile Safari runs on WebKit, Apple’s browser engine. The pull-to-refresh mechanism relies on a combination of touch event tracking and iOS's native "rubber-banding" (overscroll) physics.

Here is the step-by-step technical process:

  • Scroll Position Verification: WebKit constantly monitors the vertical scroll position of the webpage. The pull-to-refresh mechanism remains dormant unless the vertical scroll position is at zero (the absolute top of the document).
  • Touch Tracking: When the page is at the top, Safari listens for a touchstart event followed by a downward touchmove event.
  • Rubber-Banding and Threshold: As the user pulls down, the browser engages its overscroll physics, creating friction so the page moves slower than the user's finger. Safari measures the distance of this downward pull.
  • UI Feedback: As the pull distance increases, Safari renders the native iOS activity indicator (the spinning wheel) in the blank space created above the webpage.
  • Triggering the Reload: Once the user pulls past a specific pixel threshold, the browser triggers a subtle haptic feedback tap (on iPhones) and locks the spinner in place. When the touchend event registers (the user lifts their finger), Safari initiates a standard page reload, fetching the latest data from the server.

How Developers Control the Gesture

In some cases, the pull-to-refresh gesture can interfere with the user experience. For example, if a user is playing a web-based game or using a custom-built web application with its own scrolling mechanics, pulling down might accidentally reload the entire app and erase unsaved data.

Starting with Safari 16 (released alongside iOS 16), Apple gave web developers native control over this gesture using the CSS overscroll-behavior property.

To disable pull-to-refresh on a webpage in Safari, developers apply the following CSS rule to the root elements of the page:

html, body {
    overscroll-behavior-y: none;
}

Setting overscroll-behavior-y to none or contain disables the native rubber-banding effect at the top of the viewport. Because the page can no longer be pulled past its top boundary, the threshold for the pull-to-refresh gesture can never be met, effectively turning the feature off for that specific webpage.