Scroll Spy

Auto-generated "On this page" navigation that tracks every heading currently on screen. Powers the right rail of every UI Library doc page, plus the sticky collapsible bar you see on mobile.

Default

Point it at a container; ScrollSpy finds h2-h6 inside and renders a nav. Every heading that is visible lights up at once, and the rail spans the whole range. Nested headings indent and the rail bends across to meet them.

Dark previewReplay previewOpen in new tab

Introduction

Some intro copy here.

Installation

Steps to install.

Peer dependencies

Nested headings bend the rail across with a rounded elbow.

Usage

How to use the component.

Usage

Import the parts you need from the component's folder.

ts
import { ScrollSpy, ScrollSpyPopover } from "@/components/ui/scroll-spy";

API Reference

ScrollSpy

PropTypeDefaultDescription
contentSelectorstring—CSS selector for the container ScrollSpy walks for headings.
excludeSelectorstring""Skip headings whose closest match this selector (e.g. "[role=tabpanel]").
showLabelbooleantrueShow the label row above the nav.
labelstring"On this page"Text of the label row.
EventDescription
headings-foundEmitted on mount with the resolved headings array.

ScrollSpyPopover

PropTypeDefaultDescription
contentSelectorstring—CSS selector for the container ScrollSpy walks for headings.
excludeSelectorstring""Skip headings whose closest match this selector (e.g. "[role=tabpanel]").
titlestring"On this page"Shown on the trigger while no heading is in view — usually the page title.
EventDescription
headings-foundEmitted on mount with the resolved headings array.

Accessibility

Keyboard shortcuts and ARIA behavior.

  • Renders a plain list of anchors, so headings stay reachable with Tab and are announced as links.
  • The mobile trigger is a collapsible button with aria-expanded; its progress ring exposes role="progressbar".
  • Pair it with a scroll-margin-top on your headings so the sticky header does not cover the target after a jump.
Panel HistoryScroll To Top