Vue Smooth Scroll Directive

1.0.13 · active · verified Sun Apr 19

The `vue-smooth-scroll` package provides a lightweight, declarative smooth scrolling directive for Vue.js applications. It enables animated scrolling to anchor links within a page with customizable duration and offset. Currently at version 1.0.13, this library appears to be in a stable state with an infrequent release cadence, primarily targeting Vue 2 environments. Its key differentiators include a minimal footprint (under 1KB gzipped), straightforward integration through a global Vue directive, and a focus on simplicity rather than advanced features like scroll spy or complex easing functions. It serves as a practical solution for projects needing basic, reliable scroll-to-anchor functionality without the overhead of more extensive scrolling solutions. The project builds upon the foundations of the `vue-smoothscroll` library, aiming for ease of use and maintenance.

Common errors

```
[Vue warn]: Failed to resolve directive: smooth-scroll
```
cause The `v-smooth-scroll` directive was used in a template but the plugin was not correctly registered with Vue.

fix Ensure `import vueSmoothScroll from 'vue-smooth-scroll'; Vue.use(vueSmoothScroll);` is called before your Vue application mounts.
```
Uncaught TypeError: Cannot read properties of undefined (reading 'use')
```
cause The global `Vue` object is not defined or is not accessible when `Vue.use(vueSmoothScroll)` is called.

fix Make sure Vue itself is imported and globally available (e.g., `import Vue from 'vue';` or via a script tag) before attempting to use `Vue.use()`.

Warnings

breaking This package is primarily designed for Vue 2. It uses `Vue.use()` for global plugin registration, which is a Vue 2 API. Direct compatibility with Vue 3 is not guaranteed without a compatibility layer (e.g., `@vue/compat`) or a separate Vue 3 specific version.
Fix: For Vue 3 projects, investigate if a Vue 3 compatible fork or an alternative smooth scroll library is available. If using Vue 2, ensure `Vue` is globally available or imported correctly before calling `Vue.use()`.
gotcha The global registration via `Vue.use(vueSmoothScroll)` applies the directive to all Vue instances. In large applications, this can make tree-shaking less effective if the directive is only used in a few places.
Fix: For specific usage or better tree-shaking, consider manually registering the directive on a component basis or using a local directive definition if the library allows it (though this plugin is designed for global use). Alternatively, accept the global registration for simplicity given the library's small size.
gotcha The directive works by intercepting clicks on anchor (`<a>`) tags and overriding their default behavior. If you have custom click handlers or are using a Vue Router `<router-link>` with `href` attributes, this directive might conflict.
Fix: Ensure that `v-smooth-scroll` is not applied to elements where router links or other custom navigation logic is already handling the click event. Test thoroughly to avoid unexpected navigation or scrolling behavior.

Install

npm install vue-smooth-scroll npm
yarn add vue-smooth-scroll yarn
pnpm add vue-smooth-scroll pnpm

Imports

vueSmoothScroll
wrong:
```
const vueSmoothScroll = require('vue-smooth-scroll');
```
correct:
```
import vueSmoothScroll from 'vue-smooth-scroll';
```
The package exports a default module; CommonJS users must access the `.default` property if using `require`.
Vue.use
wrong:
```
app.directive('smooth-scroll', vueSmoothScroll);
```
correct:
```
Vue.use(vueSmoothScroll);
```
The library is intended for global registration via `Vue.use()` for Vue 2 applications. It exposes a plugin interface.
v-smooth-scroll
wrong:
```
<a href="#target" smooth-scroll>Jump</a>
```
correct:
```
<a href="#target" v-smooth-scroll>Jump</a>
```
This is a directive; it must be prefixed with `v-` in templates. Options are passed as an object literal.

Quickstart

This quickstart demonstrates how to install, import, and globally register `vue-smooth-scroll` as a Vue plugin. It shows basic usage of the `v-smooth-scroll` directive with and without custom options, enabling smooth scrolling to anchor tags within a single-page application.

import { createApp } from 'vue'; // For illustration, assuming a Vue 2 project or compatibility layer
import vueSmoothScroll from 'vue-smooth-scroll';

// In a typical Vue 2 setup:
// import Vue from 'vue';
// Vue.use(vueSmoothScroll);

// For modern setups (e.g., Vue 3 with a compatibility layer or if plugin adapts):
const app = createApp({
  template: `
    <div id="app">
      <h1>Vue Smooth Scroll Example</h1>
      <nav>
        <a href="#section1" v-smooth-scroll>Go to Section 1</a>
        <a href="#section2" v-smooth-scroll="{ duration: 1000, offset: -70 }">Go to Section 2 (Offset)</a>
      </nav>
      <div style="height: 800px; background-color: #f0f0f0; margin-top: 20px;" id="section1">
        <h2>Section 1</h2>
        <p>Content for section 1.</p>
      </div>
      <div style="height: 800px; background-color: #e0e0e0; margin-top: 20px;" id="section2">
        <h2>Section 2</h2>
        <p>Content for section 2 with a custom offset and duration.</p>
      </div>
    </div>
  `,
});

// This line is crucial for registering the plugin in Vue 2.
// For Vue 3, a different registration might be needed if not fully compatible.
app.use(vueSmoothScroll);

app.mount('#app');

view raw JSON →