ScrollSpy component
Scrollspy is a component that automatically updates Bootstrap navigation or list group components based on scroll position to indicate which link is currently active in the viewport. Scrollspy has a few requirements to function properly:
- 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 aheight
set andoverflow-y: scroll;
applied. - Anchors (
<a>
) are required and must point to an element with thatid
.
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 .nav
component.
Add CSS styles:
body {
position: relative;
}
And add markup:
<body data-spy="scroll" data-target=".sidebar">
[...]
<div class="sidebar sidebar-default">
<div class="sidebar-content">
[...]
</div>
</div>
[...]
</body>
Usage via JavaScript
After adding position: relative;
in your CSS, call the scrollspy via JavaScript:
// Initialize
$('body').scrollspy({ target: '.sidebar' });
Scrollspy Methods
Scrollspy supports 2 methods: refresh
- when using scrollspy in conjunction with adding or removing of elements from the DOM, you'll need to call the refresh method; dispose
- destroys an element’s scrollspy.
// Refresh Scrollspy
$('[data-spy="scroll"]').each(function () {
var $spy = $(this).scrollspy('refresh')
});
// Destroy Scrollspy
$('[data-spy="scroll"]').scrollspy('dispose');
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:
// When Scrollspy is activated
$('#myScrollspy').on('activate.bs.scrollspy', function () {
// do something…
})
Sticky component
Sticky-kit provides an easy way to attach elements to the page when the user scrolls such that the element is always visible. Just call stick_in_parent
on the elements you want to be stuck inside of their parent. Sticky elements “bottom out” so they never leave the container, no more worrying if a sticky element will accidentally cover your footer.
Example code:
// Initialize Sticky
$("#sticky_item").stick_in_parent();
// Initialize with options
$("#sticky_item").stick_in_parent(options);
Plugin options
You can pass a hash of options to configure how Sticky Kit works. The following options are accepted, each one is optional:
Option | Default value | Description |
---|---|---|
parent |
closest parent | The element will be the parent of the sticky item. The dimensions of the parent control when the sticky element bottoms out. Can be a selector |
inner_scrolling |
true |
Boolean to enable or disable the ability of the sticky element to scroll independently of the scrollbar when it’s taller than the viewport |
sticky_class |
.is_stuck |
The name of the CSS class to apply to elements when they have become stuck |
offset_top |
N/A | Offsets the initial sticking position by of number of pixels, can be either negative or positive |
spacer |
own spacer | Either a selector to use for the spacer element, or false to disable the spacer. The selector is passed to closest, so you should nest the sticky element within the spacer |
bottoming |
true |
Boolean to control whether elements bottom out |
recalc_every |
Never | Integer specifying that a recalc should automatically take place between that many ticks. A tick takes place on every scroll event |
Plugin events
Various events are triggered from a sticky element when its state changes. They are:
Event | Description |
---|---|
sticky_kit:stick |
Triggered when element becomes stuck |
sticky_kit:unstick |
Triggered when element becomes unstuck. (Note: an element is still considered stuck when it has bottomed out) |
sticky_kit:bottom |
Triggered when element bottoms out |
sticky_kit:unbottom |
Triggered when element is no longer bottomed out |
sticky_kit:recalc |
Trigger this event to cause all sticky elements to be recalculated |
sticky_kit:detach |
remove sticky kit and restore element to original position |