Improved and extended interface for smooth DOM element scrolling.
Native scrolling APIs are horrendous when using behavior: 'smooth'
because when scrollBy
is called while previous one is still animating, it starts animating from the current position, not from the target of the ongoing animation. This effectively eats up all but the last call when this method is called shortly one after another, resulting in unresponsive, and downright broken scrolling.
Features:
- Tiny, ~2KB min, ~1KB gz.
- Configurable scrolling friction coefficient.
- Can take over native mouse wheel (to match scrolling friction).
- Ability to flip wheel direction: vertical scrolling will scroll element horizontally.
- Scroll gliding, useful for implementing "scroll while cursor hovers edge".
- Scroll to/by and gliding can all be called while others are still active, everything works together seamlessly.
npm install element-scroller
import {makeScroller} from 'element-scroller';
const container = document.getElementById('container');
const scroller = makeScroller(container);
scroller.scrollBy({left: 100, top: 200, friction: 0.2});
scroller.scrollTo({top: 500});
scroller.glide({top: -100}); // up
scroller.stop(); // stop gliding or any other ongoing scrolling
scroller.dispose(); // unbinds everything and makes all methods impotent
function makeScroller(element: HTMLElement, options: Options): ElementScroller;
Any DOM HTML Element.
interface Options {
/**
* Coefficient of friction between 0 and 1, where 0 means infinite, and 1
* means instant animations. Default: 0.2
*/
friction: number;
/**
* Wether to take over wheel scrolling.
*/
handleWheel: boolean;
/**
* Wether vertical scrolls should scroll the element horizontally, and vice
* versa.
*/
flipWheel: boolean;
/**
* Coefficient of friction to use when wheel scrolling. Default: 0.25
*/
wheelFriction: number;
}
See Scroller below.
interface Scroller {
readonly element: HTMLElement;
flipWheel: boolean;
friction: number;
wheelFriction: number;
scrollTo(options: ScrollOptions): void;
scrollBy(options: ScrollOptions): void;
glide(options: Partial<Position>): void;
stop(): void;
dispose(): void;
readonly disposed: boolean;
}
interface Position {
left: number;
top: number;
}
type ScrollOptions = Partial<Position> & {friction?: number};
Type: HTMLElement
readonly
The DOM element this scroller is working with.
Type: boolean
Controls wether wheel scrolling (if handleWHeel
was requested) should be flipped.
Type: number
Default friction to use for scrollBy/scrollTo
when one is not passed.
Type: number
Friction to use when wheel scrolling.
Type: scrollTo(options: ScrollOptions): void
Scroll element to a specific coordinates.
interface ScrollOptions {
left?: number;
top?: number;
friction?: number;
}
You can use Infinity
for left
and top
to scroll to the end.
Type: scrollBy(options: ScrollOptions): void
Scroll element by an amount of pixels.
interface ScrollOptions {
left?: number;
top?: number;
friction?: number;
}
Type: glide(options: GlideOptions): void
Scroll element continuously in linear motion by configured number of pixels per second until stop()
is called.
interface GlideOptions {
left?: number;
top?: number;
}
Use negative numbers to scroll back.
Type: stop(): void
Stops gliding or any other ongoing scrolling.
Type: dispose(): void
Stops any ongoing animation, unbinds everything, and makes all methods impotent.
Type: boolean
readonly
Wether this scroller was already disposed.