perfect-scrollbar: Custom JavaScript Scrollbar Library

perfect-scrollbar is a standalone JavaScript scrollbar library that adds CSS-customizable scrollbars to scrollable containers and keeps native scrollTop and scrollLeft behavior.

The current 1.5.6 package has no runtime dependencies, and jQuery is not required.

Features:

• CSS-customizable horizontal and vertical scrollbars.
• Mouse wheel, keyboard, touch, rail-click, and thumb-drag handlers.
• Native scrollTop and scrollLeft access for programmatic scrolling.
• Independent X-axis and Y-axis controls, scrollbar length limits, and wheel propagation settings.
• RTL handling plus update() and destroy() instance methods.

Use Cases

• Long dashboard panels and sidebars that need a consistent custom scrollbar style.
• Scrollable data panels that change height after new rows or records appear.
• Horizontal content areas that need draggable scrollbar thumbs and wheel controls.
• Legacy front-end projects that want a custom scrollbar library with no jQuery dependency.

How to use perfect-scrollbar:

1. Load the CSS and JavaScript files

Load the package stylesheet and browser build in your document. jQuery is not required.

<link rel="stylesheet" href="css/perfect-scrollbar.css">
<script src="dist/perfect-scrollbar.js"></script>

For npm-based projects:

npm install perfect-scrollbar

import PerfectScrollbar from 'perfect-scrollbar';
import 'perfect-scrollbar/css/perfect-scrollbar.css';

2. Create the scrollable container

The target element needs a positioned container and constrained dimensions. The content must exceed the container size on at least one axis before a scrollbar appears.

<div id="demo">
  <div class="content">
    ...
  </div>
</div>

#demo {
  position: relative;
  width: 420px;
  height: 260px;
  overflow: auto;
}

3. Initialize perfect-scrollbar

var ps = new PerfectScrollbar('#demo', {
  wheelSpeed: 1,
  wheelPropagation: true
});

You can also pass a DOM element to the constructor.

var container = document.querySelector('#demo');
var ps = new PerfectScrollbar(container);

Available Options:

Scrolling and input options

Option	Description
handlers	Type: Array. Default: ['click-rail', 'drag-thumb', 'keyboard', 'wheel', 'touch']. Sets the input handlers used by the instance.
scrollingThreshold	Type: Number. Default: 1000. Sets the delay in milliseconds before scrolling-state classes can clear.
wheelSpeed	Type: Number. Default: 1. Multiplies the distance applied to mouse wheel scrolling.
wheelPropagation	Type: Boolean. Default: true. Lets wheel events propagate to a parent when the current container reaches a scroll boundary.
useBothWheelAxes	Type: Boolean. Default: false. Uses wheel movement on the available axis when only one scrollbar is active.
swipeEasing	Type: Boolean. Default: true. Applies easing to touch swipe scrolling.

Axis and scrollbar size options

Option	Description
minScrollbarLength	Type: Number or null. Default: null. Sets the minimum scrollbar thumb length in pixels.
maxScrollbarLength	Type: Number or null. Default: null. Sets the maximum scrollbar thumb length in pixels.
suppressScrollX	Type: Boolean. Default: false. Disables the horizontal scrollbar.
suppressScrollY	Type: Boolean. Default: false. Disables the vertical scrollbar.
scrollXMarginOffset	Type: Number. Default: 0. Adds a pixel margin before horizontal overflow activates the X-axis scrollbar.
scrollYMarginOffset	Type: Number. Default: 0. Adds a pixel margin before vertical overflow activates the Y-axis scrollbar.

API Methods:

Method	Description
update()	Recalculates scrollbar geometry after the container, content size, margins, or layout changes. Parameters: None. Returns: Nothing.
destroy()	Unbinds instance events, removes generated scrollbar elements and Perfect Scrollbar classes, and marks the instance as inactive. Parameters: None. Returns: Nothing.

Update the scrollbar after dynamic content changes

var container = document.querySelector('#demo');
var ps = new PerfectScrollbar(container);

document.querySelector('#add-content').addEventListener('click', function () {
  container.querySelector('.content').insertAdjacentHTML(
    'beforeend',
    '<p>New dynamic content</p>'
  );

  ps.update();
});

Destroy a Perfect Scrollbar instance

ps.destroy();
ps = null;

Events:

Event	Fires When
ps-scroll-x	The container scrolls horizontally in either direction.
ps-scroll-y	The container scrolls vertically in either direction.
ps-scroll-up	The vertical scroll position moves upward.
ps-scroll-down	The vertical scroll position moves downward.
ps-scroll-left	The horizontal scroll position moves left.
ps-scroll-right	The horizontal scroll position moves right.
ps-x-reach-start	The horizontal scrollbar reaches the start of the X axis.
ps-x-reach-end	The horizontal scrollbar reaches the end of the X axis.
ps-y-reach-start	The vertical scrollbar reaches the start of the Y axis.
ps-y-reach-end	The vertical scrollbar reaches the end of the Y axis.

Run code when vertical scrolling reaches the end

var container = document.querySelector('#demo');

container.addEventListener('ps-y-reach-end', function () {
  console.log('Reached the end of the scrollable content');
});

Programmatic Scrolling

perfect-scrollbar keeps the container's native scroll properties. Set scrollTop or scrollLeft directly when your application needs to move the scroll position.

var container = document.querySelector('#demo');

// Scroll to the top.
container.scrollTop = 0;

// Scroll 200 pixels from the left edge.
container.scrollLeft = 200;

More Examples:

• Default Example
• wheelSpeed Example
• wheelPropagation Example

Alternatives And Related Scrollbar Resources:

• 10 Best Custom Scrollbar Plugins In jQuery And Vanilla JS
• jQuery Custom Scrollbar Plugin - malihu
• Facebook-like jQuery Scrollbar Plugin - slimScroll
• OverlayScrollbars: Elegant Themeable Custom Scrollbars
• Performant Custom Scrollbar JavaScript Library – SimpleBar

FAQs:

Q: Does perfect-scrollbar require jQuery?
A: No. The current 1.5.6 package has no runtime dependencies and initializes through new PerfectScrollbar(...).

Q: When should I call update()?
A: Call update() after the container or its content changes size. This recalculates the scrollbar rails, thumbs, and scroll geometry.

Q: Why does the scrollbar not appear?
A: Confirm that the Perfect Scrollbar CSS file is loaded, the target has a positioned and constrained container, and its content is larger than the container on the required axis.

Q: How do I scroll to a specific position?
A: Set the target element's native scrollTop or scrollLeft property. Perfect Scrollbar uses those native scroll positions.

Q: How do I remove perfect-scrollbar from an element?
A: Call destroy() on the instance. The method unbinds its events and removes the generated scrollbar rails, thumbs, and Perfect Scrollbar classes.

Changelog:

v1.5.6 (2024-10-29)

• Formatting fix.

v1.5.1 (2021-05-04)

• Fixed scrolling past the content length.
• Fixed a scrollTop null-reference error.

v1.5.0 (2020-01-16)

• Rebuilt the package toolchain with Rollup.
• Fixed RTL behavior and mouse-wheel child-consumption logic.
• Updated TypeScript definitions.
• Added fractional-size, touch, and mobile dragging improvements.

v0.4.11 (2014-08-25)

• Removed the jquery-mousewheel dependency.

---

This awesome jQuery plugin is developed by mdbootstrap. For more Advanced Usages, please check the demo page or visit the official website.