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.
OverlayScrollbarsComponent
✓ import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';
✗ const OverlayScrollbarsComponent = require('overlayscrollbars-vue');
This package primarily targets ESM environments for Vue 3. CommonJS `require` syntax is generally incorrect in modern Vue CLI/Vite setups.
CSS
✓ import 'overlayscrollbars/overlayscrollbars.css';
✗ import 'overlayscrollbars/styles/overlayscrollbars.css';
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.
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.
import { defineComponent } from 'vue';
import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';
import 'overlayscrollbars/overlayscrollbars.css';
export default defineComponent({
components: { OverlayScrollbarsComponent },
data() {
return {
content: Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`).join('<br>')
};
},
methods: {
onScroll(instance, event) {
console.log('Scroll event!', event, instance.state().scrollOffset);
},
onInitialized(instance) {
console.log('OverlayScrollbars initialized:', instance);
}
},
template: `
<div style="width: 300px; height: 200px; border: 1px solid #ccc;">
<h3>Scrollable Content</h3>
<OverlayScrollbarsComponent
element="div"
:options="{ scrollbars: { autoHide: 'scroll', autoHideDelay: 200 } }"
:events="{ scroll: onScroll, initialized: onInitialized }"
defer
style="height: 100%;"
>
<div v-html="content"></div>
</OverlayScrollbarsComponent>
</div>
`
});
Debug
Known issues
gotchaThe `overlayscrollbars` and `vue` packages are peer dependencies and must be installed separately alongside `overlayscrollbars-vue`. Failure to install them will lead to runtime errors.fixRun `npm install overlayscrollbars vue` in your project's root directory.
affects: >=0.1.0
gotchaThe CSS import path can be ambiguous. The primary path is `overlayscrollbars/overlayscrollbars.css`, but some build systems might require `overlayscrollbars/styles/overlayscrollbars.css`.fixIf 'overlayscrollbars/overlayscrollbars.css' fails, try changing the import to 'overlayscrollbars/styles/overlayscrollbars.css'.
affects: >=0.1.0
gotchaIt 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.fixAdd the `defer` attribute to your `OverlayScrollbarsComponent`, e.g., `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.
affects: >=0.1.0
deprecatedThe `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.fixUpdate your `options.debounce` usage from a single number to an object, e.g., `{ debounce: { mutations: 100, resizes: 200 } }` instead of `{ debounce: 200 }`. affects: >=0.4.0 (for overlayscrollbars-vue, reflecting core changes from overlayscrollbars >=2.13.0)
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' or similar CSS import error
The CSS file for OverlayScrollbars could not be found, likely due to an incorrect import path or module resolution issues.
fixEnsure 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'`.
Failed to resolve component: OverlayScrollbarsComponent If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.
The `OverlayScrollbarsComponent` was used in a Vue template but not correctly imported or registered with the component.
fixEnsure `import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';` is present and the component is registered in your Vue component's `components` option: `components: { OverlayScrollbarsComponent }`. Uncaught ReferenceError: overlayscrollbars is not defined
The core `overlayscrollbars` library, a required peer dependency, is not installed or accessible.
fixInstall the core library: `npm install overlayscrollbars`.
Audit
Dependencies
vuerequiredRequired as a peer dependency for the Vue component and composable integration.
overlayscrollbarsrequiredThe core JavaScript library providing the scrollbar functionality, required as a peer dependency.