base-scroll

In the design of BetterScroll 2.0, we abstracted the core scrolling part, which is the smallest unit of use of BetterScroll. The compression volume is nearly one-third smaller than 1.0. You may only need to complete a pure scrolling, then just import this library as follows:

  npm install @better-scroll/core --save

  import BScroll from '@better-scroll/core'
  const bs = new BScroll('.div')

Get started

BetterScroll has a variety of scroll modes.

• vertical scroll

  <template>
    <div class="core-container">
      <div class="scroll-wrapper" ref="scroll">
        <div class="scroll-content">
          <div class="scroll-item" v-for="(item, index) in emojis" :key="index" @click="clickHandler(item)">{{item}}</div>
        </div>
      </div>
    </div>
  </template>

  <script type="text/ecmascript-6">
    import BScroll from '@better-scroll/core'
  
    export default {
      data () {
        return {
          emojis: [
            '😀 😁 😂 🤣 😃',
            '😄 😅 😆 😉 😊',
            '😫 😴 😌 😛 😜',
            '👆🏻 😒 😓 😔 👇🏻',
            '😑 😶 🙄 😏 😣',
            '😞 😟 😤 😢 😭',
            '🤑 😲 🙄 🙁 😖',
            '👍 👎 👊 ✊ 🤛',
            '🙄 ✋ 🤚 🖐 🖖',
            '👍🏼 👎🏼 👊🏼 ✊🏼 🤛🏼',
            '☝🏽 ✋🏽 🤚🏽 🖐🏽 🖖🏽',
            '🌖 🌗 🌘 🌑 🌒',
            '💫 💥 💢 💦 💧',
            '🐠 🐟 🐬 🐳 🐋',
            '😬 😐 😕 😯 😶',
            '😇 😏 😑 😓 😵',
            '🐥 🐣 🐔 🐛 🐤',
            '💪 ✨ 🔔 ✊ ✋',
            '👇 👊 👍 👈 👆',
            '💛 👐 👎 👌 💘',
            '👍🏼 👎🏼 👊🏼 ✊🏼 🤛🏼',
            '☝🏽 ✋🏽 🤚🏽 🖐🏽 🖖🏽',
            '🌖 🌗 🌘 🌑 🌒',
            '💫 💥 💢 💦 💧',
            '🐠 🐟 🐬 🐳 🐋',
            '😬 😐 😕 😯 😶',
            '😇 😏 😑 😓 😵',
            '🐥 🐣 🐔 🐛 🐤',
            '💪 ✨ 🔔 ✊ ✋',
            '👇 👊 👍 👈 👆',
            '💛 👐 👎 👌 💘'
          ]
        }
      },
      mounted() {
        this.init()
      },
      beforeDestroy() {
        this.bs.destroy()
      },
      methods: {
        init() {
          this.bs = new BScroll(this.$refs.scroll, {
            probeType: 3,
            click: true
          })
          this.bs.on('scrollStart', () => {
            console.log('scrollStart-')
          })
          this.bs.on('scroll', ({ y }) => {
            console.log('scrolling-')
          })
          this.bs.on('scrollEnd', (pos) => {
            console.log(pos)
          })
        },
        clickHandler (item) {
          window.alert(item)
        }
      }
    }
  </script>

  <style lang="stylus" rel="stylesheet/stylus" scoped>
  
  .core-container
    .scroll-wrapper
      height 400px
      position relative
      overflow hidden
      .scroll-item
        height 50px
        line-height 50px
        font-size 24px
        font-weight bold
        border-bottom 1px solid #eee
        text-align center
        &:nth-child(2n)
          background-color #f3f5f7
        &:nth-child(2n+1)
          background-color #42b983
  </style>

  WARNING

  BetterScroll dispatches the scroll event in real time, which requires setting probeType to 3.

