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.
Installation
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
<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.
Styling
Every Vuebar element has a child dragger element. That element also has its own child - a dragger-styler element that's purely there for you to style it any way you want. You can also style the original dragger element - just remember it has position: absolute style always applied and height and top styles dynamically added & changed when scrolling.
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.
Prevent parent taking over scrolling after reaching bottom or top of Vuebar element. This feature is in beta - right now it supports only detecting mouse wheel event and doesn't support touch scrolling. Pull requests welcome.
unselectableBody
Boolean
true
Disable user select on body when using dragger. If this value is false then user select will be only disabled on Vuebar element.
useScrollbarPseudo
Boolean
false
This is an experimental feature that works only in desktop Google Chrome and desktop Apple Safari. Instead of hiding scrollbars by using hidden overflow this feature will hide them using ::-webkit-scrollbar pseudo element selectors.
overrideFloatingScrollbar
Boolean
true
Show dragger if the element has a floating/overlaying scrollbar. It happens on touch devices and on IE & Edge with -ms-autohiding-scrollbar.
scrollThrottle
Integer
10
How frequently in ms should dragger position calculations take place on scroll event. Setting this above 30 will make dragger position refresh choppy, but may help with performance in extreme situations.
draggerThrottle
Integer
10
How frequently in ms should scroll position update when using dragger. Setting this above 30 will make scroll synchronization choppy, but may help with performance in extreme situations.
observerThrottle
Integer
100
How frequently in ms should scroll position update when there's a DOM change detected from MutationObserver. It fires in 3 scenarios; subtree change, childList change and characterData change.
resizeRefresh
Boolean
true
Refresh dragger positions on window resize.
resizeDebounce
Integer
100
Debounce value in ms controlling how frequently resize refresh is fired. Relevant only if resizeRefresh is enabled.
scrollingPhantomDelay
Integer
1000
How long in ms should phantom scrolling class stay applied to element.
draggingPhantomDelay
Integer
1000
How long in ms should phantom dragging class stay applied to element. Warning - setting this below value of scrollThrottle may have some unforeseen effects.
Customization options (custom classes)
Name
Value Type
Value Default
Description
el1Class
String
'vb'
Element 1 class.
el1ScrollVisibleClass
String
'vb-visible'
Added dynamically when the scrollbar is visible.
el1ScrollInvisibleClass
String
'vb-invisible'
Added dynamically when the scrollbar is invisible.
el1ScrollingClass
String
'vb-scrolling'
Added dynamically on scrolling.
el1ScrollingPhantomClass
String
'vb-scrolling-phantom'
Added dynamically on scrolling and removed after value of scrollingPhantomDelay.
el1DraggingClass
String
'vb-dragging'
Added dynamically when the dragger is dragged or pressed.
el1DraggingPhantomClass
String
'vb-dragging-phantom'
Added dynamically when the dragger is dragged or pressed and removed after value of draggingPhantomDelay.
el2Class
String
'vb-content'
Element 2 class.
draggerClass
String
'vb-dragger'
Dragger class.
draggerStylerClass
String
'vb-dragger-styler'
Dragger styler class.
Examples
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
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.
Swimming hundreds of feet beneath the ocean’s surface in many parts of the world are prolific architects called giant larvaceans. These zooplankton are not particularly giant themselves (they resemble tadpoles and are about the size of a pinkie finger), but every day, they construct one or more spacious "houses” that can exceed three feet in length. The houses are transparent mucus structures that encase the creatures inside. Giant larvaceans beat their tails to pump seawater through these structures, which filter tiny bits of dead or drifting organic matter for the animals to eat. When their filters get clogged, the larvaceans abandon ship and construct a new house. Laden with debris from the water column, old houses rapidly sink to the seafloor. In a study published in Science Advances on Wednesday, scientists near California’s Monterey Bay have found that, through this process, giant larvaceans can filter all of the bay’s water from about 300 to 1,000 feet deep in less than two weeks, making them the fastest known zooplankton filter feeders. In doing so, the creatures help transfer carbon that has been removed from the atmosphere by photosynthesizing organisms to the deep sea, where it can be buried and stored long term. And given their abundance in other parts of the world, these organisms likely play a crucial role in the global carbon cycle. When it comes to the flow of carbon in the ocean, "we don’t know nearly as much as we should,” said Kakani Katija, a principal engineer at the Monterey Bay Aquarium Research Institute and the study’s lead author. "If we really want to understand how the system works, we have to look at all the players involved.
4. Option overrideFloatingScrollbar set to false. Difference visible only on touch devices and on IE & Edge with -ms-autohiding-scrollbar style.
Giant larvaceans are one important group we need to learn more about.” In the past, other scientists have tried studying giant larvaceans in the laboratory. But these efforts always failed because the animals’ houses were too fragile to be harvested and collected specimens were never able to build houses outside the ocean.To study the zooplankton in their natural habitat, Dr. Katija and her collaborators developed a new deep-sea imaging instrument, called DeepPIV, which they paired with a remotely operated vehicle. DeepPIV projects a sheet of laser light that cuts straight through a larvacean’s mucus house. A high-definition camera on the remotely operated vehicle can then capture the inner pumping mechanisms illuminated by the laser.Swimming hundreds of feet beneath the ocean’s surface in many parts of the world are prolific architects called giant larvaceans. These zooplankton are not particularly giant themselves (they resemble tadpoles and are about the size of a pinkie finger), but every day, they construct one or more spacious "houses” that can exceed three feet in length. The houses are transparent mucus structures that encase the creatures inside. Giant larvaceans beat their tails to pump seawater through these structures, which filter tiny bits of dead or drifting organic matter for the animals to eat. When their filters get clogged, the larvaceans abandon ship and construct a new house. Laden with debris from the water column, old houses rapidly sink to the seafloor. In a study published in Science Advances on Wednesday, scientists near California’s Monterey Bay have found that, through this process, giant larvaceans can filter all of the bay’s water from about 300 to 1,000 feet deep in less than two weeks, making them the fastest known zooplankton filter feeders. In doing so, the creatures help transfer carbon that has been removed from the atmosphere by photosynthesizing organisms to the deep sea, where it can be buried and stored long term. And given their abundance in other parts of the world, these organisms likely play a crucial role in the global carbon cycle. When it comes to the flow of carbon in the ocean, "we don’t know nearly as much as we should,” said Kakani Katija, a principal engineer at the Monterey Bay Aquarium Research Institute and the study’s lead author. "If we really want to understand how the system works, we have to look at all the players involved.
5. Option useScrollbarPseudo set to true It works only on Chrome & Safari. Inspect el2 to see the difference.
Giant larvaceans are one important group we need to learn more about.” In the past, other scientists have tried studying giant larvaceans in the laboratory. But these efforts always failed because the animals’ houses were too fragile to be harvested and collected specimens were never able to build houses outside the ocean.To study the zooplankton in their natural habitat, Dr. Katija and her collaborators developed a new deep-sea imaging instrument, called DeepPIV, which they paired with a remotely operated vehicle. DeepPIV projects a sheet of laser light that cuts straight through a larvacean’s mucus house. A high-definition camera on the remotely operated vehicle can then capture the inner pumping mechanisms illuminated by the laser.Swimming hundreds of feet beneath the ocean’s surface in many parts of the world are prolific architects called giant larvaceans. These zooplankton are not particularly giant themselves (they resemble tadpoles and are about the size of a pinkie finger), but every day, they construct one or more spacious "houses” that can exceed three feet in length. The houses are transparent mucus structures that encase the creatures inside. Giant larvaceans beat their tails to pump seawater through these structures, which filter tiny bits of dead or drifting organic matter for the animals to eat. When their filters get clogged, the larvaceans abandon ship and construct a new house. Laden with debris from the water column, old houses rapidly sink to the seafloor. In a study published in Science Advances on Wednesday, scientists near California’s Monterey Bay have found that, through this process, giant larvaceans can filter all of the bay’s water from about 300 to 1,000 feet deep in less than two weeks, making them the fastest known zooplankton filter feeders. In doing so, the creatures help transfer carbon that has been removed from the atmosphere by photosynthesizing organisms to the deep sea, where it can be buried and stored long term. And given their abundance in other parts of the world, these organisms likely play a crucial role in the global carbon cycle. When it comes to the flow of carbon in the ocean, "we don’t know nearly as much as we should,” said Kakani Katija, a principal engineer at the Monterey Bay Aquarium Research Institute and the study’s lead author. "If we really want to understand how the system works, we have to look at all the players involved.
6. Choppy but performant. Options scrollThrottle and draggerThrottle set to 100.
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. 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.
7. Dynamic Container
8. Scrollbar invisible. Content is not tall enough.
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.
9. Max-Height example
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 & Credits
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.
