Guide · Open source

How to use better-scroll: install, set up and scroll lists

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

better-scroll is a JavaScript plugin that makes a fixed-height container scroll its content on mobile web pages, with PC support also mentioned in its README. This guide shows you how to install it, set up the HTML structure it expects, and avoid the most common problem, where content will not scroll. By the end you will be able to add a working scrollable list to a page and know where to look when something goes wrong.

better-scrollustbhuangyi/better-scroll · ★ 16.4k · MIT Install options & downloads

Quick start

1Install the package. Run npm install better-scroll -S for the full-featured build, or npm install @better-scroll/core for the core only.
2Add the wrapper and content. Create a wrapper element with a fixed height and put the scrolling content as its first child.
3Import better-scroll. Import BetterScroll from 'better-scroll' or BScroll from '@better-scroll/core' in your script.
4Initialize the scroll. Create a new instance and pass the wrapper selector or DOM element, plus any options you need.
5Add plugins if needed. Import a plugin such as PullUp and enable its option, for example pullUpLoad, in the options object.
6Check the height. If the content does not scroll, confirm the wrapper has a fixed height and the content is taller than it.

Install better-scroll with npm or the CDN

The README lists two packages. The full-featured version is installed with npm install better-scroll -S, which the README describes as 2.x. If you only need the core scroll, install @better-scroll/core instead. The prerequisites named in the source are Node.js and npm or yarn for the npm install.

The README also shows CDN links for both builds, using unpkg. Use these if you are not running a build step.

Full-featured: better-scroll (import BetterScroll from 'better-scroll')
Core only: @better-scroll/core (import BScroll from '@better-scroll/core')

npm install better-scroll -S

npm install @better-scroll/core

Understand the wrapper and content structure

better-scroll needs a fixed-height wrapper element. Its first child is the element that scrolls. The README says that the height of this content grows with its contents, and that it only scrolls once it is taller than the wrapper.

Other elements placed inside the wrapper are ignored for scrolling, so you can keep other DOM nodes there. For v2.0.4 and later, the README says you can choose the scrolling element with the specifiedIndexAsContent option.

The wrapper must have a fixed height. Without it, the content has no boundary to scroll within.
The content must be the first child of the wrapper, unless you use specifiedIndexAsContent.

<div class="wrapper">
  <ul class="content">
    <li>...</li>
    <li>...</li>
  </ul>
</div>

Initialize better-scroll on the wrapper

Pass the wrapper to the constructor. The README shows the core version with a query selector string, and notes that the constructor also accepts a plain DOM object. Both forms are shown in the source.

The full-featured package accepts options such as movable and zoom. The core example passes an empty options object.

import BScroll from '@better-scroll/core'
let wrapper = document.querySelector('.wrapper')
let scroll = new BScroll(wrapper)

// full-featured build
import BetterScroll from 'better-scroll'
let bs = new BetterScroll('.wrapper', {
  movable: true,
  zoom: true
})

Fix the common problem: content does not scroll

The README names this as the most common problem: the content does not scroll after initialization. Its explanation is that the wrapper must be shorter than the content. If the wrapper's height is not fixed, or the content fits inside it, there is nothing to scroll.

Check the wrapper's height, check that the scrolling element is the first child, and confirm the content is taller than the wrapper.

Give the wrapper a fixed height in CSS.
Make sure the scrolling element is the first child of the wrapper.
Confirm the content is taller than the wrapper, otherwise no scrolling is needed.

Add plugins for extra behaviour

The README says plugins extend the core scroll. Its example enables pull-up loading by importing the PullUp plugin and setting pullUpLoad to true in the options. The full list is on the plugins page of the docs linked from the README.

import BScroll from '@better-scroll/core'
import PullUp from '@better-scroll/pull-up'

let bs = new BScroll('.wrapper', {
  pullUpLoad: true
})

Use better-scroll with Vue or other MVVM frameworks

The README has a section on MVVM frameworks and links to an article by the author about using better-scroll with Vue, written in Chinese. It also mentions cube-ui as a mobile UI library implemented with Vue. The README asks others to share their experience with other frameworks, so it does not provide a full guide for each one.

What people use it for

Scrolling long lists in a mobile web page inside a fixed-height panel.
Migrating an existing iscroll setup, since the README says its APIs are largely compatible.
Adding pull-up loading to a list with the PullUp plugin.
Building custom scroll containers in Vue or another MVVM framework.

Frequently asked questions

Is better-scroll free to use?

better-scroll is released under the MIT licence, according to the project listing. The MIT licence generally allows use, modification and distribution, but check the licence file in the repository for the full terms.

Does better-scroll need other dependencies?

The README states that better-scroll is implemented in plain JavaScript and is dependency free. To install it you need Node.js and npm or yarn.

Why won't my content scroll with better-scroll?

The README says this is the most common problem. Make sure the wrapper has a fixed height, the scrolling content is its first child, and the content is taller than the wrapper.

Is better-scroll a replacement for iscroll?

The README says better-scroll is inspired by iscroll and its APIs are compatible with iscroll on the whole. It also adds some features and performance work, so teams migrating from iscroll may find it a close match.

Should I use better-scroll or native browser scrolling?

If your page only needs the browser's built-in scroll bars, better-scroll is probably unnecessary, since the browser already handles basic scrolling. Use it when you need a custom scrolling container with extra behaviour.

Is version 1.x still supported?

No. The README says 1.x is not maintained and recommends migrating to the current version as soon as possible.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

better-scroll suits front-end developers who need a custom scrolling container for mobile web lists, especially teams moving from iscroll or working with Vue. If you only need normal browser scrolling, or you do not write JavaScript, pick the native browser behaviour or a higher-level tool instead. Comparable projects named in the analysis include iscroll, Swiper and Locomotive Scroll.

Install options & downloads