Floating or sticky elements often benefit from being updated as a visitor scrolls down the page. For example, a sticky Table of Contents on the Article page that tracks a visitors position on the page as they scroll will help them navigate the content.
The Scrollspy extension provides a convenient way of achieving this and because it integrates with all of our other extensions you can use it in countless other ways to add fun, engaging elements to your help center.
The list or menu targeted by the Scrollspy extension should be visible on the page at all times, to ensure that visitors can see where they are on the page. The example below uses one of our pill-style navigation element to present links, but you can update any type of link, in any element.
Initializing scrollspy
You can initialize the Scrollspy extension against any list or navigation element in your help center.
The Scrollspy extension is bundled into all of our themes by default, so you can start using it straight away. The source code can be found within the extensions.(min.)js file in the theme’s Assets folder.
Scrollspy behavior can be initialized by adding data-spy="scroll" to the element you want to spy on.
<ul class=list-unstyled" data-spy="scroll">...</ul>
If data attributes are used within article content you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.
Scrollspy behavior can be initialized on a given element using JavaScript:
<ul class="custom-nav list-unstyled">...</ul>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', () => {
new Scrollspy(document.querySelector('.custom-nav'));
});
</script>
Each link within the element being spyed upon must have a resolvable target, meaning that the href attribute must point to a element that exists on the page. For example, if a link within the spied upon element had an href attribute of #heading-1, an element must exist within the scroll container with an id of heading-1.
Options
Options can be passed via data attributes or JavaScript.
For data attributes, append the option name to data- and use kebab case instead of camel case.
| Name | Type | Default | Description |
|---|---|---|---|
| offset | number | 0 | Pixels to offset from top when calculating position of scroll. |
| scrollElement | stringDOM element | window | The scrolling element that should be observed. |
| activeClass | string | 'is-active' | Class name(s) to apply to the active link. |
Events
| Class | Properties |
|---|---|
scrollspy:active | Fires when the a link within the spied upon element becomes active. |
