{"id":11510,"library":"overlayscrollbars-vue","title":"OverlayScrollbars for Vue","description":"OverlayScrollbars-Vue is the official Vue wrapper for the OverlayScrollbars library, providing highly customizable scrollbars that replace native browser scrollbars for consistent cross-browser styling and behavior. It integrates seamlessly into Vue 3 applications, offering both a component-based API (`OverlayScrollbarsComponent`) and a composable API for more granular control. Currently at version `0.5.9`, the package maintains an active release cadence, often aligning with updates to the underlying `OverlayScrollbars` core library, which is at `v2.15.0`. Recent core library updates have introduced features like configurable click-scroll behavior and performance optimizations such as a `sleep` function and enhanced debounce options. Its key differentiators include extensive customization options, performance optimizations like deferred initialization, and robust event handling, making it a powerful choice for enhancing UI/UX in Vue projects demanding bespoke scrollbar aesthetics and functionality.","status":"active","version":"0.5.9","language":"javascript","source_language":"en","source_url":"https://github.com/KingSora/OverlayScrollbars","tags":["javascript","overlayscrollbars","vue","vue2","vue3","component","composable","composition","styleable","typescript"],"install":[{"cmd":"npm install overlayscrollbars-vue","lang":"bash","label":"npm"},{"cmd":"yarn add overlayscrollbars-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add overlayscrollbars-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for the Vue component and composable integration.","package":"vue","optional":false},{"reason":"The core JavaScript library providing the scrollbar functionality, required as a peer dependency.","package":"overlayscrollbars","optional":false}],"imports":[{"note":"This package primarily targets ESM environments for Vue 3. CommonJS `require` syntax is generally incorrect in modern Vue CLI/Vite setups.","wrong":"const OverlayScrollbarsComponent = require('overlayscrollbars-vue');","symbol":"OverlayScrollbarsComponent","correct":"import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';"},{"note":"The primary CSS path is `overlayscrollbars/overlayscrollbars.css`. The alternative path `overlayscrollbars/styles/overlayscrollbars.css` can be used as a fallback if the main path doesn't resolve correctly in certain build configurations.","wrong":"import 'overlayscrollbars/styles/overlayscrollbars.css';","symbol":"CSS","correct":"import 'overlayscrollbars/overlayscrollbars.css';"}],"quickstart":{"code":"import { defineComponent } from 'vue';\nimport { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';\nimport 'overlayscrollbars/overlayscrollbars.css';\n\nexport default defineComponent({\n  components: { OverlayScrollbarsComponent },\n  data() {\n    return {\n      content: Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`).join('<br>')\n    };\n  },\n  methods: {\n    onScroll(instance, event) {\n      console.log('Scroll event!', event, instance.state().scrollOffset);\n    },\n    onInitialized(instance) {\n      console.log('OverlayScrollbars initialized:', instance);\n    }\n  },\n  template: `\n    <div style=\"width: 300px; height: 200px; border: 1px solid #ccc;\">\n      <h3>Scrollable Content</h3>\n      <OverlayScrollbarsComponent\n        element=\"div\"\n        :options=\"{ scrollbars: { autoHide: 'scroll', autoHideDelay: 200 } }\"\n        :events=\"{ scroll: onScroll, initialized: onInitialized }\"\n        defer\n        style=\"height: 100%;\"\n      >\n        <div v-html=\"content\"></div>\n      </OverlayScrollbarsComponent>\n    </div>\n  `\n});","lang":"typescript","description":"Initializes a custom scrollbar for a content area in a Vue component, demonstrating basic component usage with options, event handling, and deferred initialization for performance."},"warnings":[{"fix":"Run `npm install overlayscrollbars vue` in your project's root directory.","message":"The `overlayscrollbars` and `vue` packages are peer dependencies and must be installed separately alongside `overlayscrollbars-vue`. Failure to install them will lead to runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If 'overlayscrollbars/overlayscrollbars.css' fails, try changing the import to 'overlayscrollbars/styles/overlayscrollbars.css'.","message":"The CSS import path can be ambiguous. The primary path is `overlayscrollbars/overlayscrollbars.css`, but some build systems might require `overlayscrollbars/styles/overlayscrollbars.css`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add the `defer` attribute to your `OverlayScrollbarsComponent`, e.g., `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.","message":"It is highly recommended to use the `defer` prop on the `OverlayScrollbarsComponent` to postpone initialization to a browser's idle period, improving initial page load performance.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update your `options.debounce` usage from a single number to an object, e.g., `{ debounce: { mutations: 100, resizes: 200 } }` instead of `{ debounce: 200 }`.","message":"The `options.debounce` property in the core OverlayScrollbars library (which affects the `options` prop in this wrapper) was deprecated in v2.13.0 in favor of a new object syntax for fine-grained control over `mutations`, `resizes`, `events`, and `environmental changes`. While the old syntax is still supported, the new object syntax is preferred.","severity":"deprecated","affected_versions":">=0.4.0 (for overlayscrollbars-vue, reflecting core changes from overlayscrollbars >=2.13.0)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `overlayscrollbars` installed as a peer dependency (`npm install overlayscrollbars`) and try switching the import path between `'overlayscrollbars/overlayscrollbars.css'` and `'overlayscrollbars/styles/overlayscrollbars.css'`.","cause":"The CSS file for OverlayScrollbars could not be found, likely due to an incorrect import path or module resolution issues.","error":"Module not found: Error: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' or similar CSS import error"},{"fix":"Ensure `import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';` is present and the component is registered in your Vue component's `components` option: `components: { OverlayScrollbarsComponent }`.","cause":"The `OverlayScrollbarsComponent` was used in a Vue template but not correctly imported or registered with the component.","error":"Failed to resolve component: OverlayScrollbarsComponent If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement."},{"fix":"Install the core library: `npm install overlayscrollbars`.","cause":"The core `overlayscrollbars` library, a required peer dependency, is not installed or accessible.","error":"Uncaught ReferenceError: overlayscrollbars is not defined"}],"ecosystem":"npm"}