Scroll Behavior

Watch a free video lesson on Vue School

When using client-side routing, we may want to scroll to top when navigating to a new route, or preserve the scrolling position of history entries just like real page reload does. Vue Router allows you to achieve these and even better, allows you to completely customize the scroll behavior on route navigation.

Note: this feature only works if the browser supports history.pushState.

When creating the router instance, you can provide the scrollBehavior function:

  1. const router = createRouter({
  2.   history: createWebHashHistory(),
  3.   routes: [...],
  4.   scrollBehavior (to, from, savedPosition) {
  5.     // return desired position
  6.   }
  7. })

The scrollBehavior function receives the to and from route objects, like Navigation Guards. The third argument, savedPosition, is only available if this is a popstate navigation (triggered by the browser’s back/forward buttons).

The function can return a ScrollToOptions position object:

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     // always scroll to top
  4.     return { top: 0 }
  5.   },
  6. })

You can also pass a CSS selector or a DOM element via el. In that scenario, top and left will be treated as relative offsets to that element.

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     // always scroll 10px above the element #main
  4.     return {
  5.       // could also be
  6.       // el: document.getElementById('main'),
  7.       el: '#main',
  8.       top: -10,
  9.     }
  10.   },
  11. })

If a falsy value or an empty object is returned, no scrolling will happen.

Returning the savedPosition will result in a native-like behavior when navigating with back/forward buttons:

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     if (savedPosition) {
  4.       return savedPosition
  5.     } else {
  6.       return { top: 0 }
  7.     }
  8.   },
  9. })

If you want to simulate the “scroll to anchor” behavior:

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     if (to.hash) {
  4.       return {
  5.         el: to.hash,
  6.       }
  7.     }
  8.   },
  9. })

If your browser supports scroll behavior, you can make it smooth:

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     if (to.hash) {
  4.       return {
  5.         el: to.hash,
  6.         behavior: 'smooth',
  7.       }
  8.     }
  9.   }
  10. })

Delaying the scroll

Sometimes we need to wait a bit before scrolling in the page. For example, when dealing with transitions, we want to wait for the transition to finish before scrolling. To do this you can return a Promise that returns the desired position descriptor. Here is an example where we wait 500ms before scrolling:

  1. const router = createRouter({
  2.   scrollBehavior(to, from, savedPosition) {
  3.     return new Promise((resolve, reject) => {
  4.       setTimeout(() => {
  5.         resolve({ left: 0, top: 0 })
  6.       }, 500)
  7.     })
  8.   },
  9. })

It’s possible to hook this up with events from a page-level transition component to make the scroll behavior play nicely with your page transitions, but due to the possible variance and complexity in use cases, we simply provide this primitive to enable specific userland implementations.