Figuration v4.4 is now available!

Scrollspy scrollspy.js

The Scrollspy widget is for automatically updating nav targets based on scroll position.

How It Works

  • Scrollspy requires the use of a ul, ol, or nav as the target element containing the subset of navigation links.
  • Navigation 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>.
    • In those, hopefully rare, cases where you do not need a working link, use a data-cfw-scrollspy-target attribute on the indicator item. For example, using the attribute data-cfw-scrollspy-target="#home" would a correspond to the DOM target <div id="home"></div>.
  • Scrollspy requires the use of position: relative; on the element you're spying on, typically the <body>.
  • If you are making a scrollable container on elements (other than the <body>), be sure to have a height set and overflow-y: scroll; applied.
  • Non-:visible target elements will be ignored. Target elements that are not :visible according to jQuery will be ignored and their corresponding nav items will never be highlighted.
  • For keyboard accessibility, scrollable containers (other than the <body>) will have a tabindex="0" attribute automatically added.

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.

Examples

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

Alpha

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Beta

Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.

one

Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.

two

In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.

three

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats.

<nav id="navbar-example" class="navbar navbar-light bg-light">
<a class="navbar-brand" href="#">Navbar</a>
<ul class="nav nav-pills">
<li class="nav-item"><a href="#alpha" class="nav-link">Alpha</a></li>
<li class="nav-item"><a href="#beta" class="nav-link">Beta</a></li>
<li class="nav-item dropdown">
<a href="#" class="nav-link" data-cfw="dropdown">Dropdown <span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="#one" tabindex="-1">one</a></li>
<li><a href="#two" tabindex="-1">two</a></li>
<li class="dropdown-divider"></li>
<li><a href="#three" tabindex="-1">three</a></li>
</ul>
</li>
</ul>
</nav>
<div data-cfw="scrollspy" data-cfw-scrollspy-target="#navbar-example" data-cfw-scrollspy-offset="0">
<h4 id="alpha">Alpha</h4>
<p>...</p>
<h4 id="beta">Beta</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>

The Scrollspy widget also works with nested .navs. If a sub-.nav is .active, it's parents will also be .active. Scroll the area next to the navbar and watch the active class change.

Item 1

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Item 1-1

Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.

Item 1-2

Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.

Item 2

Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.

Item 3

In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.

Item 3-1

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Item 3-2

Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats.

<div class="row">
<div class="col-4">
<nav id="subnav-example" class="navbar navbar-light bg-light">
<a class="navbar-brand" href="#">Navbar</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link" href="#item-1">Item 1</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-1 my-0_25" href="#item-1-1">Item 1-1</a>
<a class="nav-link ms-1 my-0_25" href="#item-1-2">Item 1-2</a>
</nav>
<a class="nav-link" href="#item-2">Item 2</a>
<a class="nav-link" href="#item-3">Item 3</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-1 my-0_25" href="#item-3-1">Item 3-1</a>
<a class="nav-link ms-1 my-0_25" href="#item-3-2">Item 3-2</a>
</nav>
</nav>
</nav>
</div>
<div class="col-8">
<div data-cfw="scrollspy" data-cfw-scrollspy-target="#subnav-example" data-cfw-scrollspy-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>
</div>
</div>

List

The Scrollspy widget can also work with a .list. Scroll the area next to the list group and watch the active class change.

Item 1

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Item 2

Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.

Item 3

Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.

Item 4

In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.

Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats.

<div class="row">
<div class="col-4">
<nav id="list-example" class="list list-spaced list-ruled">
<a class="list-item list-item-action" href="#list-1">Item 1</a>
<a class="list-item list-item-action" href="#list-2">Item2</a>
<a class="list-item list-item-action" href="#list-3">Item 3</a>
<a class="list-item list-item-action" href="#list-4">Item 4</a>
</nav>
</div>
<div class="col-8">
<div data-cfw="scrollspy" data-cfw-scrollspy-target="#list-example" data-cfw-scrollspy-offset="0">
<h4 id="list-1">Item 1</h4>
<p>...</p>
<h4 id="list-2">Item 2</h4>
<p>...</p>
<h4 id="list-3">Item 3</h4>
<p>...</p>
<h4 id="list-4">Item 4</h4>
<p>...</p>
</div>
</div>
</div>

Usage

Via Data Attributes

To easily add scrollspy behavior to a navigation section, add data-cfw="scrollspy" to the element you want to spy on (most typically this would be the <body>). Then add the data-cfw-scrollspy-target attribute with the ID, or other selector, for the target element containing the subset of navigation links.

body {
position: relative;
}
<body data-cfw="scrollspy" data-cfw-scrollspy-target="#navbar-example">
...
<nav id="navbar-example">
<ul class="navbar-nav">
...
</ul>
</nav>
...
</body>

Via JavaScript

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

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

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-scrollspy, as in data-cfw-scrollspy-target="#navbar-example".

Name Type Default Description
target string null The selector for the target container.
offset integer 10 Pixels to offset from top when calculating position of scroll.
throttle integer 100 Timeout rate (milliseconds) for the throttle function helps to decrease function calls through scroll event.
$('#myScrollspy').CFW_Scrollspy({
target: '#navbar-example'
});

Methods

Methods calls should be made on the scrollspy element.

Method Name Description
refresh Update the scrollspy active indicator status.
dispose Removes the associated event listener for the given scrollspy element, leaving the target navigation in its current state.

When using scrollspy in conjunction with adding or removing elements from the DOM, it may be useful to call the refresh method like so:

$('[data-cfw="scrollspy"]').each(function() {
$(this).CFW_Scrollspy('refresh');
});

Events

Event callbacks happen on the or designated scrolling region (for init.cfw.scrollspy) or the activated navigation element (for activate.cfw.scrollspy).

Event Type Description
init.cfw.scrollspy This event fires after the scrollspy is initialized.
activate.cfw.scrollspy This event fires whenever a new item becomes activated by the scrollspy.
$('#myScrollspy').on('activate.cfw.scrollspy', function() {
// do something...
});