Skip to content
A quick and powerful plugin for your pull-to-refresh needs in your webapp.
Branch: master
Clone or download
Rafael Soto
Rafael Soto Issue template
Latest commit d33ed75 Jan 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Issue template Jan 29, 2019
demos Revert docs/ => demos/; cleanup Sep 18, 2018
dist Cleanup before release v0.1.16 Dec 18, 2018
img Update gif Dec 4, 2016
src Cleanup before release v0.1.16 Dec 18, 2018
.eslintrc Modern ESLint Dec 27, 2017
.gitattributes Cleanup before release v0.1.16 Dec 18, 2018
LICENSE.txt Issue template Jan 29, 2019
package-lock.json 0.1.16 Dec 19, 2018


Build Status NPM version CDNJS


A small, but powerful Javascript library crafted to power your webapp's pull to refresh feature. No markup needed, highly customizable and dependency-free!


Download PulltoRefresh either from the NPM Registry, CDNJS or UNPKG:

$ npm install pulltorefreshjs --save-dev
$ wget -O pulltorefresh.js

Include the JS file in your webapp and initialize it:

const ptr = PullToRefresh.init({
  mainElement: 'body',
  onRefresh() {

Bundlers can consume pulltorefreshjs as CommonJS and ES6-modules syntax:

import PullToRefresh from 'pulltorefreshjs';
// or
const PullToRefresh = require('pulltorefreshjs');


  • init(options) Will return a unique ptr-instance with a destroy() method.
  • destroyAll() Stop and remove all registered ptr-instances.
  • setPassiveMode(isPassive) Enable or disable passive mode for event handlers (new instances only).


  • distThreshold (integer) Minimum distance required to trigger the refresh.
    — Defaults to 60
  • distMax (integer) Maximum distance possible for the element.
    — Defaults to 80
  • distReload (integer) After the distThreshold is reached and released, the element will have this height.
    — Defaults to 50
  • distIgnore (integer) After which distance should we start pulling?
    — Defaults to 0
  • mainElement (string) Before which element the pull to refresh elements will be?
    — Defaults to body
  • triggerElement (string) Which element should trigger the pull to refresh?
    — Defaults to body
  • ptrElement (string) Which class will the main element have?
    — Defaults to .ptr
  • classPrefix (string) Which class prefix for the elements?
    — Defaults to ptr--
  • cssProp (string) Which property will be usedto calculate the element's proportions?
    — Defaults to min-height
  • iconArrow (string) The icon for both instructionsPullToRefresh and instructionsReleaseToRefresh
    — Defaults to ⇣
  • iconRefreshing (string) The icon when the refresh is in progress.
    — Defaults to …
  • instructionsPullToRefresh (string) The initial instructions string.
    — Defaults to Pull down to refresh
  • instructionsReleaseToRefresh (string) The instructions string when the distThreshold has been reached.
    — Defaults to Release to refresh
  • instructionsRefreshing (string) The refreshing text.
    — Defaults to Refreshing
  • refreshTimeout (integer) The delay, in milliseconds before the onRefresh is triggered.
    — Defaults to 500
  • getMarkup (function) It returns the default HTML for the widget, __PREFIX__ is replaced.
    — See src/lib/markup.js
  • getStyles (function) It returns the default CSS for the widget, __PREFIX__ is replaced.
    — See src/lib/styles.js
  • onInit (function) The initialize function.
  • onRefresh (function) What will the pull to refresh trigger? You can return a promise.
    — Defaults to window.location.reload()
  • resistanceFunction (function) The resistance function, accepts one parameter, must return a number, capping at 1.
    — Defaults to t => Math.min(1, t / 2.5)
  • shouldPullToRefresh (function) Which condition should be met for pullToRefresh to trigger?
    — Defaults to !window.scrollY


To quickly start the development workflow:

  1. Install NodeJS (NVM)
  2. Run nvm use 10 && npm install
  3. Then npm run dev

This will watch and compile the bundle for browser usage.

E2E tests are executed with Testcafé.

  • Run npm test to use standard chrome
  • Run npm run test:ci to run chrome in headless mode

Advanced debug can be achieved with testcafe-live, e.g.

$ npx testcafe-live chrome tests/e2e/cases --debug-on-fail


If you find this project helpful, please consider supporting the maintenance team!


  • More events: onPullStart, onPullDown(direction, willRefresh), onRelease(willRefresh)
  • Fully customizable CSS
  • Gallery of use cases
  • Advanced demos
  • Tests
  • Minified releases
You can’t perform that action at this time.