Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
simplebar
✓ import simplebar from 'simplebar-vue';
✗ const simplebar = require('simplebar-vue');
Primarily designed for modern ES module environments; CommonJS `require` might not work seamlessly without a bundler configured for interop. The component is registered and used directly as `simplebar` in Vue templates.
CSS Stylesheet
✓ import 'simplebar-vue/dist/simplebar.min.css';
✗ import 'simplebar/dist/simplebar.min.css';
Ensure you import the CSS specific to the Vue wrapper, which includes the necessary styles for both the wrapper and the core SimpleBar functionality.
SimpleBar instance (advanced)
✓ import SimpleBar from 'simplebar';
// ... later in Vue component method ...
const simplebarInstance = SimpleBar.instances.get(this.$refs.mySimplebarRef.$el);
To access the underlying SimpleBar instance for imperative control (e.g., forcing a scroll), you need to import the core `simplebar` library and use its `instances.get` method, passing the root DOM element of the simplebar-vue component (e.g., via a ref). This pattern is relevant since SimpleBar v5.0.1 stopped mutating the attached DOM node directly.
This quickstart demonstrates how to register and use the simplebar-vue component within a Vue 3 application, including importing its necessary CSS, and applying it to a container with overflowing content to create a custom scrollbar.
import { createApp } from 'vue';
import simplebar from 'simplebar-vue';
import 'simplebar-vue/dist/simplebar.min.css';
const app = createApp({
components: {
simplebar,
},
template: `
<div id="app-wrapper" style="height: 300px; width: 400px; border: 1px solid #eee;">
<h2>Content inside SimpleBar</h2>
<p>This is some content that will be scrollable using SimpleBar.</p>
<simplebar data-simplebar-auto-hide="false" style="max-height: 250px;">
<div style="height: 500px; padding: 20px;">
<p v-for="n in 20" :key="n">Scrollable content line {{ n }}.</p>
<p>More content to make it scroll.</p>
</div>
</simplebar>
<p>Content outside SimpleBar.</p>
</div>
`,
});
app.mount('#app-wrapper');
Debug
Known issues
gotchaSimpleBar is not intended for use on the `body` element. Applying it to the entire webpage can lead to reduced scroll performance and loss of native scroll behaviors. It is designed for internal page scrolling areas like chat boxes, modals, or specific content blocks.fixApply SimpleBar only to specific, contained elements within your page that require custom scrollbars.
affects: >=2.0
breakingStarting with core SimpleBar v6 (which simplebar-vue@2.4.2 depends on), the library no longer provides polyfills by default and was rewritten in TypeScript. If your target browsers do not natively support certain features, you might need to manually include polyfills (e.g., via Babel's `@babel/preset-env` or `polyfill.io`).fixEvaluate your target browser support and include necessary polyfills if issues arise in older browsers. Refer to SimpleBar's core documentation for polyfill recommendations.
affects: >=2.4.0 (simplebar-vue) due to simplebar >=6.0.0 dependency
breakingSimpleBar v6 dropped support for browsers that do not support scrollbar hiding via CSS. This resulted in the removal of several internal DOM elements (e.g., `.simplebar-height-auto-observer`, `.simplebar-mask`, `.simplebar-offset`). If your CSS or JavaScript directly interacted with these internal elements, your implementation might break.fixReview and update any custom CSS or JavaScript that targets SimpleBar's internal DOM structure. Adapt to the new, simplified DOM template introduced in SimpleBar v6.
affects: >=2.4.0 (simplebar-vue) due to simplebar >=6.0.0 dependency
gotchaCustom styles applied directly to the element where `simplebar-vue` is instantiated can clash with SimpleBar's internal CSS, leading to unexpected rendering or scroll issues. SimpleBar injects its own styles to manage scrollbar appearance and behavior.fixAvoid styling the `<simplebar>` component's root element directly. Instead, wrap your content in an inner `div` and apply your custom styles to that inner element.
affects: >=2.0
breakingIn core SimpleBar v4 and later, a new wrapper `.simplebar-content-wrapper` was introduced, and the method `getScrollElement()` no longer returned the content element. Developers needed to use `getContentElement()` instead. While `simplebar-vue` abstracts some DOM interaction, direct programmatic access to SimpleBar instances and their elements might be affected if not updated.fixWhen programmatically accessing SimpleBar elements, use `getContentElement()` instead of `getScrollElement()` to retrieve the scrollable content container.
affects: <2.4.0 (simplebar-vue) or direct SimpleBar instance usage when simplebar <6.0.0
breakingFrom SimpleBar v5.0.1, the library no longer mutates the attached DOM node for retrieving the SimpleBar instance. If you previously accessed `element.SimpleBar`, you now need to use `SimpleBar.instances.get(element)` after importing the core `simplebar` library.fixUpdate your code to use `SimpleBar.instances.get(DOMElement)` to retrieve the SimpleBar instance. Ensure `SimpleBar` is imported from the `simplebar` package.
affects: >=2.0 (simplebar-vue) and direct SimpleBar instance usage
Errors
Common errors & fixes
Scrollbar is not visible or looks broken, or native scrollbar is still present.
Conflicting CSS styles, incorrect sizing of the parent or SimpleBar container, or not importing the necessary SimpleBar CSS stylesheet.
fixEnsure `simplebar-vue/dist/simplebar.min.css` is imported. Verify that the parent container of `<simplebar>` has defined dimensions (e.g., `height` or `max-height`) to create an overflow condition. Also, avoid applying conflicting styles to the `<simplebar>` component itself; style its *inner content* instead.
Vue component not rendering or 'simplebar is not defined' error in template.
The `simplebar` component was not properly registered in the Vue application's `components` option.
fixMake sure to `import simplebar from 'simplebar-vue';` and add it to your Vue component's `components: { simplebar },` option before using it in the template. 'TypeError: (0 , SimpleBar.default).getOptions is not a function' or similar when using simplebar-vue@2.0.0-beta.2.
This was a known bug in a specific beta version of `simplebar-vue` related to how the core SimpleBar library was being imported and exposed.
fixUpgrade `simplebar-vue` to version `2.0.0-beta.3` or later to resolve this specific import/initialization issue. The current stable `2.4.2` should not have this problem.
Audit
Dependencies
vuerequiredPeer dependency required for the Vue component to function.
simplebarrequiredThe core custom scrollbar library that simplebar-vue wraps. simplebar-vue@2.4.2 depends on simplebar@^6.0.0.