Skip to main content

I’ve got the task to cut the width of the standard scrollbar to the minimum in the horizontal layered navigation that I made before. For this purpose I plugged jQuery extension called JScrollPane.

You have to use these 3 files to plug the extension:

  • jquery.jscrollpane.css (style file)
  • jquery.jscrollpane.min.js (the extension file)
  • jquery.mousewheel.js (add-on file for the work with a mouse wheel)

The first step is to add these files to the theme catalog. The next one is to “tell” Magento how to use them.

Place the files in the following way:

  • <theme_dir>/web/css/jScrollPane/jquery.jscrollpane.css
  • <theme_dir>/web/js/jScrollPane/jquery.jscrollpane.min.js
  • <theme_dir>/web/js/jScrollPane/jquery.mousewheel.js

Now, it is time to move to the next step: set Magento for the work with these files.

Adding files to the directories is a simple job:

  • <theme_dir>/web/css/jScrollPane/jquery.jscrollpane.css
  • <theme_dir>/web/js/jScrollPane/jquery.jscrollpane.min.js
  • <theme_dir>/web/js/jScrollPane/jquery.mousewheel.js

After this done, move to the Magento 2 settings that will run these files.

CSS files enabling

CSS files have to be included in all categories pages with layered navigation. These pages configuration set in the XML-files:

  • catalog_category_view_type_layered.xml

Add this type of a file to the catalog theme. The project that I worked on had Manadev_LayeredNavigation extension installed, that’s why I added the file in this path:

  • <theme_dir>Manadev_LayeredNavigation/layout/catalog_category_view_type_layered.xml

The content of the file which enables CSS styles:

jquery.jscrollpane.css :

<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
 <css src="css/jScrollPane/jquery.jscrollpane.css"/>

How does JScrollPane work?

Before you start to add the rules that enable JScrollPane plugin in Magento 2, make sure that you clearly understand the work of this extension.
The plugin’s work principle is quite simple. A browser has to load jquery.jscrollpane.min.js (with the extra jquery.mousewheel.js file if required) and apply the method jScrollPane after the document loading:

  • jQuery(“.some-element”).jScrollPane();

JScrollPane enabling and usage

Unlike loading CSS files, Magento 2 isn’t happy with enabling js-files via pages xml-configuration.
Js-files in Magento 2 have to be loaded:

  • via pseudo scripts <script type=”text/x-magento-init”>
  • via html attribute data-mage-init

Magento 2 loads additionaly js-files that are critical for loading the js-files via the methods mentioned above.

We’ll inspect js-loading and running variant via html-attribute data-mage-init because this variant will be used in JScrollPane plugin’s applying to the filter’s tabs.

Step by step instruction:

  • Add small custom js with the only one task of applying jScrollPane () method to html-document elements;
  • Depending on this custom js specify the js-files query.jscrollpane.min.js and jquery.mousewheel.js. In according to these dependencies, Magento will have to load these 2 files before loading and running the custom js.
  • Add the attributes data-mage-init of the elements to which the jScrollPane() method will be applied.

Details of this instruction:

Adding custom js.
Add this file to the theme catalog:

Now, we have an option of enabling this file via the attribute data-mage-init in the following way (the example is a fragment of the Manadev_LayeredNavigation template which locates in the filters’ loop and runs the displaying of filters options list:

<div class="filter-options-content <?php echo $cssClass ?>"
 <?php echo $block->renderFilter($filter) ?>

Remember that when the script category-filters-scroll.js will be run, it will get 2 parameters:

  • the object specified in the attribute data-mage-init via the colon (it will be an empty object {});
  • the html-element that belongs to the html-attribute data-mage-init (it will be div> element).

Here is the full content of the file <theme_dir>/web/js/category-filters-scroll.js:

   function ($) {
       'use strict';
       return function (config, element) {
               verticalDragMinHeight: 20,
               verticalDragMaxHeight: 20

As you can see, the dependencies contain the aliases of 3 js files. The first one –“jquery” – is the alias of jQuery library, the second and the third are the aliases of the plugin jquery.jscrollpane.min.js and the subsidiary file jquery.mousewheel.js (more about these aliases read below).
Thus, before running the custom script, the loading of jQuery libraries is guaranteed as well as loading js-files of JScrollPane plugin.

The custom script itself is quite simple and contains the only one command: calling the method jScrollPane in the <div> element got as a parameter “element”:

               verticalDragMinHeight: 20,
               verticalDragMaxHeight: 20

The last one thing to inspect is the aliases appearing in the js-files of JScrollPane plugin.

They are shown up in the theme file <theme_dir>/requirejs-config.js

It’s content:

var config = {
   paths: {
       'scrollpane': "js/jScrollPane/jquery.jscrollpane.min",
       'scrollpanewheel': "js/jScrollPane/jquery.mousewheel"
   shim: {
       'scrollpane': {
           deps: ['jquery']
       'scrollpanewheel': {
           deps: ['jquery']


The aliases itself are shown up in the “paths” block (this block has to be easy to understand without explanations).

The block that we pay attention to is “shim”. The dependencies for every alias are specified in the block “shim”. These dependencies have to load before loading js-files specified by the alias.
There is one dependence for every alias in the example, it is the jQuery library in both cases. It means that before loading any of the JScrollPane js-files, Magento confirms that the loading jQuery library has been finished. If not, jQuery loading starts.

It is a critical demand because, without the loaded jQuery library, js-files of JScrollPane plugin don’t work correctly.

Magento uses RequireJS when tracking dependencies between js-files. See more details about in on the RequireJS developer website.

iconka How to set up scroll bars in Magento 2 using the JScrollPane plugin?

Mobecls team offers fixed-price service packages for Magento store support. Moreover, we’ll help you to choose a plan according to your business needs and specifics. The starting price is $2000. You can also select the number of working hours and the range of services. A service package may include updates, the installation of modules, bug fixing, SEO support and many more. Contact us and we’ll help you.  

Vladimir Repalo

Vladimir Repalo

Magento Developer at Mobecls, 8+ years of experience. Feel free to ask me anything about this post in the comments below.