Scrollspy | Bootstrap Svelte

How It Works

Scrollspy is implemented as a Svelte attachment using the {@attach ...} directive. It works by:

Using the IntersectionObserver API to monitor when elements scroll into view
Calling a callback function when elements intersect with the scrolling container
Updating the active state of navigation elements based on the currently visible content

To use Scrollspy, you need:

A scrollable container element with the {@attach scrollspy(...)} directive
A set of navigation elements (such as Nav.Link, ListGroup.Item, or simple anchors)
Since we are using Svelte, it is not necessary to have content elements with IDs that match the href attributes of the navigation elements. However, it is a good practice to ensure that the IDs are unique and correspond to the navigation links.
A callback function to update a Svelte state variable to control the active state of navigation elements.

Navbar Example

Use Scrollspy with a Bootstrap navbar to highlight the active section as you scroll down the page.

First heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Second heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Third heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Fourth heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Fifth heading

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

            
            <script lang="ts">
import { Nav, Navbar, scrollspy } from '$lib/index.js';

// State to track which link should be active
let activeNavLinkId: string | null = $state(null);

// Callback function that will be executed when elements intersect
const callback: IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => {
    entries.forEach((entry) => {
        if (entry.isIntersecting) {
            activeNavLinkId = entry.target.id;
        }
    });
};
</script>

<Navbar.Root id="navbar-example" class="bg-body-tertiary px-3 mb-3">
    <Navbar.Brand href="#!">Navbar</Navbar.Brand>
    <Nav.Root itemStyle="pills">
        <Nav.Item>
            <Nav.Link href="#scrollspyHeading1" isActive={activeNavLinkId === 'scrollspyHeading1'}>First</Nav.Link>
        </Nav.Item>
        <Nav.Item>
            <Nav.Link href="#scrollspyHeading2" isActive={activeNavLinkId === 'scrollspyHeading2'}>Second</Nav.Link>
        </Nav.Item>
    </Nav.Root>
</Navbar.Root>

<!-- Element to be scrolled with scrollspy attached -->
<div
    {@attach scrollspy({
        targetSelector: '#navbar-example',
        callback: callback,
        observerOptions: {
            rootMargin: '0px 0px -40%',
            threshold: 0.5
        }
    })}
    class="scrollspy-example bg-body-tertiary p-3 rounded-2"
    tabindex="0"
    role="presentation">
    <h4 id="scrollspyHeading1">First heading</h4>
    <p>Content for first heading...</p>
    <h4 id="scrollspyHeading2">Second heading</h4>
    <p>Content for second heading...</p>
</div>

Nested Nav Example

Scrollspy also works with nested Nav components. When a nested nav item is active, its parent will also be active.

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 1-1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 1-2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3-1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3-2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

            
            <script lang="ts">
import { Nav, scrollspy } from '$lib/index.js';

// State to track which link should be active
let activeNestedNavId: string | null = $state(null);

// Callback function for intersection events
const nestedNavCallback: IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => {
    entries.forEach((entry) => {
        if (entry.isIntersecting) {
            activeNestedNavId = entry.target.id;
        }
    });
};
</script>

<div class="row">
    <div class="col-4">
        <Nav.Root id="navbar-example3" verticalBreakpoint="xs" itemStyle="pills">
            <Nav.Link href="#item-1" isActive={activeNestedNavId?.includes('item-1')}>Item 1</Nav.Link>
            <Nav.Root class="ms-3" verticalBreakpoint="xs">
                <Nav.Link href="#item-1-1" isActive={activeNestedNavId === 'item-1-1'}>Item 1-1</Nav.Link>
                <Nav.Link href="#item-1-2" isActive={activeNestedNavId === 'item-1-2'}>Item 1-2</Nav.Link>
            </Nav.Root>
            <Nav.Link href="#item-2" isActive={activeNestedNavId === 'item-2'}>Item 2</Nav.Link>
            <Nav.Link href="#item-3" isActive={activeNestedNavId?.includes('item-3')}>Item 3</Nav.Link>
            <Nav.Root class="ms-3" verticalBreakpoint="xs">
                <Nav.Link href="#item-3-1" isActive={activeNestedNavId === 'item-3-1'}>Item 3-1</Nav.Link>
                <Nav.Link href="#item-3-2" isActive={activeNestedNavId === 'item-3-2'}>Item 3-2</Nav.Link>
            </Nav.Root>
        </Nav.Root>
    </div>
    <div class="col-8">
        <div
            {@attach scrollspy({
                targetSelector: '#navbar-example3',
                callback: nestedNavCallback,
                observerOptions: { threshold: 0.5 }
            })}
            class="scrollspy-example-2"
            tabindex="0"
            role="presentation">
            <!-- Content with IDs matching the Nav.Link href values -->
            <div id="item-1"><h4>Item 1</h4><p>Content for item 1...</p></div>
            <div id="item-1-1"><h5>Item 1-1</h5><p>Content for item 1-1...</p></div>
        </div>
    </div>
</div>

List Group Example

Scrollspy works seamlessly with Bootstrap list groups. This example shows how to use Scrollspy with a ListGroup component.

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 4

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

            
            <script lang="ts">
import { ListGroup, scrollspy } from '$lib/index.js';

// State to track which list group item should be active
let activeListGroupItemId: string | null = $state(null);

// Callback function for intersection events
const listGroupCallback: IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => {
    entries.forEach((entry) => {
        if (entry.isIntersecting) {
            activeListGroupItemId = entry.target.id;
        }
    });
};
</script>

<div class="row">
    <div class="col-4">
        <ListGroup.Root id="list-example">
            <ListGroup.Item
                href="#list-item-1"
                isAction
                isActive={activeListGroupItemId === 'list-item-1'}>
                Item 1
            </ListGroup.Item>
            <ListGroup.Item
                href="#list-item-2"
                isAction
                isActive={activeListGroupItemId === 'list-item-2'}>
                Item 2
            </ListGroup.Item>
        </ListGroup.Root>
    </div>
    <div class="col-8">
        <div
            {@attach scrollspy({
                targetSelector: '#list-example',
                callback: listGroupCallback,
                observerOptions: { threshold: 0.5 }
            })}
            class="scrollspy-example"
            tabindex="0"
            role="presentation">
            <h4 id="list-item-1">Item 1</h4>
            <p>Content for item 1...</p>
            <h4 id="list-item-2">Item 2</h4>
            <p>Content for item 2...</p>
        </div>
    </div>
</div>

Simple Anchors Example

Scrollspy isn't limited to Nav components and list groups - it works with any anchor elements in the document. This example shows how to use Scrollspy with simple anchors.

Item 1 Item 2 Item 3 Item 4 Item 5

Item 1

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 2

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 3

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 4

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Item 5

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

            
            <script lang="ts">
import { scrollspy } from '$lib/index.js';

// State to track which anchor should be active
let activeSimpleAnchorItemId: string | null = $state(null);

// Callback function for intersection events
const simpleAnchorsCallback: IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => {
    entries.forEach((entry) => {
        if (entry.isIntersecting) {
            activeSimpleAnchorItemId = entry.target.id;
        }
    });
};
</script>

<div class="row">
    <div class="col-4">
        <div class="d-flex flex-column gap-2 text-center" id="simple-items">
            <a
                class="p-1 rounded"
                class:active={activeSimpleAnchorItemId === 'simple-item-1'}
                href="#simple-item-1">
                Item 1
            </a>
            <a
                class="p-1 rounded"
                class:active={activeSimpleAnchorItemId === 'simple-item-2'}
                href="#simple-item-2">
                Item 2
            </a>
        </div>
    </div>
    <div class="col-8">
        <div
            {@attach scrollspy({
                targetSelector: '#simple-items',
                callback: simpleAnchorsCallback,
                observerOptions: { offset: 0, threshold: 0.5 }
            })}
            class="scrollspy-example"
            tabindex="0"
            role="presentation">
            <h4 id="simple-item-1">Item 1</h4>
            <p>Content for item 1...</p>
            <h4 id="simple-item-2">Item 2</h4>
            <p>Content for item 2...</p>
        </div>
    </div>
</div>

API Reference

Scrollspy Attachment

The scrollspy function creates an attachment that can be applied to an element with the {@attach ...} directive.

            
            // Type definition for ScrollspyOptions
export type ScrollspyOptions = {
    targetSelector: string;
    callback: IntersectionObserverCallback;
    observerOptions?: IntersectionObserverInit;
};

// Usage example
<div
    {@attach scrollspy({
        targetSelector: '#element-id',     // A CSS selector to the element that contains the anchor targets.
        callback: myCallback,              // Function to call when elements intersect
        observerOptions: {                 // Standard IntersectionObserver options
            rootMargin: '0px 0px -40%',    // Margins around the root
            threshold: 0.5                 // How much of target must be visible to trigger
        }
    })}
    class="scrollspy-container"
    tabindex="0">
    <!-- Content with elements matching targetSelector -->
</div>

Options

Option	Type	Default	Description
`targetSelector`	`string`	Required	CSS selector for elements to observe within the scrolling container
`callback`	`IntersectionObserverCallback`	Required	Function called when elements intersect with the container
`observerOptions`	`IntersectionObserverInit`	`{ root:[scrollable container element], rootMargin:'0px 0px -25%', threshold:[0.1, 0.5, 1] }`	Configuration options for the IntersectionObserver. Can include `rootMargin`, `threshold`, etc. See MDN Documentation

Usage Notes

The scrollable container must have overflow: auto or overflow: scroll CSS applied
For accessibility, give the scrollable container a tabindex="0" and a role="presentation"
Each target element must have an ID that corresponds to the href attributes in your navigation
The callback should update state variables that control the isActive prop on navigation components