vue-scrollto ​

DEMO

Scrolling to elements was never this easy!

This is for vue 2.x

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

npm install --save vue-scrollto

Using yarn:

yarn add vue-scrollto

Directly include it in html:

<script src="https://cdn.jsdelivr.net/npm/vue"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-scrollto"></script>

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

{
  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 ​

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

VueScrollTo.setDefaults({
  container: 'body',
  duration: 500,
  easing: 'ease',
  offset: 0,
  force: true,
  cancelable: true,
  onStart: false,
  onDone: false,
  onCancel: false,
  x: false,
  y: true,
})

<a href="#" v-scroll-to="'#element'">Scroll to #element</a>

<div id="element">
  Hi. I'm #element.
</div>

If you need to customize the scrolling options, you can pass in an object literal to the directive:

<a
  href="#"
  v-scroll-to="{
     el: '#element',
     container: '#container',
     duration: 500,
     easing: 'linear',
     offset: -200,
     force: true,
     cancelable: true,
     onStart: onStart,
     onDone: onDone,
     onCancel: onCancel,
     x: false,
     y: true
 }"
>
  Scroll to #element
</a>

Check out the Options section for more details about the available options.

Programatically ​

var VueScrollTo = require('vue-scrollto')

var options = {
  container: '#container',
  easing: 'ease-in',
  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.

Default: ease

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

let easings = {
  ease: [0.25, 0.1, 0.25, 1.0],
  linear: [0.0, 0.0, 1.0, 1.0],
  'ease-in': [0.42, 0.0, 1.0, 1.0],
  'ease-out': [0.0, 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.)

import { scroller } from 'vue-scrollto/src/scrollTo'
const firstScrollTo = scroller()
const secondScrollTo = scroller()
firstScrollTo('#el1')
secondScrollTo('#el2')

License ​

MIT