core-logo

Bootstrap scrollspy

Bootstrap scrollspy component automatically update navigation or list group components based on scroll position to indicate which link is currently active in the viewport. Learn how to use Bootstrap scrollspy.

On this page:



How it works

Scrollspy has a few requirements to function properly:

  • If you’re building our JavaScript from source, it requires util.js.
  • It must be used on a Bootstrap nav component or list group.
  • Scrollspy requires position: relative; on the element you’re spying on, usually the <body>.
  • When spying on elements other than the <body>, be sure to have a height set and overflow-y: scroll; applied.
  • Anchors (<a>) are required and must point to an element with that id.

When successfully implemented, your nav or list group will update accordingly, moving the .active class from one item to the next based on their associated targets.

Example in navbar

Scroll the area below the navbar and watch the active class change. The dropdown items will be highlighted as well.

@fat

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce consequat, purus at luctus pulvinar, sapien libero scelerisque neque, sed bibendum ex dui at felis. Integer sed imperdiet nibh, non eleifend lectus. Sed interdum, tortor et rutrum elementum, nisi risus venenatis risus, eget dictum ligula lacus et magna. Nullam pharetra enim quis velit pellentesque euismod. Integer nec neque massa. Maecenas sollicitudin id justo id varius. Maecenas vel nisl eget velit aliquam facilisis. Aenean luctus placerat ornare. Cras congue dolor et enim molestie rhoncus. Proin volutpat, augue eget luctus scelerisque, orci nisi mollis eros, ut volutpat ipsum justo ac tortor.

@mdo

Curabitur eget arcu quam. Nullam blandit justo eu commodo mollis. Quisque hendrerit orci vitae ante faucibus molestie. Praesent maximus et dolor eu condimentum. Praesent egestas est eu sem scelerisque tempor. Curabitur posuere metus vitae risus ultricies fermentum. Nulla fermentum, elit ac maximus laoreet, arcu massa bibendum ipsum, ac feugiat tellus orci id erat. Pellentesque elit felis, vehicula et egestas nec, pulvinar quis magna. Morbi sit amet malesuada erat, a placerat ex.

one

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

two

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce consequat, purus at luctus pulvinar, sapien libero scelerisque neque, sed bibendum ex dui at felis. Integer sed imperdiet nibh, non eleifend lectus. Sed interdum, tortor et rutrum elementum, nisi risus venenatis risus, eget dictum ligula lacus et magna. Nullam pharetra enim quis velit pellentesque euismod. Integer nec neque massa. Maecenas sollicitudin id justo id varius. Maecenas vel nisl eget velit aliquam facilisis. Aenean luctus placerat ornare. Cras congue dolor et enim molestie rhoncus. Proin volutpat, augue eget luctus scelerisque, orci nisi mollis eros, ut volutpat ipsum justo ac tortor.

three

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

<nav id="navbar-example2" class="c-navbar c-navbar-light c-bg-light">
  <a class="c-navbar-brand" href="#">Navbar</a>
  <ul class="c-nav c-nav-pills">
    <li class="c-nav-item">
      <a class="c-nav-link" href="#fat">@fat</a>
    </li>
    <li class="c-nav-item">
      <a class="c-nav-link" href="#mdo">@mdo</a>
    </li>
    <li class="c-nav-item c-dropdown">
      <a class="c-nav-link c-dropdown-toggle" data-toggle="c-dropdown" href="#" role="button" aria-expanded="false">Dropdown</a>
      <div class="c-dropdown-menu">
        <a class="c-dropdown-item" href="#one">one</a>
        <a class="c-dropdown-item" href="#two">two</a>
        <div role="separator" class="c-dropdown-divider"></div>
        <a class="c-dropdown-item" href="#three">three</a>
      </div>
    </li>
  </ul>
</nav>
<div data-spy="scroll" data-target="#navbar-example2" data-offset="0">
  <h4 id="fat">@fat</h4>
  <p>...</p>
  <h4 id="mdo">@mdo</h4>
  <p>...</p>
  <h4 id="one">one</h4>
  <p>...</p>
  <h4 id="two">two</h4>
  <p>...</p>
  <h4 id="three">three</h4>
  <p>...</p>
</div>

Example with nested nav

Scrollspy also works with nested .navs. If a nested .nav is .active, its parents will also be .active. Scroll the area next to the navbar and watch the active class change.

