Skip to content
WunderUI

Pull to Refresh

Free

Drag a list down from the top past a threshold to refresh it, with a spinner that follows the pull and a spring back when the request is done.

npx wunderui-cli add pull-to-refresh

Playground

Notifications

Pull down to refresh

  • Weekly report ready2 min ago
  • New comment on Q3 plan14 min ago
  • Invoice #1042 paid58 min ago
  • Deploy finished3 h ago

Installation

bash
npx wunderui-cli add pull-to-refresh

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { PullToRefresh } from "@/components/wunderui/pull-to-refresh"

Then use it:

tsx
import { useState } from "react"
import { PullToRefresh } from "@/components/ui/pull-to-refresh"

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export function Notifications() {
  const [updated, setUpdated] = useState("Pull down to refresh")

  async function refresh() {
    await wait(1000)
    setUpdated("Updated just now")
  }

  return (
    <PullToRefresh onRefresh={refresh} className="h-64 bg-bg-page">
      <p role="status" className="p-4 text-sm">{updated}</p>
    </PullToRefresh>
  )
}

Expected result: You should see the text Pull down to refresh. Drag it down past about 140 px and release: a spinner turns for a second and the text reads Updated just now.

When to use

Use Pull to Refresh for

  • A touch-first list or feed that people reload by hand, such as an inbox or a notification list
  • Content that a server owns and that goes stale, such as figures or a status board
  • A mobile layout where a Refresh button would take room from the list

Use something else for

  • Button for a refresh that must work with a keyboard or a screen reader, on its own or beside the list
  • Spinner for a load with no gesture, such as a page or a panel that is loading
  • Pagination for a long list that people move through page by page

Result

The spinner stays until the refresh settles, then the list springs back. If it fails, the error handler runs and the spinner stops, and the component shows no errors, so say so in text.

Notifications

Updated 2 min ago

  • Weekly report ready2 min ago
  • New comment on Q3 plan14 min ago
  • Invoice #1042 paid58 min ago
  • Deploy finished3 h ago

Trigger

The drag has no keyboard route and no announcement. Put a Refresh button beside the list that calls the same function, so people who cannot drag can refresh too.

Notifications

Pull down to refresh

  • Weekly report ready2 min ago
  • New comment on Q3 plan14 min ago
  • Invoice #1042 paid58 min ago
  • Deploy finished3 h ago

Content

The pull starts only when everything above the finger is scrolled to the top. In a scrolling list, a downward drag first scrolls back up and the pull takes over at the top.

Notifications

Pull down to refresh

  • Weekly report ready2 min ago
  • New comment on Q3 plan14 min ago
  • Invoice #1042 paid58 min ago
  • Deploy finished3 h ago

Keyboard interactions

PullToRefresh is a pointer gesture. It adds no tab stop, key handling or announcement, so the keyboard route is a button that you provide.

TaborShiftTab
Moves focus through the controls inside the content and the Refresh button beside it. The wrapper itself is skipped.
EnterorSpace
On your Refresh button: runs the same function as . Show its pending state with on Button.

The content area is not focusable and does not react to Arrow keys, Page Up or Page Down. Scrolling a list inside it works as usual.

Behavior and motion

What the gesture does with scrolling, taps, the request and motion.

When a pull starts
A press becomes a pull only after it moves 8 px, mostly downward, with everything above scrolled to the top. Until then a tap stays a tap, and sideways or upward movement goes back to the browser.
Mouse and touch
With a finger the page must be at its top too, because a finger scrolls the page. A mouse drag never scrolls, and only the primary pointer starts a pull, so a second finger is ignored.
Scrolling content
Inside content that is scrolled down, the downward gesture scrolls it back up first. At the top the browser leaves the downward pull to the component but keeps horizontal scrolling and pinch zoom.
Resistance
The content follows the pointer at half speed and stops at the maximum pull. The indicator fades in and turns with the progress, up to the threshold.
Release
If the content has moved at least the threshold, it settles there, the spinner turns and the refresh runs. Below it, the content springs back; presses are ignored during a refresh.
Failure
When the refresh fails, the spinner stops, the content springs back and the error handler is called, so the pull never stays locked. Without one the failure is swallowed, so tell people yourself.
Cancel
If the browser takes the gesture, for example for a system swipe, the pointer is released and the content springs back without refreshing.
The click after a pull
The release that ends a pull is not a click: it is swallowed once, so the row under the finger does not open. The next press clears it.
Motion
While the pointer is down the content moves with it and has no transition. After release it settles with a slow ease, and the spinner turns while the refresh runs.
Reduced motion
With reduced motion the content jumps to the threshold on release and back when the refresh ends, and the spinner stays a static icon. Pair it with a text status, since a static icon is not a signal.

