{"id":12034,"library":"simplebar-vue","title":"SimpleBar for Vue","description":"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.","status":"active","version":"2.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/grsmto/simplebar","tags":["javascript","typescript"],"install":[{"cmd":"npm install simplebar-vue","lang":"bash","label":"npm"},{"cmd":"yarn add simplebar-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add simplebar-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the Vue component to function.","package":"vue","optional":false},{"reason":"The core custom scrollbar library that simplebar-vue wraps. simplebar-vue@2.4.2 depends on simplebar@^6.0.0.","package":"simplebar","optional":false}],"imports":[{"note":"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.","wrong":"const simplebar = require('simplebar-vue');","symbol":"simplebar","correct":"import simplebar from 'simplebar-vue';"},{"note":"Ensure you import the CSS specific to the Vue wrapper, which includes the necessary styles for both the wrapper and the core SimpleBar functionality.","wrong":"import 'simplebar/dist/simplebar.min.css';","symbol":"CSS Stylesheet","correct":"import 'simplebar-vue/dist/simplebar.min.css';"},{"note":"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.","symbol":"SimpleBar instance (advanced)","correct":"import SimpleBar from 'simplebar';\n// ... later in Vue component method ...\nconst simplebarInstance = SimpleBar.instances.get(this.$refs.mySimplebarRef.$el);"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport simplebar from 'simplebar-vue';\nimport 'simplebar-vue/dist/simplebar.min.css';\n\nconst app = createApp({\n  components: {\n    simplebar,\n  },\n  template: `\n    <div id=\"app-wrapper\" style=\"height: 300px; width: 400px; border: 1px solid #eee;\">\n      <h2>Content inside SimpleBar</h2>\n      <p>This is some content that will be scrollable using SimpleBar.</p>\n      <simplebar data-simplebar-auto-hide=\"false\" style=\"max-height: 250px;\">\n        <div style=\"height: 500px; padding: 20px;\">\n          <p v-for=\"n in 20\" :key=\"n\">Scrollable content line {{ n }}.</p>\n          <p>More content to make it scroll.</p>\n        </div>\n      </simplebar>\n      <p>Content outside SimpleBar.</p>\n    </div>\n  `,\n});\n\napp.mount('#app-wrapper');","lang":"javascript","description":"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."},"warnings":[{"fix":"Apply SimpleBar only to specific, contained elements within your page that require custom scrollbars.","message":"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.","severity":"gotcha","affected_versions":">=2.0"},{"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.","message":"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`).","severity":"breaking","affected_versions":">=2.4.0 (simplebar-vue) due to simplebar >=6.0.0 dependency"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.4.0 (simplebar-vue) due to simplebar >=6.0.0 dependency"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0"},{"fix":"When programmatically accessing SimpleBar elements, use `getContentElement()` instead of `getScrollElement()` to retrieve the scrollable content container.","message":"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.","severity":"breaking","affected_versions":"<2.4.0 (simplebar-vue) or direct SimpleBar instance usage when simplebar <6.0.0"},{"fix":"Update your code to use `SimpleBar.instances.get(DOMElement)` to retrieve the SimpleBar instance. Ensure `SimpleBar` is imported from the `simplebar` package.","message":"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.","severity":"breaking","affected_versions":">=2.0 (simplebar-vue) and direct SimpleBar instance usage"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Conflicting CSS styles, incorrect sizing of the parent or SimpleBar container, or not importing the necessary SimpleBar CSS stylesheet.","error":"Scrollbar is not visible or looks broken, or native scrollbar is still present."},{"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.","cause":"The `simplebar` component was not properly registered in the Vue application's `components` option.","error":"Vue component not rendering or 'simplebar is not defined' error in template."},{"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.","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.","error":"'TypeError: (0 , SimpleBar.default).getOptions is not a function' or similar when using simplebar-vue@2.0.0-beta.2."}],"ecosystem":"npm"}