Item 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce consequat, purus at luctus pulvinar, sapien libero scelerisque neque, sed bibendum ex dui at felis. Integer sed imperdiet nibh, non eleifend lectus. Sed interdum, tortor et rutrum elementum, nisi risus venenatis risus, eget dictum ligula lacus et magna. Nullam pharetra enim quis velit pellentesque euismod. Integer nec neque massa. Maecenas sollicitudin id justo id varius. Maecenas vel nisl eget velit aliquam facilisis. Aenean luctus placerat ornare. Cras congue dolor et enim molestie rhoncus. Proin volutpat, augue eget luctus scelerisque, orci nisi mollis eros, ut volutpat ipsum justo ac tortor.

Item 1-1

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

Item 1-2

Curabitur eget arcu quam. Nullam blandit justo eu commodo mollis. Quisque hendrerit orci vitae ante faucibus molestie. Praesent maximus et dolor eu condimentum. Praesent egestas est eu sem scelerisque tempor. Curabitur posuere metus vitae risus ultricies fermentum. Nulla fermentum, elit ac maximus laoreet, arcu massa bibendum ipsum, ac feugiat tellus orci id erat. Pellentesque elit felis, vehicula et egestas nec, pulvinar quis magna. Morbi sit amet malesuada erat, a placerat ex.

Item 2

Quis magna Lorem anim amet ipsum do mollit sit cillum voluptate ex nulla tempor. Laborum consequat non elit enim exercitation cillum aliqua consequat id aliqua. Esse ex consectetur mollit voluptate est in duis laboris ad sit ipsum anim Lorem. Incididunt veniam velit elit elit veniam Lorem aliqua quis ullamco deserunt sit enim elit aliqua esse irure. Laborum nisi sit est tempor laborum mollit labore officia laborum excepteur commodo non commodo dolor excepteur commodo. Ipsum fugiat ex est consectetur ipsum commodo tempor sunt in proident.

Item 3

<

Curabitur eget arcu quam. Nullam blandit justo eu commodo mollis. Quisque hendrerit orci vitae ante faucibus molestie. Praesent maximus et dolor eu condimentum. Praesent egestas est eu sem scelerisque tempor. Curabitur posuere metus vitae risus ultricies fermentum. Nulla fermentum, elit ac maximus laoreet, arcu massa bibendum ipsum, ac feugiat tellus orci id erat. Pellentesque elit felis, vehicula et egestas nec, pulvinar quis magna. Morbi sit amet malesuada erat, a placerat ex.

Item 3-1

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

Item 3-2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce consequat, purus at luctus pulvinar, sapien libero scelerisque neque, sed bibendum ex dui at felis. Integer sed imperdiet nibh, non eleifend lectus. Sed interdum, tortor et rutrum elementum, nisi risus venenatis risus, eget dictum ligula lacus et magna. Nullam pharetra enim quis velit pellentesque euismod. Integer nec neque massa. Maecenas sollicitudin id justo id varius. Maecenas vel nisl eget velit aliquam facilisis. Aenean luctus placerat ornare. Cras congue dolor et enim molestie rhoncus. Proin volutpat, augue eget luctus scelerisque, orci nisi mollis eros, ut volutpat ipsum justo ac tortor.

<nav id="navbar-example3" class="c-navbar c-navbar-light c-bg-light">
  <a class="c-navbar-brand" href="#">Navbar</a>
  <nav class="c-nav c-nav-pills c-flex-column">
    <a class="c-nav-link" href="#item-1">Item 1</a>
    <nav class="c-nav c-nav-pills c-flex-column">
      <a class="c-nav-link c-ml-3 c-my-1" href="#item-1-1">Item 1-1</a>
      <a class="c-nav-link c-ml-3 c-my-1" href="#item-1-2">Item 1-2</a>
    </nav>
    <a class="c-nav-link" href="#item-2">Item 2</a>
    <a class="c-nav-link" href="#item-3">Item 3</a>
    <nav class="c-nav c-nav-pills c-flex-column">
      <a class="c-nav-link c-ml-3 c-my-1" href="#item-3-1">Item 3-1</a>
      <a class="c-nav-link c-ml-3 c-my-1" href="#item-3-2">Item 3-2</a>
    </nav>
  </nav>
</nav>

<div data-spy="scroll" data-target="#navbar-example3" data-offset="0">
  <h4 id="item-1">Item 1</h4>
  <p>...</p>
  <h5 id="item-1-1">Item 1-1</h5>
  <p>...</p>
  <h5 id="item-1-2">Item 1-2</h5>
  <p>...</p>
  <h4 id="item-2">Item 2</h4>
  <p>...</p>
  <h4 id="item-3">Item 3</h4>
  <p>...</p>
  <h5 id="item-3-1">Item 3-1</h5>
  <p>...</p>
  <h5 id="item-3-2">Item 3-2</h5>
  <p>...</p>
