Custom Vue Scrollbar

Common errors

• Component 'CustomScrollbar' is not defined.

  cause The CustomScrollbar component has not been globally registered or locally imported and registered within the current Vue component.
  fix For global registration, add `app.component(CustomScrollbar.name, CustomScrollbar);` in your `main.ts` file. For local usage, import it and add it to the `components` option of your Vue component.

• Scrollbars are not visible or scrolling does not work as expected.

  cause The `<custom-scrollbar>` component itself or its content does not have sufficient dimensions (width and height) to create an overflow condition, or the necessary CSS stylesheet is not loaded.
  fix Ensure the `<custom-scrollbar>` component has fixed `width` and `height` styles applied (e.g., `:style="{ width: '500px', height: '300px' }"`) and verify `import 'custom-vue-scrollbar/dist/style.css';` is present in your entry file.

• TypeError: Cannot read properties of undefined (reading 'scrollEl')

  cause Attempting to access `scroll.value.scrollEl` before the component is mounted or if the ref is not properly assigned or resolved.
  fix Ensure the component is mounted and the ref (`scrollRef`) is correctly bound to the `<custom-scrollbar>` instance in the template. Always add a null/undefined check before accessing properties, e.g., `if (scrollRef.value?.scrollEl) { ... }`.

Warnings

• breaking As of version 0.0.8, this package is in early development. Significant API changes, including breaking alterations to props, events, or component structure, are highly probable before a stable `1.0.0` release. Users should anticipate and prepare for such changes.
  Fix: Refer to the project's GitHub repository and README for the latest API documentation with each update.
• gotcha The `custom-scrollbar` component requires explicit `width` and `height` styles to be set on itself to establish a scrollable container. Without these, the component may not display scrollbars or function correctly, similar to native scroll elements.
  Fix: Ensure that the `<custom-scrollbar>` component has defined dimensions, for example, `:style="{ width: '500px', height: '300px' }"`.
• gotcha This library provides custom scrollbars but often expects interaction with the underlying native scroll element via `ref.scrollEl` for programmatic scrolling or obtaining scroll positions. Developers used to fully abstracted scroll APIs might find this approach different.
  Fix: Access the native scroll element through a template ref, e.g., `const scroll = ref<{ scrollEl: HTMLDivElement }>();` and then `scroll.value.scrollEl.scrollTo(...)`.

Install

• npm install custom-vue-scrollbar npm
• yarn add custom-vue-scrollbar yarn
• pnpm add custom-vue-scrollbar pnpm

Imports

• CustomScrollbar
  wrong:

  const CustomScrollbar = require('custom-vue-scrollbar');

  correct:

  import CustomScrollbar from 'custom-vue-scrollbar';

  The component is exported as a default export, typically used in ESM contexts.
• Styling
  wrong:

  @import '~custom-vue-scrollbar/dist/style.css';

  correct:

  import 'custom-vue-scrollbar/dist/style.css';

  The necessary CSS stylesheet must be imported to apply the scrollbar's default visual styles.
• Global Component Registration

  import CustomScrollbar from 'custom-vue-scrollbar';
  app.component(CustomScrollbar.name, CustomScrollbar);

  For global availability across your Vue application, register the component via `app.component` in your entry file (e.g., `main.ts`).

Quickstart

Demonstrates how to register and use the CustomScrollbar component, applying necessary styles and accessing the native scroll element via a ref for programmatic scrolling.

import { createApp, ref } from 'vue';
import CustomScrollbar from 'custom-vue-scrollbar';
import 'custom-vue-scrollbar/dist/style.css';

const app = createApp({
  template: `
    <custom-scrollbar ref="scrollRef" :style="{ width: '500px', height: '300px', border: '1px solid #ccc', margin: '20px' }">
        <div :style="{ width: '1000px', height: '600px', background: 'linear-gradient(to bottom right, #f0f8ff, #add8e6)' }">
            <p>Some great content that extends beyond the scroll area, allowing the custom scrollbar to demonstrate its functionality.</p>
            <p>Click the button below to scroll to the top smoothly.</p>
            <button @click="handleClickScrollToTop">Scroll to Top</button>
        </div>
    </custom-scrollbar>
  `,
  setup() {
    const scrollRef = ref<{ scrollEl: HTMLDivElement }>();

    const handleClickScrollToTop = () => {
      if (scrollRef.value?.scrollEl) {
        scrollRef.value.scrollEl.scrollTo({ top: 0, behavior: 'smooth' });
      }
    };
    return { scrollRef, handleClickScrollToTop };
  }
});
app.component(CustomScrollbar.name, CustomScrollbar);
app.mount('#app');