• Horizontal scroll

  <template>
    <div class="horizontal-container">
      <div class="scroll-wrapper" ref="scroll">
        <div class="scroll-content">
          <div class="scroll-item" v-for="(item, index) in emojis" :key="index">{{item}}</div>
        </div>
      </div>
    </div>
  </template>

  <script type="text/ecmascript-6">
    import BScroll from '@better-scroll/core'
  
    export default {
      data () {
        return {
          emojis: [
            '👉🏼 😁 😂 🤣 👈🏼',
            '😄 😅 😆 😉 😊',
            '😫 😴 😌 😛 😜',
            '👆🏻 😒 😓 😔 👇🏻',
            '😑 😶 🙄 😏 😣',
            '😞 😟 😤 😢 😭',
            '🤑 😲 ☹️ 🙁 😖',
            '👍 👎 👊 ✊ 🤛',
            '☝️ ✋ 🤚 🖐 🖖',
            '👍🏼 👎🏼 👊🏼 ✊🏼 🤛🏼',
            '☝🏽 ✋🏽 🤚🏽 🖐🏽 🖖🏽',
            '🌖 🌗 🌘 🌑 🌒'
          ]
        }
      },
      mounted() {
        this.init()
      },
      beforeDestroy() {
        this.bs.destroy()
      },
      methods: {
        init() {
          this.bs = new BScroll(this.$refs.scroll, {
            scrollX: true,
            probeType: 3 // listening scroll event
          })
          this.bs.on('scrollStart', () => {
            console.log('scrollStart-')
          })
          this.bs.on('scroll', ({ y }) => {
            console.log('scrolling-')
          })
          this.bs.on('scrollEnd', () => {
            console.log('scrollingEnd')
          })
        }
      }
    }
  </script>

  <style lang="stylus" rel="stylesheet/stylus" scoped>
  
  .horizontal-container
    .scroll-wrapper
      position relative
      width 90%
      margin 80px auto
      white-space nowrap
      border 3px solid #42b983
      border-radius 5px
      overflow hidden
      .scroll-content
        display inline-block
      .scroll-item
        height 50px
        line-height 50px
        font-size 24px
        display inline-block
        text-align center
        padding 0 10px
  </style>

  WARNING

  BetterScroll achieves horizontal scrolling, which is more demanding for CSS. First you need to make sure that the wrapper doesn't wrap, and the display of content is inline-block.

  .scroll-wrapper
    // ...
    white-space nowrap
  .scroll-content
    // ...
    display inline-block
  

• freeScroll（Horizontal and vertical scroll simultaneously）

  <template>
    <div class="free-scroll-container">
      <div class="free-scroll-wrapper">
        <div class="scroll-wrapper" ref="wrapper">
          <div class="scroll-content">
            <p>
              Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
          </div>
        </div>
      </div>
    </div>
  </template>

  <script>
    import BScroll from '@better-scroll/core'
    export default {
      mounted () {
        this.init()
      },
      methods: {
        init () {
          this.bs = new BScroll(this.$refs.wrapper, {
            freeScroll: true,
            bounce: {
              bottom: false,
              left: false,
              right: false,
              top: false
            }
          })
        }
      }
    }
  </script>

  <style lang="stylus" scoped>
  .free-scroll-container
    position: relative
    width: 100%
    height: 100%
    .free-scroll-wrapper
      position: relative
      width: 100%
      height: 100%
      border: 1px solid rgb(96, 108, 113)
      box-sizing: border-box
      .scroll-wrapper
        position: absolute
        top: 0
        left: 0
        right: 0
        bottom: 0
        overflow: hidden
        .scroll-content
          background-color: #efeff4
          width: 1500px
          height: 1000px
          p
            font-size: 16px
            padding: 20px
            line-height: 200%
            margin: 0
  </style>

Dynamic Content 2.0.4

For the 2.0.4 version, it has the ability to detect content becoming other elements, you can check the following example.

<template>
  <div class="core-dynamic-content-container">
    <div class="scroll-wrapper" ref="scroll">
      <div class="scroll-content c1" key="1" v-if="!switcher">
        <div class="scroll-item" v-for="n in nums1" :key="n">{{n}}</div>
      </div>
      <div class="scroll-content c2" key="2" v-else>
        <div class="scroll-item" v-for="n in nums2" :key="n">{{nums2 - n + 1}}</div>
      </div>
    </div>
    <button class="btn" @click="handleClick">switch content element</button>
  </div>
</template>

<script type="text/ecmascript-6">
  import BScroll from '@better-scroll/core'

  export default {
    data () {
      return {
        nums1: 30,
        nums2: 60,
        switcher: false
      }
    },
    mounted() {
      this.init()
    },
    beforeDestroy() {
      this.bs.destroy()
    },
    methods: {
      handleClick() {
        this.switcher = !this.switcher
        // wait for Vue rerender
        this.$nextTick(() => {
          this.bs.refresh()
        })
      },
      init() {
        this.bs = new BScroll(this.$refs.scroll, {
          probeType: 3
        })
        this.bs.on('contentChanged', (content) => {
          console.log('--- newContent ---')
          console.log(content)
        })
        this.bs.on('scroll', () => {
          console.log('scrolling-')
        })
        this.bs.on('scrollEnd', () => {
          console.log('scrollingEnd')
        })
      }
    }
  }
</script>

<style lang="stylus" scoped>

.core-dynamic-content-container
  text-align center
  .scroll-wrapper
    height 300px
    overflow hidden
    .scroll-item
      height 50px
      line-height 50px
      font-size 24px
      font-weight bold
      border-bottom 1px solid #eee
      text-align center
      &:nth-child(2n)
        background-color #f3f5f7
      &:nth-child(2n+1)
        background-color #42b983
	.btn
		margin 40px auto
		padding 10px
		color #fff
		border-radius 4px
		font-size 20px
		background-color #666    
</style>

specifiedIndexAsContent 2.0.4

For the 2.0.4 version, you can specify a child of wrapper as content. In previous versions, BetterScroll would only process the first child element of the wrapper. For details.

