custom-vue-scrollbar(Vue3)

custom-react-scrollbar (react version here)

English | 中文

Demos

It's dependencies of custom-vue-table.

• Few APIs, used like native scroll container.
• Customize the scroll bar style.
• Support the minimum size/maximum size setting of the scroll bar.
• Automatically hide the scroll bar and optional set the automatic hide delay.
• Floating scroll bar (when the scroll container exceeds the visible area of ​​the screen, the scroll bar is fixed at the bottom of the screen).
• High performance.Optional debounce/throttle to observe size changes.。
• Support native scroll mode (default) and simulate scroll mode (useful in scenes such as: scroll synchronously with outer float elements).
• it's lightweight. 16.5kb uncompressed, 4.5kb after compression (gzip).
• typescript support.

Install

npm install --save custom-vue-scrollbar

// main.ts
import CustomScrollbar from 'custom-vue-scrollbar';
import 'custom-vue-scrollbar/dist/style.css';
app.component(CustomScrollbar.name, CustomScrollbar);

declare module 'vue' {
    export interface GlobalComponents {
        CustomScrollbar: typeof CustomScrollbar;
    }
}

Basic Usage

Just give it a fixed size like using a native scroll container.The native scroll api can be used via the ref.scrollEl.

<template>
    <custom-scrollbar :style="{ width: '500px', height: '300px' }">
        <div :style="{ width: '1000px', height: '600px' }">
            Some great content...
        </div>
    </custom-scrollbar>
</template>

<script lang="ts" setup>
import { ref } from 'vue';
const scroll = ref<{ scrollEl: HTMLDivElement; }>();

const handleClickScrollToTop = () => {
    if (!scroll.value.scrollEl) return;
    scroll.value.scrollEl.scrollTo({ top: 0, behavior: 'smooth' });
}
</script>

Props

In addition to the following component Props, all native DOM properties and events can also be used.

class :string = undefined Container class, which is generally only used to set the size.

style :object = undefined Container style.

contentClass :string = undefined Content class, the place to set display, padding, etc.

contentStyle :object = undefined Content style.

direction :'horizontal' | 'vertical' = 'vertical'
If you need to change the content container to horizontal layout, you can set the component property 'direction' to 'horizontal' to change the layout to 'display': 'flex' & 'flex-direction': 'row'. Or set it manually via 'contentClass' / 'contentStyle' properties. However, it is not recommended to set it manually, as the 'direction' property is related to the 'fixedThumb' property below.

thumbMinSize / thumbMaxSize :number = 48 / Infinity
Sets the minimum/maximum size of the scrollbar.

autoHide :boolean = true
When turned on, the scrollbar will be displayed only when the mouse hovers over the scroll container.

autoHideDelay :number(ms) = 900 When the scrolling is triggered, the scrollbar will be hidden only after the delay set by autoHideDelay.

autoExpand :boolean = true
Scroll bar default is 8px wide, the actual external has a 12px placeholder container, click, drag and drop logic is hanging on this placeholder container (convenient to click, 8px visually comfortable but difficult). When this option is turned on, the occupancy container hover, the scrollbar width will change to the width of the occupancy container.

fixedThumb :boolean = false The 'direction' property specifies the direction as the 'major axis direction'. When the 'fixedThumb' property is turned on, if the secondary axis has a scrollbar and the major axis has a scroll container that is partially off-screen. The scrollbar of the secondary axis will float to the edge of the screen.

throttleType :'throttle' | 'debounce' | 'none' = 'debounce' ResizeObserver listens for changes in the size of the container/content DOM Node to update the size of the scrollbar. Most scenarios do not require a high refresh rate and using 'debounce' is sufficient in most scenarios.

throttleWait :number = 333 The time to trigger when the 'throttleType' attribute is not 'none'.

simulateScroll :boolean = false Use 'wheel' to simulate scrolling instead of native scrolling. Turn it on when you need to synchronize the scrolling progress with an external floating element to eliminate the jitter caused by native scrolling that is not in the same event loop when synchronizing.

Emit

interface Rect {
    left: number;
    top: number;
    right: number;
    bottom: number;
    width: number;
    height: number;
    x: number;
    y: number;
}

wrapperResize :(rect: Rect) => void Triggered when the size of the scroller container changes

contentResize :(rect: Rect) => void Triggered when the size of the scroller content changes

Overwrite scrollbar style

// Modify the scrollbar size (placeholder container), the width of the scrollbar display before hover is 2/3 of the placeholder container, as follows, it is 12px.
.scrollbar__thumbPlaceholder--vertical {
    width: 20px;
}
.scrollbar__thumbPlaceholder--horizontal {
    height: 20px;
}

// Modify the scrollbar style.
.scrollbar__thumb {
    background-color: red;
}

Running example

Run the demos:

npm install
npm run dev

Build lib

npm install
npm run build:lib

License

MIT