OverlayScrollbars for Vue

Common errors

• Module not found: Error: Can't resolve 'overlayscrollbars/overlayscrollbars.css' in '...' or similar CSS import error

  cause The CSS file for OverlayScrollbars could not be found, likely due to an incorrect import path or module resolution issues.
  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'`.

• Failed to resolve component: OverlayScrollbarsComponent If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.

  cause The `OverlayScrollbarsComponent` was used in a Vue template but not correctly imported or registered with the component.
  fix Ensure `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

  cause The core `overlayscrollbars` library, a required peer dependency, is not installed or accessible.
  fix Install the core library: `npm install overlayscrollbars`.

Warnings

• gotcha 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.
  Fix: Run `npm install overlayscrollbars vue` in your project's root directory.
• gotcha The CSS import path can be ambiguous. The primary path is `overlayscrollbars/overlayscrollbars.css`, but some build systems might require `overlayscrollbars/styles/overlayscrollbars.css`.
  Fix: If 'overlayscrollbars/overlayscrollbars.css' fails, try changing the import to 'overlayscrollbars/styles/overlayscrollbars.css'.
• gotcha 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.
  Fix: Add the `defer` attribute to your `OverlayScrollbarsComponent`, e.g., `<OverlayScrollbarsComponent defer>...</OverlayScrollbarsComponent>`.
• deprecated 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.
  Fix: Update your `options.debounce` usage from a single number to an object, e.g., `{ debounce: { mutations: 100, resizes: 200 } }` instead of `{ debounce: 200 }`.

Install

• npm install overlayscrollbars-vue npm
• yarn add overlayscrollbars-vue yarn
• pnpm add overlayscrollbars-vue pnpm

Imports

• OverlayScrollbarsComponent
  wrong:

  const OverlayScrollbarsComponent = require('overlayscrollbars-vue');

  correct:

  import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';

  This package primarily targets ESM environments for Vue 3. CommonJS `require` syntax is generally incorrect in modern Vue CLI/Vite setups.
• CSS
  wrong:

  import 'overlayscrollbars/styles/overlayscrollbars.css';

  correct:

  import 'overlayscrollbars/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.

Quickstart

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>
  `
});