Registry / web-framework / vue3-smooth-scroll

vue3-smooth-scroll

JSON →
library0.8.1jsnpmunverified

vue3-smooth-scroll is a lightweight, actively maintained Vue 3 plugin dedicated to facilitating smooth scrolling experiences within web applications. It provides two primary methods for implementation: a declarative directive (`v-smooth-scroll`) that can be applied directly to anchor tags, and a more flexible programmatic API accessible through `this.$smoothScroll` in the Options API or `inject('smoothScroll')` within the Composition API. The plugin's design prioritizes Vue 3 compatibility, including robust Server-Side Rendering (SSR) support, which was recently improved in version 0.8.1 to address `window is not defined` errors. It uses `requestAnimationFrame` for efficient, non-blocking animations, with a graceful fallback for broader compatibility across different browser environments. Key features include Y-axis scrolling, the ability to define specific scroll containers, configurable animation duration, offset, and custom easing functions, providing a high degree of customization for scroll behavior. Its small bundle size (approximately 1.4kB gzipped) makes it a performant choice, offering significantly more advanced control and a programmatic interface compared to the native `scroll-behavior` CSS property, especially for intricate scrolling requirements or dynamic content. Releases appear to be driven by bug fixes and compatibility updates rather than a strict schedule, with 0.8.1 being the current stable version.

npm install vue3-smooth-scroll
INSTALL
IMPORT
SIG · VUE3-SMOOTH-SCROLL
V
vue3-smooth-scroll
web-frameworkjavascriptv0.8.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueSmoothScroll
import VueSmoothScroll from 'vue3-smooth-scroll'
import { VueSmoothScroll } from 'vue3-smooth-scroll'
The plugin is exported as a default export for `app.use()` installation.
smoothScroll
const smoothScroll = inject('smoothScroll')
import { smoothScroll } from 'vue3-smooth-scroll'
The programmatic scrolling function is exposed via Vue's `inject` in the Composition API or `this.$smoothScroll` in the Options API, not as a direct named import from the package.
SmoothScrollOptions
import type { SmoothScrollOptions } from 'vue3-smooth-scroll'
While not explicitly shown in the README, it's common for TypeScript-enabled libraries to export their configuration interfaces for type safety.

This example demonstrates both directive-based (`v-smooth-scroll`) and programmatic (`inject('smoothScroll')`) smooth scrolling, including usage with custom scroll containers and global/local options for duration and offset.

import { createApp, ref, inject } from 'vue'; import VueSmoothScroll from 'vue3-smooth-scroll'; const App = { template: ` <div id="main-content"> <h1>Vue3 Smooth Scroll Example</h1> <nav> <a href="#section1" v-smooth-scroll="{ duration: 800, offset: -20 }">Go to Section 1</a> | <a href="#section2" v-smooth-scroll="{ container: '#scrollContainer', duration: 1200 }">Go to Section 2 (in container)</a> | <button @click="scrollToMyEl" style="margin-left: 10px;">Scroll to My Element (Programmatic)</button> </nav> <div style="height: 500px; background: #f0f0f0; margin-top: 20px; padding: 20px;"> <p>Content before sections to allow sufficient scrolling space.</p> <p>This area provides initial context before the scroll targets.</p> </div> <section id="section1" style="height: 400px; background: lightblue; padding: 20px; border-radius: 8px; margin-top: 40px;"> <h2>Section 1</h2> <p>This is the first section. We will scroll here using a directive with custom options.</p> </section> <div id="scrollContainer" style="height: 300px; overflow-y: scroll; border: 1px solid #ccc; margin-top: 40px; border-radius: 8px;"> <div style="height: 600px; padding: 20px;"> <p>Content inside a custom scroll container.</p> <p>Scrolling within this container is independent of the main window scroll.</p> <div style="height: 200px; background: #e0f7fa; margin: 15px 0;">Placeholder</div> <section id="section2" ref="myContainerEl" style="height: 150px; background: lightcoral; padding: 10px; border-radius: 5px;"> <h3>Section 2 (inside container)</h3> <p>This section is specifically located inside the custom scrollable div.</p> </section> </div> </div> <div style="height: 700px; background: #f0f0f0; margin-top: 40px; padding: 20px;"> <p>More content after sections to ensure the ability to scroll back up and down.</p> <p>This helps in testing the scroll behavior effectively.</p> </div> <div ref="myEl" style="height: 100px; background: lightgreen; margin-top: 50px; padding: 20px; border-radius: 8px;"> <h3>My Programmatic Target Element</h3> <p>This element is targeted programmatically from the button click.</p> </div> </div> `, setup() { const myEl = ref(null); const smoothScroll = inject('smoothScroll'); const scrollToMyEl = () => { if (smoothScroll && myEl.value) { smoothScroll({ scrollTo: myEl.value, duration: 700, offset: -100, hash: '#myProgrammaticTarget' // Optional hash update }); } }; return { myEl, scrollToMyEl }; } }; const app = createApp(App); app.use(VueSmoothScroll, { duration: 500, updateHistory: true // Global default for history updates }); app.mount('#app');
Debug
Known issues
gotchaSSR environments on versions prior to v0.8.1 may encounter `window is not defined` errors when the scrolling logic attempts to access browser-specific APIs.
fix
Upgrade to `vue3-smooth-scroll` version `0.8.1` or later. If the issue persists or for older versions, ensure the plugin or scrolling logic is only executed client-side or properly guarded within `if (typeof window !== 'undefined')` checks.
affects: <0.8.1
gotchaFor very simple, static smooth scrolling needs, the native CSS `scroll-behavior: smooth` property can provide a lightweight alternative without a JavaScript dependency, potentially improving performance slightly.
fix
Consider using `html { scroll-behavior: smooth; }` in your CSS if advanced features like specific offsets, custom easing functions, programmatic control, or custom scroll containers are not required.
affects: *
Errors
Common errors & fixes
window is not defined
Attempting to execute client-side DOM or window-related JavaScript code in a Server-Side Rendering (SSR) environment without proper checks.
fix
Update `vue3-smooth-scroll` to version `0.8.1` or newer, as this version specifically addresses SSR compatibility. If using an older version or if the error persists with custom logic, ensure client-side code is conditionally executed (`if (typeof window !== 'undefined')`) or wrapped in SSR-aware components (e.g., `<ClientOnly>` in Nuxt).
Upgrade
Version history
0.8.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
Bingbot
1
OpenAI (training)
1
Resources
vue3-smooth-scroll — npm install vue3-smooth-scroll · libregistry