Components - Affix & Scrollspy
Affix and Scrollspy
This is an example of Affix and Scrollspy bootstrap components working together. Scroll down or use the links in the right nav menu to navigate the page.Using 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 .nav component.
Add CSS styles:
body {
position: relative;
}And add markup:
<body data-spy="scroll" data-target=".navbar-example">
...
<div class="navbar-example">
<ul class="nav nav-tabs">
...
</ul>
</div>
...
</body>Using JavaScript
After adding position: relative; in your CSS, call the scrollspy via JavaScript:
$('body').scrollspy({ target: '.navbar-example' });Scrollspy 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')
});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. |
Scrollspy Events
| Event Type | Description |
|---|---|
| activate.bs.scrollspy | This event fires whenever a new item becomes activated by the scrollspy. |
Example code:
$('#myScrollspy').on('activate.bs.scrollspy', function () {
// do something…
})Positioning via CSS
Use the affix plugin via data attributes or manually with your own JavaScript. In both situations, you must provide CSS for the positioning and width of your affixed content.
The affix plugin toggles between three classes, each representing a particular state: .affix, .affix-top, and .affix-bottom. You must provide the styles for these classes yourself (independent of this plugin) to handle the actual positions.
Here's how the affix plugin works:
- To start, the plugin adds
.affix-topto indicate the element is in its top-most position. At this point no CSS positioning is required. - Scrolling past the element you want affixed should trigger the actual affixing. This is where
.affixreplaces.affix-topand setsposition: fixed;(provided by Bootstrap's code CSS). - If a bottom offset is defined, scrolling past that should replace
.affixwith.affix-bottom. Since offsets are optional, setting one requires you to set the appropriate CSS. In this case, addposition: absolute;when necessary. The plugin uses the data attribute or JavaScript option to determine where to position the element from there.
Follow the above steps to set your CSS for either of the usage options below.
Using Data Attributes
To easily add affix behavior to any element, just add data-spy="affix" to the element you want to spy on. Use offsets to define when to toggle the pinning of an element.
<div data-spy="affix" data-offset-top="60" data-offset-bottom="200">
...
</div>Using JavaScript
Call the affix plugin via JavaScript:
$('#my-affix').affix({
offset: {
top: 100,
bottom: function () {
return (this.bottom = $('.footer').outerHeight(true))
}
}
});Affix Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-offset-top="200".
| Name | Type | Default | Description |
|---|---|---|---|
| offset | number | function | object | 10 | Pixels to offset from screen when calculating position of scroll. If a single number is provided, the offset will be applied in both top and bottom directions. To provide a unique, bottom and top offset just provide an object offset: { top: 10 } or offset: { top: 10, bottom: 5 }. Use a function when you need to dynamically calculate an offset. |
| target | selector | node | jQuery element | the window object |
Specifies the target element of the affix. |
Affix Events
Bootstrap's affix class exposes a few events for hooking into affix functionality.
| Event Type | Description |
|---|---|
| affix.bs.affix | This event fires immediately before the element has been affixed. |
| affixed.bs.affix | This event is fired after the element has been affixed. |
| affix-top.bs.affix | This event fires immediately before the element has been affixed-top. |
| affixed-top.bs.affix | This event is fired after the element has been affixed-top. |
| affix-bottom.bs.affix | This event fires immediately before the element has been affixed-bottom. |
| affixed-bottom.bs.affix | This event is fired after the element has been affixed-bottom. |