Pull to Refresh
FreeDrag 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-refreshPlayground
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
npx wunderui-cli add pull-to-refreshWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { PullToRefresh } from "@/components/wunderui/pull-to-refresh"Then use it:
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
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
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
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
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
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
- Daniel Okafor shared a file4 h ago
- Maya Kessler joined WunderUI5 h ago
- Contract signed7 h ago
- Tomás Ferreira closed 3 tickets9 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.
- TaborShift+Tab
- 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
- 1data-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.
- 2data-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.
- 3
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| threshold | number | 70 | How 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. |
| maxPull | number | 110 | The 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 required | React.ReactNode | — | The content that is pulled down. Taps reach it normally; a drag that has begun does not click anything. |
| className | string | — | 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.
get_component("pull-to-refresh")npx wunderui-cli add pull-to-refreshThe full library index for assistants is at /llms.txt.
Related components
- 3
Team
- NLNora LindgrenOwnerOwner
- DODaniel OkaforEngineeringAdmin
- PRPriya RamanDesignMember
Data & Tables8 stylesProList GroupA 400 px card of list rows with an optional header — sixteen ready patterns: basic, icon, avatar, brand, metric, selectable, toggle, sortable, expandable, grouped, ranking, comparison, tree, action, discussion and master–detail.