Bootstrap - Scrollspy


What is the purpose of the ScrollSpy plugin?

The ScrollSpy plugin is for automatically updating nav targets based on scroll position. Scroll the area below the navbar and watch the active class change. The dropdown sub items will be highlighted as well. See

On the Bootstrap site, as the user scroll down a long documentation page, the code behind the scene automatically move the mark on the vertical navigation bar to indicate the current section that the user is reading.

The navbar can be a vertical navbar or it can be a horizontal navbar as well.

What are the requirements for using the ScrollSpy plugin?

  1. Scrollspy currently requires the use of a Bootstrap nav component for proper highlighting of active links.
  2. 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>.
  3. Non-:visible target elements ignored: Target elements that are not :visible according to jQuery will be ignored and their corresponding nav items will never be highlighted.
  4. Requires relative positioning: No matter the implementation method, scrollspy requires the use of position: relative; on the element you're spying on. In most cases this is the <body>. When scrollspying on elements other than the <body>, be sure to have a height set and overflow-y: scroll; applied.

How can we add scrollspy behavior via the data attribute?

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 .nav component.

<body data-spy="scroll" data-target="#navbar-example">
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">

Scrollspy requires position: relative on the element that you spy on. In most cases, this is the <body> element:

body {
  position: relative;

How can we add scrollspy behavior by using JavaScript?

After adding position: relative; to the element that you are spying on, call the scrollspy via JavaScript:

$('body').scrollspy({ target: '#navbar-example' })

What is the purpose of the refresh method?

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')

How can we pass options to the Scrollspy plugin?

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

What is the purpose of the offset option for the Scrollspy plugin?

  • type: number
  • default: 10
  • description: Pixels to offset from top when calculating position of scroll.

What event types are fired by Scrollspy?

  1. This event fires whenever a new item becomes activated by the scrollspy.
$('#myScrollspy').on('', function () {
  // do something…
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License