Guide

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, scrollSpy returns an inert object and autoScrollSpy does nothing.
  • No runtime dependencies.

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>

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.

Table of contentsLive preview

Links to #id sections get aria-current="true" once their section crosses the line at 25% of the box. A clicked link stays highlighted while the box scrolls to it.

Overview

Install

Usage

FAQ

Explore the code

HTML / CDN

HTML

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

style.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

main.js
// 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

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

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

style.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

main.js
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

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