Vuebar

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

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 built for GGather.com where it plays nicely with a lot of dynamic content changes and most importantly infinite scrolling and drag and drop features. And now after testing, fixes, improvements and added customization options - it's ready to be shared with the world.

• Directive instead of a 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 vuebar --save

CDN

https://unpkg.com/vuebar

Manual

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

Alternative #1: Include in browser

<script src="vuebar.js"></script>

Alternative #2: Include in your build

import Vuebar from 'vuebar';
Vue.use(Vuebar);

Basic Markup

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

Markup with example options

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

How it works

Every Vuebar scrollable content needs to be wrapped in parent element el1 that 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 Vuebar initialization.

New in 0.0.6: Instead of hiding the scrollbar using el1 Vuebar now has a useScrollbarPseudo feature that hides the scrollbar using pseudo element selector ::-webkit-scrollbar. Due to browsers limitations for now it works only on desktop Chrome & desktop Safari at the moment.

The Vuebar 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 Vuebar 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).

Public methods (experimental & work in progress)

You can access them from your component context: this.$vuebar. Alternatively you can access them from your main Vue instance: Vue.vuebar.

Every method needs to have passed Vuebar scroll container element as the first argument. You can do that easily using $refs.

• initScrollbar(DOM Element, options)
• getState(DOM Element)
• refreshScrollbar(DOM Element, options)
• destroyScrollbar(DOM Element)

Tips

• If you want to access internal Vuebar state (like scrollbar height, scrollbar top or even dragger element reference) then you can access _vuebarState property of element 1 with v-bar directive. Or you can use getState method.
• 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.
• If the original browser scrollbar is floated/overlayed (-ms-autohiding-scrollbar, touch devices, etc.) then el2 also has padding-right changed.
• Similar thing with dragger - it has programmatically added styles position: absolute and height with top that have values in pixels relative to scroll position.

Default Style

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

.vb > .vb-dragger {
    z-index: 5;
    width: 12px;
    right: 0;
}

.vb > .vb-dragger > .vb-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;
}

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

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

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

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

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

1. JSFiddle

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

3. Option preventParentScroll set to true. Update with additional content Hide additional content

4. Option overrideFloatingScrollbar set to false. Difference visible only on touch devices and on IE & Edge with -ms-autohiding-scrollbar style.

5. Option useScrollbarPseudo set to true It works only on Chrome & Safari. Inspect el2 to see the difference.

6. Choppy but performant. Options scrollThrottle and draggerThrottle set to 100.

7. Dynamic Container

8. Scrollbar invisible. Content is not tall enough.

9. Max-Height example

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.

Contributing

There's still a lot that can be introduced to Vuebar. If you're willing you can help out with the issues below.

• [High priority] Support for horizontal scrolling.
• [Medium priority] Support for Vue 1.x.
• [Medium priority] Automated tests for pull requests & general development.
• [Medium priority] Support for compatibility of Vuebar element classes with component scoped CSS selectors. (Is it even possible?).
• [Medium priority] preventParentScroll supporting scrolling with scrolling while dragging cursor, touch scrolling and also keyboard keys (space, shift+space, arrows, page up, pagedown). Maybe with options which ones to prevent and which ones to leave out.
• [Low priority] Support for scrollbar refresh on orientationchange event.
• [Low priority] Support for dragging dragger using touch events.
• [Low priority] Utility methods like; scroll to top/bottom/element/etc., force disable scrolling, dragger active class flash. And (disableable) events emit for e.g. when content was scrolled to top/bottom/element/etc.
• [Low priority] useScrollbarPseudo styles added with custom class instead of el1Class.

Credits

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