Skip to content
@samline/scroll-spyv1.0.1
AboutInstallRecipesFAQExamplesDocs

@samline/scroll-spy

Explore Scroll Spy

A starting point, a working example, and the details when you need them.

  • 01AboutUnderstand the problem and the approach.
  • 02InstallChoose your setup and follow the first steps.
  • 03RecipesUseful patterns and integration context.
  • 04FAQFind the practical details.
  • 05ExamplesTry a preview and explore its code.
  • 06DocsRead guides and the complete reference.

Around the project

  • GitHub(opens in a new tab)
  • npm(opens in a new tab)

v1.0.1·MIT

GitHub(opens in a new tab)Get started
Examples

Scroll Spy examples.

Live previews of distinct scenarios, each with independently copyable files. The same examples appear in the documentation.

Try the exampleInstallation guide

Each preview runs the real package. The copied files load the published browser bundle, so they run as they are.

Choose an example

Table of contentsOne-page menuLong contents
01 / Table of contents

Highlight the section you are reading

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.

OverviewInstallUsageFAQ

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>
02 / One-page menu

A one-page menu with a class and the URL hash

One-page menuLive preview

activeClass styles the current item, and updateHash keeps the address shareable without adding history entries.

HomeWorkAboutContact

Home

Work

About

Contact

URL hash: none

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>A one-page menu with a class and the URL hash</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <div id="page">
        <nav class="menu" data-scroll-spy>
          <a href="#home">Home</a>
          <a href="#work">Work</a>
          <a href="#about">About</a>
          <a href="#contact">Contact</a>
        </nav>
        <section id="home" style="min-height: 14rem">
          <h2>Home</h2>
        </section>
        <section id="work" style="min-height: 14rem">
          <h2>Work</h2>
        </section>
        <section id="about" style="min-height: 14rem">
          <h2>About</h2>
        </section>
        <section id="contact" style="min-height: 14rem">
          <h2>Contact</h2>
        </section>
      </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
#page {
  height: 16rem;
  overflow-y: auto;
  scroll-behavior: smooth;
  border: 1px solid #ccc;
}
.menu {
  position: sticky;
  top: 0;
  display: flex;
  gap: 1rem;
  padding: 0.75rem 1rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
.menu a {
  color: #555;
  text-decoration: none;
}
.menu a.is-active {
  color: #111;
  font-weight: 600;
  text-decoration: underline;
}
section {
  padding: 0 1rem;
  scroll-margin-top: 3rem;
}

JavaScript

main.js
ScrollSpy.auto({
  root: document.querySelector('#page'),
  activeClass: 'is-active',
  updateHash: true,
})

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>A one-page menu with a class and the URL hash</title>
    <style>
      #page {
        height: 16rem;
        overflow-y: auto;
        scroll-behavior: smooth;
        border: 1px solid #ccc;
      }
      .menu {
        position: sticky;
        top: 0;
        display: flex;
        gap: 1rem;
        padding: 0.75rem 1rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      .menu a {
        color: #555;
        text-decoration: none;
      }
      .menu a.is-active {
        color: #111;
        font-weight: 600;
        text-decoration: underline;
      }
      section {
        padding: 0 1rem;
        scroll-margin-top: 3rem;
      }
    </style>
  </head>
  <body>
    <main>
      <div id="page">
        <nav class="menu" data-scroll-spy>
          <a href="#home">Home</a>
          <a href="#work">Work</a>
          <a href="#about">About</a>
          <a href="#contact">Contact</a>
        </nav>
        <section id="home" style="min-height: 14rem">
          <h2>Home</h2>
        </section>
        <section id="work" style="min-height: 14rem">
          <h2>Work</h2>
        </section>
        <section id="about" style="min-height: 14rem">
          <h2>About</h2>
        </section>
        <section id="contact" style="min-height: 14rem">
          <h2>Contact</h2>
        </section>
      </div>
    </main>
    <script src="https://cdn.jsdelivr.net/npm/@samline/scroll-spy@1.0.1/dist/browser/scroll-spy.global.js"></script>
    <script>
      ScrollSpy.auto({
        root: document.querySelector('#page'),
        activeClass: 'is-active',
        updateHash: true,
      })
    </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>A one-page menu with a class and the URL hash</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <div id="page">
        <nav class="menu" data-scroll-spy>
          <a href="#home">Home</a>
          <a href="#work">Work</a>
          <a href="#about">About</a>
          <a href="#contact">Contact</a>
        </nav>
        <section id="home" style="min-height: 14rem">
          <h2>Home</h2>
        </section>
        <section id="work" style="min-height: 14rem">
          <h2>Work</h2>
        </section>
        <section id="about" style="min-height: 14rem">
          <h2>About</h2>
        </section>
        <section id="contact" style="min-height: 14rem">
          <h2>Contact</h2>
        </section>
      </div>
    </main>
    <script type="module" src="./main.js"></script>
  </body>
</html>

CSS

style.css
#page {
  height: 16rem;
  overflow-y: auto;
  scroll-behavior: smooth;
  border: 1px solid #ccc;
}
.menu {
  position: sticky;
  top: 0;
  display: flex;
  gap: 1rem;
  padding: 0.75rem 1rem;
  background: #fff;
  border-bottom: 1px solid #ddd;
}
.menu a {
  color: #555;
  text-decoration: none;
}
.menu a.is-active {
  color: #111;
  font-weight: 600;
  text-decoration: underline;
}
section {
  padding: 0 1rem;
  scroll-margin-top: 3rem;
}

