Skip to main content

Components

Scrollspy

Highlight the nav link for the section in view — a scroll-driven animation, with a plain anchor list underneath.

How it works

Scrollspy is the one component that is enhancement only. Wrap a nav and the content in .scrollspy. Each direct child of .scrollspy-content is a section with its own view-timeline; the nth link in the nav runs an animation on the nth section's timeline, and that animation is simply "look active". When a section occupies the top of the scrollport, its link is highlighted. Scroll past it and the highlight moves on.

  • Baseline: a nav of anchor links. Click one and the browser scrolls to the section. Nothing is highlighted.
  • Enhancement: scroll-driven animations with timeline-scope (Chrome 116+, Safari 26, Firefox behind a flag). The highlight follows the scroll position.
  • Fallback: the baseline is the fallback. There is no scripted path.
Pairing is by position: the first link spies the first section, and so on, up to 12. Links can be .nav-links inside a .nav (with or without .nav-item wrappers) or .list-group-items in a .list-group. The nav and the content do not have to be siblings — only descendants of the same .scrollspy.

The scroll container is whatever scrolls the sections. In the demos below .scrollspy-content has a fixed height and overflow-y: auto (the docs helper .docs-scroll-demo). Leave that off and the document itself is the scroller, which is the usual case for a page with a sticky sidebar.

Example with nav pills

A horizontal pill nav above a scrolling box. Scroll the box, or click a pill.

First heading

The opening bout. Two young talents, ten minutes, a clean finish. Nobody remembers it, everybody enjoyed it.

Second heading

Tag team action. One partner does the work, the other gets the pin. A tale as old as the territories.

Third heading

The intercontinental title. The workhorse belt. Ladder, rope, time limit — pick a stipulation.

Fourth heading

A grudge match. The promos were better than the match. The match was still good.

Fifth heading

Main event. Steel cage. The crowd stands for the last five minutes and does not sit back down.

HTML
<div class="scrollspy" style="--bs-scrollspy-offset: 0px">
  <ul class="nav nav-pills mb-4">
    <li class="nav-item"><a class="nav-link" href="#scrollspy-heading-1">First</a></li>
    <li class="nav-item"><a class="nav-link" href="#scrollspy-heading-2">Second</a></li>
    <li class="nav-item"><a class="nav-link" href="#scrollspy-heading-3">Third</a></li>
    <li class="nav-item"><a class="nav-link" href="#scrollspy-heading-4">Fourth</a></li>
    <li class="nav-item"><a class="nav-link" href="#scrollspy-heading-5">Fifth</a></li>
  </ul>
  <div class="scrollspy-content docs-scroll-demo px-4 pb-8">
    <section id="scrollspy-heading-1" style="min-height: 220px">
      <h4 class="pt-3">First heading</h4>
      <p>The opening bout. Two young talents, ten minutes, a clean finish. Nobody remembers it, everybody enjoyed it.</p>
    </section>
    <section id="scrollspy-heading-2" style="min-height: 220px">
      <h4 class="pt-3">Second heading</h4>
      <p>Tag team action. One partner does the work, the other gets the pin. A tale as old as the territories.</p>
    </section>
    <section id="scrollspy-heading-3" style="min-height: 220px">
      <h4 class="pt-3">Third heading</h4>
      <p>The intercontinental title. The workhorse belt. Ladder, rope, time limit — pick a stipulation.</p>
    </section>
    <section id="scrollspy-heading-4" style="min-height: 220px">
      <h4 class="pt-3">Fourth heading</h4>
      <p>A grudge match. The promos were better than the match. The match was still good.</p>
    </section>
    <section id="scrollspy-heading-5" style="min-height: 220px">
      <h4 class="pt-3">Fifth heading</h4>
      <p>Main event. Steel cage. The crowd stands for the last five minutes and does not sit back down.</p>
    </section>
  </div>
</div>

Example with nested nav

Nesting is visual here. Because pairing is by index, keep one flat .nav and indent the sub-links with a margin utility. A real nested <ul class="nav"> would restart the count at 1 and spy the wrong sections.

Item 1

Top-level section. Its link is a plain pill.

Item 2

A parent section, short on purpose so its children come up quickly.

Item 2-1

Indented link, same mechanism. The nav item carries .ms-5.

Item 2-2

Fourth section, fourth link.

Item 3

Another parent.

Item 3-1

Sixth section, sixth link.

Item 3-2

Seventh and last.

HTML
<div class="scrollspy row" style="--bs-scrollspy-offset: 0px">
  <div class="col-4">
    <nav class="h-100 flex-column align-items-stretch pe-4 border-end">
      <ul class="nav nav-pills flex-column">
        <li class="nav-item"><a class="nav-link" href="#scrollspy-item-1">Item 1</a></li>
        <li class="nav-item"><a class="nav-link" href="#scrollspy-item-2">Item 2</a></li>
        <li class="nav-item ms-5"><a class="nav-link" href="#scrollspy-item-2-1">Item 2-1</a></li>
        <li class="nav-item ms-5"><a class="nav-link" href="#scrollspy-item-2-2">Item 2-2</a></li>
        <li class="nav-item"><a class="nav-link" href="#scrollspy-item-3">Item 3</a></li>
        <li class="nav-item ms-5"><a class="nav-link" href="#scrollspy-item-3-1">Item 3-1</a></li>
        <li class="nav-item ms-5"><a class="nav-link" href="#scrollspy-item-3-2">Item 3-2</a></li>
      </ul>
    </nav>
  </div>
  <div class="col-8">
    <div class="scrollspy-content docs-scroll-demo px-4 pb-8" style="height: 320px">
      <div id="scrollspy-item-1" style="min-height: 320px">
        <h4 class="pt-3">Item 1</h4>
        <p>Top-level section. Its link is a plain pill.</p>
      </div>
      <div id="scrollspy-item-2" style="min-height: 160px">
        <h4 class="pt-3">Item 2</h4>
        <p>A parent section, short on purpose so its children come up quickly.</p>
      </div>
      <div id="scrollspy-item-2-1" style="min-height: 320px">
        <h5 class="pt-3">Item 2-1</h5>
        <p>Indented link, same mechanism. The nav item carries <code>.ms-5</code>.</p>
      </div>
      <div id="scrollspy-item-2-2" style="min-height: 320px">
        <h5 class="pt-3">Item 2-2</h5>
        <p>Fourth section, fourth link.</p>
      </div>
      <div id="scrollspy-item-3" style="min-height: 160px">
        <h4 class="pt-3">Item 3</h4>
        <p>Another parent.</p>
      </div>
      <div id="scrollspy-item-3-1" style="min-height: 320px">
        <h5 class="pt-3">Item 3-1</h5>
        <p>Sixth section, sixth link.</p>
      </div>
      <div id="scrollspy-item-3-2" style="min-height: 320px">
        <h5 class="pt-3">Item 3-2</h5>
        <p>Seventh and last.</p>
      </div>
    </div>
  </div>
</div>

Example with list-group

A list group of .list-group-item-action links works the same way; the active item turns gold.

Item 1

The list group item for this section is gold while it is at the top of the box.

Item 2

Second section.

Item 3

Third section.

Item 4

Fourth section.

HTML
<div class="scrollspy row" style="--bs-scrollspy-offset: 0px">
  <div class="col-4">
    <div class="list-group">
      <a class="list-group-item list-group-item-action" href="#scrollspy-list-1">Item 1</a>
      <a class="list-group-item list-group-item-action" href="#scrollspy-list-2">Item 2</a>
      <a class="list-group-item list-group-item-action" href="#scrollspy-list-3">Item 3</a>
      <a class="list-group-item list-group-item-action" href="#scrollspy-list-4">Item 4</a>
    </div>
  </div>
  <div class="col-8">
    <div class="scrollspy-content docs-scroll-demo px-4 pb-8">
      <div id="scrollspy-list-1" style="min-height: 220px">
        <h4 class="pt-3">Item 1</h4>
        <p>The list group item for this section is gold while it is at the top of the box.</p>
      </div>
      <div id="scrollspy-list-2" style="min-height: 220px">
        <h4 class="pt-3">Item 2</h4>
        <p>Second section.</p>
      </div>
      <div id="scrollspy-list-3" style="min-height: 220px">
        <h4 class="pt-3">Item 3</h4>
        <p>Third section.</p>
      </div>
      <div id="scrollspy-list-4" style="min-height: 220px">
        <h4 class="pt-3">Item 4</h4>
        <p>Fourth section.</p>
      </div>
    </div>
  </div>
</div>

Simple anchors

Any .nav will do. Without .nav-pills the active link takes the emphasis colour; with .nav-underline it also gets the rule beneath it. Links may be direct children of the .nav, no .nav-item needed.

Red corner

Weighing in at 275 pounds.

Blue corner

Weighing in at 240 pounds.

Referee

Counts slow when it matters.

HTML
<div class="scrollspy" style="--bs-scrollspy-offset: 0px">
  <nav class="nav nav-underline mb-4">
    <a class="nav-link" href="#scrollspy-simple-1">Red corner</a>
    <a class="nav-link" href="#scrollspy-simple-2">Blue corner</a>
    <a class="nav-link" href="#scrollspy-simple-3">Referee</a>
  </nav>
  <div class="scrollspy-content docs-scroll-demo px-4 pb-8">
    <div id="scrollspy-simple-1" style="min-height: 220px">
      <h4 class="pt-3">Red corner</h4>
      <p>Weighing in at 275 pounds.</p>
    </div>
    <div id="scrollspy-simple-2" style="min-height: 220px">
      <h4 class="pt-3">Blue corner</h4>
      <p>Weighing in at 240 pounds.</p>
    </div>
    <div id="scrollspy-simple-3" style="min-height: 220px">
      <h4 class="pt-3">Referee</h4>
      <p>Counts slow when it matters.</p>
    </div>
  </div>
</div>

Usage

  • Offset. --bs-scrollspy-offset on .scrollspy is a view-timeline-inset at the top of the scrollport. Set it to the height of a fixed header (e.g. 56px) so a section counts as "at the top" when it sits just below the header. Default 0px.
  • Sections. Only direct children of .scrollspy-content are spied. Wrap each section's heading and body together.
  • Count. Up to 12 sections and links. More links are plain anchors.
  • Page-level. With no height on .scrollspy-content, the document scrolls and the sections should be the page's own sections. Put .sticky-top on the nav column.
  • Last section. A section can only reach the top if there is room to scroll it there. Give the last one enough height, or pad the bottom of the scroller — the demos use .pb-8.
  • At rest. The active range starts the moment a section's top edge passes the (inset) top of the scrollport, so before any scrolling nothing is highlighted. If you want the first link lit on load, set --bs-scrollspy-offset: 1px — the first section is then already one pixel "past" the edge.
  • Smooth scrolling is the browser's; add scroll-behavior: smooth to the scroller if you want it.

Accessibility

  • The links are real anchors, so the baseline is fully accessible without the enhancement.
  • The highlight is purely visual; it does not change aria-current. Nothing is announced as the user scrolls, which is the same as Bootstrap's behaviour.
  • Give every section a heading with the same text as its link.
  • Scroll-driven animations are not affected by prefers-reduced-motion because nothing moves — the state follows the user's own scrolling.

CSS

One custom property:

.scrollspy {
  --bs-scrollspy-offset: 0px;   /* top inset of the scrollport; match a fixed header */
}

The active colours reuse the nav and list-group variables, so overriding those overrides the spy:

@keyframes rb-spy-nav {
  from, to {
    color: var(--bs-nav-pills-link-active-color, var(--bs-emphasis-color));
    background-color: var(--bs-nav-pills-link-active-bg, transparent);
    border-bottom-color: currentcolor;
  }
}

@keyframes rb-spy-list {
  from, to {
    color: var(--bs-list-group-active-color);
    background-color: var(--bs-list-group-active-bg);
    border-color: var(--bs-list-group-active-border-color);
  }
}

Behavioural selectors, all inside @supports (timeline-scope: --rb) and (animation-timeline: --rb):

.scrollspy                                   // timeline-scope: --rb-spy-1 … --rb-spy-12
.scrollspy-content > :nth-child(n)           // view-timeline-name: --rb-spy-n; inset from --bs-scrollspy-offset
.scrollspy .nav > :nth-child(n) > .nav-link,
.scrollspy .nav > .nav-link:nth-child(n),
.scrollspy .list-group > :nth-child(n)       // animation-timeline: --rb-spy-n
.scrollspy .nav .nav-link                    // animation: rb-spy-nav; animation-range: exit 0% exit 100%
.scrollspy .list-group > .list-group-item    // animation: rb-spy-list; same range