Registry / web-framework / vue-use-active-scroll

vue-use-active-scroll

library1.1.3jsnpmunverified

Vue 3 composable for accurate TOC/sidebar active link tracking without Intersection Observer compromises. Current stable version 1.1.3 (released 2024). Zero runtime dependencies, ships TypeScript types. Unlike typical Intersection Observer solutions, it implements a custom scroll observer that reliably highlights clicked links that never intersect, handles first/last link at page boundaries, and works consistently across scroll speeds, smooth scrolling, and hash navigation. Supports template refs or DOM elements in place of IDs, customizable offsets per scroll direction, and custom scroll containers. Does not scroll to targets or manipulate DOM. Released on npm with monthly cadence.

web-framework http-networking observability

npm install vue-use-active-scroll

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-USE-ACTIVE-SCR

vue-use-active-scroll

web-frameworkjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

useActiveScroll

✓ import { useActiveScroll } from 'vue-use-active-scroll'

✗ const useActiveScroll = require('vue-use-active-scroll')

ESM-only. The package does not provide a CommonJS entry.

useActiveScroll

✓ import { useActiveScroll } from 'vue-use-active-scroll'

✗ import useActiveScroll from 'vue-use-active-scroll'

This is a named export, not a default export. Both 'use-active-scroll' (kebab-case) and 'UseActiveScroll' (PascalCase) will not work.

isActive

✓ import { isActive } from 'vue-use-active-scroll'

✗ import { IsActive } from 'vue-use-active-scroll'

Exported as a PascalCase ref for use in templates, but import name is camelCase. Also available via return from useActiveScroll.

Basic example: track active section based on scroll position and highlight a sidebar link accordingly.

<template> <nav> <a v-for="item in items" :key="item.id" :href="'#' + item.id" :class="{ active: activeId === item.id }" > {{ item.title }} </a> </nav> <main> <section v-for="item in items" :key="item.id" :id="item.id"> <h2>{{ item.title }}</h2> <p>{{ item.content }}</p> </section> </main> </template> <script setup lang="ts"> import { ref } from 'vue' import { useActiveScroll } from 'vue-use-active-scroll' const items = [ { id: 'introduction', title: 'Introduction', content: '...' }, { id: 'installation', title: 'Installation', content: '...' }, { id: 'usage', title: 'Usage', content: '...' }, ] // Array of target IDs (strings, no hash prefix) const targetIds = items.map((item) => item.id) const { activeId } = useActiveScroll(targetIds, { offset: { top: 80, bottom: 80 }, firstTopMargin: 100, lastBottomMargin: 100, }) </script>

Debug

Known issues

gotchaVue Router is required for hash-based scrolling unless using Nuxt. Without configuring scrollBehavior in createRouter({...}), clicking hash links may not scroll to the target element.

fix

Add scrollBehavior(to) { if (to.hash) return { el: to.hash } } to your Vue Router instance.

affects: >=1.0.0

gotchaCSS scroll-behavior must be set on html element (e.g., scroll-behavior: smooth) for smooth scrolling. If omitted, scrolling jumps instantly and active highlight may feel abrupt.

fix

Add 'html { scroll-behavior: smooth; }' in your global CSS.

affects: >=1.0.0

breakingVersion 1.1.0 changed target API: targets can now be set using template refs or DOM elements in place of IDs. If you previously relied on string IDs only, this is backward-compatible, but passing refs now works differently.

fix

No action needed if using string IDs. If using refs, ensure they are valid TemplateRef or HTMLElement.

affects: >=1.1.0

gotchaThe activeId returned is a Ref<string | null>, not a plain string. In templates it auto-unwraps, but in script you must use .value.

fix

Access activeId.value in script setup or composition functions.

affects: >=1.0.0

deprecatedThe export 'isActive' is deprecated since v1.1.1? Actually 'isActive' is still exported but also available via useActiveScroll return. There is no deprecation notice, but note that using isActive alone might not work in SSR (fixed in 1.1.1).

fix

Import useActiveScroll and destructure isActive from its return, or upgrade to >=1.1.1.

affects: >=1.0.0 <1.1.1

Errors

Common errors & fixes

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'hash')

Vue Router scrollBehavior not configured or to.hash undefined when clicking a hash link.

fix

Add scrollBehavior(to) { if (to.hash) return { el: to.hash } } to createRouter({...}).

useActiveScroll is not a function

Using a default import instead of named import.

fix

Use import { useActiveScroll } from 'vue-use-active-scroll' instead of import useActiveScroll from 'vue-use-active-scroll'.

Cannot find module 'vue-use-active-scroll' or its corresponding type declarations.

Package not installed or TypeScript cannot resolve types.

fix

Run npm install vue-use-active-scroll (or pnpm/yarn/bun add) and ensure tsconfig includes node_modules/@types.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/smastrom/vue-use-active-scroll ↗

packagehttps://www.npmjs.com/package/vue-use-active-scroll ↗

homepagehttps://vue-use-active-scroll.netlify.app/ ↗