Know where the reader is.

Scroll Spy
The right link, lit at the right time.

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-spy

About 2.4 KB gzipZero dependenciesMIT licensed

Scroll Spy previewLive preview

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.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than an observer

The section you read.
Not the one passing by.

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.

aria-current built in

The active link gets aria-current="true", which screen readers announce and your CSS can target, with an optional class.

Steady on click

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.

The end is reachable

At the bottom of the page the last section in view becomes active, even when it is too short to reach the line.

Long tables of contents

When the navigation scrolls itself, the active link is kept in view by scrolling the navigation, never the page.

Any scroll container

Watch the page or a scrolling panel with root, and optionally keep the URL hash in sync without history entries.

02 / Fit it into your stack

Links first. Script when you need it.

Your navigation stays plain links that work without JavaScript.

Package

@samline/scroll-spy

scrollSpy and autoScrollSpy as ESM or CommonJS.

One navigation

scrollSpy(nav, options)

Returns { active, refresh, destroy }.

Whole page

autoScrollSpy(options)

Every [data-scroll-spy], including navigations added later.

HTML / CDN

window.ScrollSpy

A classic script that starts on its own.

Changes

onChange({ id, section, links })

React to the active section, for progress bars or analytics.

Styling

[aria-current]

No stylesheet: style the active link your way.

03 / Install and follow

One attribute. One call.

Highlight the table of contents entry of the section in view.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/scroll-spy

pnpm

Terminal
pnpm add @samline/scroll-spy

yarn

Terminal
yarn add @samline/scroll-spy

bun

Terminal
bun add @samline/scroll-spy

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js" defer></script>
2

Mark the navigation

Plain links to the ids of your sections, inside a [data-scroll-spy] element.

index.html
<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>

Continue with every option, the activation line and scroll containers.

Explore the options
04 / Beyond a highlight

Plain links.
Precise state.

Three common jobs, without measuring a single section yourself.

offset

Below a sticky header

Move the activation line under your header.

Read the options
index.html
<nav data-scroll-spy data-scroll-spy-offset="96">…</nav>
aria-current

Style it your way

Target the active link from CSS.

Read the options
style.css
nav a[aria-current] {
  color: var(--accent);
  border-inline-start-color: currentColor;
}
onChange

Reading progress

Show where the reader is, outside the navigation.

Read the API
main.js
scrollSpy('#toc', {
  onChange: ({ section }) => {
    label.textContent = section?.querySelector('h2')?.textContent ?? ''
  },
})
Explore working examples
05 / Before you build

A few details. Clearly answered.

When is a section active?
When its top has crossed the activation line, 25% down the viewport by default, and it is the last one that has. Before the first section nothing is active; at the bottom of the page, the last section in view is.
Does it work without a bundler?
Yes. Load dist/browser/scroll-spy.global.js; it watches every [data-scroll-spy] on its own. Add data-manual to the script tag to start it yourself with ScrollSpy.auto(). Pin the version in production.
Can I style the active link with a class?
Yes. Set activeClass, or data-scroll-spy-class, and the class is added next to aria-current. aria-current stays on by default; set ariaCurrent to 'location' or false to change it.
I have a sticky header. What offset do I use?
Anything below the header works, for example data-scroll-spy-offset="96" for a 80px header. Also set scroll-padding-top on html so clicked sections land below it.
Why not IntersectionObserver?
Thresholds misreport very tall and very short sections. scroll-spy reads section positions once per frame while scrolling, which stays cheap and always agrees with what the reader sees.
Does it work with smooth scrolling?
Yes, with CSS scroll-behavior or your own scripted scroll. Clicks whose default you prevent still lock the link until scrolling settles.
What happens without JavaScript?
The navigation is plain links, so it still jumps to each section. Only the highlight is missing.
Does it see navigations added later?
autoScrollSpy and the CDN script watch the page for new navigations. When links or sections change inside one, call refresh().
Navigation that follows

Show where they are, every step of the way.

Try the examples or follow the first steps.

Guides, the complete API and release notes, in one place.

Read the documentation