https://github.com/antfu/vue-router-better-scroller
Enhanced scroll behavior for Vue Router
https://github.com/antfu/vue-router-better-scroller
Last synced: about 1 month ago
JSON representation
Enhanced scroll behavior for Vue Router
- Host: GitHub
- URL: https://github.com/antfu/vue-router-better-scroller
- Owner: antfu
- License: mit
- Created: 2023-06-07T14:33:25.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-06-09T08:49:53.000Z (almost 2 years ago)
- Last Synced: 2024-10-30T05:57:43.672Z (6 months ago)
- Language: TypeScript
- Homepage:
- Size: 83 KB
- Stars: 328
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome - antfu/vue-router-better-scroller - Enhanced scroll behavior for Vue Router (TypeScript)
- awesome - antfu/vue-router-better-scroller - Enhanced scroll behavior for Vue Router (TypeScript)
README
# vue-router-better-scroller
[](https://www.npmjs.com/package/vue-router-better-scroller)
Enhanced [scroll behavior](https://router.vuejs.org/guide/advanced/scroll-behavior.html) for [Vue Router v4](https://router.vuejs.org/).
## Motivation
Vue Router currently only preserves the scrolling state on the `window` object. Sometimes, in your apps you might have a different scrollable element (e.g. `body`, `#app`) or even multiple ones. To gain a better user experience, we typically want to preserve the scroll state of them when going back and forth.
This plugin is introduced to experiment with a better way to handle such cases. With a lot of help from [@posva](https://github.com/posva) 🙏.
## Install
```bash
npm i vue-router-better-scroller
```
In your main entry:
```ts
import { createRouter, createWebHistory } from 'vue-router'
import { createRouterScroller } from 'vue-router-better-scroller'
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
const router = createRouter({
history: createWebHistory(),
routes
})
app.use(router)
app.use(createRouterScroller({
selectors: {
'window': true,
'body': true,
'.scrollable': true
},
}))
app.mount('#app')
```
## Options
### `selectors`
This plugin supports preserving the state of multiple scrollable elements. By passing the selectors object, you can specify which elements you want to preserve the scroll state.
When set to `true`, we will preserve and restore the scroll state of them automatically, when users navigate back and forth (but not `RouteLink` or `router.push` navigation).
You can also pass a custom handler:
```ts
createRouterScroller({
selectors: {
// use default handler for `window`
window: true,
// custom handler for scrolling on `body`
body({ to, from, type, savedPosition, element }) {
// navigation triggered by RouteLink or router.push
if (type === 'push') {
return false // disable scroll restoration
}
// navigation triggered by browser back/forward, or router.back()
else if (type === 'history') {
if (to.fullPath === '/') {
// return a custom position
return {
top: 10
}
}
// custom handling
element.scrollTo({
...savedPosition,
behavior: 'smooth',
})
}
},
},
})
```
## Sponsors
## License
[MIT](./LICENSE) License © 2022 [Anthony Fu](https://github.com/antfu)