@chapiter/smooth-scrollbar v7.3.2

Smooth Scrollbar

Smooth scrolling in modern browsers.

Table of Contents

• Install
• Browser Compatibility
• Demo
• Why is native scrolling slow?
• Usage
• Available Options for Scrollbar
• DOM Structure
• APIs
  • Static Methods
    • Scrollbar.init()
    • Scrollbar.initAll()
    • Scrollbar.has()
    • Scrollbar.get()
    • Scrollbar.getAll()
    • Scrollbar.destroy()
    • Scrollbar.destroyAll()
  • Instance Properties and Methods
    • scrollbar.targets
    • scrollbar.offset
    • scrollbar.limit
    • scrollbar.scrollTop
    • scrollbar.scrollLeft
    • scrollbar.wheelReversed
    • scrollbar.reverseWheel()
    • scrollbar.update()
    • scrollbar.getSize()
    • scrollbar.setPosition()
    • scrollbar.scrollTo()
    • scrollbar.addListener()
    • scrollbar.scrollIntoView()
    • scrollbar.isVisible()
    • scrollbar.infiniteScroll()
    • scrollbar.stop()
    • scrollbar.destroy()
• Common mistakes
• FAQ
• Related Projects

Install

Via npm:

npm install smooth-scrollbar --save

Via bower:

bower install smooth-scrollbar --save

Browser Compatibility

Demo

http://idiotwu.github.io/smooth-scrollbar/

Why is native scrolling slow?

As is explained in this article, browser repaint every frame in scrolling. Less painting is better.

To avoid repainting, I use translate3d in scroll content to create composite layers and force hardware accelerating.

Usage

Smooth scrollbar is defined as an UMD module which named Scrollbar, you can use any loader to load it:

import Scrollbar from 'smooth-scrollbar';

Or get it from window object:

var Scrollbar = window.Scrollbar;

Don't forget to include the stylesheet in your page:

<link rel="stylesheet" href="dist/smooth-scrollbar.css">

There are three ways to tell the plugin which element should be a smooth scrollbar:

1. As an element:

   <scrollbar>...</scrollbar>

2. As an attribute:

   <section scrollbar>...</section>

3. As a data attribute

   <section data-scrollbar>...</section>

Then init all scrollbars:

Scrollbar.initAll(options);

Or you can call Scrollbar.init(elem, options) to manually init the scrollbar:

Scrollbar.init(document.getElementById('my-scrollbar'), options);

Available Options for Scrollbar

Confusing with the option field? Try edit tool here!

DOM Structure

Following is the DOM structure that Scrollbar yields:

<scrollbar>
    <article class="scroll-content">
        your contents here...
    </article>
    <aside class="scrollbar-track scrollbar-track-x">
        <div class="scrollbar-thumb scrollbar-thumb-x"></div>
    </aside>
    <aside class="scrollbar-track scrollbar-track-y">
        <div class="scrollbar-thumb scrollbar-thumb-y"></div>
    </aside>
</scrollbar>

APIs

In this documentation, we are using Scrollbar (in capitalized) to represent the constructor and scrollbar (in lowercase) for the instance object.

Static Methods

Scrollbar.init()

Scrollbar.init(elem, options?): SmoothScrollbar

Initializes a scrollbar on the given element and returns scrollbar instance:

var scrollbar = Scrollbar.init(document.body, { speed: 0.75 });

Scrollbar.initAll()

Scrollbar.init(options): [SmoothScrollbar]

Automatically init scrollbar on all elements refer to the selector scrollbar, [scrollbar], [data-scrollbar], returns an array of scrollbars collection:

<scrollbar> ... </scrollbar>

<article scrollbar> ... </article>

<article data-scrollbar> ... </article>

Scrollbar.initAll(); // [ SmoothScrollbar, SmoothScrollbar, SmoothScrollbar ]

Scrollbar.has()

Scrollbar.has(elem): boolean

Check if scrollbar exists on given element:

Scrollbar.init(document.body);

Scrollbar.has(document.body); // true

Scrollbar.get()

Scrollbar.get(elem): SmoothScrollbar

Get scrollbar on the given element, if no scrollbar instance exsits, return undefined:

var scrollbar = Scrollbar.init(document.body);

Scrollbar.get(document.body) === scrollbar; // true

Scrollbar.get(document.documentElement); // undefined

Scrollbar.getAll()

Scrollbar.getAll(): [SmoothScrollbar]

Return an array that contains all scrollbar instances:

Scrollbar.getAll(); // [ SmoothScrollbar, SmoothScrollbar, ... ]

Scrollbar.destroy()

Scrollbar.destroy(elem): void

Remove scrollbar on the given element.

Scrollbar.destroyAll()

Scrollbar.destroyAll(): void

Remove all scrollbar instances from current page.

Instance Properties and Methods

A scrollbar instance refer to what you get from Scrollbar.init() method:

var scrollbar = Scrollbar.init(elem)

scrollbar.targets

• Type: object

An object that contains main parts of current scrollbar:

{
    container,
    content,
    xAxis: { track, thumb },
    yAxis: { track, thumb }
}

scrollbar.offset

• Type: object

Current scrolling offset:

console.log(scrollbar.offset); // { x: 123, y: 456 }

scrollbar.limit

• Type: object

Max-allowed scrolling distance:

console.log(scrollbar.limit); // { x: 1000, y: 1000 }

scrollbar.scrollTop

• Type: number

Alias for scrollbar.offset.y:

console.log(scrollbar.scrollTop); // 123

console.log(scrollbar.scrollTop === scrollbar.offset.y); // true

scrollbar.scrollLeft

