keepScrollPosition

Environment: client
Type: boolean | string | string[] | ((pageContext: PageContextClient) => boolean | string | string[])
Default value: false

The keepScrollPosition setting enables you to control whether the page scrolls to the top upon navigation.

It's commonly used for nested layouts such as tabs, see API > <Layout> > Nested layouts.

For a control on a link-by-link basis, see <a href="/some-url" keep-scroll-position />.

Basics

By default, the page is scrolled to the top upon navigation. But if you set keepScrollPosition to true then the page's scroll position is preserved instead.

// pages/product/@id/+config.js
 
export default {
  // Don't scroll to top when navigating between the pages defined at pages/product/@id/**
  keepScrollPosition: true
}
pages/product/@id/+config.js
pages/product/@id/pricing/+Page.js
pages/product/@id/reviews/+Page.js

# Scroll is preserved when navigating between:
/product/42
/product/42/pricing
/product/42/reviews
 
# Scroll is preserved when navigating between:
/product/1337
/product/1337/pricing
/product/1337/reviews

Note that the scroll isn't preserved (the page scrolls to the top) if the @id parameter differs.

# Scroll *isn't* preserved when navigating between:
/product/42/pricing
/product/1337/pricing

See Advanced if this behavior doesn't fit your use case.

Advanced

You can preserve the scroll position between any arbitrary group of pages (the "scroll group").

// /pages/product/@id/+config.js
 
export default {
  keepScrollPosition: 'name-of-the-scroll-group'
}
# Scroll is preserved when navigating between:
/product/42/pricing
/product/1337/pricing
// /pages/reviews/@id/+config.js
 
export default {
  keepScrollPosition: 'name-of-the-scroll-group'
}
# Scroll is preserved when navigating between:
/product/42
/reviews/1337

If two URLs belong to the same scroll group, then the scroll position is preserved.

You can also programmatically set the scroll group:

// /pages/product/@id/+keepScrollPosition.js
// Environment: client
 
export default (pageContext, { configDefinedAt }) => {
  console.log(configDefinedAt) // Prints '/pages/product/@id/+keepScrollPosition.js'
  // This is the value Vike sets by default:
  return [configDefinedAt, pageContext.routeParams['id']]
}

See also