PullToRefresh

PullToRefresh

<PullToRefresh onRefresh={async () => { await reload(); }}>
  <List divided>
    {items.map((it) => (
      <List.Item key={it.id} primary={it.title} secondary={it.summary} />
    ))}
  </List>
</PullToRefresh>

Install: @helixui/core

import { PullToRefresh } from '@helixui/core'

status: beta · since: 0.5.0

Tags: mobile, gesture, refresh, scroll

Anatomy

↓ Pull down to refresh ↓
────────────────────────
[ scrollable content ]

Layout

• display — block
• width — fill
• height — fill
• intrinsicSize — fills available; intercepts top-edge pull
• stackable — false
• fullBleed — false

Visual

A scroll container that exposes a small spinner when the user drags down past the top. Past a threshold, releasing fires the async refresh and the spinner spins until the promise resolves.

Props

Name	Type	Default	Description
onRefresh	() => void | Promise<void>	—	Required. Called when the user releases past threshold. While the returned promise is pending, the spinner stays visible and disabled.
threshold	number	64	Pixel distance past which release triggers refresh.
maxPull	number	120	Soft cap on pull distance (rubber-band beyond this).

Slots

• children — the scrollable content

Tokens used

color.bg.surface.default, color.text.action.brand, radius.full, font.family.sans, shadow.md

Accessibility

Notes

• Pull-to-refresh is a touch gesture; it should never be the only way to refresh. Pair with a visible Refresh button or a CommandPalette entry.
• The component listens to pointer events so it works with mouse drag for desktop testing, but the gesture is mobile-first.

Composes with

Component	Relation	Note
List	child	Common: PullToRefresh wraps a List.
ChatList	alternative	ChatList has its own scroll behavior.
SwipeableListItem	sibling

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

mobile feed pull-to-refresh

“pull to refresh wrapping a feed list”

<PullToRefresh onRefresh={loadFeed}>
  <List>{rows}</List>
</PullToRefresh>

Related

• List
• SwipeableListItem