---
title: Pull to Refresh
description: Pull down from the top of a page to refresh its content.
---
import Source from './_generated/pull-to-refresh.mdx';

Wrap a page's scroll content and let users pull down from the top to refresh it. Past a threshold the gesture arms and fires; the platform indicator holds while the work runs and retracts when it settles. iOS scales a pull-spinner in and ticks it round; Material descends an elevated disc whose arc fills with the pull and spins on trigger.

The gesture is touch-only — preview it with device emulation (Chrome DevTools) or a real device.

<DemoFrame component="pull-to-refresh" height={480} />

## Installation

```bash
npx touchcn add pull-to-refresh
```

## Usage

<CodeGroup>

```html Angular
<tcn-pull-to-refresh #ptr="tcnPullToRefresh" (refresh)="onRefresh(ptr)">
  <!-- scrollable content -->
</tcn-pull-to-refresh>
```

```tsx React
import { TcnPullToRefresh } from '@/components/ui/pull-to-refresh';

<TcnPullToRefresh onRefresh={onRefresh}>
  {/* scrollable content */}
</TcnPullToRefresh>
```

```vue Vue
<script setup lang="ts">
import { TcnPullToRefresh } from '@/components/ui/pull-to-refresh';
</script>

<template>
  <TcnPullToRefresh :on-refresh="onRefresh">
    <!-- scrollable content -->
  </TcnPullToRefresh>
</template>
```

</CodeGroup>

On Angular, run the refresh work when `refresh` fires and call `complete()` (via the template ref) to retract. On React, return a Promise from `onRefresh` — the indicator holds until it settles.

## Props

| Prop                    | Type                          | Default | Description                                            |
| ----------------------- | ----------------------------- | ------- | ------------------------------------------------------ |
| `refresh` / `onRefresh` | `() => void \| Promise<void>` | —       | Fires when pulled past the threshold.                  |
| `threshold`             | `number`                      | `70`    | Finger distance (px) that arms the refresh.            |
| `disabled`              | `boolean`                     | `false` | Disables arming (an in-flight refresh still resolves). |
| `complete()`            | method (Angular)              | —       | Retracts the indicator; React resolves via the Promise. |

<Source />