Pull To Refresh React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Pull To Refresh is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import PullToRefresh from @/components/ui/pull-to-refresh.

"use client"

import { useState } from "react"
import { RotateCw } from "lucide-react"
import { Button } from "@/components/ui/button"
import { PullToRefresh, type PullToRefreshApi } from "@/components/ui/pull-to-refresh"

type Message = { id: string; from: string; text: string }

export function Inbox({ load }: { load: () => Promise<Message[]> }) {
  const [messages, setMessages] = useState<Message[]>([])
  const [api, setApi] = useState<PullToRefreshApi>()

  return (
    <div className="flex h-dvh flex-col">
      <header className="flex h-14 items-center justify-between px-4">
        <h1 className="text-lg font-semibold">Inbox</h1>
        <Button variant="ghost" size="icon" radius="full" aria-label="Reload" onClick={() => api?.refresh()}>
          <RotateCw />
        </Button>
      </header>
      <PullToRefresh
        scroll="self"
        className="min-h-0 flex-1"
        setApi={setApi}
        onRefresh={async () => setMessages(await load())}
        labels={{ pull: "Pull to check for mail", release: "Let go to check", refreshing: "Checking for mail…", done: "Up to date", error: "Could not check for mail" }}
      >
        <ul className="divide-y divide-foreground/10">
          {messages.map((m) => (
            <li key={m.id} className="px-4 py-3">
              <p className="font-medium">{m.from}</p>
              <p className="text-sm text-muted-foreground">{m.text}</p>
            </li>
          ))}
        </ul>
      </PullToRefresh>
    </div>
  )
}

Props

• children
  ReactNode

  The list or feed that gets pulled.

• onRefresh
  (() => void | Promise<unknown>)

  The reload. The indicator spins until the returned promise settles, and for 500ms at least so it never flashes. A rejection shows the error state.

• variantdefault "arrow"
  "arrow" | "ios" | "material"

  arrow: an arrow that turns at the threshold and becomes a spinner; the content moves down. ios: 12 spokes that draw one by one as you pull, then spin like UIRefreshControl; the content moves down. material: a floating circle whose ring fills while you pull, then spins; the content stays put.

• sizedefault "md"
  "sm" | "md" | "lg"

  Indicator 20 / 24 / 28px; the material circle 36 / 40 / 44px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The indicator color. neutral is the quiet muted gray (the material ring is black / white); the other tones use their tone text color and fill.

• colordefault ""
  string

  Any CSS color for the indicator. Replaces the tone. Leave empty to use the tone.

• showLabeldefault false
  boolean

  Text under the indicator that follows the state: pull, release, refreshing, done or error.

• labels
  Partial<PullToRefreshLabels>

  The strings shown with showLabel and announced to screen readers: pull "Pull to refresh", release "Release to refresh", refreshing "Refreshing…", done "Updated", error "Couldn't refresh". Pass only the keys you translate.

• refreshingdefault false
  boolean

  Shows the refreshing state for a reload the app started itself (the content parks at the threshold with a spinner). OR-ed with the internal state, so false never blocks a pull.

• disableddefault false
  boolean

  No pulling (offline, editing, a filter is active). Turning it on mid-pull springs back without refreshing.

• doneDurationdefault 600
  number

  Milliseconds the check (or the alert) stays before the content glides back. 0 skips the done state.

• thresholddefault 72
  number

  Pixels of resisted pull that arm the refresh; also where the content rests while it refreshes.

• maxPulldefault 128
  number

  The furthest the content moves, however far the finger goes.

• indicatorOffsetdefault 0
  number

  Pixels from the top of the root to the indicator's resting line, for a sticky or translucent bar over the list.

• scrolldefault "parent"
  "parent" | "self"

  parent: watches scrollTarget, else the provided scroll container (ScrollContainerProvider), else the nearest scrolling ancestor, else the window. self: the root is the scroll container (h-full overflow-y-auto overscroll-y-contain).

• scrollTarget
  HTMLElement | Window | RefObject<HTMLElement | null> | null

  The scroller to watch when scroll is parent. null forces the window.

• wheeldefault true
  boolean

  A trackpad or mouse wheel scrolling up at the very top pulls too, the desktop path. Momentum that carries a scroll up to the top never pulls.

• pullWithMousedefault false
  boolean

  A mouse drag at the top pulls, for kiosks and touch emulation. Off by default so it never fights text selection and clicks.

• hapticsdefault true
  boolean

  A "medium" tick when the pull arms and an "error" buzz when a pulled refresh fails, through lib/haptics.

• shortcutdefault ""
  string

  A key that refreshes, in mod+k notation ("mod+r", "shift+r"). None by default.

• setApi
  (api: PullToRefreshApi) => void

  Receives { refresh(): Promise<void> }, which runs the same flow as a pull (indicator, promise, done). Calls during a running refresh return the running promise.

• classNames
  Partial<Record<"indicator" | "icon" | "spinner" | "label" | "content", string>>

  Extra classes for the indicator row, the arrow / check / alert icon, the spinner, the label and the content wrapper.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React mobile components