Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rigor789/vue-scrollto
Adds a directive that listens for click events and scrolls to elements.
https://github.com/rigor789/vue-scrollto
directive easings nuxt-module request-animation-frame vue vue-plugin vuejs
Last synced: 4 days ago
JSON representation
Adds a directive that listens for click events and scrolls to elements.
- Host: GitHub
- URL: https://github.com/rigor789/vue-scrollto
- Owner: rigor789
- License: mit
- Created: 2016-04-10T17:40:10.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2023-08-16T09:34:20.000Z (over 1 year ago)
- Last Synced: 2024-10-29T14:59:52.073Z (2 months ago)
- Topics: directive, easings, nuxt-module, request-animation-frame, vue, vue-plugin, vuejs
- Language: JavaScript
- Homepage: https://vue-scrollto.rigor789.com/
- Size: 4.23 MB
- Stars: 2,071
- Watchers: 16
- Forks: 99
- Open Issues: 80
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- stars - rigor789/vue-scrollto
README
# vue-scrollto
[](https://vuejs.org/v2/guide/)
[](https://v3.vuejs.org/guide/introduction.html)
[](https://www.npmjs.com/package/vue-scrollto)
[](https://www.npmjs.com/package/vue-scrollto)
[](https://github.com/rigor789/vue-scrollto/blob/master/LICENSE)
[DEMO](https://vue-scrollto.rigor789.com/examples)
Scrolling to elements was never this easy!
This is for `vue 2.x` and `vue 3.x` (since [`v2.19.0`](https://github.com/rigor789/vue-scrollto/releases/tag/v2.19.0))
For `vue 1.x` use `[email protected]` (note the capital T) but keep in mind that the old version depends on `jquery`.
## Under the hood
`vue-scrollto` uses `window.requestAnimationFrame` to perform the animations, thus giving the best performance.
Easing is done using [bezier-easing](https://github.com/gre/bezier-easing) - A well tested easing micro-library.
It even knows when the user interrupts, and doesn't force scrolling that would result in bad UX.
## Installing
This package is available on npm.
If you used this package before, please ensure you are using the right one, since it has been renamed from `vue-scrollTo` to `vue-scrollto`
Using npm:
```bash
npm install --save vue-scrollto
```
Using yarn:
```bash
yarn add vue-scrollto
```
Directly include it in html:
```html
```
When including it in html, it will automatically call `Vue.use` and also set a `VueScrollTo` variable that you can use!
## Nuxt.js
Add `vue-scrollto/nuxt` to modules section of `nuxt.config.js`
```js
{
modules: [
'vue-scrollto/nuxt',
// Or if you have custom options...
['vue-scrollto/nuxt', { duration: 300 }],
]
}
```
## Usage
vue-scrollto can be used either as a vue directive, or programatically from your javascript.
### As a vue directive
```js
var Vue = require('vue');
var VueScrollTo = require('vue-scrollto');
Vue.use(VueScrollTo)
// You can also pass in the default options
Vue.use(VueScrollTo, {
container: "body",
duration: 500,
easing: "ease",
offset: 0,
force: true,
cancelable: true,
onStart: false,
onDone: false,
onCancel: false,
x: false,
y: true
})
```
In case you are using the browser version (directly including the script on your page), you can set the defaults with
```js
VueScrollTo.setDefaults({
container: "body",
duration: 500,
lazy: false,
easing: "ease",
offset: 0,
force: true,
cancelable: true,
onStart: false,
onDone: false,
onCancel: false,
x: false,
y: true
})
```
```html
Scroll to #element
Hi. I'm #element.
```
If you need to customize the scrolling options, you can pass in an object literal to the directive:
```html
Scroll to #element
```
Check out the Options section for more details about the available options.
### Programmatically
```js
var VueScrollTo = require('vue-scrollto');
var options = {
container: '#container',
easing: 'ease-in',
lazy: false,
offset: -60,
force: true,
cancelable: true,
onStart: function(element) {
// scrolling started
},
onDone: function(element) {
// scrolling is done
},
onCancel: function() {
// scrolling has been interrupted
},
x: false,
y: true
}
var cancelScroll = VueScrollTo.scrollTo(element, duration, options)
// or alternatively inside your components you can use
cancelScroll = this.$scrollTo(element, duration, options)
// to cancel scrolling you can call the returned function
cancelScroll()
```
## Options
#### el / element
The element you want to scroll to.
#### container
The container that has to be scrolled.
*Default:* `body`
#### duration
The duration (in milliseconds) of the scrolling animation.
*Default:* `500`
#### easing
The easing to be used when animating. Read more in the [Easing section](#easing-detailed).
*Default:* `ease`
#### lazy
By default targetX/targetY are calculated once at the start of a scroll, however if the target may shift around during the scroll - setting `lazy` to `false` will force recalculation of targetX/targetY at each scroll step.
*Default:* `true`
#### offset
The offset that should be applied when scrolling. This option accepts a callback function since `v2.8.0`.
*Default:* `0`
#### force
Indicates if scrolling should be performed, even if the scroll target is already in view.
*Default:* `true`
#### cancelable
Indicates if user can cancel the scroll or not.
*Default:* `true`
#### onStart
A callback function that should be called when scrolling has started. Receives the target element as a parameter.
*Default:* `noop`
#### onDone
A callback function that should be called when scrolling has ended. Receives the target element as a parameter.
*Default:* `noop`
#### onCancel
A callback function that should be called when scrolling has been aborted by the user (user scrolled, clicked etc.). Receives the abort event and the target element as parameters.
*Default:* `noop`
#### x
Whether or not we want scrolling on the `x` axis
*Default:* `false`
#### y
Whether or not we want scrolling on the `y` axis
*Default:* `true`
Easing
Easing is calculated using [bezier-easing](https://github.com/gre/bezier-easing) so you can pass your own values into `options.easing` in the form of an array with 4 values, or you can use any of the default easings by referencing their names as strings (`ease`, `linear`, `ease-in`, `ease-out`, `ease-in-out`).
vue-scrollto uses the following values for the default easings:
```js
let easings = {
'ease': [0.25, 0.1, 0.25, 1.0],
'linear': [0.00, 0.0, 1.00, 1.0],
'ease-in': [0.42, 0.0, 1.00, 1.0],
'ease-out': [0.00, 0.0, 0.58, 1.0],
'ease-in-out': [0.42, 0.0, 0.58, 1.0]
}
```
## Simultaneous Scrolling
If you need to scroll multiple containers simultaneously, you can import the scroller factory directly and create multiple instances. (Using the default `scrollTo` methods allows for only one scroll action at a time for performance reasons.)
```js
import {scroller} from 'vue-scrollto/src/scrollTo'
const firstScrollTo = scroller()
const secondScrollTo = scroller()
firstScrollTo('#el1')
secondScrollTo('#el2')
```
## License
MIT