Scrollspy·续

<div class="col-8"> <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0"> <div id="item-1"> <h4>Item 1</h4> <p>...</p> </div> <div id="item-1-1"> <h5>Item 1-1</h5> <p>...</p> </div> <div id="item-1-2"> <h5>Item 1-2</h5> <p>...</p> </div> <div id="item-2"> <h4>Item 2</h4> <p>...</p> </div> <div id="item-3"> <h4>Item 3</h4> <p>...</p> </div> <div id="item-3-1"> <h5>Item 3-1</h5> <p>...</p> </div> <div id="item-3-2"> <h5>Item 3-2</h5> <p>...</p> </div> </div> </div> </div>


### List group

Scrollspy also works with `.list-group`s. Scroll the area next to the list group and watch the active class change.

<Example showMarkup={false} code={`
<div class="row">
  <div class="col-4">
    <div id="list-example" class="list-group">
      <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="list-item-1">Item 1</h4>
      <p>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.</p>
      <h4 id="list-item-2">Item 2</h4>
      <p>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.</p>
      <h4 id="list-item-3">Item 3</h4>
      <p>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.</p>
      <h4 id="list-item-4">Item 4</h4>
      <p>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.</p>
    </div>
  </div>
</div>
`} />

```html
&lt;div class="row">
  &lt;div class="col-4">
    &lt;div id="list-example" class="list-group">
      &lt;a class="list-group-item list-group-item-action" href="#list-item-1">Item 1&lt;/a>
      &lt;a class="list-group-item list-group-item-action" href="#list-item-2">Item 2&lt;/a>
      &lt;a class="list-group-item list-group-item-action" href="#list-item-3">Item 3&lt;/a>
      &lt;a class="list-group-item list-group-item-action" href="#list-item-4">Item 4&lt;/a>
    &lt;/div>
  &lt;/div>
  &lt;div class="col-8">
    &lt;div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      &lt;h4 id="list-item-1">Item 1&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="list-item-2">Item 2&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="list-item-3">Item 3&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="list-item-4">Item 4&lt;/h4>
      &lt;p>...&lt;/p>
    &lt;/div>
  &lt;/div>
&lt;/div>

Simple anchors

Scrollspy is not limited to nav components and list groups, so it will work on any <a> anchor elements in the current document. Scroll the area and watch the .active class change.

<Example showMarkup={false} code={`


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.

`} />

&lt;div class="row">
  &lt;div class="col-4">
    &lt;div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center">
      &lt;a class="p-1 rounded" href="#simple-list-item-1">Item 1&lt;/a>
      &lt;a class="p-1 rounded" href="#simple-list-item-2">Item 2&lt;/a>
      &lt;a class="p-1 rounded" href="#simple-list-item-3">Item 3&lt;/a>
      &lt;a class="p-1 rounded" href="#simple-list-item-4">Item 4&lt;/a>
      &lt;a class="p-1 rounded" href="#simple-list-item-5">Item 5&lt;/a>
    &lt;/div>
  &lt;/div>
  &lt;div class="col-8">
    &lt;div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      &lt;h4 id="simple-list-item-1">Item 1&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="simple-list-item-2">Item 2&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="simple-list-item-3">Item 3&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="simple-list-item-4">Item 4&lt;/h4>
      &lt;p>...&lt;/p>
      &lt;h4 id="simple-list-item-5">Item 5&lt;/h4>
      &lt;p>...&lt;/p>
    &lt;/div>
  &lt;/div>
&lt;/div>

Debug overlay

It can be hard to picture exactly where Scrollspy decides a section is active. Since our documentation pages use Scrollspy on our table of contents (the navigation on the right), you can enable a debug overlay to draw red guides over the viewport to illustrate the behavior.

  • The red dashed line near the top is the activation line. A section becomes active as its heading scrolls above this line. On these docs it sits at 96px, just below the navbar with a little room to breathe.
  • The red bottom zone lights up when you reach the bottom of the page. This is where the last section stays active even if its heading never reaches the activation line.

Scroll the page and watch the highlighted item in table of contents change as headings cross the line. Guide positions are computed from the same topMargin/rootMargin detection math the plugin uses.

Non-visible elements

Target elements that aren’t visible will be ignored and their corresponding nav items won’t receive an .active class. Scrollspy instances initialized in a non-visible wrapper will ignore all target elements. Use the refresh method to check for observable elements once the wrapper becomes visible.

document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => {
  el.addEventListener('shown.bs.tab', () => {
    const target = el.getAttribute('data-bs-target')
    const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`)
    bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh()
  })
})

Usage

Via data attributes

To easily add scrollspy behavior to your topbar navigation, add data-bs-spy="scroll" to the element you want to spy on (most typically this would be the <body>). Then add the data-bs-target attribute with the id or class name of the parent element of any Bootstrap .nav component.

Attribute Description
data-bs-spy="scroll" Enables ScrollSpy on the scrollable element (often <body>).
data-bs-target CSS selector for the nav whose links match sections in the spied element.
&lt;body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  &lt;div id="navbar-example">
    &lt;ul class="nav nav-tabs" role="tablist">
      ...
    &lt;/ul>
  &lt;/div>
  ...
&lt;/body>

Via JavaScript

const scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})

Dependencies

Options

Name Type Default Description
rootMargin string, null null Advanced override for the IntersectionObserver rootMargin. When set it takes precedence over topMargin and is passed straight to the observer (for example 0px 0px -40%). Leave null to derive the activation line from topMargin.
smoothScroll boolean false Enables smooth scrolling when a user clicks on a link that refers to ScrollSpy observables. Once the scroll settles, the URL hash and focus are moved to the target section.
target string, DOM element null Specifies element to apply Scrollspy plugin.
threshold array [0] IntersectionObserver threshold valid input, when calculating scroll position.
topMargin string 12% Position of the activation line, measured from the top of the scroll root. Accepts a percentage (12%) or pixels (96px, e.g. to sit below a sticky navbar). Ignored when rootMargin is set.

Methods

Method Description
dispose Destroys an element’s scrollspy. (Removes stored data on the DOM element)
getInstance Static method to get the scrollspy instance associated with a DOM element.
getOrCreateInstance Static method to get the scrollspy instance associated with a DOM element, or to create a new one in case it wasn’t initialized.
refresh When adding or removing elements in the DOM, you’ll need to call the refresh method.

Here’s an example using the refresh method:

const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})

Events

Event Description
activate.bs.scrollspy This event fires on the scroll element whenever an anchor is activated by the scrollspy.
const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})