Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Developmint/vue-next-level-scroll

Bring your scroll game to the next level!
https://github.com/Developmint/vue-next-level-scroll

scroll vue vue-component vuejs2

Last synced: about 1 month ago
JSON representation

Bring your scroll game to the next level!

Lists

README 

        
# VueNextLevelScroll - Bring your scroll game to the next level!





  Build Status

  Code coverage

  Downloads

  Version

  License

  We use Conventional Commits

  Thanks badge




> "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/](https://oqxy5xr5ny.sse.codesandbox.io/).



### :package: Through NPM



```

$ npm install vue-next-level-scroll

```



#### Synchronous import



```js

import VueNextLevelScroll from 'vue-next-level-scroll'



export default {

  components: {

    VueNextLevelScroll

  }

}



```



#### Async import



```js

export default {

  components: {

    VueNextLevelScroll: () => import('vue-next-level-scroll')

  }

}



```



### :link: Using a CDN



[UNPKG](https://unpkg.com/vue-next-level-scroll/dist/) | [jsDelivr](https://cdn.jsdelivr.net/npm/vue-next-level-scroll/dist/) (available as window.nextLevelScroll)



```js

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`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior) 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](https://github.com/iamdustan/smoothscroll) (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:



```html



  



```



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



```html



  





```



#### Scroll to non-existing query selector



When the `target` prop is given but no node matches, a console error will appear.



```html



  





```



```js

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:



```html



    

      

    

    



export default {

 methods: {

   myScroll (target) { doSomeMagicHere(target) }

  }

}



```



You might not need the polyfill then as well :wink:



## :gear: Contributing



Please see our [CONTRIBUTING.md](./CONTRIBUTING.md)



## :bookmark_tabs: License



[MIT License](./LICENSE.md) - Copyright (c) Developmint - Alexander Lichter