VueNextLevelScroll - Bring your scroll game to the next level!
"Click to scroll" component using the modern Browser API.
🔥 Features
- Just one tiny file
- Component based (great for async loading and code splitting)
- Supports navigation through VueRouter
- Universal code/SSR-safe
- Well tested and documented
- Compatible with Node 8.0+
- Vue as the only dependency
- Highly customizable
🔎 Getting started
⭐ Demo
A live demo is available at https://oqxy5xr5ny.sse.codesandbox.io/.
📦 Through NPM
$ npm install vue-next-level-scroll
Synchronous import
import VueNextLevelScroll from 'vue-next-level-scroll'
export default {
components: {
VueNextLevelScroll
}
}Async import
export default {
components: {
VueNextLevelScroll: () => import('vue-next-level-scroll')
}
}🔗 Using a CDN
UNPKG | jsDelivr (available as window.nextLevelScroll)
Vue.component('scroll', window.nextLevelScroll)
// Continue as you wish. If you want to load a scroll behavior polyfill, do it **before** adding the CDN link.🛠️ Usage
You might like to go for a Polyfill
VueNextLevelScroll uses the new ScrollBehavior specification by default.
Unfortunately, Firefox is the only browser that has it built-in (by now).
For this reason, you might like to go for this polyfill (don't worry, less than 2kB after GZIP).
The component based approach
As you likely have seen, there are various Vue directives out their that handle scrolling as well. You might have used one or two of them already or built one yourself.
But! A component can sometimes be the better approach, as it can be tree shaken, is better suited for universal/SSR code and can be loaded asynchronously as well!
Prop overview
| Prop | Optional? | Comment |
|---|---|---|
| target | Can be any query selector you want (or a function that returns such). Will be passed to the scroll function | |
| tag | Defaults to div. The HTML tag used for the VueNextLevelScroll component |
|
| scrollFunction | You can define an own scroll function that will take the target prop as parameter and can do whatever you like. |
|
| shouldNavigate | If set, VueRouter will reflect navigation changes in the url(top: no hash, target: hash) | |
| navigationType | Defaults to push. The navigation type of that VueRouter should use. Usually either push or replace |
Default scroll function explained
Scroll to top
When no target prop is set, the default scroll function will trigger a scroll to top:
<vue-next-level-scroll>
<img src="https://developmint.de/logo.png">
</vue-next-level-scroll>Scroll to query selector
When the target prop is provided, the default scroll function look the DOM node up and smooth scroll to it.
If the target is a class query, the first found element will be chosen to scroll to.
<vue-next-level-scroll target="#my-target">
<img src="https://developmint.de/logo.png">
</vue-next-level-scroll>
<div id="my-target"/>Scroll to non-existing query selector
When the target prop is given but no node matches, a console error will appear.
<vue-next-level-scroll target="#my-target">
<img src="https://developmint.de/logo.png">
</vue-next-level-scroll>
<div id="my-non-existing-target"/>Error: Could not scroll to #my-targetCustom scroll function
Most users are satisfied with the default scroll function provided by VueNextLevelScroll However if you need other behavior you can simply write your own function:
<template>
<vue-next-level-scroll
target="#my-target"
:scrollFunction="myScroll">
<img src="https://developmint.de/logo.png">
</vue-next-level-scroll>
<div id="my-non-existing-target"/>
</template>
<script>
export default {
methods: {
myScroll (target) { doSomeMagicHere(target) }
}
}
</script>You might not need the polyfill then as well
⚙️ Contributing
Please see our CONTRIBUTING.md
📑 License
MIT License - Copyright (c) Developmint - Alexander Lichter