JavaScript

main.js
import { autoScrollSpy } from '@samline/scroll-spy'

autoScrollSpy({
  root: document.querySelector('#page'),
  activeClass: 'is-active',
  updateHash: true,
})

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>A one-page menu with a class and the URL hash</title>
    <style>
      #page {
        height: 16rem;
        overflow-y: auto;
        scroll-behavior: smooth;
        border: 1px solid #ccc;
      }
      .menu {
        position: sticky;
        top: 0;
        display: flex;
        gap: 1rem;
        padding: 0.75rem 1rem;
        background: #fff;
        border-bottom: 1px solid #ddd;
      }
      .menu a {
        color: #555;
        text-decoration: none;
      }
      .menu a.is-active {
        color: #111;
        font-weight: 600;
        text-decoration: underline;
      }
      section {
        padding: 0 1rem;
        scroll-margin-top: 3rem;
      }
    </style>
  </head>
  <body>
    <main>
      <div id="page">
        <nav class="menu" data-scroll-spy>
          <a href="#home">Home</a>
          <a href="#work">Work</a>
          <a href="#about">About</a>
          <a href="#contact">Contact</a>
        </nav>
        <section id="home" style="min-height: 14rem">
          <h2>Home</h2>
        </section>
        <section id="work" style="min-height: 14rem">
          <h2>Work</h2>
        </section>
        <section id="about" style="min-height: 14rem">
          <h2>About</h2>
        </section>
        <section id="contact" style="min-height: 14rem">
          <h2>Contact</h2>
        </section>
      </div>
    </main>
    <script type="module">
      import { autoScrollSpy } from '@samline/scroll-spy'

      autoScrollSpy({
        root: document.querySelector('#page'),
        activeClass: 'is-active',
        updateHash: true,
      })
    </script>
  </body>
</html>
03 / Long contents

A long table of contents that follows along

Long contentsLive preview

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

Chapter 1Chapter 2Chapter 3Chapter 4Chapter 5Chapter 6Chapter 7Chapter 8Chapter 9Chapter 10Chapter 11Chapter 12

Chapter 1

Chapter 2

Chapter 3

Chapter 4

Chapter 5

Chapter 6

Chapter 7

Chapter 8

Chapter 9

Chapter 10

Chapter 11

Chapter 12

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>A long table of contents that follows along</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <div class="layout">
        <nav data-scroll-spy aria-label="Chapters">
          <a href="#chapter-1">Chapter 1</a>
          <a href="#chapter-2">Chapter 2</a>
          <a href="#chapter-3">Chapter 3</a>
          <a href="#chapter-4">Chapter 4</a>
          <a href="#chapter-5">Chapter 5</a>
          <a href="#chapter-6">Chapter 6</a>
          <a href="#chapter-7">Chapter 7</a>
          <a href="#chapter-8">Chapter 8</a>
          <a href="#chapter-9">Chapter 9</a>
          <a href="#chapter-10">Chapter 10</a>
          <a href="#chapter-11">Chapter 11</a>
          <a href="#chapter-12">Chapter 12</a>
        </nav>
        <div id="book">
          <section id="chapter-1"><h2>Chapter 1</h2></section>
          <section id="chapter-2"><h2>Chapter 2</h2></section>
          <section id="chapter-3"><h2>Chapter 3</h2></section>
          <section id="chapter-4"><h2>Chapter 4</h2></section>
          <section id="chapter-5"><h2>Chapter 5</h2></section>
          <section id="chapter-6"><h2>Chapter 6</h2></section>
          <section id="chapter-7"><h2>Chapter 7</h2></section>
          <section id="chapter-8"><h2>Chapter 8</h2></section>
          <section id="chapter-9"><h2>Chapter 9</h2></section>
          <section id="chapter-10"><h2>Chapter 10</h2></section>
          <section id="chapter-11"><h2>Chapter 11</h2></section>
          <section id="chapter-12"><h2>Chapter 12</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;
  height: 16rem;
  overflow-y: auto;
}
nav a {
  padding: 0.375rem 0.5rem;
  color: #555;
  text-decoration: none;
}
nav a[aria-current] {
  background: #efeafd;
  color: #111;
}
#book {
  height: 16rem;
  overflow-y: auto;
  padding: 0 1rem;
  border: 1px solid #ccc;
}
section {
  min-height: 10rem;
}

