Tailwind CSS Scrollspy

Use responsive tabs component with helper examples for horizontal and vertical tabs, tabs ui colors, custom classes & more. Free download, open-source license.

Basic example

Scrollspy is a popular type of intra-page navigation that tracks specific page elements and shows which element the user's screen is currently on. This is useful when you have a lot of content on your site and you want to organize it or send the user directly to the content they are interested in.

Section 1

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore earum natus vel minima quod error maxime, molestias ut. Fuga dignissimos nisi nemo necessitatibus quisquam obcaecati et reiciendis quaerat accusamus numquam.

Section 2

Section 3 Subsection A

Subsection B

HTML
javascript

        
            
      <div class="grid grid-cols-3">
        <div class="col-span-2">
          <div
            data-te-spy="scroll"
            data-te-target="#scrollspy1"
            data-te-offset="200"
            class="relative h-48 overflow-auto">
            <section id="example-1">
              <h3 class="pb-3 pt-5 text-xl font-semibold">Section 1</h3>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
            </section>
            <section id="example-2">
              <h3 class="pb-3 pt-5 text-xl font-semibold">Section 2</h3>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
            </section>
            <section id="example-3">
              <h3 class="pb-3 pt-5 text-xl font-semibold">Section 3</h3>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <section id="example-sub-A">
                <h3 class="pb-3 pt-5 text-xl font-semibold">Subsection A</h3>
                <p>
                  Lorem ipsum dolor sit amet, consectetur adipisicing elit.
                  Labore earum natus vel minima quod error maxime, molestias ut.
                  Fuga dignissimos nisi nemo necessitatibus quisquam obcaecati
                  et reiciendis quaerat accusamus numquam.
                </p>
                <p>
                  Lorem ipsum dolor sit amet, consectetur adipisicing elit.
                  Labore earum natus vel minima quod error maxime, molestias ut.
                  Fuga dignissimos nisi nemo necessitatibus quisquam obcaecati
                  et reiciendis quaerat accusamus numquam.
                </p>
              </section>
              <section id="example-sub-B">
                <h3 class="pb-3 pt-5 text-xl font-semibold">Subsection B</h3>
                <p>
                  Lorem ipsum dolor sit amet, consectetur adipisicing elit.
                  Labore earum natus vel minima quod error maxime, molestias ut.
                  Fuga dignissimos nisi nemo necessitatibus quisquam obcaecati
                  et reiciendis quaerat accusamus numquam.
                </p>
                <p>
                  Lorem ipsum dolor sit amet, consectetur adipisicing elit.
                  Labore earum natus vel minima quod error maxime, molestias ut.
                  Fuga dignissimos nisi nemo necessitatibus quisquam obcaecati
                  et reiciendis quaerat accusamus numquam.
                </p>
              </section>
            </section>
            <section id="example-4">
              <h3 class="pb-3 pt-5 text-xl font-semibold">Section 4</h3>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
              <p>
                Lorem ipsum dolor sit amet, consectetur adipisicing elit. Labore
                earum natus vel minima quod error maxime, molestias ut. Fuga
                dignissimos nisi nemo necessitatibus quisquam obcaecati et
                reiciendis quaerat accusamus numquam.
              </p>
            </section>
          </div>
        </div>

        <div>
          <!-- Scrollspy -->
          <div id="scrollspy1" class="sticky-top pl-3 text-sm">
            <ul data-te-nav-list-ref>
              <li class="py-1">
                <a
                  data-te-nav-link-ref
                  data-te-nav-link-active
                  class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                  href="#example-1"
                  >Section 1</a
                >
              </li>
              <li class="py-1">
                <a
                  data-te-nav-link-ref
                  class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                  href="#example-2"
                  >Section 2</a
                >
              </li>
              <li class="py-1">
                <a
                  data-te-nav-link-ref
                  class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                  href="#example-3"
                  >Section 3</a
                >
                <ul data-te-nav-list-ref class="pl-3">
                  <li class="py-1">
                    <a
                      data-te-nav-link-ref
                      class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                      href="#example-sub-A"
                      >Subsection A</a
                    >
                  </li>
                  <li>
                    <a
                      data-te-nav-link-ref
                      class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                      href="#example-sub-B"
                      >Subsection B</a
                    >
                  </li>
                </ul>
              </li>
              <li class="py-1">
                <a
                  data-te-nav-link-ref
                  class="bg-transparent px-[5px] text-neutral-600 shadow-none dark:text-neutral-200"
                  href="#example-4"
                  >Section 4</a
                >
              </li>
            </ul>
          </div>
          <!-- Scrollspy -->
        </div>
      </div>

        
            
      // Initialization for ES Users
      import {
        ScrollSpy,
        initTE,
      } from "tw-elements";
      
      initTE({ ScrollSpy });

