Plugins
Scrollspy

Tailwind CSS ScrollSpy Plugin API

Headless, unstyled scrollspy plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

JavaScript Typescript

Installation

To get started, install Scrollspy plugin via npm, else you can skip this step if you are already using Preline UI as a package.

Install the plugin

Install @preline/scrollspy via npm

Terminal

                          
                            npm i @preline/scrollspy

Add the plugin CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

main.css

                          
                            @import "tailwindcss";
                            
                            /* @preline/scrollspy */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/scrollspy/*.js";
                            @import "./node_modules/@preline/scrollspy/variants.css";
                            @import "./node_modules/@preline/scrollspy/theme.css";

Add the plugin JavaScript

Include the JavaScript <script> that powers the interactive elements near the end of your </body> tag:
HTML
<script src="./node_modules/@preline/scrollspy/index.js"></script>
```
                          
                        
```
Additional Initialization Options

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.
HTML (non-auto)
<script type="module"> // [!code highlight:3] import HSScrollspy from "@preline/scrollspy/non-auto.mjs"; new HSScrollspy(document.querySelector("#scrollspy")); </script>
```
                          
                        
```
Via bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.
JavaScript (auto)
```
                          
                            import "@preline/scrollspy";
                          
                        
```
JavaScript (non-auto)
```
                          
                            import HSScrollspy from "@preline/scrollspy/non-auto";
                            
                            HSScrollspy.autoInit();
                            
                            // Or initialize a specific element manually
                            const el = document.querySelector("#scrollspy");
                            if (el) new HSScrollspy(el);
                          
                        
```

Basic usage

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

First

This is some placeholder content for the scrollspy page. Note that as you scroll down the page, the appropriate navigation link is highlighted. It's repeated throughout the component example. We keep adding some more example copy here to emphasize the scrolling and highlighting.

Second

Third

Fourth

Fifth

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

HTML

                      
                        <div id="hs-scrollspy-scrollable-parent-basic-usage" class="max-h-96 overflow-y-auto">
                          <div data-hs-scrollspy="#hs-scrollspy-basic-usage" class="flex flex-wrap gap-3">
                            <a class="active" href="#first">First</a>
                            <a href="#second">Second</a>
                            <a href="#third">Third</a>
                            <a href="#fourth">Fourth</a>
                            <a href="#fifth">Fifth</a>
                          </div>

                          <div id="hs-scrollspy-basic-usage">
                            <div id="first" class="h-48">
                              First
                            </div>

                            <div id="second" class="h-48">
                              Second
                            </div>

                            <div id="third" class="h-48">
                              Third
                            </div>

                            <div id="fourth" class="h-48">
                              Fourth
                            </div>

                            <div id="fifth" class="h-48">
                              Fifth
                            </div>
                          </div>
                        </div>

JavaScript behavior

Data Options

Name	Description	Options	Default value
`data-hs-scrollspy`	A container containing sections. This must be a valid selector. Should be added to the nav that contains Scrollspy links.	string	—
`data-hs-scrollspy-scrollable-parent`	Specifies the element to be scrolled. This must be a valid selector. Should be added to the nav that contains Scrollspy links.	string	`window`

Class Options

Name	Description	Options	Default value
`[--scrollspy-offset:*]`	Adds offset when scrolling to the section and to determine if the section is active. Should be added to the nav that contains Scrollspy links.	number	`0`

Tailwind Modifiers

Name	Description
`hs-scrollspy-active:*`	A modifier that allows you to set Tailwind classes when the section is active for link

Methods

The HSScrollspy object is contained within the global window object

Method	Description
Public methods
`destroy()`	Destroys the instance, removes generated markup (if any), removes added classes and attributes.
Static methods
`HSScrollspy.getInstance(target, isInstance)`	Returns the element associated to the `target`. `target` should be a Node or string (valid selector) `isInstance` boolean. Returns the instance instead of Node if `true`

Destroy instance.

JavaScript

                      
                        const { element } = HSScrollspy.getInstance('#scrollspy', true);
                        const destroyBtn = document.querySelector('#destroy-btn');
                        
                        destroyBtn.addEventListener('click', () => {
                          element.destroy();
                        });

Events

Method	Description	Returning value
`on:beforeScroll`	Called before scrolling begins. Could be Promise.	Instance

An example of executing a function after collapsing the accordion.

JavaScript

                      
                        const el = HSScrollspy.getInstance('[data-hs-scrollspy="#scrollspy"]', true);
                        const collapse = HSCollapse.getInstance('[data-hs-collapse="#navbar-collapse-example"]', true);
                
                        el.element.on('beforeScroll', (instance) => {
                          return new Promise((res) => {
                            if (collapse.element.el.classList.contains('open')) {
                              collapse.element.hide();
                              HSStaticMethods.afterTransition(collapse.element.content, () => res(true));
                            } else {
                              res(true);
                            }
                          });
                        });