# pulldown

# Introduction

The pulldown plugin provides BetterScroll with the ability to monitor pulldown operation.

# Install

npm install @better-scroll/pull-down --save

// or

yarn add @better-scroll/pull-down

# Usage

First, install the plugin via the static method BScroll.use()

import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'


pass in the correct configuration in options, for example:

new BScroll('.bs-wrapper', {
  pullDownRefresh: true

# Demo

  • Basic Usage
  <div class="pulldown">
      <div class="pulldown-scroller">
        <div class="pulldown-wrapper">
          <div v-show="beforePullDown">
            <span>Pull Down and refresh</span>
          <div v-show="!beforePullDown">
            <div v-show="isPullingDown">
            <div v-show="!isPullingDown">
              <span>Refresh success</span>
        <ul class="pulldown-list">
            v-for="i of dataList"
          >{{ `I am item ${i} ` }}</li>
  • Sina-Weibo 2.4.0

In order to match the effects of App, in version v2.4.0, pulldown has made some changes and is compatible with previous versions. During a pulldown procedure, there are three internal circulation states, and the states are irreversible. They are as follows:

  1. default

The initial state.

  1. moving

Moving state, this state represents that the user's finger is manipulating BetterScroll, and the finger is keeping in touch. In this state, BetterScroll will dispatch two events.

  • enterThreshold

    Dispatched when BetterScroll scrolls into the pulldown threshold area. Inside this event, you can do the logic of texts initialization, such as prompting the user to "pull down to refresh"

  • leaveThreshold

    Dispatched when BetterScroll scrolls out of the pulldown threshold area. You can prompt the user to "Release finger"

  1. fetching

Once the finger went away, the pullingDown event is triggered to execute the logic of fetching data

The state change can only be default -> moving -> fetching or default -> moving. The latter means that at the moment the user's finger is released, the conditions for triggering the pullingDown event are not met.

# pullDownRefresh Options

# threshold

  • Type: number
  • Default: 90

Configure the top pull-down distance to determine dispatching pullingDown hooks.

# stop

  • Type: number
  • Default: 40

Rebound distance. After BetterScroll dispatches the pullingDown hook, it will immediately execute the rebound animation.


When pullDownRefresh is configured as true, the plugin uses the default plugin option.

const bs = new BScroll('.wrapper', {
  pullDownRefresh: true

// equals

const bs = new BScroll('.wrapper', {
  pullDownRefresh: {
    threshold: 90,
    stop: 40

# Instance Methods


All methods are proxied to BetterScroll instance, for example:

import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'


const bs = new BScroll('.bs-wrapper', {
  pullDownRefresh: true


# finishPullDown()

  • Details: End the pull-down refresh behavior.


Every time the pullingDown hook is triggered, you should actively call finishPullDown() to tell BetterScroll to be ready for the next pullingDown hook.

# openPullDown(config: PullDownRefreshOptions = {})

  • Details: Turn on the pull-down refresh dynamically.

  • Arguments:

    • { PullDownRefreshOptions } config: Modify the option of the pulldown plugin
    • PullDownRefreshOptions:
    export type PullDownRefreshOptions = Partial<PullDownRefreshConfig> | true
    export interface PullDownRefreshConfig {
      threshold: number
      stop: number


The openPullDown method should be used with closePullDown, because in the process of generating the pulldown plugin, the pull-down refresh action has been automatically monitored.

# closePullDown()

  • Details: Turn off the pull-down refresh dynamically.

# Events

# pullingDown

  • Arguments: None
  • Trigger: A pullingDown event is fired when the top pull-down distance is greater than the threshold value after touchend.


After the pull-down refresh action is detected, the consumption opportunity of the pullingDown hook is only once, so you need to call finishPullDown() to tell BetterScroll to provide the next consumption opportunity of the pullingDown event.

# enterThreshold 2.4.0

  • Arguments: None
  • Trigger: when pulldown is in the moving state and enters threshold area.

# leaveThreshold 2.4.0

  • Arguments: None
  • Trigger: when pulldown is in the moving state and leaves threshold area.