How to Enable a Bootstrap Scrollbar Using ScrollBarHelper: Complete Guide

Bootstrap's ScrollBarHelper utility automatically manages scrollbar visibility by measuring native scrollbar width, disabling overflow, and adding compensating padding to prevent layout shift.

The twbs/bootstrap repository includes a powerful JavaScript utility called ScrollBarHelper that gives you precise control over the bootstrap scrollbar behavior. Located in js/src/util/scrollbar.js, this helper is designed to eliminate the layout jank that occurs when scrollbars appear or disappear, particularly when modals or offcanvas components are active.

What Is the Bootstrap ScrollBarHelper?

The ScrollBarHelper is a utility class that abstracts the complexity of scrollbar management into four core operations:

• getWidth() – Calculates the exact pixel width of the browser's native scrollbar by creating a temporary DOM element.
• hide() – Disables scrolling on the target element (default is document.body) and adds compensating right-padding to prevent content from shifting.
• reset() – Restores the original overflow and padding values using stored data attributes.
• _disableOverFlow() – An internal method that sets overflow: hidden while preserving the element's previous scroll position.

This mechanism ensures that when you enable a bootstrap scrollbar control, the page layout remains stable with no visible jumping or resizing.

Automatic Scrollbar Handling in Bootstrap Components

You don't always need to invoke ScrollBarHelper manually. Bootstrap's Modal and Offcanvas components automatically instantiate and manage the helper.

Modal Implementation

In js/src/modal.js, the Modal component creates a ScrollBarHelper instance during initialization:

this._scrollBar = new ScrollBarHelper()

When the modal opens, it calls:

this._scrollBar.hide()

This disables body scrolling and adds the compensating padding. When the modal closes, reset() restores the original state.

Offcanvas Implementation

Similarly, js/src/offcanvas.js uses the helper to prevent background scrolling when a sidebar slides in:

const scrollBar = new ScrollBarHelper()
scrollBar.hide()

The helper targets the body by default, ensuring the bootstrap scrollbar behavior remains consistent across all overlay components.

Manual Scrollbar Control with ScrollBarHelper

For custom implementations—such as scrollable sidebars, drawers, or panels—you can import and use ScrollBarHelper directly.

Targeting a Specific Element

By default, the helper operates on document.body. To target a different element, set the _element property before calling methods:

import ScrollBarHelper from 'bootstrap/js/src/util/scrollbar.js'

const sidebar = document.querySelector('.custom-sidebar')
const scrollHelper = new ScrollBarHelper()

// Point the helper at your element
scrollHelper._element = sidebar

// Disable scrolling and add compensating padding
scrollHelper.hide()

Restoring Scroll Behavior

When you're ready to re-enable scrolling, call reset():

// Restore original overflow and padding
scrollHelper.reset()

This method retrieves the original values stored in data attributes and removes the temporary styles applied by hide().

Using the Bundled Version Without a Build Step

If you're using Bootstrap via CDN without a module bundler, ScrollBarHelper is available on the global bootstrap object:

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
<script>
  // Access the helper globally
  const scrollHelper = new bootstrap.ScrollBarHelper()
  
  // Apply to body or custom element
  scrollHelper._element = document.querySelector('.scroll-container')
  scrollHelper.hide()
  
  // Later...
  scrollHelper.reset()
</script>

The bundled version contains the exact same implementation found in js/src/util/scrollbar.js, ensuring consistent bootstrap scrollbar behavior across all deployment methods.

Summary

• Bootstrap's ScrollBarHelper in js/src/util/scrollbar.js provides the core mechanism for scrollbar management.
• Automatic handling occurs in Modal and Offcanvas components via hide() and reset() methods.
• Manual control requires instantiating ScrollBarHelper, optionally setting _element to target specific containers, and calling hide() to disable or reset() to restore.
• Layout stability is maintained by calculating native scrollbar width with getWidth() and adding compensating padding.

Frequently Asked Questions

How do I enable a bootstrap scrollbar on a specific div?

Import ScrollBarHelper from bootstrap/js/src/util/scrollbar.js, create an instance, set scrollHelper._element to your target div, and call scrollHelper.hide(). This disables native scrolling on that specific container while maintaining layout integrity through automatic padding compensation.

What is the difference between bootstrap scrollbar and native browser scrollbars?

The bootstrap scrollbar feature refers to Bootstrap's JavaScript utility (ScrollBarHelper) that programmatically hides, shows, and compensates for native browser scrollbars. It does not replace the browser's rendering engine but rather manages the overflow and padding properties to prevent layout shift when scrollbars appear or disappear.

Does Bootstrap 5 require additional CSS for scrollbar styling?

No. The ScrollBarHelper utility in Bootstrap 5 operates entirely through JavaScript by manipulating inline styles and data attributes. While you can add custom CSS for visual scrollbar styling (WebKit scrollbars, etc.), the functional bootstrap scrollbar management requires only the Bootstrap JavaScript bundle.

How do I prevent layout shift when hiding scrollbars in Bootstrap?

Use the ScrollBarHelper class instead of manually setting overflow: hidden. The helper's hide() method automatically calculates the native scrollbar width via getWidth() and adds equivalent padding-right to the target element. This compensation ensures that content width remains constant, eliminating the visible jump that occurs when scrollbars disappear.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}