Anatomy

The component rests with the indicator hidden, so the figure poses it mid-pull, as the Figma pulling state is drawn. The indicator is visible and the content has moved down.

  • Weekly report ready2 min ago
  • New comment on Q3 plan14 min ago
  • Invoice #1042 paid58 min ago
  • data-slot="pull-to-refresh"

    A clipping box around your content. Give it a height and a background, since the indicator sits behind the content and shows as it moves down.

  • data-slot="pull-to-refresh-indicator"

    The spinner icon at the top of the box. It fades in and turns with the pull, then spins until the refresh settles.

  • The wrapper around your content that moves down with the pull. It takes the pointer events, lets the browser keep scrolling the content up, and shows a grab cursor, so text inside cannot be selected.

Best practices

  • Do

    Return the promise from the refresh handler. The spinner and the lock stay until it settles, so a slow request never looks finished.

  • Do

    Pass an error handler and show the failure in text, such as Couldn't refresh. The component resets after a failure but shows nothing itself, and without a handler the failure is swallowed silently.

  • Do

    Put a visible Refresh button beside the list that calls the same function. The gesture is pointer-based, with no keyboard route and no announcement.

  • Do

    Announce the result in a status line, such as Updated just now. The component says nothing to assistive technology.

  • Do

    Give the box a height, a background and content that fills it. The box clips what moves out of it, and its background shows behind the content during the pull.

  • Do

    Keep the threshold at or below the maximum pull (defaults 70 and 110). The pull moves at half the finger speed, so people drag about twice the threshold.

  • Don’t

    Don't make the gesture the only way to refresh. Many people use a keyboard, a switch or a screen reader, and on a desktop mouse the drag is easy to miss.

  • Don’t

    Don't use it for data that updates by itself. Show the new state instead and skip the gesture.

  • Don’t

    Don't put text people should select inside the content. A drag must not select text, so the content blocks selection and nothing there can be copied.

  • Don’t

    Don't expect a tap to work right after a pull. The click that ends a drag is swallowed on purpose, so the item under the finger is not opened.

API reference

PullToRefresh is a plain component, so the table lists every prop. It keeps the pull and refresh state itself and reports only through the refresh handler.

A clipping box around your content. Give it a height and a background, since the indicator sits behind the content and shows as it moves down.

PropTypeDefaultDescription
onRefresh required() => void | Promise<void>—Called once when the content is released past . Return a promise: the spinner turns and the pull stays locked until it settles, also when it rejects or throws, which is reported to .
onError(error: unknown) => void—Called with the error when throws or its promise rejects. The indicator has already reset. Optional: without it the failure is swallowed, so show it in your own UI.
thresholdnumber70How far the content must have moved, in px, before a release refreshes. It is also the height of the indicator area and where the content rests while refreshing. Defaults to 70.
maxPullnumber110The most the content can move, in px. The pull moves at half the pointer speed, so this takes about twice as much dragging. Keep it at or above . Defaults to 110.
children requiredReact.ReactNode—The content that is pulled down. Taps reach it normally; a drag that has begun does not click anything.
classNamestring—Extra classes for the outer box (), for example a height and a background such as .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("pull-to-refresh")
Installnpx wunderui-cli add pull-to-refresh

The full library index for assistants is at /llms.txt.