Scrollbar

Bootstrap 5 Scrollbar

Scrollbar method which allows you to create a custom scrollbar.

Note: Read the API tab to find all available options and advanced customization

Required ES init: PerfectScrollbar *
* UMD autoinits are enabled by default. This means that you don't need to initialize the component manually. However if you are using MDBootstrap ES format then you should pass the required components to the initMDB method.

Basic example

Scrollbar is initialized automatically when you add data-mdb-perfect-scrollbar-init attribute to your container.

Wild Landscape
Edit in sandbox 
        
            
              <div data-mdb-perfect-scrollbar-init style="position: relative; width: 600px; height: 400px">
                <img src="https://mdbcdn.b-cdn.net/img/new/slides/041.webp" alt="Wild Landscape" style="height: 700px; width: 1000px" />
              </div>
            
        
    
        
            
              // Initialization for ES Users
              import { PerfectScrollbar, initMDB } from "mdb-ui-kit";

              initMDB({ PerfectScrollbar });

Options

JavaScript init

You can easily init scrollbar with JavaScript. You have to invoke new mdb.PerfectScrollbar() and include options within that.

Wild Landscape
Edit in sandbox 
        
            
                <div id="init-by-js" style="position: relative; width: 600px; height: 400px;">
                  <img src="https://mdbcdn.b-cdn.net/img/new/slides/041.webp" alt="Wild Landscape" style="height: 700px; width: 1000px;" />
                </div>
              
        
    
        
            
                import { PerfectScrollbar } from "mdb-ui-kit";
              
                const initByJS = document.querySelector('#init-by-js');
                const psInitByJS = new PerfectScrollbar(initByJS);
              
        
    
        
            
                const initByJS = document.querySelector('#init-by-js');
                const psInitByJS = new mdb.PerfectScrollbar(initByJS);

Data attributes

You can easily set options with data-mdb attributes. For example, insert data-mdb-suppress-scroll-x='true' into your container.

Wild Landscape
Edit in sandbox 
        
            
                <div data-mdb-perfect-scrollbar-init data-mdb-suppress-scroll-x="true" style="position: relative; width: 600px; height: 400px">
                  <img src="https://mdbcdn.b-cdn.net/img/new/slides/041.webp" alt="..." style="height: 700px; width: 1000px" />
                </div>
              
        
    
        
            
                // Initialization for ES Users
                import { PerfectScrollbar, initMDB } from "mdb-ui-kit";

                initMDB({ PerfectScrollbar });

Colors example

Scrollbar's thumb and rail's colors can be customized with simple CSS. Use class that describes the element of Scrollbar you would like to edit: .ps__rail-y, .ps__rail-x, .ps__thumb-y, .ps__thumb-x

...
Edit in sandbox 
        
            
                <div data-mdb-perfect-scrollbar-init style="position: relative; width: 600px; height: 400px">
                  <img src="https://mdbcdn.b-cdn.net/img/new/slides/041.webp" alt="..." style="height: 700px; width: 1000px" />
                </div>
              
        
    
        
            
                .ps__rail-y {
                  background-color: lightgreen !important;
                }
                
                .ps__thumb-y {
                  background-color: darkgreen !important;
                }
                
                .ps__rail-x {
                  background-color: lightgreen !important;
                }
                
                .ps__thumb-x {
                  background-color: darkgreen !important;
                }
              
        
    
        
            
                // Initialization for ES Users
                import { PerfectScrollbar, initMDB } from "mdb-ui-kit";

                initMDB({ PerfectScrollbar });

Events

PerfectScrollbar dispatches custom events.

  • ScrollX
  • ScrollY
  • ScrollUp
  • ScrollDown
  • ScrollLeft
  • ScrollRight
  • ScrollXEnd
  • ScrollYEnd
  • ScrollXStart
  • ScrollYStart

Example

Wild Landscape
Edit in sandbox 
        
            
                <div id="scroll-x" style="position: relative; width: 600px; height: 400px;">
                  <img src="https://mdbcdn.b-cdn.net/img/new/slides/041.webp" alt="Wild Landscape" style="height: 700px; width: 1000px;" />
                </div>
              
        
    
        
            
                import { PerfectScrollbar } from "mdb-ui-kit";
 
                const scrollX = document.querySelector('#scroll-x');
                const initscrollX = new PerfectScrollbar(scrollX);

                scrollX.addEventListener('scrollX.mdb.ps', (e) => {
                  // do something...
                });
              
        
    
        
            
                const scrollX = document.querySelector('#scroll-x');
                const initscrollX = new mdb.PerfectScrollbar(scrollX);

                scrollX.addEventListener('scrollX.mdb.ps', (e) => {
                  // do something...
                });

Import

Importing components depends on how your application works. If you intend to use the MDBootstrap ES format, you must first import the component and then initialize it with the initMDB method. If you are going to use the UMD format, just import the mdb-ui-kit package.