</div>

Example with list-group

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

Item 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce consequat, purus at luctus pulvinar, sapien libero scelerisque neque, sed bibendum ex dui at felis. Integer sed imperdiet nibh, non eleifend lectus. Sed interdum, tortor et rutrum elementum, nisi risus venenatis risus, eget dictum ligula lacus et magna. Nullam pharetra enim quis velit pellentesque euismod. Integer nec neque massa. Maecenas sollicitudin id justo id varius. Maecenas vel nisl eget velit aliquam facilisis. Aenean luctus placerat ornare. Cras congue dolor et enim molestie rhoncus. Proin volutpat, augue eget luctus scelerisque, orci nisi mollis eros, ut volutpat ipsum justo ac tortor.

Item 2

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

Item 3

Praesent imperdiet, nulla sit amet vehicula volutpat, dolor velit aliquet mauris, a placerat orci urna vitae tellus. In hac habitasse platea dictumst. Donec ut elit eu urna tristique pellentesque. Maecenas dignissim iaculis scelerisque. Aenean ligula neque, efficitur sed elementum id, posuere eget lectus. Sed tristique sollicitudin arcu at interdum. Donec eget gravida nisi, id mollis nibh. Aliquam id accumsan quam. Praesent at suscipit magna. Sed porttitor tincidunt congue. Fusce dignissim dapibus consectetur. Ut bibendum finibus sem eu sodales. Nullam porta nisi lacus, at mollis arcu malesuada at.

Item 4

Curabitur eget arcu quam. Nullam blandit justo eu commodo mollis. Quisque hendrerit orci vitae ante faucibus molestie. Praesent maximus et dolor eu condimentum. Praesent egestas est eu sem scelerisque tempor. Curabitur posuere metus vitae risus ultricies fermentum. Nulla fermentum, elit ac maximus laoreet, arcu massa bibendum ipsum, ac feugiat tellus orci id erat. Pellentesque elit felis, vehicula et egestas nec, pulvinar quis magna. Morbi sit amet malesuada erat, a placerat ex.

<div id="list-example" class="c-list-group">
  <a class="c-list-group-item c-list-group-item-action" href="#list-item-1">Item 1</a>
  <a class="c-list-group-item c-list-group-item-action" href="#list-item-2">Item 2</a>
  <a class="c-list-group-item c-list-group-item-action" href="#list-item-3">Item 3</a>
  <a class="c-list-group-item c-list-group-item-action" href="#list-item-4">Item 4</a>
</div>
<div data-spy="scroll" data-target="#list-example" data-offset="0" class="scrollspy-example">
  <h4 id="list-item-1">Item 1</h4>
  <p>...</p>
  <h4 id="list-item-2">Item 2</h4>
  <p>...</p>
  <h4 id="list-item-3">Item 3</h4>
  <p>...</p>
  <h4 id="list-item-4">Item 4</h4>
  <p>...</p>
</div>

Usage

Via data attributes

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

body {
  position: relative;
}
<body data-spy="scroll" data-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="c-nav c-nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

Via JavaScript (jQuery)

After adding position: relative; in your CSS, call the scrollspy via JavaScript:

$('body').scrollspy({ target: '#navbar-example' })
Resolvable ID targets required

Navbar links must have resolvable id targets. For example, a <a href="#home">home</a> must correspond to something in the DOM like <div id="home"></div>.

Non-visible target elements ignored

Target elements that are not visible will be ignored and their corresponding nav items will never be highlighted.

Methods

.scrollspy('refresh')

When using scrollspy in conjunction with adding or removing of elements from the DOM, you’ll need to call the refresh method like so:

$('[data-spy="scroll"]').each(function () {
  var $spy = $(this).scrollspy('refresh')
})
.scrollspy('dispose')

Destroys an element’s scrollspy.

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-offset="".

Name Type Default Description
offset number 10 Pixels to offset from top when calculating position of scroll.
method string auto Finds which section the spied element is in. auto will choose the best method get scroll coordinates. offset will use the Element.getBoundingClientRect() method to get scroll coordinates. position will use the HTMLElement.offsetTop and HTMLElement.offsetLeft properties to get scroll coordinates.
target string Specifies element to apply Scrollspy plugin.

Events

Event Type Description
activate.coreui.scrollspy This event fires on the scroll element whenever a new item becomes activated by the scrollspy.
$('[data-spy="scroll"]').on('activate.coreui.scrollspy', function () {
  // do something...
})