Pull-to-refresh Web Component Demo

Basic Example

Pull down from the top to trigger a refresh. The random number will update.

Basic Usage

The component listens for pull gestures and fires a ptr:refresh event.

<pull-to-refresh>
  <div class="content">
    <h3>My Content</h3>
    <p>Pull down to refresh</p>
    <p>Random: <span id="random1">0</span></p>
  </div>
</pull-to-refresh>

Open in new window

Custom Threshold

Demonstrating a custom threshold distance (120px instead of default 80px).

Using threshold Attribute

You need to pull further down to trigger the refresh.

<pull-to-refresh threshold="120">
  <div class="content">
    <p>Pull 120px to refresh</p>
  </div>
</pull-to-refresh>

Open in new window

Custom Indicator Text

Customize the text shown in the pull indicator.

Custom Messages

Using custom text for the indicator states.

<pull-to-refresh
  indicator-text="⬇ Swipe down"
  release-text="🔄 Let go!"
  refreshing-text="⏳ Loading...">
  <div class="content">
    <p>Custom messages</p>
  </div>
</pull-to-refresh>

Open in new window

Disable Text Selection

By default, text selection is allowed during pull gestures. Use the disable-selection attribute to prevent accidental text selection while pulling.

Using disable-selection Attribute

Text selection is blocked during the pull gesture. Try selecting text while pulling down to see the difference.

<pull-to-refresh disable-selection>
  <div class="content">
    <p>Selection blocked during pull</p>
  </div>
</pull-to-refresh>

Open in new window

Localization (i18n)

The component automatically detects language and uses appropriate translations for 16 languages.

Spanish (Español)

Using the lang="es" attribute.

<pull-to-refresh lang="es">
  <div class="content">
    <p>Contenido en español</p>
  </div>
</pull-to-refresh>

Open in new window

French (Français)

Using the lang="fr" attribute.

<pull-to-refresh lang="fr">
  <div class="content">
    <p>Contenu en français</p>
  </div>
</pull-to-refresh>

Open in new window

Japanese (日本語)

Using the lang="ja" attribute.

<pull-to-refresh lang="ja">
  <div class="content">
    <p>日本語のコンテンツ</p>
  </div>
</pull-to-refresh>

Open in new window

Supported Languages

The component includes built-in translations for:

English (en)
Chinese/中文 (zh)
Hindi/हिन्दी (hi)
Spanish/Español (es)
French/Français (fr)
Arabic/العربية (ar)
Bengali/বাংলা (bn)
Portuguese/Português (pt)
Russian/Русский (ru)
Japanese/日本語 (ja)
German/Deutsch (de)
Punjabi/ਪੰਜਾਬੀ (pa)
Javanese (jv)
Korean/한국어 (ko)
Vietnamese/Tiếng Việt (vi)
Italian/Italiano (it)

Regional variants (e.g., en-US, es-MX) automatically fall back to the base language.

API Reference

Attributes

threshold - Distance in pixels to trigger refresh (default: 80)
indicator-text - Text when pulling (default: localized "↓ Pull to refresh")
release-text - Text when ready to release (default: localized "↻ Release to refresh")
refreshing-text - Text while refreshing (default: localized "⏳ Refreshing...")
lang - Language code for localization (auto-detected from element, ancestor, or document)
disabled - Disables pull-to-refresh functionality
disable-selection - Prevents text selection during pull gesture

Events

ptr:pull-start - Fired when pull gesture starts
ptr:pull-move - Fired during pull (detail contains distance)
ptr:pull-end - Fired when pull gesture ends
ptr:refresh - Fired when refresh is triggered
ptr:refresh-complete - Fired when refresh completes

CSS Custom Properties

--ptr-indicator-height - Height of indicator (default: 3.125rem)
--ptr-indicator-bg - Indicator background (default: ButtonFace)
--ptr-indicator-color - Indicator text color (default: ButtonText)
--ptr-indicator-font-size - Indicator font size (default: 0.875rem)
--ptr-transition-duration - Transition duration (default: 0.2s)

For complete documentation and browser support, see the README.