• Type: number

Alias for scrollbar.offset.x:

console.log(scrollbar.scrollLeft); // 456

console.log(scrollbar.scrollLeft === scrollbar.offset.x); // true

scrollbar.wheelReversed

• Type: boolean

Whether event wheel is reversed:

console.log(scrollbar.wheelReversed); // true or false

scrollbar.reverseWheel()

scrollbar.reverseWheel(reverse): void

Invert the axis of the wheel event.

scrollbar.reverseWheel(true);
console.log(scrollbar.reverseWheel); // true

scrollbar.update()

scrollbar.update(async?): void

Forces scrollbar to update metrics.

By default, scrollbars are automatically updated with 100ms debounce (or childList changes if MutationObserver is supported). You can call this method to force an update when you modified contents inside scrollbar:

// append some contents to the scrollbar element...

// force an update
scrollbar.update();

// force an asynchronous update
scrollbar.update(true);

scrollbar.getSize()

scrollbar.getSize(): object

Return the size of scrollbar container element and scroll content element, it may be something like this:

{
    container: {
        width: 600,
        height: 400
    },
    content: {
        width: 1000,
        height: 3000
    }
}

scrollbar.setPosition()

scrollbar.setPosition(x, y): void

Likes the window.scrollTo() method, use this method to set the scrollbar to the given offset without easing:

// limit = { x: 500, y: 500 }
scrollbar.setPosition(100, 100);
console.log(scrollbar.offset); // { x: 100, y: 100 }

If the offset is out of limitation, it will be shrinked:

// limit = { x: 0, y: 100 }
scrollbar.setPosition(1024, 1024);
console.log(scrollbar.offset); // { x: 0, y: 100 }

scrollbar.scrollTo()

scrollbar.scrollTo(x, y, duration?, callback?): void

Scrolls to given position with quadratic easing function:

scrollbar.scrollTo(100, 100, 300, function (scrollbar) {
    // ...
});

scrollbar.addListener()

scrollbar.addListener(listener): void

Since scrollbars will not fire a native scroll event, we need to registers thought scrollbar.addListener() method.

Notice: the callback functions will be invoked in every small scrolling, so be careful not to add time-consuming listeners that will slow down scrolling.

The status object contains following properties:

{
    direction: {
        // scrolling direction compares to the last offset
        x: 'none' | 'right' | 'left',
        y: 'none' | 'up' | 'down',
    },
    offset: {
        // current scrolling offset, equivalent to `scrollbar.offset`
        x: number,
        y: number,
    },
    limit: {
        // max-allowed scrolling distance, equivalent to `scrollbar.limit`
        x: number,
        y: number,
    }
}

scrollbar.scrollIntoView()

scrollbar.scrollIntoView(elem, options?): void

Scrolls the target element into visible area of scrollbar, like DOM method element.scrollIntoView(). This will be helpful when you want to create some anchors.

scrollbar.scrollIntoView(document.getElementById('a-section'), {
    offsetTop: 12,
    offsetLeft: 34,
    onlyScrollIfNeeded: true,
});

scrollbar.isVisible()

scrollbar.isVisible(elem): boolean

Checks if an element is visible in the current view area.

scrollbar.isVisible(document.getElementById('greet'))

scrollbar.infiniteScroll()

scrollbar.infiniteScroll(handler, threshold?): void

This is another useful method when you want to make infinite scrolling. Handlers will be invoked with the status object when you scrolling down over the given threshold:

instance.infiniteScroll(function (status) {
    // ...
}, 100);

scrollbar.stop()

scrollbar.stop(): void

Clears all pending movements and stops scrolling immediately.

// offset = { x: 0, y: 0 }
scrollbar.scrollTo(100, 100);
scrollbar.stop();

console.log(scrollbat.offset); // { x: 0, y: 0 }

scrollbar.destroy()

scrollbar.destroy(): void

Remove this scrollbar instance:

Before:

<section data-scrollbar style="overflow: hidden">
    <article class="scroll-content">
        ...
    </article>

    <aside class="scrollbar-track scrollbar-track-x">
        <div class="scrollbar-thumb scrollbar-thumb-x"></div>
    </aside>
    <aside class="scrollbar-track scrollbar-track-y">
        <div class="scrollbar-thumb scrollbar-thumb-y"></div>
    </aside>
</section>

After:

<section data-scrollbar>
    ...
</section>

Common mistakes

Initialize a scrollbar without a limited width or height

Likes the native scrollbars, a scrollable area means the content insides it is larger than the container itself, for example, a 500*500 area with a content which size is 1000*1000.

Therefore, it necessary to set the width or height for the container element:

#my-scrollbar {
    width: 500px;
    height: 500px;
    overflow: auto;
}

FAQ

How to listen to the scroll event?

Since scrollbars will not fire a native scroll event, we need to registers thought scrollbar.addListener() method:

scrollbar.addListener(function (status) {
    // ...
});

Related Projects

• angular-smooth-scrollbar
• react-smooth-scrollbar

Contributing

• Create an issue with an example on jsbin.com, including latest version of smooth-scrollbar through:

  <link rel="stylesheet" href="https://unpkg.com/smooth-scrollbar@latest/dist/smooth-scrollbar.css">
  
  <script src="https://unpkg.com/smooth-scrollbar@latest/dist/smooth-scrollbar.js"></script>

• Run your forks locally with following steps:

  1. Clone the repo: git clone https://github.com/idiotWu/smooth-scrollbar.git,
  2. Install dependencies: npm run install,
  3. Start server: npm start.

Before making pull requests, make sure you have run npm test!

License

MIT.