Hey there 👋 we want to make TW elements a community-driven project. It's open source and free, and we would like it to stay that way. If you enjoy it, help the project grow by sharing it with your peers. Every share counts, thank you!

Share via Reddit Share via StumbleUpon

How it works

Scrollspy has a few requirements to function properly:

It must be used on a Bootstrap nav component or list group.
Scrollspy requires position: relative; on the element you’re spying on, usually the <body>.
When spying on elements other than the <body>, be sure to have a height set and overflow-y: scroll; applied.
Anchors (<a>) are required and must point to an element with that id.

When successfully implemented, your nav or list group will update accordingly, moving the .active class from one item to the next based on their associated targets.

Import

Importing components depends on how your application works. If you intend to use the TW elements ES format, you must first import the component and then initialize it with the initTE method. If you are going to use the UMD format, just import the tw-elements package.

javascript
umd

ES UMD

        
            
        import { ScrollSpy, initTE } from "tw-elements";
        initTE({ ScrollSpy });

        
            
        import "tw-elements";

Usage

Via data attributes

To easily add scrollspy behavior to your topbar navigation, add data-te-spy="scroll" to the element you want to spy on (most typically this would be the <body>). Then add the data-te-target attribute with the ID or class of the parent element of any nav component. For ES format, you must first import and call the initTE method.

HTML

        
            
        <body data-te-spy="scroll" data-te-target="#navbar-example">
          ...
          <div id="navbar-example">
            <ul data-te-nav-list-ref role="tablist">
              ...
            </ul>
          </div>
          ...
        </body>

Via JavaScript

You can access an instance from your Javascript code, by using the getInstance static method of the ScrollSpy class - it allows making use of all the public methods listed in the Methods section.

javascript
umd

ES UMD

        
            
        const scrollSpy = new ScrollSpy(document.body, {
          target: '#navbar-example'
        });

        
            
        const scrollSpy = new te.ScrollSpy(document.body, {
          target: '#navbar-example'
        });

Resolvable ID targets required:
Navbar links must have resolvable id targets. For example, a <a href="#home">home</a> must correspond to something in the DOM like <div id="home"></div>.

Non-visible target elements ignored:
Target elements that are not visible will be ignored and their corresponding nav items will never be highlighted.

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-te-, as in data-te-offset="".

Name	Type	Default	Description
`offset`	number	`10`	Pixels to offset from top when calculating position of scroll.
`method`	string	`'auto'`	Finds which section the spied element is in. `auto` will choose the best method to get scroll coordinates. `offset` will use the `Element.getBoundingClientRect(),` method to get scroll coordinates. `position,` will use the `HTMLElement.offsetTop,` and `HTMLElement.offsetLeft,` properties to get scroll coordinates.
`target`	string or DOM element	`true`	Specifies element to apply Scrollspy plugin.

Classes

Custom classes can be passed via data attributes or JavaScript. For data attributes, append the class name to data-te-class, as in data-te-class-active="!text-green".

Name	Default	Description
`active`	!text-[#1266f1] font-semibold border-l-[0.125rem] border-solid border-[#1266f1]	Visual properties for an active Scrollspy element.

Methods

Method	Description	Example
`refresh`	When using scrollspy in conjunction with adding or removing of elements from the DOM, you’ll need to call the refresh method.	`instance.refresh()`
`dispose`	Destroys an element’s tab.	`instance.dispose()`
`getInstance`	Static method which allows you to get the scrollspy instance associated to a DOM element.	`ScrollSpy.getInstance(dataSpyEl)`

javascript
umd

ES UMD

        
            
            const dataSpyList = [].slice.call(document.querySelectorAll('[data-te-spy="scroll"]'));
            dataSpyList.forEach((dataSpyEl) => {
              ScrollSpy.getInstance(dataSpyEl).refresh();
            });

        
            
            const dataSpyList = [].slice.call(document.querySelectorAll('[data-te-spy="scroll"]'));
            dataSpyList.forEach((dataSpyEl) => {
              te.ScrollSpy.getInstance(dataSpyEl).refresh();
            });

Events

Event type	Description
`activate.te.scrollspy`	This event fires on the scroll element whenever a new item becomes activated by the scrollspy.

JavaScript

        
            
              const firstScrollSpyEl = document.querySelector('[data-te-spy="scroll"]');
              firstScrollSpyEl.addEventListener('activate.te.scrollspy', () => {
                // do something...
              });

Scrollspy

Basic example

Section 1

Section 2

Section 3

Subsection A

Subsection B

Section 4

How it works

Related resources

Tutorials:

Extended Docs:

Design System (Figma):

Scrollspy - API

Import

Usage

Via data attributes

Via JavaScript

Options

Classes

Methods

Events