<template>
  <div class="core-specified-content-container">
    <div class="scroll-wrapper" ref="scroll">
      <div class="ignore-content">
        The Blue area is not taken as BetterScroll's content
      </div>
      <div class="scroll-content">
        <div class="scroll-item" v-for="n in nums" :key="n">{{n}}</div>
      </div>
    </div>
  </div>
</template>

<script type="text/ecmascript-6">
  import BScroll from '@better-scroll/core'

  export default {
    data () {
      return {
        nums: 30
      }
    },
    mounted() {
      this.init()
    },
    beforeDestroy() {
      this.bs.destroy()
    },
    methods: {
      init() {
        window.bs = this.bs = new BScroll(this.$refs.scroll, {
          specifiedIndexAsContent: 1,
          probeType: 3
        })
        this.bs.on('scroll', () => {
          console.log('scrolling-')
        })
        this.bs.on('scrollEnd', () => {
          console.log('scrollingEnd')
        })
      }
    }
  }
</script>

<style lang="stylus" scoped>

.core-specified-content-container
  text-align center
  .scroll-wrapper
    height 400px
    overflow hidden
    border 1px solid #42b983
    .ignore-content
      padding 20px
      color white
      font-size 20px
      font-weight bold
      background-color #2c3e50
    .scroll-item
      height 50px
      line-height 50px
      font-size 24px
      font-weight bold
      border-bottom 1px solid #eee
      text-align center
      &:nth-child(2n)
        background-color #f3f5f7
      &:nth-child(2n+1)
        background-color #42b983
</style>

quadrant 2.3.0

For the 2.3.0 version, If the parent element or ancestor element of BetterScroll wrapper DOM rotates, you can use the quadrant option to modify the user's interactive behavior.

• Vertical becomes Horizontal

<template>
  <div class="vertical-rotated-container">
    <div class="description">Horizontal layout via CSS</div>
    <div class="scroll-wrapper" ref="scroll">
      <div class="scroll-content">
        <div class="scroll-item" v-for="num in nums" :key="num">{{num}}</div>
      </div>
    </div>
  </div>
</template>

<script type="text/ecmascript-6">
  import BScroll from '@better-scroll/core'

  export default {
    data () {
      return {
        nums: 8
      }
    },
    mounted() {
      this.init()
    },
    beforeDestroy() {
      this.bs.destroy()
    },
    methods: {
      init() {
        this.bs = new BScroll(this.$refs.scroll, {
          // v2.3.0
          quadrant: 2 // rotate90
        })
      }
    }
  }
</script>

<style lang="stylus" rel="stylesheet/stylus" scoped>

/* horizontal by CSS */
.scroll-wrapper
  transform rotate(90deg)
.vertical-rotated-container
  .description
    text-align center
  .scroll-wrapper
    height 250px
    width 100px
    position relative
    overflow hidden
    margin 0 auto
    border 1px solid #ccc
    .scroll-item
      height 100px
      width 100px
      line-height 100px
      font-size 24px
      font-weight bold
      text-align center
      &:nth-child(2n)
        background-color #f3f5f7
      &:nth-child(2n+1)
        background-color #42b983
</style>

• Horizontal scroll flipped

<template>
  <div class="horizontal-rotated-container">
    <div class="description">Flipping layout via CSS</div>
    <div class="scroll-wrapper" ref="scroll">
      <div class="scroll-content">
        <div class="scroll-item" v-for="num in nums" :key="num">{{num}}</div>
      </div>
    </div>
  </div>
</template>

<script type="text/ecmascript-6">
  import BScroll from '@better-scroll/core'

  export default {
    data () {
      return {
        nums: 8
      }
    },
    mounted() {
      this.init()
    },
    beforeDestroy() {
      this.bs.destroy()
    },
    methods: {
      init() {
        this.bs = new BScroll(this.$refs.scroll, {
          scrollX: true,
          scrollY: false,
          // v2.3.0
          quadrant: 3 // rotate180
        })
      }
    }
  }
</script>

<style lang="stylus" rel="stylesheet/stylus" scoped>

/* flipping by CSS */
.scroll-wrapper
  transform rotate(180deg)
.horizontal-rotated-container
  .description
    margin-bottom 40px
    text-align center
  .scroll-wrapper
    height 100px
    width 250px
    position relative
    overflow hidden
    white-space nowrap
    margin 0 auto
    border 1px solid #ccc
    .scroll-content
      display inline-block
    .scroll-item
      height 100px
      width 100px
      line-height 100px
      font-size 24px
      font-weight bold
      text-align center
      display inline-block
      &:nth-child(2n)
        background-color #f3f5f7
      &:nth-child(2n+1)
        background-color #42b983
</style>

Warm Tips

TIP

If there is any situation where scrolling is not possible, you should first check if the height/width of the content element is greater than the height/width of the wrapper. This is a prerequisite for content to scroll.

If the content has an image, it may happen that the image has not been downloaded when the DOM element is rendered, so the height of the content element is less than expected, and the scrolling is not normal. At this point you should call the bs.refresh method after the image has been loaded, such as the onload event callback, which will recalculate the latest scrolling size.