SimpleBar for Vue

2.4.2 · active · verified Sun Apr 19

simplebar-vue is a Vue.js component wrapper for the highly customizable native JavaScript scrollbar library, SimpleBar. It enables developers to easily integrate custom scrollbars into their Vue applications, leveraging native browser scroll behavior for performance while offering extensive styling options. The current stable version of simplebar-vue is 2.4.2, which depends on SimpleBar core v6.x. The core SimpleBar library itself sees fairly regular updates, including major version bumps with breaking changes, which are then reflected in subsequent simplebar-vue releases. Its key differentiator lies in its approach to custom scrollbars: instead of recreating scroll behavior with JavaScript, it maintains the native scrolling experience, ensuring accessibility and performance, particularly for internal web page scrolling areas like chat boxes or modals, rather than the entire `body` element.

Common errors

```
Scrollbar is not visible or looks broken, or native scrollbar is still present.
```
cause Conflicting CSS styles, incorrect sizing of the parent or SimpleBar container, or not importing the necessary SimpleBar CSS stylesheet.

fix Ensure `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.
```
cause The `simplebar` component was not properly registered in the Vue application's `components` option.

fix Make 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.
```
cause 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.

fix Upgrade `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.

Warnings

gotcha SimpleBar 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.
Fix: Apply SimpleBar only to specific, contained elements within your page that require custom scrollbars.
breaking Starting 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`).
Fix: Evaluate your target browser support and include necessary polyfills if issues arise in older browsers. Refer to SimpleBar's core documentation for polyfill recommendations.
breaking SimpleBar 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.
Fix: Review 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.
gotcha Custom 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.
Fix: Avoid 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.
breaking In 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.
Fix: When programmatically accessing SimpleBar elements, use `getContentElement()` instead of `getScrollElement()` to retrieve the scrollable content container.
breaking From 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.
Fix: Update your code to use `SimpleBar.instances.get(DOMElement)` to retrieve the SimpleBar instance. Ensure `SimpleBar` is imported from the `simplebar` package.

Install

npm install simplebar-vue npm
yarn add simplebar-vue yarn
pnpm add simplebar-vue pnpm

Imports

simplebar
wrong:
```
const simplebar = require('simplebar-vue');
```
correct:
```
import simplebar from '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
wrong:
```
import 'simplebar/dist/simplebar.min.css';
```
correct:
```
import 'simplebar-vue/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.

Quickstart

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');

view raw JSON →