Vue2Native Scrollbar

The first Vue 2 custom scrollbar library that only enhances scrolling instead of reimplementing it with custom scroll behavior.

It uses native scroll events to detect and synchronize scrollbar position. This makes possible to hack into the native events of scrolling element without hassle.

It was created initially for GGather.com where it plays nicely with a lot of dynamic content changes and most importantly - with infinite scrolling. And now after testing, fixes, improvements and added customization options - it's ready to be shared with the world.

• Directive instead custom component, which saves a lot of headaches.
• Native scroll events, no jankiness, no hijacking.
• Simple to use, lightweight & performant.
• Works in browser and also build (webpack, etc.) environments.
• Compatible with all major browsers including IE9 and above.
• Useful customization options.
• No 3rd party dependencies.
• Tested in production.

NPM

npm install vue-native-scrollbar --save

CDN

https://unpkg.com/vue-native-scrollbar

Manual

Download the .js file directly from latest commit and include manually in your project

Basic Markup

<div v-scrollbar> <!-- el1 -->
  <div> <!-- el2 -->
     <!-- your scrollable content -->
  </div>
  <!-- dragger will be automatically added here -->
</div>

Markup with example options

<div v-scrollbar="{
    preventParentScroll: true,
    scrollThrottle: 30,
}"> <!-- el1 -->
  <div> <!-- el2 -->
     <!-- your scrollable content -->
  </div>
  <!-- dragger will be automatically added here -->
</div>

How It Works

Every Vue Native Scrollbar (referenced further as VNS) scrollable content needs to be wrapped in two elements. First outermost parent element el1 hides the native browser scrollbar of the second parent element el2 and it also contains the custom scrollbar element (referenced further as dragger) which gets appended automatically on the VNS initialization.

The VNS internals listen to el2 scroll event and synchronize dragger position when you scroll. And vice versa - when you directly use dragger it listens to mouse events to detect the position of dragger and sets scroll position of el2.

Other than setting the scroll position when you use dragger the VNS doesn't interfere at all with native browser scrolling and you can listen to scroll/wheel/etc. events as you would normally do.

This also means the scroll behavior will remain unchanged. You'll still be able to use mouse wheel click scrolling or touch scrolling with momentum. It doesn't try to reimplement the scrolling from scratch like most of similar libraries try (with bad results).

Gotchas

• Element el1 has programmatically added styles position: relative and overflow: hidden so you can't change them without using !important. But you shouldn't do it anyway - your scrollbar will break.
• Element el2 has programmatically added styles overflow-x: hidden, overflow-y: scroll, height: 100%, -ms-overflow-style: scrollbar and width which value depends on browser.
• Similar thing with dragger - it has programmatically added styles position: absolute and height with top that have values in pixels relative to scroll position.
• Sometimes in rare cases the scrollbar won't refresh on child components update. In such cases please manually use $forceUpdate (in the scope of component containing VNS) to refresh scrollbar.
• Right now VNS doesn't support loading detection of img elements so either set width and height properties of image from beginning or manually detect load events and $forceUpdate component to refresh scrollbar. Pull requests welcome.

How to Style Scrollbar

Default Style

If you were looking for this library it means you want to style your scrollbars as you want - so VNS doesn't include default styles internally. But if you e.g. want to quickly try or understand how you should style VNS scrollbars then below are prepared default styles that you can copy-paste into your project.

.vns > .vns-dragger {
    z-index: 2;
    width: 12px;
    right: 0;
}

.vns > .vns-dragger > .vns-dragger-styler {
    -webkit-backface-visibility: hidden;
    backface-visibility: hidden;
    -webkit-transform: rotate3d(0,0,0,0);
    transform: rotate3d(0,0,0,0);
    -webkit-transition:
        background-color 100ms ease-out,
        margin 100ms ease-out,
        height 100ms ease-out;
    transition:
        background-color 100ms ease-out,
        margin 100ms ease-out,
        height 100ms ease-out;
    background-color: rgba(48, 121, 244,.1);
    margin: 5px 5px 5px 0;
    border-radius: 20px;
    height: calc(100% - 10px);
    display: block;
}

.vns.vns-scrolling-phantom > .vns-dragger > .vns-dragger-styler {
    background-color: rgba(48, 121, 244,.3);
}

