import { enConfig } from './en.ts'

import { sharedConfig } from './shared.ts'

import { zhConfig } from './zh.ts'

import { zhSearch } from './zh.ts'

import { typedRouterFileAsModule } from '../twoslash-files.ts'

import { extraFiles } from '../twoslash/files.ts'

import typedocSidebar from '../../api/typedoc-sidebar.json' with { type: 'json' }

::: warning Experimental

This API is experimental and might have breaking changes.

:::

Scroll restoration lets components save and restore their own scroll positions. It is the **upcoming replacement** for the `scrollBehavior` router option.

With it, you can:

- Save multiple positions for one page

- Use custom capture and restore functions, for example with `scrollIntoView()`

- Control how pages share scroll restoration rather than relying on history entries

[[toc]]

Install `ScrollRestoration` before the router. Give it the router, and the default capture and restore functions:

```ts [main.ts]

import { createApp } from 'vue'

import {

ScrollRestoration,

SCROLL_RESTORATION_CAPTURE_DEFAULT,

SCROLL_RESTORATION_RESTORE_DEFAULT,

} from 'vue-router/experimental'

import App from './App.vue'

import { router } from './router'

const app = createApp(App)

app.use(ScrollRestoration, {

router,

capture: SCROLL_RESTORATION_CAPTURE_DEFAULT,

restore: SCROLL_RESTORATION_RESTORE_DEFAULT,

})

app.use(router)

app.mount('#app')

The default functions save and restore the window scroll position and imitate the current mechanism combined with `scrollBehavior()` and some smart defaults. They are automatically inherited by nested components and can be overridden anywhere. Call `useScrollRestoration()` in a component to use them.

Installing the plugin sets `history.scrollRestoration` to `manual`. Setting it to auto can with scroll restoration, especially in the context of _anchor links_. Set it back to `auto` if this is not an issue for you.

Call `useScrollRestoration()` in any page component that needs to restore its scroll position:

```vue [pages/Articles.vue]

The router _captures_ the position **when you leave the page** and _restores_ it after a navigation, when the component is mounted or updated using `onRouteRendered()`.

`capture()` returns an object. Each property is one saved position. Use `default` for the main position and add other names for other scroll containers:

```vue [pages/Docs.vue]

`capture()` and `restore()` must be synchronous.

You can save an element selector and scroll to it with a saved offset:

```vue [pages/Products.vue]

Return `null` from `capture()` to remove the saved entry.

By default, the key is `to.path + to.hash`. The same path and hash always use the same saved entry, including a new visit from a link. For example, if the users navigates to `/articles/42#comments`, scrolls down, and then navigates to `/articles/43`, navigating back **or** navigating directly again to `/articles/42#comments` will restore the previous position.

Use a different key when pages must share or split entries:

useScrollRestoration({

key: to => to.path,

})

useScrollRestoration({

key: to => to.fullPath,

})

useScrollRestoration({

key: 'products',

})

Components that are active at the same time must use different keys.

Set `manual: true` when the content is not ready after navigation, like animations or virtualized list. Then call `scroll()` when the content is displayed:

```vue [pages/Feed.vue]

The router still captures the position automatically.

<html lang="en">

<head>

<meta charset="UTF-8" />

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<meta http-equiv="X-UA-Compatible" content="ie=edge" />

<title>Navigation API - instances in guards</title>

<link rel="stylesheet" href="/global.css" />

<style>

.fade-enter-active,

.fade-leave-active {

transition: opacity 2s ease;

}

.fade-enter-from,

.fade-leave-active {

opacity: 0;

}

</style>

</head>

<body>

<a href="/navigation-api/">&lt;&lt; Back to Navigation API</a>

<hr />

<main id="app"></main>

<script type="module" src="/navigation-api/guards-instances.ts"></script>

</body>

import '../guards-instances/index'

const URL_START = `${location.protocol}//${location.host}`

function cleanUrl(url: string | null | undefined): string {

return url ? url.slice(URL_START.length) : '<empty>'

const delay = (time: number) =>

new Promise(resolve => setTimeout(resolve, time))

navigation.addEventListener('navigate', event => {

console.table({

id: event.destination.id,

key: event.destination.key,

type: event.navigationType,

info: event.info,

url: event.destination.url,

state: event.destination.getState(),

cancelable: event.cancelable,

})

console.log(

`🧭 ${cleanUrl(navigation.currentEntry?.url)} -> ${cleanUrl(event.destination.url)}`

)

if (!event.canIntercept) {

console.warn('Cannot intercept navigation event', event)

return

}

if (event.downloadRequest) {

console.warn('Navigation event has download request', event)

return

}

if (navigation.transition) {

console.log('🚗 pending navigation from', navigation.transition.from.url)

}

const url = new URL(event.destination.url)

event.intercept({

async handler() {

const delayTime = Number(url.searchParams.get('delay')) || 1000

console.log('🐢 navigating with delay of', delayTime, 'ms')

await delay(delayTime)

console.log('🐢 ✅')

console.log('Is aborted?', event.signal.aborted)

if (url.searchParams.has('cancel')) {

event.preventDefault()

return

}

if (url.searchParams.has('throw')) {

throw new Error('Navigation aborted')

}

},

focusReset: 'after-transition',

scroll: 'after-transition',

})