{"id":12633,"library":"vue3-smooth-scroll","title":"Vue3 Smooth Scroll","description":"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.","status":"active","version":"0.8.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/laineus/vue3-smooth-scroll","tags":["javascript","vue","smooth","scroll","typescript"],"install":[{"cmd":"npm install vue3-smooth-scroll","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-smooth-scroll","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-smooth-scroll","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The plugin is exported as a default export for `app.use()` installation.","wrong":"import { VueSmoothScroll } from 'vue3-smooth-scroll'","symbol":"VueSmoothScroll","correct":"import VueSmoothScroll from 'vue3-smooth-scroll'"},{"note":"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.","wrong":"import { smoothScroll } from 'vue3-smooth-scroll'","symbol":"smoothScroll","correct":"const smoothScroll = inject('smoothScroll')"},{"note":"While not explicitly shown in the README, it's common for TypeScript-enabled libraries to export their configuration interfaces for type safety.","symbol":"SmoothScrollOptions","correct":"import type { SmoothScrollOptions } from 'vue3-smooth-scroll'"}],"quickstart":{"code":"import { createApp, ref, inject } from 'vue';\nimport VueSmoothScroll from 'vue3-smooth-scroll';\n\nconst App = {\n  template: `\n    <div id=\"main-content\">\n      <h1>Vue3 Smooth Scroll Example</h1>\n      <nav>\n        <a href=\"#section1\" v-smooth-scroll=\"{ duration: 800, offset: -20 }\">Go to Section 1</a> |\n        <a href=\"#section2\" v-smooth-scroll=\"{ container: '#scrollContainer', duration: 1200 }\">Go to Section 2 (in container)</a> |\n        <button @click=\"scrollToMyEl\" style=\"margin-left: 10px;\">Scroll to My Element (Programmatic)</button>\n      </nav>\n\n      <div style=\"height: 500px; background: #f0f0f0; margin-top: 20px; padding: 20px;\">\n        <p>Content before sections to allow sufficient scrolling space.</p>\n        <p>This area provides initial context before the scroll targets.</p>\n      </div>\n\n      <section id=\"section1\" style=\"height: 400px; background: lightblue; padding: 20px; border-radius: 8px; margin-top: 40px;\">\n        <h2>Section 1</h2>\n        <p>This is the first section. We will scroll here using a directive with custom options.</p>\n      </section>\n\n      <div id=\"scrollContainer\" style=\"height: 300px; overflow-y: scroll; border: 1px solid #ccc; margin-top: 40px; border-radius: 8px;\">\n        <div style=\"height: 600px; padding: 20px;\">\n          <p>Content inside a custom scroll container.</p>\n          <p>Scrolling within this container is independent of the main window scroll.</p>\n          <div style=\"height: 200px; background: #e0f7fa; margin: 15px 0;\">Placeholder</div>\n          <section id=\"section2\" ref=\"myContainerEl\" style=\"height: 150px; background: lightcoral; padding: 10px; border-radius: 5px;\">\n            <h3>Section 2 (inside container)</h3>\n            <p>This section is specifically located inside the custom scrollable div.</p>\n          </section>\n        </div>\n      </div>\n\n      <div style=\"height: 700px; background: #f0f0f0; margin-top: 40px; padding: 20px;\">\n        <p>More content after sections to ensure the ability to scroll back up and down.</p>\n        <p>This helps in testing the scroll behavior effectively.</p>\n      </div>\n\n      <div ref=\"myEl\" style=\"height: 100px; background: lightgreen; margin-top: 50px; padding: 20px; border-radius: 8px;\">\n        <h3>My Programmatic Target Element</h3>\n        <p>This element is targeted programmatically from the button click.</p>\n      </div>\n    </div>\n  `,\n  setup() {\n    const myEl = ref(null);\n    const smoothScroll = inject('smoothScroll');\n\n    const scrollToMyEl = () => {\n      if (smoothScroll && myEl.value) {\n        smoothScroll({\n          scrollTo: myEl.value,\n          duration: 700,\n          offset: -100,\n          hash: '#myProgrammaticTarget' // Optional hash update\n        });\n      }\n    };\n\n    return {\n      myEl,\n      scrollToMyEl\n    };\n  }\n};\n\nconst app = createApp(App);\napp.use(VueSmoothScroll, {\n  duration: 500,\n  updateHistory: true // Global default for history updates\n});\napp.mount('#app');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"SSR 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.","severity":"gotcha","affected_versions":"<0.8.1"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to execute client-side DOM or window-related JavaScript code in a Server-Side Rendering (SSR) environment without proper checks.","error":"window is not defined"}],"ecosystem":"npm"}