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.
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 | Specifies the ID selector of the scrollable element that the scrollspy should monitor. | ||
data-kt-scrollspy-offset | 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 | Enables smooth scrolling animation when navigating between sections in the scrollspy, providing a more fluid user experience. |
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. |
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. |
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 |
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 |
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 |
off(eventName, eventId) | Removes an event listener for the |
dispose() | Removes the KTScrollspy instance from an element, including any associated data stored on the DOM element. |
const scrollspyItemEl = document.querySelector('#my_scrollspy_item');
const scrollspyEl = document.querySelector('#my_scrollspy');
const scrollspy = KTScrollspy.getInstance(scrollspyEl);
scrollspy.scrollTo(scrollspyItemEl);
scrollspy.update();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 |
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 |
getOrCreateInstance(element) | Returns the existing |
// Initialize all scrollspys
KTScrollspy.init()
// Initialzie pending scrollspys
KTScrollspy.createInstances();
// Get scrollspy object
const scrollspyEl = document.querySelector('#my_scrollspy');
const scrollspy = KTScrollspy.getInstance(scrollspyEl);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. |
const scrollspyEl = document.querySelector('#my_scrollspy');
const scrollspy = KTScrollspy.getInstance(scrollspyEl);
scrollspy.on('activate', (element) => {
console.log('anchor activate event');
});