Live Demo — Examples: With Template Refs - Nuxt Content Nested TOC

The Intersection Observer is a great API. But it may not be the one-size-fits-all solution to highlight TOC/sidebar links as it makes hard if not impossible to:

• Highlight any clicked link even if it will never intersect
• Always highlight first/last link once reached the top/bottom of the page
• Get consistent results regardless of scroll speed
• Immediately highlight links on click/hash navigation if smooth scrolling is enabled
• Avoid unnatural highlighting with custom easings or smooth scrolling

Vue Use Active Scroll implements a custom scroll observer which automatically adapts to any type of scroll behavior and trigger and always returns the "correct" active target.

If you and your users don't care about the above gotchas, then no, please don't use this package because it adds a couple of unnecessary KBs to your bundle.

You can achieve an acceptable result with the Intersection Observer API as well. Alternatively, you can build an accurate scroll observer that acts similar to this package by looking at the SvelteKit Website's TOC source code in 100-150 lines of code.

• Precise and stable at any speed
• CSS scroll-behavior or JS scroll agnostic
• Adaptive behavior on mount, hash and prev/next navigation, scroll, click, cancel.
• Customizable offsets for each scroll direction
• Customizable offsets for first and last target
• Customizable behavior on top/bottom reached
• Supports custom scrolling containers
• Supports both plain ids and template refs

• Scroll to targets
• Mutate the DOM and inject styles
• Require specific scroll behavior
• Require or configure hash navigation

pnpm add vue-use-active-scroll

# yarn add vue-use-active-scroll
# npm i vue-use-active-scroll
# bun add vue-use-active-scroll

As explained in the above warning, Vue Router needs to be configured in order to scroll to anchors.

const router = createRouter({
   // Add this method 👇
   scrollBehavior(to) {
      if (to.hash) {
         return {
            el: to.hash,
         }
      }
   },
})

The above is the bare minimum required to get started and it will make sure that when clicking on a RouterLink that has an anchor in its href the window will scroll to that element.

Later on, see the Vue Router Section for additional configurations (container scroll, fixed header offsets, etc.).

Somewhere in your global CSS, add the following rule to enable smooth scrolling:

html {
   scroll-behavior: smooth; /* or 'auto' if you prefer instant scrolling */
}

Later on, see the Scroll Behavior Section for additional scroll configurations or on how to use JS-based scrolling.

This package exports a single composable named useActiveScroll which accepts an array of targets to observe with the following signature:

type Targets = Ref<HTMLElement[]> | Ref<string[]>

You can provide targets using template refs, HTML elements or DOM IDs.

The composable returns an object with properties to react to the active link and a method to include in your click handler: it doesn't scroll to targets and it's required if scroll is also originated by clicks.

const { setActive, activeId, activeIndex /*, ... */ } = useActiveScroll(targets)

If you are in charge of rendering the content nodes (e.g. using v-for), simply pass the template refs to useActiveScroll:

<script setup>
import { ref, reactive, computed } from 'vue'
import { useActiveScroll } from 'vue-use-active-scroll'

// This may come from a CMS, markdown file, etc.
const content = reactive([
   { id: 'introduction', title: 'Introduction', content: '...' },
   { id: 'quick-start', title: 'Quick Start', content: '...' }, // ...
])

const links = computed(() =>
   content.map(({ id, title }) => ({ href: id, label: title }))
)

const targets = ref([])

const { setActive, activeId } = useActiveScroll(targets)
</script>

<template>
   <!-- Content -->
   <section v-for="section in content">
      <h2 :id="section.id" ref="targets">{{ section.title }}</h2>
      <p>{{ section.content }}</p>
   </section>

   <!-- Sidebar -->
   <nav>
      <RouterLink
         v-for="link in links"
         @click="setActive(link.href)"
         :key="link.href"
         :to="{ hash: `#${link.href}` }"
         :ariaCurrentValue="link.href === activeId"
         :class="{ 'sidebar-link--active': link.href === activeId }"
      >
         {{ link.label }}
      </RouterLink>
   </nav>
</template>

Nuxt Content is great because not only automatically applies IDs to your headings, but also provides a useContent composable to query a reactive TOC in any component.

Since the object is reactive and kept in sync with the content, you can directly pass the IDs to useActiveScroll:

<script setup lang="ts">
import { useActiveScroll } from 'vue-use-active-scroll'

const { toc } = useContent()

// ['introduction', 'introduction-sub-1', 'quick-start']
const ids = computed(() =>
   toc.value.links.flatMap(({ id, children = [] }) => [
      id,
      ...children.map(({ id }) => id), // Flatten any nested link
   ])
)

const { setActive, activeId } = useActiveScroll(ids)
</script>

<template>
   <ContentDoc />

   <nav>
      <NuxtLink
         v-for="link in toc.links"
         @click="setActive(link.id)"
         :key="link.id"
         :to="`#${link.id}`"
         :ariaCurrentValue="link.href === activeId"
         :class="{ 'sidebar-link--active': activeId === link.id }"
      >
         {{ link.text }}
      </NuxtLink>
   </nav>
