https://github.com/helltraitor/nuxt-anchorscroll
Scroll to top and to anchor support for Nuxt
https://github.com/helltraitor/nuxt-anchorscroll
nuxt nuxt-module typescript vue
Last synced: about 1 year ago
JSON representation
Scroll to top and to anchor support for Nuxt
- Host: GitHub
- URL: https://github.com/helltraitor/nuxt-anchorscroll
- Owner: helltraitor
- License: mit
- Created: 2023-07-08T18:49:35.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-01T15:08:21.000Z (over 1 year ago)
- Last Synced: 2025-02-27T11:43:02.187Z (about 1 year ago)
- Topics: nuxt, nuxt-module, typescript, vue
- Language: TypeScript
- Homepage: https://stackblitz.com/github/helltraitor/nuxt-anchorscroll
- Size: 1.1 MB
- Stars: 7
- Watchers: 1
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nuxt-anchorscroll
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]
This module provides scroll implementation (scroll to top and scroll to anchor element).
Originally it was intended for anchor scrolling that's why it's called `nuxt-anchorscroll`
- [Online playground](https://stackblitz.com/github/helltraitor/nuxt-anchorscroll?file=playground%2Fapp.vue)
## Features
- Configured out of the box
- Supports both kinds of layouts*
- Extendable
### Configured out of the box
1. For top scroll - scroll instantly, until top with zero offset, ignore `x` axis
2. For anchor scroll - scroll smoothly, until top element with zero offset, ignore `x` axis
3. Surfaces - `html` and `body` elements
4. General function - scroll to anchor if element exist (uses `route.hash` as selector),
otherwise to top - respects page meta `nuxt-anchorscroll` options
### Supports both kinds of layouts*
In common case, you use cropped html or full html. In first case (you can check this now)
scroll to anchor will not work. If it so, you can have a minimal setup.
But in case if anchor scroll is handled (by browser), you need additional setup -
full explanation in module playground.
### Extendable
Anchor scroll can be specified for needed route via `matched` field of `NuxtApp.$anchorScroll`
runtime configuration (default configuration setups before `script setup`)
```ts
nuxtApp.$anchorScroll!.matched.push(({ path, hash }) => {
// Exit when route is not represent fixed example
if (!path.startsWith('/standard/fixed'))
return undefined
if (hash) {
// All anchor element on this route is mangled
const targetSelector = `#fixed-${hash.slice(1)}`
const targetElement = document.querySelector(targetSelector)
if (targetElement) {
return {
toAnchor: {
target: targetElement as HTMLElement,
scrollOptions: toValue(useNuxtApp().$anchorScroll?.defaults?.toAnchor) ?? {},
},
}
}
}
})
```
Also your matched function can specify different surfaces for scrolling.
```ts
nuxtApp.$anchorScroll!.matched.push(({ path, hash }) => {
// Exit when route is not represent fixed example
if (!path.startsWith('/scrollable'))
return undefined
const surfaces = [...document.querySelectorAll('#exited-scrollable-surface')]
return {
toAnchor: {
surfaces,
scrollOptions: {
/* ... */
},
},
toTop: {
surfaces,
scrollOptions: {
/* ... */
},
}
}
})
```
## Quick Setup
1. Add `nuxt-anchorscroll` dependency to your project
Use your favorite package manager (I prefer yarn)
```bash
yarn add -D nuxt-anchorscroll
pnpm add -D nuxt-anchorscroll
npm install --save-dev nuxt-anchorscroll
```
Or install it via `nuxi module`
```bash
npx nuxi@latest module add nuxt-anchorscroll
```
2. Add `nuxt-anchorscroll` to the `modules` section of `nuxt.config.ts`
```ts
export default defineNuxtConfig({
modules: [
'nuxt-anchorscroll',
]
})
```
3. Additionally, if you are using transitions, probably you also want to scroll on different hook
```ts
export default defineNuxtConfig({
modules: [
'nuxt-anchorscroll',
],
anchorscroll: {
hooks: [
// Or any valid hook if needed
// Default is `page:finish`
'page:transition:finish',
],
},
})
```
4. Additionally, if you using standard layout, see playground explanation.
That's it! You can now use `nuxt-anchorscroll` in your Nuxt app ✨
## Composable
Most probably that you want to scroll to anchor ro to top on click. That's possible via `useAnchorScroll` composable
```ts
// Default to top is instant
const { scrollToAnchor, scrollToTop } = useAnchorScroll({
toTop: {
scrollOptions: {
behavior: 'smooth',
offsetTop: 0,
}
},
})
```
And use it in template
```html
#
```
[npm-version-src]: https://img.shields.io/npm/v/nuxt-anchorscroll/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-version-href]: https://npmjs.com/package/nuxt-anchorscroll
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-anchorscroll.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-downloads-href]: https://npmjs.com/package/nuxt-anchorscroll
[license-src]: https://img.shields.io/npm/l/nuxt-anchorscroll.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://npmjs.com/package/nuxt-anchorscroll
[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
[nuxt-href]: https://nuxt.com