Pull to Refresh

Pull-to-refresh scroll container with thresholds, resistance, async refresh state, and reduced-motion hooks.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { PullToRefresh, PullToRefreshTrigger } from "@vizejs/ui/pull-to-refresh";

Or copy the source into your project with vize lib pull pull-to-refresh (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Scrollable inbox that reloads by pulling down or with the keyboard-accessible refresh button. -->
<script setup lang="ts">
import { ref } from "vue";

import { PullToRefresh, PullToRefreshTrigger } from "@vizejs/ui/pull-to-refresh";

const messages = ref(["Welcome to your inbox", "Your order has shipped", "Weekly digest"]);
const refreshCount = ref(0);
// The root is the scroll container, so it needs a bounded block size to scroll.
const scrollerSize = { blockSize: "12rem", overflow: "auto" };

async function loadNewMessages(): Promise<void> {
  await Promise.resolve();
  refreshCount.value += 1;
  messages.value = [`New message ${refreshCount.value}`, ...messages.value];
}
</script>

<template>
  <PullToRefresh
    v-slot="{ state, refreshing }"
    :refresh-action="loadNewMessages"
    :style="scrollerSize"
  >
    <p role="status">
      {{ refreshing ? "Refreshing…" : state === "armed" ? "Release to refresh" : "" }}
    </p>
    <PullToRefreshTrigger v-slot="{ refreshing: busy }">
      {{ busy ? "Refreshing" : "Refresh inbox" }}
    </PullToRefreshTrigger>
    <ul aria-label="Messages">
      <li v-for="message in messages" :key="message">{{ message }}</li>
    </ul>
  </PullToRefresh>
</template>

API

PullToRefresh

Source: src/families/interaction/pull-to-refresh/pull-to-refresh.vue

Props

Events

Slots

Exposed

PullToRefreshTrigger

Source: src/families/interaction/pull-to-refresh/pull-to-refresh-trigger.vue

Slots

Behavior

Normative state x input -> outcome table for pull-to-refresh.vue and pull-to-refresh-trigger.vue (@vizejs/ui/pull-to-refresh). The root is the consumer-styled scroll container. Every row is proven by the named test in pull-to-refresh.test.ts or pull-to-refresh-ssr.test.ts.

The subpath ships no CSS.