Edit in sandbox 
        
            
          import { PerfectScrollbar, initMDB } from "mdb-ui-kit";
          initMDB({ PerfectScrollbar });
        
        
    
        
            
          import 'mdb-ui-kit';

Usage

Via data attributes

Using the Perfect Scrollbar method doesn't require any additional JavaScript code - simply add data-mdb-perfect-scrollbar-init attribute to element that need scroll and use other data attributes to set all options. For ES format, you must first import and call the initMDB method.

Edit in sandbox 
        
            
            <div data-mdb-perfect-scrollbar-init data-mdb-handlers="click-rail" style="position: relative; width: 600px; height: 400px;">
              <img src="https://mdbootstrap.com/img/new/slides/041.webp" alt="..." style="height: 700px; width: 1000px;" />
            </div>

Via JavaScript

Edit in sandbox 
        
            
           const myPs = new PerfectScrollbar(document.getElementById('myPsID'), options);
        
        
    
        
            
           const myPs = new mdb.PerfectScrollbar(document.getElementById('myPsID'), options);

Via jQuery

Note: By default, MDB does not include jQuery and you have to add it to the project on your own.

Edit in sandbox 
        
            
        $(document).ready(() => {
          $('.example-class').perfectScrollbar(options);
        });

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-mdb-, as in data-mdb-wheel-speed="".

Name Type Default Description
handlers String | Array ['click-rail', 'drag-thumb', 'keyboard', 'wheel', 'touch'] It is a list of handlers to scroll the element.
wheelSpeed Number 1 The scroll speed applied to mousewheel event.
wheelPropagation Boolean true If this option is true, when the scroll reaches the end of the side, mousewheel event will be propagated to parent element.
swipeEasing Boolean true If this option is true, swipe scrolling will be eased.
minScrollbarLength Number | null null When set to an integer value, the thumb part of the scrollbar will not shrink below that number of pixels.
maxScrollbarLength Number | null null When set to an integer value, the thumb part of the scrollbar will not expand over that number of pixels.
scrollingThreshold Number 1000 This sets threshold for ps--scrolling-x and ps--scrolling-y classes to remain. In the default CSS, they make scrollbars shown regardless of hover state. The unit is millisecond.
suppressScrollX Boolean false When set to true, the scrollbar in X-axis will not be available, regardless of the content width.
suppressScrollY Boolean false When set to true, the scroll bar in Y-axis will not be available, regardless of the content height.
scrollXMarginOffset Number 0 The number of pixels the content width can surpass the container width without enabling the X-axis scroll bar. Allows some "wiggle room" or "offset break", so that X-axis scroll bar is not enabled just because of a few pixels.
scrollYMarginOffset Number 0 The number of pixels the content width can surpass the container width without enabling the X-axis scroll bar. Allows some "wiggle room" or "offset break", so that X-axis scroll bar is not enabled just because of a few pixels.

Methods

Name Description Example
dispose Destroy ps myPs.dispose()
getInstance Static method which allows you to get the perfect scrollbar instance associated to a DOM element. PerfectScrollbar.getInstance(myPs)
getOrCreateInstance Static method which returns the perfect scrollbar instance associated to a DOM element or create a new one in case it wasn't initialized. PerfectScrollbar.getOrCreateInstance(myPs)
update Update ps myPs.update()
Edit in sandbox 
        
            
          const myPs = document.getElementById('myPsID');
          const ps = new PerfectScrollbar(myPs);
          ps.dispose();
        
        
    
        
            
          const myPs = document.getElementById('myPsID');
          const ps = new mdb.PerfectScrollbar(myPs);
          ps.dispose();

Events

Name Description
scrollX.mdb.ps This event fires when the x-axis is scrolled in either direction.
scrollY.mdb.ps This event fires when the y-axis is scrolled in either direction.
scrollUp.mdb.ps This event fires when scrolling upwards.
scrollDown.mdb.ps This event fires when scrolling downwards.
scrollLeft.mdb.ps This event fires when scrolling to the left.
scrollRight.mdb.ps This event fires when scrolling to the right.
scrollLeft.mdb.ps This event fires when scrolling to the left.
scrollYStart.mdb.ps This event fires when scrolling to the right.
scrollYStart.mdb.ps This event fires when scrolling reaches the start of the y-axis.
scrollXStart.mdb.ps This event fires when scrolling reaches the start of the x-axis.
scrollXEnd.mdb.ps This event fires when scrolling reaches the end of the x-axis.
scrollYEnd.mdb.ps This event fires when scrolling reaches the end of the y-axis (useful for infinite scroll).
Edit in sandbox 
        
            
        const myPs = document.getElementById('element-id')
        myPs.addEventListener('scrollYEnd.mdb.ps', (e) => {
          // do something...
        })