.vns > .vns-dragger:hover > .vns-dragger-styler {
    background-color: rgba(48, 121, 244,.5);
    margin: 0px;
    height: 100%;
}

.vns.vns-dragging > .vns-dragger > .vns-dragger-styler {
    background-color: rgba(48, 121, 244,.5);
    margin: 0px;
    height: 100%;
}

.vns.vns-dragging-phantom > .vns-dragger > .vns-dragger-styler {
    background-color: rgba(48, 121, 244,.5);
}

Other than examples below - this site itself is an example of Vue Native Scrollbar usage. If you look to the right it has a custom white scrollbar that showcases itself pretty nicely.

Default without options Update with additional content Hide additional content

By examining data from the two volcanoes, Mr. Jones and his team suggested an alternative: The chemical signature, along with this double-track volcanism as it’s called, occurred three million years ago when the plates above the hot spot shifted direction, moving north. This shimmy rearranged zones of magma that are heated under different pressures in the shallower part of the mantle — when they cool, the volcanic rock that results reflects this difference. Previously stacked on top of one another, the movement of the plates exposed now geographically separates magma zones that fed the volcanoes individually. Mauna Loa, the biggest volcano on Earth — and one of the most active — covers half the Island of Hawaii. Just 35 miles to the northeast, Mauna Kea, known to native Hawaiians as Mauna a Wakea, rises nearly 14,000 feet above sea level. To them it represents a spiritual connection between our planet and the heavens above. These volcanoes, which have beguiled millions of tourists visiting the Hawaiian islands, have also plagued scientists with a long-running mystery: If they are so close together, how did they develop in two parallel tracks along the Hawaiian-Emperor chain formed over the same hot spot in the Pacific Ocean — and why are their chemical compositions so different? "We knew this was related to something much deeper, but we couldn’t see what,” said Tim Jones, an earth science Ph.D. student at Australian National University and the lead author of a paper published in Nature on Wednesday that may hold the answer. Mr. Jones and his colleagues developed a model that simulates what’s happening in our planet’s mantle, beneath the crust that we live on, offering a window to the center of the Earth — or close to it.

Their study may one day allow a reconstruction of the history of the movement of Earth’s plates — and the processes linked to these movements over billions of years, like mass extinction events, diamond and oil deposits, and changes in climate. If you were to drill nearly 4,000 miles into the Earth, you’d reach its core, a ball of solid iron surrounded by liquid that scientists estimate is hotter than the sun. Before making it there, you’d hit the mantle — an 1,800-mile-thick layer of solid rock that can flow like a liquid, just substantially slower. This mantle is the reason plates move across the surface. It’s why we have continents, earthquakes and volcanoes. The closest anyone ever got to the mantle was a seven-mile-deep hole drilled into the crust on a peninsula in western Russia. But now we can better understand what’s happening below by looking at Mauna Kea and Mauna Loa, said Mr. Jones. The prevailing hypothesis has been that volcanoes like these two in Hawaii are chemical fingerprints of the Earth’s composition at the deep mantle, just at the border of its core. Scientists have seismic evidence that the deep part of the mantle is a graveyard where long ago slabs of earth were subducted, or thrust underneath one another, creating separate regions with different chemical compositions that eventually made their way to the surface in a hot mantle plume, or upwelling, as the core heated the rock into magma.

But that didn’t explain the separate tracks along which the volcanoes formed.

Enabled preventParentScroll Update with additional content Hide additional content

Choppy - scrollThrottle and draggerThrottle set to 100

Scrollbar invisible

Contributing

There's still a lot that can be introduced to Vue Native Scrollbar. If you have willingness you can help out on GitHub with the issues below.

• Option to dynamically enable/disable scrollbar.
• Support for compatibility of Vue Native Scrollbar element classes with component scoped selectors.
• Support for scrollbar refresh on dynamic content (mainly img) load (MutationObserver?).
• Support for scrollbar refresh on orientationchange event.
• Support for dragging dragger using touch events.
• preventParentScroll support for touch scrolling.
• Support for horizontal scrolling.
• Issue of scrollbar sometimes not refreshing on child components updates.

Credits

Created by Dominik Serafin for GGather.com.
Inspired by nanoScroller.