A library for scrollspy functionality

@fsegurai/scrollspy is a dependency-free, lightweight scrollspy library that highlights navigation links based on scroll position. Perfect for documentation sites, blogs, and landing pages with sticky tables of contents.

📋 Table of Contents

• 🚀 Features
• 📦 Installation
  • NPM
  • CDN / HTML
• 🧠 Usage
  • HTML Example
  • JavaScript/TypeScript Example
• ⚙️ Options
• 📡 Events
  • gumshoeactivate
  • gumshoedeactivate
• 🔁 Dynamic Content Support
• 📘 API
• ✅ Browser Support
• 🧼 License

🚀 Features

• ⚡️ Lightweight (no dependencies)
• 🔍 Intelligent scroll-based section detection
• 🧩 Nested navigation support
• 🧭 Works with dynamic or static content
• 🎯 Scroll offset for fixed headers
• 🔄 Automatic DOM mutation observer (optional)
• 🎉 Emits custom activation events
• 🧼 Clean API with setup/destroy

📦 Installation

NPM

npm install @fsegurai/scrollspy

CDN / HTML

<script type="module" src="path/to/scrollspy.esm.js"></script>

🧠 Usage

HTML Example

<nav id="toc">
    <ul>
        <li><a href="#intro">Intro</a></li>
        <li><a href="#install">Install</a></li>
        <li>
            <a href="#usage">Usage</a>
            <ul>
                <li><a href="#basic">Basic</a></li>
                <li><a href="#advanced">Advanced</a></li>
            </ul>
        </li>
    </ul>
</nav>

<main>
    <h2 id="intro">Intro</h2>
    <p>...</p>
    <h2 id="install">Install</h2>
    <p>...</p>
    <h2 id="usage">Usage</h2>
    <h3 id="basic">Basic</h3>
    <p>...</p>
    <h3 id="advanced">Advanced</h3>
    <p>...</p>
</main>

JavaScript/TypeScript Example

import scrollspy from '@fsegurai/scrollspy';

const spy = new scrollspy('#toc', {
    offset: 80,
    nested: true,
    nestedClass: 'parent-active',
    reflow: true,
    events: true,
    observe: true
});

⚙️ Options

All available options for customizing behavior:

| Option | Type | Default | Description | |---------------------|-----------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | nav | string | — | (Required) Selector for the navigation container. Specifies where to find the navigation links (usually your Table of Contents or sidebar). | | content | string | [data-gumshoe] | Selector for scrollable content sections (matched by ID from nav href). Used for observing DOM mutations (if observe: true) and for internal mapping. You don’t usually need to change this unless your content isn’t identified by IDs directly | | nested | boolean | false | Add a class to parent <li> items in nested TOC structures | | nestedClass | string | 'active-parent' | Class name for parent <li> elements when nested is true | | offset | number \| () => number | 0 | Scroll offset in pixels or a function returning an offset (e.g. fixed headers) | | bottomThreshold | number | 100 | Distance (in px) from bottom of page where last section is auto-activated. | | reflow | boolean | false | If true, recomputes layout on window resize | | events | boolean | true | Emits custom DOM events (gumshoeactivate, gumshoedeactivate) | | observe | boolean | false | Enables a MutationObserver to track DOM changes and refresh content | | fragmentAttribute | string \| (item: Element) => string \| null | null | Attribute or function used to map nav items to content sections, instead of relying on the href attribute. | | navItemSelector | string | 'a[href*="#"]'| Selector for nav items (anchors). Use to further filter which anchors are considered navigation items. |

If you're using observe: true, make sure your headings or section wrappers have a consistent structure, and set a data-gumshoe attribute if you change the default selector.

Advanced Fragment Mapping (SPA/Angular)

If you need to support full URLs in href (e.g. /route#fragment) or use a custom attribute (e.g. data-scrollspy-fragment), use the fragmentAttribute option:

// Use a custom attribute
const spy = new scrollspy('#toc', {
  fragmentAttribute: 'data-scrollspy-fragment',
});

// Or use a function for advanced mapping
const spy = new scrollspy('#toc', {
  fragmentAttribute: (item) => item.getAttribute('data-scrollspy-fragment') || null,
});

• The library will now match anchors using the custom attribute or function, not just href.
• This is useful for Angular/SPA scenarios where you want the user to see the full URL in the browser, but scrollspy to map by fragment only.

📡 Events

These custom events are fired on the document when scrollspy updates:

gumshoeactivate

Triggered when a new section becomes active.

document.addEventListener('gumshoeactivate', (e) => {
    console.log('Activated:', e.detail.target.id);
});

gumshoedeactivate

Triggered when a section is deactivated (not currently visible).

document.addEventListener('gumshoedeactivate', (e) => {
    console.log('Deactivated:', e.detail.target.id);
});

Event detail includes:

• target: The content section element
• content: Alias of target
• nav: Corresponding anchor tag from the TOC

🔁 Dynamic Content Support

If you update the TOC or headings dynamically, call:

spy.refresh();

Or initialize with observe: true to let it auto-refresh using a MutationObserver.

📘 API

| Method | Description | |-------------|---------------------------------------------------------------------| | setup() | Manually sets up the scrollspy instance again from scratch | | detect() | Re-runs detection logic based on current scroll position | | refresh() | Rebuilds internal nav/content map (used after dynamic updates) | | destroy() | Tears down scrollspy instance, removes listeners and DOM references |

✅ Browser Support

| Browser | Support | |---------|---------| | Chrome | ✅ | | Firefox | ✅ | | Safari | ✅ | | Edge | ✅ | | IE11 | ❌ |

⚠️ Requires IntersectionObserver and CustomEvent. You may need polyfills for legacy environments.

🧼 License

Licensed under MIT.