Scroll

@better-scroll/scroll-bar TouchScroll

Behavior Notes

BetterScroll Mode
- Supports bounce with a more consistent scrollbar appearance
- Content/container changes auto refresh() (configurable via refreshOnContentChange)
Native Mode
- Uses native browser scrolling
- direction maps to overflow-x/y to keep structure consistent
- macOS Safari uses native scrolling directly
- Automatically falls back to native scrolling on macOS + Chromium 145+ (Chromium already supports it natively)
- Set unified=true to force BetterScroll takeover across environments

Runtime Strategy (Priority)

native=true: always use native scrolling (highest priority).
unified=true: always let BetterScroll take over (consistent cross-environment behavior).
Running on macOS Safari: use native scrolling directly.
nativeAutoFallback=true and macOS + Chromium >= 145: auto switch to native scrolling.
Otherwise: use BetterScroll.

Basic Usage

Scroll

Demo loads on client.

Direction and Scrollbar

Scroll (horizontal)

Demo loads on client.

Scroll (bounce + always show scrollbar)

Demo loads on client.

Scroll Chaining (Advanced)

By default inner scrolling does not propagate to the outer container (even at edges). Enable scrollChaining if you want scroll to bubble at the top/bottom.

⚠️ We do not recommend enabling scrollChaining by default. In nested scrolling layouts, it can make users unsure which layer is actually scrolling. Enable it only when parent-child scroll handoff is explicitly required.

Scroll (scroll chaining, advanced)

Demo loads on client.

Use Native Scrolling

If you do not need BetterScroll behavior, switch to native scrolling (keeps the same container structure).

Scroll (native)

Demo loads on client.

Pull-to-Refresh and Load More

Pull-to-refresh: enable pullDownRefresh, listen to @pulling-down, then call finishPullDown() when done.
Load more: enable pullUpLoad, listen to @pulling-up, then call finishPullUp() when done.
In native=true or auto-native fallback mode, events are degraded triggers; pullDownStop only works in BetterScroll mode.

Scroll (pull down + pull up)

Demo loads on client.

API

Props

Prop	Type	Default	Description
`native`	`boolean`	`false`	Description for native.
`unified`	`boolean`	`false`	Force BetterScroll takeover for consistent cross-environment behavior (overrides Safari/Chromium auto-native; `native=true` still wins).
`nativeAutoFallback`	`boolean`	`true`	Controls auto-native fallback on macOS + Chromium `145+`; does not affect the macOS Safari native-first rule.
`noPadding`	`boolean`	`false`	Description for noPadding.
`scrollChaining`	`boolean`	`false`	Allow parent scroll handoff at boundaries; not recommended by default, enable only when nested handoff is explicitly needed.
`direction`	`'vertical' \| 'horizontal' \| 'both'`	`'vertical'`	TextDirection
`scrollbar`	`boolean`	`true`	Description for scrollbar.
`scrollbarFade`	`boolean`	`true`	Description for scrollbarFade.
`scrollbarInteractive`	`boolean`	`true`	Description for scrollbarInteractive.
`scrollbarAlwaysVisible`	`boolean`	`false`	Description for scrollbarAlwaysVisible.
`scrollbarMinSize`	`number`	`18`	Description for scrollbarMinSize.
`probeType`	`0 \| 1 \| 2 \| 3`	`3`	BetterScroll `probeType`
`bounce`	`boolean`	`true`	Description for bounce.
`click`	`boolean`	`true`	Description for click.
`wheel`	`boolean`	`true`	Description for wheel.
`refreshOnContentChange`	`boolean`	`true`	Description for refreshOnContentChange.
`pullDownRefresh`	`boolean \| Record<string, unknown>`	`false`	Text（BetterScroll Text；native TextTrigger）
`pullDownThreshold`	`number`	`70`	Description for pullDownThreshold.
`pullDownStop`	`number`	`56`	Description for pullDownStop.
`pullUpLoad`	`boolean \| Record<string, unknown>`	`false`	TextLoadingText（BetterScroll Text；native TextTrigger）
`pullUpThreshold`	`number`	`0`	Description for pullUpThreshold.
`options`	`Record<string, unknown>`	`{}`	Description for options.

Events

Event	Params	Description
`scroll`	`{ scrollTop: number; scrollLeft: number }`	Description for scroll.
`pulling-down`	-	Description for pulling-down.
`pulling-up`	-	Description for pulling-up.