Design means consistency

Good web design is characterized by a well conceived color scheme, an interesting layout, a catchy navigation, the choice of appropriate typefaces and an on-topic preparation of content. A professional website is an artistic synthesis that delivers important information and finally convinces by consistency. However, a website is always viewed through a web browser which uses system-specific functionalities or embeds its own control elements. Beside the outer window chrome that includes tabs, the address bar and the window buttons, the scrollbar is the only remaining element inside the website frame that is not styled by web designers normally. If you would enter fullscreen when surfing on a website, the scrollbar would still look system-specific.

This is where CustomScrollbar.js comes in: this small script allows you to style the vertical scrollbar of the entire web page by using CSS. You can adjust the appearance of the scrollbar background and the scroll thumbs that include arrows for scrolling up and down. The script is used right here on this page, just have a look at the right side of the screen.

Facts

Here are some key facts that should provide a short overview of what CustomScrollbar.js is and how it works:

  • Easy to use and simple configuration
  • Fully customizable via CSS
  • Usage of browsers' default scroll behavior
  • Cross-browser and multi-system support
  • Native scrolling on mobile devices
  • No external dependencies

As you can see the script makes use of the default browser scroll behavior. This means that no kinetic scrolling or real-time calculations are needed. CustomScrollbar.js simply hides the native window scrollbars and adds a custom overlay to the web page. There are some hooks and optimizations for Chrome and Internet Explorer but this is also one of the strengths of the script: it's well tested on different platforms and browsers including Windows, Mac OS X, iOS, Android and mobile devices like Android smartphones and tablets, iPhone/iPad and Microsoft Surface. For mobile devices there is a small device detection which disables CustomScrollbar.js since you normally want to make use of the native mobile scrolling on that devices.

Usage

After downloading the package from GitHub, you just need to include the JavaScript file on your site and call it at the end of the HTML code inside your <body> element (or by using jQuery's $(document).ready).

var scrollbar = CustomScrollbar({
    thumbHeight: 40
});

So basically this is the only configuration you need. The thumbHeight property defines the height of the scroll thumb in percentage, so in this example it gets the height of 40% of the window height. There are two more optional parameters called bodyPaddingRight and selectors. This allow you to add some space on the right side or change the default CSS ID selectors that are set to scrollthumb and scrollbar by default.

This leads to the final CSS configuration of the scrollbar. The code of this website looks like this:

html::-webkit-scrollbar {
    width:0 !important;
}

#scrollbar {
    position:absolute;
    top:0;
    right:0;
    height:100%;
    width:20px;
    background-color:#272b2f;
    z-index:2;
}

#scrollthumb {
    position:absolute;
    top:0;
    right:0;
    width:20px;
    background:#e94525;
}

#scrollthumb:before {
    position:absolute;
    top:0;
    left:0;
    width:20px;
    height:20px;
    background-image:url("../assets/arrows.png");
    background-repeat:no-repeat;
    background-position:0 0;
    content:"";
    display:block;
}

#scrollthumb:after {
    position:absolute;
    bottom:0;
    left:0;
    width:20px;
    height:20px;
    background-image:url("../assets/arrows.png");
    background-repeat:no-repeat;
    background-position:0 -20px;
    content:"";
    display:block;
}

So there is a necessary part for WebKit browsers and the configuration of the scrollbar itself. As you can see, the custom scrollbar simply consists of a collection of absolute positioned elements and pseudo-elements for the up/down arrows. In this example there are transparent PNG images that are used for the appearance of the arrows but you could also use a custom icon font or SVG.

One last thing is to mention that the scrollbar should at least have a width of 18px since the native scrollbar in Firefox on Windows is still fully visible but gets overlapped of the custom scrollbar. It's also important to know that the script only generates a vertical scrollbar since it was developed with responsiveness in mind. The era of horizontal scrollbars has come to an end so it shouldn't be necessary to support this element anymore.

Examples

Beside this website there are some other websites where CustomScrollbar.js is being used. You can have a look at them to see how it integrates: