{"id":10706,"library":"custom-vue-scrollbar","title":"Custom Vue Scrollbar","description":"custom-vue-scrollbar is a lightweight (4.5KB gzipped) and high-performance Vue 3 component designed to provide customizable scrollbars while maintaining a native-like scrolling experience. As of version 0.0.8, it is in early development, with an irregular release cadence. It aims to offer advanced features like floating scrollbars (which fix at the bottom of the screen if the container exceeds visible area), toggleable native/simulated scroll modes for diverse use cases (e.g., synchronizing with outer elements), and automatic scrollbar hiding with configurable delay options. A key differentiator is its emphasis on minimal intrusion, few APIs, and direct access to the native scroll element, distinguishing it from libraries that significantly alter native scrolling behavior or introduce complex abstractions like `better-scroll`. It supports TypeScript and prioritizes performance, outperforming older alternatives by optimizing rendering and minimizing JavaScript-level calculations.","status":"active","version":"0.0.8","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install custom-vue-scrollbar","lang":"bash","label":"npm"},{"cmd":"yarn add custom-vue-scrollbar","lang":"bash","label":"yarn"},{"cmd":"pnpm add custom-vue-scrollbar","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for debounce/throttle functionality when observing size changes, which contributes to its high performance claims.","package":"lodash-es","optional":false},{"reason":"Peer dependency as it is a Vue 3 component library.","package":"vue","optional":false}],"imports":[{"note":"The component is exported as a default export, typically used in ESM contexts.","wrong":"const CustomScrollbar = require('custom-vue-scrollbar');","symbol":"CustomScrollbar","correct":"import CustomScrollbar from 'custom-vue-scrollbar';"},{"note":"The necessary CSS stylesheet must be imported to apply the scrollbar's default visual styles.","wrong":"@import '~custom-vue-scrollbar/dist/style.css';","symbol":"Styling","correct":"import 'custom-vue-scrollbar/dist/style.css';"},{"note":"For global availability across your Vue application, register the component via `app.component` in your entry file (e.g., `main.ts`).","symbol":"Global Component Registration","correct":"import CustomScrollbar from 'custom-vue-scrollbar';\napp.component(CustomScrollbar.name, CustomScrollbar);"}],"quickstart":{"code":"import { createApp, ref } from 'vue';\nimport CustomScrollbar from 'custom-vue-scrollbar';\nimport 'custom-vue-scrollbar/dist/style.css';\n\nconst app = createApp({\n  template: `\n    <custom-scrollbar ref=\"scrollRef\" :style=\"{ width: '500px', height: '300px', border: '1px solid #ccc', margin: '20px' }\">\n        <div :style=\"{ width: '1000px', height: '600px', background: 'linear-gradient(to bottom right, #f0f8ff, #add8e6)' }\">\n            <p>Some great content that extends beyond the scroll area, allowing the custom scrollbar to demonstrate its functionality.</p>\n            <p>Click the button below to scroll to the top smoothly.</p>\n            <button @click=\"handleClickScrollToTop\">Scroll to Top</button>\n        </div>\n    </custom-scrollbar>\n  `,\n  setup() {\n    const scrollRef = ref<{ scrollEl: HTMLDivElement }>();\n\n    const handleClickScrollToTop = () => {\n      if (scrollRef.value?.scrollEl) {\n        scrollRef.value.scrollEl.scrollTo({ top: 0, behavior: 'smooth' });\n      }\n    };\n    return { scrollRef, handleClickScrollToTop };\n  }\n});\napp.component(CustomScrollbar.name, CustomScrollbar);\napp.mount('#app');","lang":"typescript","description":"Demonstrates how to register and use the CustomScrollbar component, applying necessary styles and accessing the native scroll element via a ref for programmatic scrolling."},"warnings":[{"fix":"Refer to the project's GitHub repository and README for the latest API documentation with each update.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure that the `<custom-scrollbar>` component has defined dimensions, for example, `:style=\"{ width: '500px', height: '300px' }\"`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Access the native scroll element through a template ref, e.g., `const scroll = ref<{ scrollEl: HTMLDivElement }>();` and then `scroll.value.scrollEl.scrollTo(...)`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The CustomScrollbar component has not been globally registered or locally imported and registered within the current Vue component.","error":"Component 'CustomScrollbar' is not defined."},{"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.","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.","error":"Scrollbars are not visible or scrolling does not work as expected."},{"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) { ... }`.","cause":"Attempting to access `scroll.value.scrollEl` before the component is mounted or if the ref is not properly assigned or resolved.","error":"TypeError: Cannot read properties of undefined (reading 'scrollEl')"}],"ecosystem":"npm"}