Tailwind Scrollspy component enhances user navigation by highlighting active links as users scroll through different sections of a webpage. This feature is particularly useful for single-page applications and long-form content, providing a clear visual indicator of the user's current position on the page.
Examples
Basic Usage
Implement a Tailwind Scrollspy within a scrollable container to automatically highlight navigation links as you scroll through various sections.
Implement a Tailwind Scrollspy within a scrollable container to automatically highlight nested navigation links as you scroll through various sections.
These data attributes allow you to set options for the scrollspy component during auto initialization.
Option
Type
Default
Description
data-kt-scrollspy-target
string
"body"
Specifies the ID selector of the scrollable element that the scrollspy should monitor.
data-kt-scrollspy-offset
number
0
Defines the number of pixels to offset when activating each section of the scrollspy, allowing for fine-tuned control over the activation point.
data-kt-scrollspy-smooth
boolean
true
Enables smooth scrolling animation when navigating between sections in the scrollspy, providing a more fluid user experience.
Selectors
This table details the custom classes and data attributes used by the scrollspy component.
Name
Description
Data Attributes
data-kt-scrollspy="true"
A selector used to auto-initialize the scrollspy object on page load.
data-kt-scrollspy-anchor="true"
Indicates a scrollspy navigation item element where the href attribute value provides the linked content ID selector, facilitating scroll tracking and navigation highlighting.
data-kt-scrollspy-group="true"
Specifies a group element that contains nested child anchors, organizing them into a hierarchy for the scrollspy navigation.
Classes
active
Sets a specific scrollspy item to be open initially when used togather with data-kt-scrollspy-item selector.
Tailwind Modifiers
Custom modifiers to control the scrollspy’s style and behavior with Tailwind classes.
Name
Description
kt-scrollspy-active:*
A custom Tailwind variant the scrollspy item becomes active.
Methods
Use KTScrollspy component's API methods to programmatically control its behavior.
Method
Description
new KTScrollspy(element, options)
Creates an object instance of KTScrollspy class for the given DOM element and configuration options .
scrollTo(anchorElement)
Programmatically scrolls to the specified anchor element, aligning it within the viewport according to the scrollspy's configuration. This method facilitates direct navigation to scrollspy sections without user-initiated scrolling.
update()
Refreshes and recalculates the positions and states of all scrollspy elements, ensuring that the scrollspy functionality accurately reflects the current layout and scroll position of the page.
updateAnchor(anchorElement)
Updates the specific anchor element within the scrollspy system, recalculating its position and state based on the current scroll position. This is useful for dynamically added content or changes in the layout that affect only certain anchors.
isActive(anchorElement)
Returns a boolean value indicating whether the specified anchor element is currently active within the scrollspy system, allowing for custom logic or styles to be applied based on the active state of the element.
getOption(name)
Retrieves the value of a configuration option by name parameter from a KTScrollspy instance.
getElement()
Retrieves the DOM element linked to a specific KTScrollspy instance.
on(eventName, handler)
Allows attaching event listeners to the KTScrollspy custom events using the eventName and eventId string parameters. These events enable programmatic interaction based on user actions or internal state changes of KTScrollspy. The function returns string as a unique identifier for the registered listener, allowing you to remove it later if needed.
off(eventName, eventId)
Removes an event listener for the eventName and eventId parameters attached with the on method.
dispose()
Removes the KTScrollspy instance from an element, including any associated data stored on the DOM element.
Manage and interact with KTScrollspy instances using these static methods of KTScrollspy JavaScript class.
Method
Description
init()
Automatically initializes KTScrollspy object for all elements with the data-kt-scrollspy="true" attribute on page load.
createInstances()
Allows to create KTScrollspy instances for all elements that have been dynamically added to the DOM but haven't been activated yet.
getInstance(element)
Returns the KTScrollspy object associated with the given DOM element element .
getOrCreateInstance(element)
Returns the existing KTScrollspy object for the provided DOM element element , or creates a new instance if none exists, then returns the same.
// Initialize all scrollspysKTScrollspy.init();// Initialzie pending scrollspysKTScrollspy.createInstances();// Get scrollspy objectconst scrollspyEl = document.querySelector('#my_scrollspy');const scrollspy = KTScrollspy.getInstance(scrollspyEl);
Events
KTScrollspy custom events allows you to register callback functions(event listeners) that will be invoked automatically whenever specific custom events are triggered within the component.
Event
Description
activate
This event fires on the scroll element whenever an anchor is activated by the scrollspy.
