https://github.com/bennyxguo/vue3-scroll-spy
A vue3 directive for scroll menu tracking.
https://github.com/bennyxguo/vue3-scroll-spy
menu scroll scrollspy vue3 vue3-typescript
Last synced: 4 months ago
JSON representation
A vue3 directive for scroll menu tracking.
- Host: GitHub
- URL: https://github.com/bennyxguo/vue3-scroll-spy
- Owner: bennyxguo
- License: mit
- Created: 2021-02-26T17:23:12.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-04-11T13:37:59.000Z (about 3 years ago)
- Last Synced: 2025-11-20T02:22:20.275Z (8 months ago)
- Topics: menu, scroll, scrollspy, vue3, vue3-typescript
- Language: TypeScript
- Homepage: https://gh.bennyxguo.com/vue3-scroll-spy/
- Size: 1.67 MB
- Stars: 26
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Vue3 Scroll-Spy Directive
Scrollspy and animated scroll-to for Vue3, inspired by vue2-scrollspy.
—— Made with ❤️ by Benny Guo
[｜ 📙 中文文档](https://github.com/bennyxguo/vue3-scroll-spy/blob/master/README_CN.md)
[｜ 📙 Changelog](https://github.com/bennyxguo/vue3-scroll-spy/blob/master/CHANGELOG.md)
## Installation
```bash
npm i vue3-scroll-spy -S
```
OR
```bash
yarn add vue3-scroll-spy
```
## Usage
### Support
| Supported Package | Version |
| ----------------- | ------- |
| Vue | 3+ |
### Install Directive
```javascript
// global register at main.js
import { registerScrollSpy } from 'vue3-scroll-spy';
const app = createApp(App)
// Using default options
registerScrollSpy(app)
// or custom global options
registerScrollSpy(app, options)
app.mount('#app')
```
### On template
```html
Header 1
Content
Header 2
Content
```
## Configuration
### v-scroll-spy
Binding scroll-spy to sections (or elements) of a container.
| Directive name | Description | Default |
| --------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------ |
| `v-scroll-spy="{allowNoActive: true}"` | When scroll position is outside of the container, active class will be removed. | Keep one section stays active at all time. |
| `v-scroll-spy="{offset: 50}"` | TAdding offset to scroll and active elements. | Default: `0` |
| `v-scroll-spy="{time: 200, steps: 30}"` | Set the animation options, time is animation duration, steps is step per frame. | `{time: 200, steps: 30}` |
### v-scroll-spy-active
Setting active elements' `selector` and `class` properties.
| Directive name | Description | Default |
| -------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------- |
| `v-scroll-spy-active="{selector: 'li.menu-item', class: 'custom-active'}"` | Customize elements selector and class name. | `{selector: null, class: 'active'}` |
### v-scroll-spy-link
Add `click handler` on children elements allow scrolling to the related section.
| Directive name | Description | Default |
| ----------------------------------------------- | ------------------------------ | ----------------------------------- |
| `v-scroll-spy-link="{selector: 'a.menu-link'}"` | Customize menu links selector. | `{selector: null, class: 'active'}` |
### Bezier animations
```javascript
import { registerScrollSpy, Easing } from '@/directives/ScrollSpy'
const app = createApp(App)
// or custom global options
registerScrollSpy(app, {
easing: Easing.Cubic.In
})
app.mount('#app')
```
## Note
- You should have the same number of children elements for `v-scroll-spy`, `v-scroll-spy-active`, `v-scroll-spy-link` for this directive to work correctly.
- If you need to share this scroll-spy directive on multiple containers, you can add `data-scroll-spy-id=""` on each element container, where this directive is bind.
### Nested sections
Vue3 Scroll-Spy also support multi-leveled sections:
```html
```
## Liscense
MIT License