Dakwamine

The road to custom scrollbars

Reminiscing.

I am currently working on a website for a video game reviews project I have had with an old friend of mine (FuuDoh). Obviously, I have switched to Drupal to get a result quicker than what I would get with the PHP only solution I have been working on a few years ago (it was fun though).

One of the main problems I have came across while theming was to give a consistent look across various web browsers (and now devices—mobile and tablets were not as much a concern as nowadays). Bootstrap was not as popular as it is now and it saved a lot of my time for my current project. But it did not fix one of the other problems I am still experiencing today: scrollbars.

I hate how they cannot be themed natively. In an overflow: auto setting, they push all the content by their width when they appear, potentially changing the height of the content; which is not very elegant in my opinion. You cannot change their size, nor their color.

With the big grow in the recent years in the JS scene, we have now good enough JS libraries which gives developers means to achieve better, cross-browser, cross-platform scrollbars.

I have checked a Drupal 8 module, scrollbar, which unfortunately does not work well (or was misconfigured). The bars were not refreshing when the browser window is resized. Maybe I’ll post an issue on the Drupal module tracker, but it does not seem to be the fault of the module. But there was one big drawback with the library used by this module (jScrollPane): the scroll behaviour is not the native browser’s scroll behaviour. You will not get any ease in the scroll animation (or maybe you could have it by configuring the library).

Then I have searched a little and found two candidates:

• simplebar: https://grsmto.github.io/simplebar/
• OverlayScrollbars: https://kingsora.github.io/OverlayScrollbars/

Both are JS libraries which use native browser’s capabilities to scroll the content; you will not feel anything different between normal scrollbars and those custom ones, which is perfect! The first library is currently (May 2018) used on Twitch.tv. I have not tested it, but it claims to be cross browser. But it also claims that there may be some performance impact when used on the body element. That is why I chose OverlayScrollbars, which is recommended by simplebar in its documentation by the way.

Relieved.

After having spent some time trying to figure out why it did not work, I have finally got it working nicely with the bootstrap+sass theme! The implementation is in fact trivial for a Drupal themer but here are the steps to achieve it.

Steps

1. Download the OverlayScrollbars library (link to releases) and extract the files to the themes/custom/THEMENAME/libraries/OverlayScrollbars directory (create necessary directories). This OverlayScrollbars folder must contain the css and js directories which came from the zip (remove any wrapping directory).
2. Create a file named trigger.js at this location: themes/custom/THEMENAME/js/overlayscrollbars/trigger.js
3. Add this to the file:

   (function ($) {
       //The passed argument has to be at least a empty object or a object with your desired options
       $('body').overlayScrollbars({ });
       // .overlayScrollbars({ }) must be appended on any single element you want a scrollbar.
       $('nav.article-list').overlayScrollbars({ });
   }(jQuery));
   
   

4. The THEMENAME.libraries.yml of your subtheme may look like this (the overlayscrollbars is what we care about):

   framework:
     css:
       theme:
         css/style.css: {}
     js:
       bootstrap/assets/javascripts/bootstrap/affix.js: {}
       bootstrap/assets/javascripts/bootstrap/alert.js: {}
       bootstrap/assets/javascripts/bootstrap/button.js: {}
       bootstrap/assets/javascripts/bootstrap/carousel.js: {}
       bootstrap/assets/javascripts/bootstrap/collapse.js: {}
       bootstrap/assets/javascripts/bootstrap/dropdown.js: {}
       bootstrap/assets/javascripts/bootstrap/modal.js: {}
       bootstrap/assets/javascripts/bootstrap/tooltip.js: {}
       bootstrap/assets/javascripts/bootstrap/popover.js: {}
       bootstrap/assets/javascripts/bootstrap/scrollspy.js: {}
       bootstrap/assets/javascripts/bootstrap/tab.js: {}
       bootstrap/assets/javascripts/bootstrap/transition.js: {}
   overlayscrollbars:
     js:
       libraries/OverlayScrollbars/js/jquery.overlayScrollbars.js: {}
       js/overlayscrollbars/trigger.js: {}
     dependencies:
       - core/jquery
   

5. Add an import directive in the _overrides.scss, right after the other imports (remember, I am using sass; if you use less, you have to adapt it):

   // Custom scrollbars library.
   @import "../libraries/OverlayScrollbars/css/OverlayScrollbars.css";
   

6. Compile the scss.
7. Add this hook in your THEMENAME.theme:

   /**
    * Implements hook_page_attachments_alter().
    *
    * {@inherit}
    */
   function THEMENAME_page_attachments_alter(array &$page) {
     $page['#attached']['library'][] = 'THEMENAME/overlayscrollbars';
   }
   
   

8. Rebuild the Drupal cache: drush cr.

Additional information

• Tested on Drupal 8.5.3.
• Tested on official standard Bootstrap theme, sass flavor.
• The original install guide is here: https://kingsora.github.io/OverlayScrollbars/#!overview. You will also get a list of options on the original guide.
• You can also put the content of the trigger.js file directly into the twig (not tested though); html.html.twig would be a good candidate.