Registry / web-framework / custom-vue-scrollbar

custom-vue-scrollbar

library0.0.8jsnpmunverified

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.

web-framework

npm install custom-vue-scrollbar

package ↗

INSTALL

IMPORT

SIG · CUSTOM-VUE-SCROLLB

custom-vue-scrollbar

web-frameworkjavascriptv0.0.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CustomScrollbar

✓ import CustomScrollbar from 'custom-vue-scrollbar';

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

The component is exported as a default export, typically used in ESM contexts.

Styling

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

✗ @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`).

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');

Debug

Known issues

breakingAs 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.

affects: <1.0.0

gotchaThe `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' }"`.

affects: >=0.0.1

gotchaThis 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(...)`.

affects: >=0.0.1

Errors

Common errors & fixes

Component 'CustomScrollbar' is not defined.

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.

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')

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) { ... }`.

Upgrade

Version history

0.0.8latest on npm

Audit

Dependencies

lodash-esrequiredUsed for debounce/throttle functionality when observing size changes, which contributes to its high performance claims.

vuerequiredPeer dependency as it is a Vue 3 component library.

Agent activity

8 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/custom-vue-scrollbar ↗