Scroll Spy

A utility component that automatically tracks the active section within a scrolling container and highlights the corresponding navigation items.

Installation

npx raya-ui@latest add scroll-spy

File Structure

your-project

components

scroll-spy

ScrollSpy.vue

ScrollSpyNav.vue

ScrollSpyLink.vue

ScrollSpyViewport.vue

ScrollSpySection.vue

API Reference

ScrollSpy (Root)

container

HTMLElement | null

window

Crucial: A reference to the scrolling element that contains your viewport. If omitted, it defaults to tracking the browser's window scroll.

orientation

enum

"vertical"

Defines layout flow context. vertical implies a side-by-side flex-row. horizontal implies stacked flex-col.

offset

number

0

Top margin offset (in pixels) for triggering section activation.

ScrollSpyNav

indicator

boolean

false

Enables the animated moving line indicator underneath or beside the active navigation item.

indicatorPosition

enum

"before"

Position of the animated line. Accepts 'before' (Left/Top) or 'after' (Right/Bottom).

Docs

Introduction

Sidebar layout uses orientation="vertical".

Installation

The indicator tracks section boundaries.

Configuration

Customize offsets and behavior easily.

Settings

Component Layout

Scroll Offset0px

Show Indicator

Indicator Position

source-code.vue

<script setup lang="ts">
import { ref } from 'vue'
import { ScrollSpy, ScrollSpyNav, ScrollSpyLink, ScrollSpyViewport, ScrollSpySection } from '@/components/ui/scroll-spy'

const scrollContainer = ref<HTMLElement | null>(null)
</script>

<template>
  <ScrollSpy
    :container="scrollContainer"
    orientation="vertical"
    class="flex w-full h-[400px] border border-border rounded-lg bg-background overflow-hidden"
  >
    <div class="w-48 border-r border-border p-6 bg-muted/30">
      <h4 class="mb-4 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Docs</h4>
      <ScrollSpyNav indicator>
        <ScrollSpyLink value="s1-intro" class="block py-2 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline">Introduction</ScrollSpyLink>
        <ScrollSpyLink value="s1-install" class="block py-2 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline">Installation</ScrollSpyLink>
        <ScrollSpyLink value="s1-config" class="block py-2 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline">Configuration</ScrollSpyLink>
      </ScrollSpyNav>
    </div>

    <div ref="scrollContainer" class="flex-1 overflow-y-auto p-8 scroll-smooth relative">
      <ScrollSpyViewport class="space-y-16 pb-32">
        <ScrollSpySection value="s1-intro" class="space-y-2">
          <h2 class="text-2xl font-bold text-foreground">Introduction</h2>
          <p class="text-muted-foreground">Sidebar layout active.</p>
          <div class="h-32 bg-muted/50 border border-border border-dashed rounded" />
        </ScrollSpySection>
        <ScrollSpySection value="s1-install" class="space-y-2">
          <h2 class="text-2xl font-bold text-foreground">Installation</h2>
          <p class="text-muted-foreground">Scroll down to see it move.</p>
          <div class="h-32 bg-muted/50 border border-border border-dashed rounded" />
        </ScrollSpySection>
        <ScrollSpySection value="s1-config" class="space-y-2">
          <h2 class="text-2xl font-bold text-foreground">Configuration</h2>
          <p class="text-muted-foreground">Customize offsets and behavior.</p>
          <div class="h-32 bg-muted/50 border border-border border-dashed rounded" />
        </ScrollSpySection>
      </ScrollSpyViewport>
    </div>
  </ScrollSpy>
</template>