One activation line
A section is active once its top crosses a line at 25% of the view, so short and very tall sections both behave.
Add data-scroll-spy to a navigation and the link of the section being read gets aria-current, in the page or any scroll container.
Install it, scroll the live preview, then read the full reference.
npm install @samline/scroll-spyAbout 2.4 KB gzipZero dependenciesMIT licensed
On this page
Introduction
Scroll this box, or pick a link: it stays highlighted while the box scrolls to it.
Installation
Scroll this box, or pick a link: it stays highlighted while the box scrolls to it.
Usage
Scroll this box, or pick a link: it stays highlighted while the box scrolls to it.
Options
Scroll this box, or pick a link: it stays highlighted while the box scrolls to it.
FAQ
A short last section still becomes active at the bottom.
ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.
A section is active once its top crosses a line at 25% of the view, so short and very tall sections both behave.
The active link gets aria-current="true", which screen readers announce and your CSS can target, with an optional class.
A clicked link lights up at once and stays lit while the page scrolls to it, instead of flickering through every section on the way.
At the bottom of the page the last section in view becomes active, even when it is too short to reach the line.
When the navigation scrolls itself, the active link is kept in view by scrolling the navigation, never the page.
Watch the page or a scrolling panel with root, and optionally keep the URL hash in sync without history entries.
Your navigation stays plain links that work without JavaScript.
Package
scrollSpy and autoScrollSpy as ESM or CommonJS.
One navigation
Returns { active, refresh, destroy }.
Whole page
Every [data-scroll-spy], including navigations added later.
HTML / CDN
A classic script that starts on its own.
Changes
React to the active section, for progress bars or analytics.
Styling
No stylesheet: style the active link your way.
Highlight the table of contents entry of the section in view.
Read the installation guideInstall
npm
npm install @samline/scroll-spypnpm
pnpm add @samline/scroll-spyyarn
yarn add @samline/scroll-spybun
bun add @samline/scroll-spyHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js" defer></script>Mark the navigation
Plain links to the ids of your sections, inside a [data-scroll-spy] element.
<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>Start watching
import { autoScrollSpy } from '@samline/scroll-spy'
autoScrollSpy()Continue with every option, the activation line and scroll containers.
Explore the optionsThree common jobs, without measuring a single section yourself.
<nav data-scroll-spy data-scroll-spy-offset="96">…</nav>nav a[aria-current] {
color: var(--accent);
border-inline-start-color: currentColor;
}scrollSpy('#toc', {
onChange: ({ section }) => {
label.textContent = section?.querySelector('h2')?.textContent ?? ''
},
})Try the examples or follow the first steps.
Guides, the complete API and release notes, in one place.
Read the documentation