Morioh
Login
Vue Developers

Vue Developers

4 years ago

Perfect Scrollbar directive for Vue.js

What is perfect-scrollbar?

Perfect Scrollbar is a JavaScript Plugin that allows you customizing high perfermance scrollbars cross browsers. With the flexible plugin system, we can easily redesign the scrollbar as we want. perfect-scrollbar is minimalistic but perfect (for us, and maybe for most developers) scrollbar plugin.

No change on design layout
No manipulation on DOM tree
Use plain scrollTop and scrollLeft
Scrollbar style is fully customizable
Efficient update on layout change

We hope you will love it!

Before using perfect-scrollbar

The following requirements should meet.
the container must have a position style.
the container must be a normal container element.
The following requirements are included in the basic CSS, but please keep in mind when you’d like to change the CSS files.

the container must have an overflow: hidden css style.
the scrollbar’s position must be absolute.
the scrollbar-x must have bottom or top, and the scrollbar-y must have right or left.
Finally, scroll hooking is generally considered as a bad practice, and perfect-scrollbar should be used carefully. Unless custom scroll is really needed, using browser-native scroll is always recommended.

Caveats
perfect-scrollbar emulates some scrolls, but not all of the kinds. It also does not work in some situations. You can find these cases in Caveats. Basically, items listed in the caveats are hacky to implement and may not be implemented in the future. If the features are really needed, please consider using browser-native scroll.

How to use vue perfect scrollbar

npm i @morioh/v-perfect-scrollbar

or

yarn add @morioh/v-perfect-scrollbar

Register

import Vue from 'vue'
import ScrollBar from '@morioh/v-perfect-scrollbar'

// global register
Vue.use(ScrollBar);

or use via CDN

<script src="https://cdn.jsdelivr.net/npm/@morioh/v-perfect-scrollbar@latest/dist/scrollbar.min.js" type="text/javascript"></script>

unpkg CDN

<script src="https://unpkg.com/@morioh/v-perfect-scrollbar@latest/dist/scrollbar.min.js" type="text/javascript"></script>

<div v-scrollbar style="height: 500px">
  <img src="https://i.imgur.com/vIhs3zq.jpg" style="width:100%">
</div>

Common mistakes

Initialize a scrollbar without a limited width or height
Likes the native scrollbars, a scrollable area means the content insides it is larger than the container itself, for example, a 500x500 area with a content which size is 1000x1000:

              container
                 /
       +--------+
  #####################
  #    |        |     #
  #    |        |     #
  #    +--------+     # -- content
  #                   #
  #                   #
  #####################

Therefore, it’s necessary to set the width or height for the container element:

<div v-scrollbar style="max-height: 500px; max-height:500px"></div>

<div v-scrollbar style="height: 500px; height:500px"></div>

Horizontal Scrollbar

<div v-scrollbar style="width: 300px;">
  <div>
    <img style="width:500px" src="https://i.imgur.com/vIhs3zq.jpg">
  </div>

</div>

If the container element is natively scrollable before initializing the Scrollbar, it means you are on the correct way.

Perfect Scrollbar directive options

<div v-scrollbar="{
  wheelSpeed: 2,
  wheelPropagation: true,
  minScrollbarLength: 20
}" style="height: 500px;"></div>

Options

handlers {String[]}

It is a list of handlers to scroll the element.

Default: ['click-rail', 'drag-thumb', 'keyboard', 'wheel', 'touch']

wheelSpeed {Number}

The scroll speed applied to mousewheel event.

Default: 1

wheelPropagation {Boolean}

If this option is true, when the scroll reaches the end of the side, mousewheel
event will be propagated to parent element.

Default: true

swipeEasing {Boolean}

If this option is true, swipe scrolling will be eased.

Default: true

minScrollbarLength {Number?}

When set to an integer value, the thumb part of the scrollbar will not shrink
below that number of pixels.

Default: null

maxScrollbarLength {Number?}

When set to an integer value, the thumb part of the scrollbar will not expand
over that number of pixels.

Default: null

scrollingThreshold {Number}

This sets threshold for ps--scrolling-x and ps--scrolling-y classes to
remain. In the default CSS, they make scrollbars shown regardless of hover
state. The unit is millisecond.

Default: 1000

useBothWheelAxes {Boolean}

When set to true, and only one (vertical or horizontal) scrollbar is visible
then both vertical and horizontal scrolling will affect the scrollbar.

Default: false

suppressScrollX {Boolean}

When set to true, the scrollbar in X-axis will not be available, regardless of
the content width.

Default: false

suppressScrollY {Boolean}

When set to true, the scroll bar in Y-axis will not be available, regardless of
the content height.

Default: false

scrollXMarginOffset {Number}

The number of pixels the content width can surpass the container width without
enabling the X-axis scroll bar. Allows some “wiggle room” or “offset break”, so
that X-axis scroll bar is not enabled just because of a few pixels.

Default: 0

scrollYMarginOffset {Number}

The number of pixels the content height can surpass the container height without
enabling the Y-axis scroll bar. Allows some “wiggle room” or “offset break”, so
that Y-axis scroll bar is not enabled just because of a few pixels.

Default: 0

Live Preview: https://lab.morioh.com/v-perfect-scrollbar

Source Code: https://github.com/Morioh-Lab/v-perfect-scrollbar

Perfect Scrollbar: https://github.com/mdbootstrap/perfect-scrollbar

Recommended

☞ Smooth Scrollbar directive for Vue.js

☞ Quill Rich Text Editor component for Vue.js

☞ Markdown Editor component for Vue.js

☞ Simple notify handler component for Vue.js

☞ Lightbox Photo Grid and Slideshow component for Vue.JS

☞ Video Embed Component for Vue.JS

#vue.js #scrollbar #perfect-scrollbar #javascript

Perfect Scrollbar directive for Vue.js
126.75 GEEK