Loading…

Pull to Refresh

beta

A sheet you pull down to refresh, with rubber-band resistance, a dot ring that fills as you pull and springs that carry the pull's velocity.

Feedback
1 file
2 npm packages
Accessibility notes
Animates with motion

Playground

Installation

The CLI installs button as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add pull-to-refresh

npm packages installed: class-variance-authority, motion.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { PullToRefresh } from "@/components/ui/pull-to-refresh";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Scrolling Feed

API

Generated from the component's own types, so a prop cannot appear here without existing.

<PullToRefresh>

Prop	Type	Default
`corner` Sheet radius in px, 0–40. Default 26.	`number`	`26`
`disabled`	`boolean`	`false`
`dots` Dots in the ring, 3–10. Default 6.	`number`	`6`
`fill`	`"light" \| "dark"`	`"light"`
`hint` Instructions linked to the sheet with aria-describedby.	`string`	`"Pull down, or press Enter, to refresh."`
`label` Names the sheet. Default "Refreshable content".	`string`	`"Refreshable content"`
`minDuration` Shortest time the refreshing state shows, so a fast refresh still reads (ms). Default 600.	`number`	`600`
`onRefresh` Runs the refresh. The sheet stays in the refreshing state until a returned promise settles.	`() => Promise<unknown> \| void`	—
`refreshButtonLabel` The refresh button's text. Default "Refresh".	`string`	`"Refresh"`
`refreshedLabel` Announced when a refresh ends. Default "Refreshed".	`string`	`"Refreshed"`
`refreshing` Controlled refreshing state. Leave undefined to let the promise drive it.	`boolean`	—
`refreshingLabel` Announced when a refresh starts. Default "Refreshing…".	`string`	`"Refreshing…"`
`showRefreshButton` Renders a visible Refresh button under the sheet. Default true.	`boolean`	`true`
`spin` Ring rotation speed, 0–100 (2400ms per turn at 50). Default 50.	`number`	`50`
`stroke` A 1px inset hairline on the sheet.	`boolean`	`false`
`threshold` Pull distance (px) that arms the refresh; also the resting offset while refreshing. Default 58.	`number`	`58`
`children`	`ReactNode`	—

Plus every attribute of <div> except onRefresh.

Accessibility

The sheet is a named, focusable group described by a hint; Enter on it refreshes, and a visible Refresh button (showRefreshButton, on by default) gives a pointer-free path for touch and screen reader users, so pulling is never the only way. While refreshing the sheet is aria-busy and a polite status region announces "Refreshing…" then "Refreshed". The dot ring is aria-hidden decoration and stops under reduced motion, where the springs are also instant; the refresh itself still works. A pull only starts when the sheet is scrolled to the top, and the click a pull leaves behind is swallowed.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — does not apply
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

corner

Sheet radius in px, 0–40. Default 26.

number

26

disabled

boolean

false

dots

Dots in the ring, 3–10. Default 6.

number

6

fill

"light" | "dark"

"light"

hint

Instructions linked to the sheet with aria-describedby.

string

"Pull down, or press Enter, to refresh."

label

Names the sheet. Default "Refreshable content".

string

"Refreshable content"

minDuration

Shortest time the refreshing state shows, so a fast refresh still reads (ms). Default 600.

number

600

onRefresh

Runs the refresh. The sheet stays in the refreshing state until a returned promise settles.

() => Promise<unknown> | void

—

refreshButtonLabel

The refresh button's text. Default "Refresh".

string

"Refresh"

refreshedLabel

Announced when a refresh ends. Default "Refreshed".

string

"Refreshed"

refreshing

Controlled refreshing state. Leave undefined to let the promise drive it.

boolean

—

refreshingLabel

Announced when a refresh starts. Default "Refreshing…".

string

"Refreshing…"

showRefreshButton

Renders a visible Refresh button under the sheet. Default true.

boolean

true

spin

Ring rotation speed, 0–100 (2400ms per turn at 50). Default 50.

number

50

stroke

A 1px inset hairline on the sheet.

boolean

false

threshold

Pull distance (px) that arms the refresh; also the resting offset while refreshing. Default 58.

number

58

children

ReactNode

—