JavaScript

main.js
ScrollSpy.auto({ root: document.querySelector('#book') })

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>A long table of contents that follows along</title>
    <style>
      .layout {
        display: grid;
        grid-template-columns: 9rem 1fr;
        gap: 1rem;
      }
      nav {
        display: grid;
        align-content: start;
        height: 16rem;
        overflow-y: auto;
      }
      nav a {
        padding: 0.375rem 0.5rem;
        color: #555;
        text-decoration: none;
      }
      nav a[aria-current] {
        background: #efeafd;
        color: #111;
      }
      #book {
        height: 16rem;
        overflow-y: auto;
        padding: 0 1rem;
        border: 1px solid #ccc;
      }
      section {
        min-height: 10rem;
      }
    </style>
  </head>
  <body>
    <main>
      <div class="layout">
        <nav data-scroll-spy aria-label="Chapters">
          <a href="#chapter-1">Chapter 1</a>
          <a href="#chapter-2">Chapter 2</a>
          <a href="#chapter-3">Chapter 3</a>
          <a href="#chapter-4">Chapter 4</a>
          <a href="#chapter-5">Chapter 5</a>
          <a href="#chapter-6">Chapter 6</a>
          <a href="#chapter-7">Chapter 7</a>
          <a href="#chapter-8">Chapter 8</a>
          <a href="#chapter-9">Chapter 9</a>
          <a href="#chapter-10">Chapter 10</a>
          <a href="#chapter-11">Chapter 11</a>
          <a href="#chapter-12">Chapter 12</a>
        </nav>
        <div id="book">
          <section id="chapter-1"><h2>Chapter 1</h2></section>
          <section id="chapter-2"><h2>Chapter 2</h2></section>
          <section id="chapter-3"><h2>Chapter 3</h2></section>
          <section id="chapter-4"><h2>Chapter 4</h2></section>
          <section id="chapter-5"><h2>Chapter 5</h2></section>
          <section id="chapter-6"><h2>Chapter 6</h2></section>
          <section id="chapter-7"><h2>Chapter 7</h2></section>
          <section id="chapter-8"><h2>Chapter 8</h2></section>
          <section id="chapter-9"><h2>Chapter 9</h2></section>
          <section id="chapter-10"><h2>Chapter 10</h2></section>
          <section id="chapter-11"><h2>Chapter 11</h2></section>
          <section id="chapter-12"><h2>Chapter 12</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>
      ScrollSpy.auto({ root: document.querySelector('#book') })
    </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>A long table of contents that follows along</title>
    <link rel="stylesheet" href="./style.css" />
  </head>
  <body>
    <main>
      <div class="layout">
        <nav data-scroll-spy aria-label="Chapters">
          <a href="#chapter-1">Chapter 1</a>
          <a href="#chapter-2">Chapter 2</a>
          <a href="#chapter-3">Chapter 3</a>
          <a href="#chapter-4">Chapter 4</a>
          <a href="#chapter-5">Chapter 5</a>
          <a href="#chapter-6">Chapter 6</a>
          <a href="#chapter-7">Chapter 7</a>
          <a href="#chapter-8">Chapter 8</a>
          <a href="#chapter-9">Chapter 9</a>
          <a href="#chapter-10">Chapter 10</a>
          <a href="#chapter-11">Chapter 11</a>
          <a href="#chapter-12">Chapter 12</a>
        </nav>
        <div id="book">
          <section id="chapter-1"><h2>Chapter 1</h2></section>
          <section id="chapter-2"><h2>Chapter 2</h2></section>
          <section id="chapter-3"><h2>Chapter 3</h2></section>
          <section id="chapter-4"><h2>Chapter 4</h2></section>
          <section id="chapter-5"><h2>Chapter 5</h2></section>
          <section id="chapter-6"><h2>Chapter 6</h2></section>
          <section id="chapter-7"><h2>Chapter 7</h2></section>
          <section id="chapter-8"><h2>Chapter 8</h2></section>
          <section id="chapter-9"><h2>Chapter 9</h2></section>
          <section id="chapter-10"><h2>Chapter 10</h2></section>
          <section id="chapter-11"><h2>Chapter 11</h2></section>
          <section id="chapter-12"><h2>Chapter 12</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;
  height: 16rem;
  overflow-y: auto;
}
nav a {
  padding: 0.375rem 0.5rem;
  color: #555;
  text-decoration: none;
}
nav a[aria-current] {
  background: #efeafd;
  color: #111;
}
#book {
  height: 16rem;
  overflow-y: auto;
  padding: 0 1rem;
  border: 1px solid #ccc;
}
section {
  min-height: 10rem;
}

