Skip to content

Latest commit

 

History

History
188 lines (146 loc) · 5.35 KB

README.md

File metadata and controls

188 lines (146 loc) · 5.35 KB
Raw

Vue Smooth Scroll

All Contributors

Vue 3.x Vue 2.x npm npm-downloades license

Lightweight Vue plugin for smooth-scrolling.

For simple use-cases, the native scroll-behavior CSS property (working draft) may be enough.

Compatible with Vue 3.x and Vue 2.x

Features

  • Compatible with Vue 3.x, 2.x
  • Directive and programmatic API with global and local config overrides
  • SSR
  • Smooth, non-blocking animation using requestAnimationFrame (with fallback)
  • Y-axis or vertical scrolling
  • Specific scroll containers
  • 1.4kB gzipped, 2.9kB min

Installation

npm install --save v-smooth-scroll
import VueSmoothScroll from 'v-smooth-scroll'

// Vue 2.x
Vue.use(VueSmoothScroll)

// Vue 3.x
const app = Vue.createApp({ /* options */ })
app.use(VueSmoothScroll)
app.mount('#app')

Usage

Directive

<a href="#sec-3" v-smooth-scroll>Section 3</a>

<section id="sec-3"></section>

Programmatic

const myEl = this.$refs.myEl || this.$el || document.getElementById(...)

this.$smoothScroll({
  scrollTo: myEl,
  hash: '#sampleHash'  // required if updateHistory is true
})

Direct in <script>

Vue 2.x

<body>
  <div id="app">
    <a href="#bottom" v-smooth-scroll>Let's go to #bottom!</a>
    <div style="height: 2000px;"></div>
    <span id="bottom">bottom</span>
  </div>

  <script src="https://unpkg.com/vue/dist/vue.js"></script>
  <script src="https://unpkg.com/v-smooth-scroll"></script>
  <script>
    Vue.use(window.VueSmoothScroll)
    var app = new Vue({
      el: '#app'
    })
  </script>
</body>

Vue 3.x

<body>
  <div id="app">
    <a href="#bottom" v-smooth-scroll>Let's go to #bottom!</a>
    <div style="height: 2000px;"></div>
    <span id="bottom">bottom</span>
  </div>

  <script src="https://unpkg.com/vue@next"></script>
  <script src="https://unpkg.com/v-smooth-scroll"></script>
  <script>
    var app = Vue.createApp({ /* options */ })
    app.use(window.VueSmoothScroll)
    app.mount('#app')
  </script>
</body>

Custom options

Defaults

{
  duration: 500,       // animation duration in ms
  offset: 0,           // offset in px from scroll element, can be positive or negative
  container: '',       // selector string or Element for scroll container, default is window
  updateHistory: true  // whether to push hash to history
  easingFunction: null // gives the ability to provide a custom easing function `t => ...`
                       // (see https://gist.github.com/gre/1650294 for examples)
                       // if nothing is given, it will defaults to `easeInOutCubic`
}

Global

import VueSmoothScroll from 'v-smooth-scroll'

// Vue 2.x
Vue.use(VueSmoothScroll, {
  duration: 400,
  updateHistory: false,
})

// Vue 3.x
vueApp.use(VueSmoothScroll, {
  duration: 400,
  updateHistory: false,
})

Directive:

<div id="container">
  <a href="#div-id" v-smooth-scroll="{ duration: 1000, offset: -50, container: '#container' }">Anchor</a>

  <div id="div-id"></div>
</div>

Programmatic

this.$smoothScroll({
  scrollTo: this.$refs.myEl,
  duration: 1000,
  offset: -50,
})

TODO

  • [] fix Typescript type lose efficacy problem
  • [] example website
  • [] unitest

License

MIT

Contributors ✨

Thanks goes to these wonderful people (emoji key):


James
💻
a-kriya
💻 🐛 📖

This project follows the all-contributors specification. Contributions of any kind welcome!