Scrollspy

Update a set of links based on the scroll position of an element or page.

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.

Sticky table of contents

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 string
DOM 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.

Related extensions

Article navigation Free

Article navigation

Display links to next and previous articles.

Category dropdown Free

Category dropdown

Display all categories within a menu in the page header.

Collapse Free

Collapse

Create versatile collapsible content areas anywhere in your help center.