JavaScript

main.js
import { autoScrollSpy } from '@samline/scroll-spy'

autoScrollSpy({ root: document.querySelector('#book') })

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>A long table of contents that follows along</title>
    <style>
      .layout {
        display: grid;
        grid-template-columns: 9rem 1fr;
        gap: 1rem;
      }
      nav {
        display: grid;
        align-content: start;
        height: 16rem;
        overflow-y: auto;
      }
      nav a {
        padding: 0.375rem 0.5rem;
        color: #555;
        text-decoration: none;
      }
      nav a[aria-current] {
        background: #efeafd;
        color: #111;
      }
      #book {
        height: 16rem;
        overflow-y: auto;
        padding: 0 1rem;
        border: 1px solid #ccc;
      }
      section {
        min-height: 10rem;
      }
    </style>
  </head>
  <body>
    <main>
      <div class="layout">
        <nav data-scroll-spy aria-label="Chapters">
          <a href="#chapter-1">Chapter 1</a>
          <a href="#chapter-2">Chapter 2</a>
          <a href="#chapter-3">Chapter 3</a>
          <a href="#chapter-4">Chapter 4</a>
          <a href="#chapter-5">Chapter 5</a>
          <a href="#chapter-6">Chapter 6</a>
          <a href="#chapter-7">Chapter 7</a>
          <a href="#chapter-8">Chapter 8</a>
          <a href="#chapter-9">Chapter 9</a>
          <a href="#chapter-10">Chapter 10</a>
          <a href="#chapter-11">Chapter 11</a>
          <a href="#chapter-12">Chapter 12</a>
        </nav>
        <div id="book">
          <section id="chapter-1"><h2>Chapter 1</h2></section>
          <section id="chapter-2"><h2>Chapter 2</h2></section>
          <section id="chapter-3"><h2>Chapter 3</h2></section>
          <section id="chapter-4"><h2>Chapter 4</h2></section>
          <section id="chapter-5"><h2>Chapter 5</h2></section>
          <section id="chapter-6"><h2>Chapter 6</h2></section>
          <section id="chapter-7"><h2>Chapter 7</h2></section>
          <section id="chapter-8"><h2>Chapter 8</h2></section>
          <section id="chapter-9"><h2>Chapter 9</h2></section>
          <section id="chapter-10"><h2>Chapter 10</h2></section>
          <section id="chapter-11"><h2>Chapter 11</h2></section>
          <section id="chapter-12"><h2>Chapter 12</h2></section>
        </div>
      </div>
    </main>
    <script type="module">
      import { autoScrollSpy } from '@samline/scroll-spy'

      autoScrollSpy({ root: document.querySelector('#book') })
    </script>
  </body>
</html>

These examples show a few possibilities. The next ideas are yours: combine the package’s capabilities with your own content, design and interactions to create the experience your project needs.

Read the example guideDownload the Scroll Spy skill for AI agents
@samline/scroll-spy

Highlight the navigation link of the section in view, for tables of contents and one-page menus, with aria-current, click locking and scroll containers, for vanilla JavaScript, any framework and plain HTML.

v1.0.1·MIT

Explore

DocsInstallation guideWorking examples

Project

Scroll Spy skill for AI agentsGitHub(opens in a new tab)Changelognpm(opens in a new tab)License(opens in a new tab)

© 2026 samline · Made for the open web.

Back to top