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

Basic example

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

Wild Landscape
Edit in sandbox 
        
            
              <div data-mdb-perfect-scrollbar="true" 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>

Options

JavaScript init

You can easily init scrollbar with JavaScript. You have to invoke 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>
              
        
    
        
            
                const initByJS = document.querySelector('#init-by-js');
                const psInitbyJS = new mdb.PerfectScrollbar(initByJS);

Data attributes

You can easily init scrollbar with options with data-mdb-attributes. You have to add data-mdb-perfect-scrollbar to your wrapper. If you want add options with data-mdb-attr you have to add for example data-mdb-suppress-scroll-x='true' to your container.

Wild Landscape
Edit in sandbox 
        
            
                <div data-mdb-perfect-scrollbar="true" 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>

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="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>
              
        
    
        
            
                .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;
                }

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>
              
        
    
        
            
                const scrollX = document.querySelector('#scroll-x');
                const initscrollX = new mdb.PerfectScrollbar(scrollX);

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

Usage

Via data attributes

Edit in sandbox 
        
            
        <div data-mdb-perfect-scrollbar="true" 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 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, JavaScript, or jQuery. For data attributes, append the option name to data-mdb-, as in data-mdb-handlers="".

Name Type Default Description
handlers String[] ['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 Boolean null When set to an integer value, the thumb part of the scrollbar will not shrink below that number of pixels.
maxScrollbarLength Boolean 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 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...
        })

Import

MDB UI KIT also works with module bundlers. Use the following code to import this component:

Edit in sandbox 
        
            
        import { PerfectScrollbar } from 'mdb-ui-kit';