README

VueNextLevelScroll - Bring your scroll game to the next level!

"Click to scroll" component using the modern Browser API.

:fire: 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

:mag_right: Getting started

:star: Demo

A live demo is available at https://oqxy5xr5ny.sse.codesandbox.io/.

:package: 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')
  }
}

:link: 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.

:hammer_and_wrench: 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	:white_check_mark:	Can be any query selector you want (or a function that returns such). Will be passed to the scroll function
tag	:white_check_mark:	Defaults to `div`. The HTML tag used for the VueNextLevelScroll component
scrollFunction	:white_check_mark:	You can define an own scroll function that will take the `target` prop as parameter and can do whatever you like.
shouldNavigate	:white_check_mark:	If set, VueRouter will reflect navigation changes in the url(top: no hash, target: hash)
navigationType	:white_check_mark:	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-target

Custom 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"
      :scroll="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 :wink:

:gear: Contributing

Please see our CONTRIBUTING.md

vue-next-level-scroll

Usage no npm install needed!