Using OverlayScrollbars in my Drupal installation.
How to add OverlayScrollbars to your Drupal 10+ installation
There are several cases why you’d want to change the native browser scrollbars for your website—whether you feel like they take up too much space, want to play around a bit, or simply don’t like how they look. One way to do so is the JavaScript plugin OverlayScrollbars. The maintainer describes the project as
A javascript scrollbar plugin that hides the native scrollbars, provides custom styleable overlay scrollbars, and preserves the native functionality and feel.
In the code blocks I frequently use in my blog, the native scrollbars bothered me because they were too big and clunky in many browsers. Hence, I was looking for a solution to replace them with OverlayScrollbars.
First I tried the Drupal contributed module that should accomplish this. However, when I tried to install the module with composer, I got an error:
Could not find a matching version of package drupal/overlayscrollbars. Check the package spelling, your version constraint and that the package is available in a stability which matches your minimum-stability (dev).Maybe this would have been an easy fix, but I simply decided to implement the scrollbars in my theme instead. Luckily, this turned out to be is a quite simple process. You need two things to accomplish this:
- Add the OverlayScrollbar library to your theme
- Define which native scrollbars should be replaced with OverlayScrollbars
Add the OverlayScrollbar library to your theme
This is a fairly simple task, but depends a bit on how your theme is implemented. You could simply copy the library to a specific location in your theme folder (e.g. [yourtheme]/vendor/OverlayScrollbars), use the NPM package, or add it as an external script.
After doing so, it’s time to tell your theme about the library by adding the following lines to mytheme.libraries.yml:
OverlayScrollbars:
version: 2.11.1
licence: MIT
url: https://github.com/KingSora/OverlayScrollbars
gpl-compatible: true
js:
vendor/KingSora/OverlayScrollbars/browser/overlayscrollbars.browser.es6.min.js: {}
css:
base:
vendor/KingSora/OverlayScrollbars/styles/overlayscrollbars.min.css: {}
dependencies:
- core/drupalMake sure to change the lines accordingly so they fit your theme structure and installed version (you could also leave that line, though).
And now in your mytheme.info.yml (under libraries, where all other libraries are listed as well):
- ooo/OverlayScrollbarsThe title must be the same as in your libraries.yml file. See the Drupal documentation for more info on how to include JavaScript libraries.
This is sufficient for your theme to include the library. Now you must tell your theme what scrollbars should be replaced.
Define which scrollbars should be replaced with OverlayScrollbar
You must initialise OverlayScrollbar per element. To achieve this, you need some additional JavaScript code. Again, depending on how your theme is implemented, this can be achieved in different ways. I simply added a new JavaScript file to my theme, where everything related to OverlayScrollbars goes. To do the same, create a new (empty) JavaScript file and add it to your mytheme.libraries.yml file. I simply added a new line to OverlayScrollbars:
OverlayScrollbars:
version: 2.11.1
licence: MIT
url: https://github.com/KingSora/OverlayScrollbars
gpl-compatible: true
js:
vendor/KingSora/OverlayScrollbars/browser/overlayscrollbars.browser.es6.min.js: {}
js/overlayScrollbars.js: {}
css:
base:
vendor/KingSora/OverlayScrollbars/styles/overlayscrollbars.min.css: {}
dependencies:
- core/drupalNote the new line js/overlayScrollbars.js: {}. Change the location and file name accordingly. Now we edit that file we just created. Remember, you must initialise the scrollbars per element. In my case, the scrollbars should be added to all code blocks. I achieved this with the following code:
(function (Drupal) {
const { OverlayScrollbars } = OverlayScrollbarsGlobal;
// Since OverlayScrollbars is initialised per element, we must loop through all
// "code" paragraphs serparately
let codeParagraphs = document.querySelectorAll('.paragraph--type--code code');
let codeParagraphsArray = [...codeParagraphs];
codeParagraphsArray.forEach(code => {
OverlayScrollbars(code, {});
});
})(Drupal);The first and last line is needed by Drupal to load your function, and setting Drupal (last line) as a dependency. See the documentation for more information.
The second line accesses the OverlayScrollbars API according to the project’s documentation, and allows you to work with it.
The rest of the code defines what elements should be replaced by looping through all .paragraph--type--code code elements, using spread syntax and a forEach loop.
Again, the code must be adapted to suit your needs (whether you want to work with jQuery and add it as a dependency, or simply change the element classes you want to replace, or something entirely different).
That’s it—enjoy your pretty scrollbars!