Skip to content
Get packs

better-scroll

A JavaScript library that adds smooth, touch-friendly scrolling to mobile web pages.

GitHub Download v2.4.2
Stars
16.4k
Forks
2.6k
Licence
MIT
Language
TypeScript
Last update
2.4 years ago
Type
Library

No commits in over a year — check for forks or alternatives before adopting.

What it is

BetterScroll is a dependency-free JavaScript plugin for handling scrolling in mobile web pages, with PC support also mentioned. It is based on the iscroll library and its APIs are described as largely compatible with iscroll, with added features and performance work. Developers use it when a fixed-height container needs to scroll its content, such as long lists.

  • Make a long product or contact list scroll smoothly inside a fixed-height wrapper
  • Add pull-up loading to a list using the official plugins
  • Enable zoom or movable behaviour on a container using options such as zoom and movable

Great for

  • Front-end developers building mobile web lists or scrollable panels
  • Teams migrating from iscroll who want a compatible API with extra features
  • Developers using Vue or other MVVM frameworks who need custom scroll containers

Not ideal for

  • Projects that only need native browser scrolling, since the browser already handles basic scroll bars (the README's explanation implies this)
  • Non-developers, because it requires writing JavaScript and HTML structure
  • Anyone needing version 1.x, which the README says is no longer maintained
Step-by-step guide: how to use better-scrollInstall, first run, examples, tips and FAQs
better-scroll vs VUXbetter-scroll vs Swiper

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js and npm or yarn (for npm install)

    Install full-featured version (2.x)

    npm install better-scroll -S

    Install core only

    npm install @better-scroll/core
  2. 2

    Run it

    • Create a wrapper div with a fixed height and put a single content element as its first child.
    • Import BScroll from @better-scroll/core or BetterScroll from better-scroll.
    • Create an instance with the wrapper selector, for example new BScroll('.wrapper', {}).
    • Check that the content is taller than the wrapper, since content only scrolls when it overflows.
  3. 3

    Get the most out of it

    • Use the specifiedIndexAsContent option (v2.0.4 and later) if the scrolling element is not the first child.
    • Add official plugins such as pull-up loading via the pullUpLoad option.
    • Use the CDN builds from unpkg for quick prototyping without a build step.
    • Read the official docs site for the full list of options and plugins.

Downloads

Source code (.zip)dev branch · straight from GitHubRelease v2.4.2Release notes and sourceOfficial website & docsbetter-scroll.github.io/docs/en-US/

Strengths

  • Dependency-free plain JavaScript, according to the README
  • API designed to be compatible with iscroll
  • Modular design: a core package plus optional plugins

Trade-offs

  • Requires a fixed-height wrapper with the scrolling content as its first child, which is a common source of confusion
  • Documentation for many options is referenced externally rather than in the README
  • The README is truncated and the last push date is June 2024, so current maintenance status is unclear

How it compares

ProjectStarsTypeLevelUpdatedBest for
better-scroll (this)16.4kLibraryintermediate2.4 years agoFront-end developers building mobile web lists or scrollable panels
iscroll12.8kLibraryintermediate7.9 years agoWeb developers who need custom scrolling behavior inside a page element
swiper41.9kLibraryintermediate7 days agoFront-end developers adding a swipeable slider or image gallery to a website
vux17.4kLibraryintermediate4 months agoDevelopers building mobile web pages with Vue 2
quasar27.2kFrameworkintermediate18 days agoDevelopers already familiar with Vue.js
NativeScript25.7kFrameworkintermediate4 days agoJavaScript or TypeScript developers who want to build native iOS or Android apps

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.