- Docs
- Getting started
Getting started
Install @samline/scroll-spy with a package manager or a script tag and highlight the section in view in your first navigation.
Install @samline/scroll-spy, then follow the Package / ESM or the HTML / CDN path to the first navigation. Both use the same API.
Requirements
- Any modern browser. Without JavaScript the links still jump to their sections.
- On the server,
scrollSpyreturns an inert object andautoScrollSpydoes nothing. - No runtime dependencies.
Install
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>Package / ESM
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;
}
autoScrollSpy() watches every [data-scroll-spy] in the page, including navigations added later. To watch one navigation, call scrollSpy(nav, options); it returns { active, refresh, destroy }. Available as ESM and CommonJS (require('@samline/scroll-spy')). There is no stylesheet.
HTML / CDN
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>
To pass options, add data-manual to the script tag and start it yourself, or call ScrollSpy.auto() from a script that runs before the DOM is ready (a deferred or inline script after the bundle):
<script
src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js"
data-manual
defer
></script>
<script type="module">
ScrollSpy.auto({ offset: 96, activeClass: 'is-active' })
</script>
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Highlight the section you are reading</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<div class="layout">
<nav data-scroll-spy aria-label="Article sections">
<a href="#overview">Overview</a>
<a href="#install">Install</a>
<a href="#usage">Usage</a>
<a href="#faq">FAQ</a>
</nav>
<div id="article">
<section id="overview" style="min-height: 12rem">
<h2>Overview</h2>
</section>
<section id="install" style="min-height: 12rem">
<h2>Install</h2>
</section>
<section id="usage" style="min-height: 12rem">
<h2>Usage</h2>
</section>
<section id="faq" style="min-height: 4rem">
<h2>Faq</h2>
</section>
</div>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
.layout {
display: grid;
grid-template-columns: 9rem 1fr;
gap: 1rem;
}
nav {
display: grid;
align-content: start;
gap: 0.25rem;
}
nav a {
padding: 0.25rem 0.5rem;
border-left: 2px solid #ddd;
color: #555;
text-decoration: none;
}
nav a[aria-current] {
border-color: #a21caf;
color: #111;
font-weight: 600;
}
#article {
height: 16rem;
overflow-y: auto;
scroll-behavior: smooth;
padding: 0 1rem;
border: 1px solid #ccc;
}
JavaScript
// The article scrolls instead of the page, so pass it as the root.
// Called before the DOM is ready, this replaces the automatic start.
ScrollSpy.auto({ root: document.querySelector('#article') })
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Highlight the section you are reading</title>
<style>
.layout {
display: grid;
grid-template-columns: 9rem 1fr;
gap: 1rem;
}
nav {
display: grid;
align-content: start;
gap: 0.25rem;
}
nav a {
padding: 0.25rem 0.5rem;
border-left: 2px solid #ddd;
color: #555;
text-decoration: none;
}
nav a[aria-current] {
border-color: #a21caf;
color: #111;
font-weight: 600;
}
#article {
height: 16rem;
overflow-y: auto;
scroll-behavior: smooth;
padding: 0 1rem;
border: 1px solid #ccc;
}
</style>
</head>
<body>
<main>
<div class="layout">
<nav data-scroll-spy aria-label="Article sections">
<a href="#overview">Overview</a>
<a href="#install">Install</a>
<a href="#usage">Usage</a>
<a href="#faq">FAQ</a>
</nav>
<div id="article">
<section id="overview" style="min-height: 12rem">
<h2>Overview</h2>
</section>
<section id="install" style="min-height: 12rem">
<h2>Install</h2>
</section>
<section id="usage" style="min-height: 12rem">
<h2>Usage</h2>
</section>
<section id="faq" style="min-height: 4rem">
<h2>Faq</h2>
</section>
</div>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js"></script>
<script>
// The article scrolls instead of the page, so pass it as the root.
// Called before the DOM is ready, this replaces the automatic start.
ScrollSpy.auto({ root: document.querySelector('#article') })
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Highlight the section you are reading</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<div class="layout">
<nav data-scroll-spy aria-label="Article sections">
<a href="#overview">Overview</a>
<a href="#install">Install</a>
<a href="#usage">Usage</a>
<a href="#faq">FAQ</a>
</nav>
<div id="article">
<section id="overview" style="min-height: 12rem">
<h2>Overview</h2>
</section>
<section id="install" style="min-height: 12rem">
<h2>Install</h2>
</section>
<section id="usage" style="min-height: 12rem">
<h2>Usage</h2>
</section>
<section id="faq" style="min-height: 4rem">
<h2>Faq</h2>
</section>
</div>
</div>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
.layout {
display: grid;
grid-template-columns: 9rem 1fr;
gap: 1rem;
}
nav {
display: grid;
align-content: start;
gap: 0.25rem;
}
nav a {
padding: 0.25rem 0.5rem;
border-left: 2px solid #ddd;
color: #555;
text-decoration: none;
}
nav a[aria-current] {
border-color: #a21caf;
color: #111;
font-weight: 600;
}
#article {
height: 16rem;
overflow-y: auto;
scroll-behavior: smooth;
padding: 0 1rem;
border: 1px solid #ccc;
}
JavaScript
import { autoScrollSpy } from '@samline/scroll-spy'
// The article scrolls instead of the page, so pass it as the root.
autoScrollSpy({ root: document.querySelector('#article') })
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Highlight the section you are reading</title>
<style>
.layout {
display: grid;
grid-template-columns: 9rem 1fr;
gap: 1rem;
}
nav {
display: grid;
align-content: start;
gap: 0.25rem;
}
nav a {
padding: 0.25rem 0.5rem;
border-left: 2px solid #ddd;
color: #555;
text-decoration: none;
}
nav a[aria-current] {
border-color: #a21caf;
color: #111;
font-weight: 600;
}
#article {
height: 16rem;
overflow-y: auto;
scroll-behavior: smooth;
padding: 0 1rem;
border: 1px solid #ccc;
}
</style>
</head>
<body>
<main>
<div class="layout">
<nav data-scroll-spy aria-label="Article sections">
<a href="#overview">Overview</a>
<a href="#install">Install</a>
<a href="#usage">Usage</a>
<a href="#faq">FAQ</a>
</nav>
<div id="article">
<section id="overview" style="min-height: 12rem">
<h2>Overview</h2>
</section>
<section id="install" style="min-height: 12rem">
<h2>Install</h2>
</section>
<section id="usage" style="min-height: 12rem">
<h2>Usage</h2>
</section>
<section id="faq" style="min-height: 4rem">
<h2>Faq</h2>
</section>
</div>
</div>
</main>
<script type="module">
import { autoScrollSpy } from '@samline/scroll-spy'
// The article scrolls instead of the page, so pass it as the root.
autoScrollSpy({ root: document.querySelector('#article') })
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of scrollSpy, autoScrollSpy and window.ScrollSpy.
Attributes and options.
Layouts and containersSticky headers, scroll containers, smooth scrolling and nested lists.
Accessibility and navigationFocus, reduced motion and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and page swaps.