Highlight the navigation link of the section being read, for tables of contents, docs sidebars and one-page menus, with aria-current, steady clicks, scroll containers and long navigations that follow along. For vanilla JavaScript, any framework and plain HTML.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/scroll-spypnpm add @samline/scroll-spybun add @samline/scroll-spyAny modern browser; without JavaScript the links still jump to their sections. On the server, every function is inert. No runtime dependencies.
import { autoScrollSpy } from '@samline/scroll-spy'
autoScrollSpy()<nav data-scroll-spy aria-label="On this page">
<a href="#install">Install</a>
<a href="#usage">Usage</a>
</nav>
<section id="install">…</section>
<section id="usage">…</section>nav a[aria-current] {
font-weight: 600;
}For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It watches every [data-scroll-spy] as soon as the DOM is ready. Pin the version in production.
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js"
defer
></script>The bundle defines window.ScrollSpy. Add data-manual to the script tag and call ScrollSpy.auto(options) to start it with your own options.
A section is active once its top crosses an activation line, 25% down the view by default, so very short and very tall sections both behave. Before the first section nothing is active, and at the bottom of the page the last section in view is, even when it is too short to reach the line.
The active link gets aria-current="true" (or your value), announced by screen readers and easy to target in CSS, plus an optional class. Every link to the same section is marked.
A clicked link lights up at once and stays lit while the page scrolls to it, with CSS smooth scrolling or your own scripted scroll, instead of flickering through every section on the way.
Watch the page or a scroll container (root), move the line below a sticky header (offset), keep long navigations scrolled to the active link without moving the page, and optionally keep the URL hash in sync without history entries.
| API | Purpose |
|---|---|
autoScrollSpy(options?) |
Watch every [data-scroll-spy], including navigations added later. |
scrollSpy(nav, options?) |
Watch one navigation. Returns { active, refresh, destroy }. |
onChange(change) |
The active section changed: { id, section, links, previous }. |
data-scroll-spy-* attributes |
Offset, class, click lock, follow and hash per navigation. |
| Entrypoint | When to use |
|---|---|
@samline/scroll-spy |
ESM or CommonJS, scrollSpy and autoScrollSpy. |
@samline/scroll-spy/vanilla |
scrollSpy as the default export. |
@samline/scroll-spy/browser |
Classic script that defines window.ScrollSpy. |
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files.
| Guide | What it covers |
|---|---|
| Installation | npm, CDN and the first navigation. |
| API reference | scrollSpy, autoScrollSpy and window.ScrollSpy. |
| Options | Attributes and options. |
| Layouts | Sticky headers, scroll containers, smooth scrolling and nested lists. |
| Frameworks | React, Vue, Svelte, Astro and page swaps. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The Scroll Spy skill teaches verified package integration. Its maintained repository source and website download are the same file. Verify the installed package version before applying its guidance.
Download SKILL.md into a scroll-spy/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/scroll-spy
curl --fail --location https://samline.github.io/scroll-spy/skills/scroll-spy/SKILL.md \
--output .agents/skills/scroll-spy/SKILL.mdKeep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.