</template>

<script setup>
import { ref, watch } from 'vue'
import { useActiveScroll } from 'vue-use-active-scroll'

const container = ref(null)
const targets = ref([])
const links = ref([])

function resetTargets() {
   targets.value = []
   links.value = []
}

function setTargets(container) {
   const _targets = []
   const _links = []

   container.querySelectorAll('h2').forEach((h2) => {
      /**
       * Add IDs to headings if your CMS doesn't
       */
      h2.id = h2.textContent.toLowerCase().replace(/\s /g, '-')

      _targets.push(h2)
      _links.push({ href: h2.id, label: h2.textContent })
   })

   links.value = _links
   targets.value = _targets
}

watch(container, (c) => (c ? setTargets(c) : resetTargets()), {
   immediate: true,
   flush: 'post',
})

const { setActive, activeId } = useActiveScroll(targets)
</script>

<template>
   <!-- Content -->
   <article v-html="data.html" ref="container" />

   <!-- Sidebar -->
   <nav>
      <RouterLink
         v-for="link in links"
         @click="setActive(link.href)"
         :key="link.href"
         :to="{ hash: `#${link.href}` }"
         :ariaCurrentValue="link.href === activeId"
         :class="{ 'sidebar-link--active': link.href === activeId }"
      >
         {{ link.label }}
      </RouterLink>
   </nav>
</template>

useActiveScroll accepts an optional configuration object as last argument:

const { activeId, setActive } = useActiveScroll(targets, {
   // ...
})

You're free to choose between CSS scroll-behavior (smooth or auto), scrollIntoView or even a JS library like animated-scroll-to.

• Content scrolled by the window:

html {
   scroll-behavior: smooth; /* or 'auto' */
}

• Content scrolled by a container:

.scrolling-container {
   scroll-behavior: smooth;
}

<script setup>
import { useActiveScroll } from 'vue-use-active-scroll'
import animateScrollTo from 'animated-scroll-to'

// ...

const { setActive, activeId } = useActiveScroll(targets)

function scrollTo(event, id) {
   // ...
   setActive(id) // 👈🏻 Include setActive
   animateScrollTo(document.getElementById(id), {
      easing: easeOutBack,
      minDuration: 300,
      maxDuration: 600,
   })
}
</script>

<template>
   <button
      v-for="link in links"
      @click="scrollTo($event, link.href)"
      :class="{ 'sidebar-btn--active': link.href === activeId }"
   >
      {{ link.label }}
   </button>
</template>

To scroll to a target inside of a container, use scrollIntoView method and pass the target's ID.

const router = createRouter({
   // ...
   scrollBehavior(to) {
      if (to.hash) {
         // Content scrolled by a container
         if (to.name === 'PageNameUsingContainer') {
            return document.querySelector(to.hash).scrollIntoView()
         }

         // Content scrolled by the window
         return {
            el: to.hash,
            // top: 100 // Eventual fixed header (overlayHeight)
         }
      }
   },
})

💡 There's no need to define smooth or auto here. Adding the CSS rule is enough.

💡 There's no need need to set overlayHeight if using scrollIntoView as the method is aware of target's scroll-margin-top property.

To navigate back to the top of the same page (e.g. clicking on browser's back button from hash to the page root), use the scroll method for containers and return top for content scrolled by the window.

const router = createRouter({
   // ...
   scrollBehavior(to, from) {
      if (from.hash && !to.hash) {
         // Content scrolled by a container
         if (
            to.name === 'PageNameUsingContainer' &&
            from.name === 'PageNameUsingContainer'
         ) {
            return document.getElementById('scrolling_container').scroll(0, 0)
         }

         // Content scrolled by the window
         return { top: 0 }
      }
   },
})

You may noticed that when clicking on a link, a new entry is added to the history. When navigating back, the page will scroll to the previous target and so on.

To disable this, choose to replace instead of pushing the hash:

<template>
   <!-- ... -->
   <RouterLink
      @click="setActive(link.href)"
      :to="{ hash: `#${item.href}`, replace: true /* 👈🏻 */ }"
      :class="{
         active: link.href === activeId,
      }"
   />
   <!-- ... -->
</template>

You might noticed that if you have a fixed header and defined an overlayHeight, once clicked to scroll, the target may be underneath the header. In this case, add scroll-margin-top to your targets:

useActiveScroll(targets, { overlayHeight: 100 })

.target {
   scroll-margin-top: 100px;
}

Since useActiveScroll won't kick in until the page is hydrated, you probably want to render the first link as active on the server.

<script setup>
const isSSR = ref(true)

onMounted(() => (isSSR.value = false))
</script>

<template>
   <nav>
      <RouterLink
         v-for="(link, idx) in links"
         :class="{
            'sidebar-link--active':
               (isSSR && idx === 0) || link.href === activeId,
         }"
      >
         {{ link.label }}
      </RouterLink>
   </nav>
</template>

MIT