Scroll spy

Track the section currently passing through a scrollable reading region.

Preview

Default

123456789101112131415161718192021222324252627282930313233343536373839import { useId, useRef, useState } from "react";
import { ScrollSpy } from "@/components/ui/scroll-spy";
import { TableOfContents } from "@/components/ui/table-of-contents";
var sections = [
  { id: "setup", title: "Set up the workspace", text: "Connect the source and choose the people who can review changes." },
  { id: "review", title: "Review the changes", text: "Compare the proposed edits with the current version before sharing." },
  { id: "publish", title: "Publish the update", text: "When the review is complete, publish the update for your team." },
  { id: "follow-up", title: "Follow up", text: "Check the activity log to see who has read the update." }
];
function ScrollSpyDemo() {
  const prefix = useId();
  const rootRef = useRef(null);
  const items = sections.map((section) => ({ id: `${prefix}-${section.id}`, label: section.title, depth: 2 }));
  const [activeId, setActiveId] = useState(items[0].id);
  return <div data-preview-wide style={{ display: "grid", gridTemplateColumns: "minmax(0, .8fr) minmax(0, 1.2fr)", gap: 16, width: "100%" }}>
    <TableOfContents items={items} activeId={activeId} compact="tree" label="" onNavigate={(id, event) => {
    event?.preventDefault();
    const root = rootRef.current, target = root && [...root.querySelectorAll("[id]")].find((node) => node.id === id);
    if (root && target) root.scrollTo({ top: root.scrollTop + target.getBoundingClientRect().top - root.getBoundingClientRect().top - 20 });
  }} />
    <div ref={rootRef} data-workspace-scroll="native" style={{ height: 280, overflowY: "auto", minWidth: 0, paddingInline: 12, borderInlineStart: "1px solid var(--border)" }}>
      <ScrollSpy rootRef={rootRef} ids={items.map((item) => item.id)} onActiveChange={setActiveId} />
      {sections.map((section, index) => <section key={section.id} id={items[index].id} style={{ minHeight: 210, paddingBlock: 20 }}>
        <h3 style={{ margin: "0 0 12px", fontSize: 16, fontWeight: 400, lineHeight: "24px" }}>{section.title}</h3>
        <p style={{ margin: 0, color: "var(--muted-foreground)", lineHeight: "24px" }}>{section.text}</p>
      </section>)}
    </div>
  </div>;
}


function Example() {
  return <>
<ScrollSpyDemo />
</>;
}
export {
  Example as default
};

Design guidance

Use Scroll spy when a page needs to know which target is active inside a specific scroll container. Compose it with Table of contents when you also need a provided heading-navigation view; keep router state, links, and the selected ID with the caller.

Installation

Install

No source.

Install the shared theme tokens when your surrounding interface uses Ghost styles. Scroll spy itself has no stylesheet.

Download example files — JSX recipes, demo styles and any sample assets. Install the component first.

Basic usage

123456789101112131415161718import * as React from "react";
import { ScrollSpy } from "@/components/ui/scroll-spy";

function ReadingPane() {
  const rootRef = React.useRef<HTMLDivElement>(null);
  const [activeId, setActiveId] = React.useState("setup");

  return (
    <>
      <ScrollSpy rootRef={rootRef} ids={["setup", "review"]} onActiveChange={setActiveId} />
      <p aria-live="polite">Current section: {activeId}</p>
      <div ref={rootRef} style={{ height: 320, overflowY: "auto" }}>
        <section id="setup" style={{ minHeight: 240 }}>Set up the workspace</section>
        <section id="review" style={{ minHeight: 240 }}>Review the changes</section>
      </div>
    </>
  );
}

The ids list limits observation to matching targets. Place ScrollSpy alongside the root in the same React tree; the root ref points to the element that actually scrolls.

Structures

ScrollSpy is a headless leaf. Render it beside the scroll root it observes; target elements with matching IDs remain caller-owned content.

Examples

Independent reading panes

Render one observer per scroll root. Give each target a unique ID and keep each pane's active ID separate. The preview above uses a local reading region and canonical Table of contents; its links scroll that region without changing the page URL.

API reference

ScrollSpy returns no DOM. It listens to the supplied root's scroll, resize, content mutation, and font-loading changes, then reports the active included target. Target order follows the DOM. offset is measured from the root's top edge. enabled={false} pauses observation.

Prop	Type	Default	Description
`rootRef`	`React.RefObject<HTMLElement \| null>`		Required ref to the scrollable element whose content contains the targets.
`ids`	`readonly string[]`		IDs of targets to observe. The active target follows matching DOM order.
`onActiveChange`	`(id: string) => void`		Receives the active target ID when an included, visible target is found.
`offset`	`number`	`20`	Pixel offset below the root's top edge used to choose the active target.
`enabled`	`boolean`	`true`	When false, observation is not attached.
`exclude`	`string`		Optional CSS selector for subtrees whose targets should be ignored, such as embedded previews.

Set up the workspace

Connect the source and choose the people who can review changes.

Review the changes

Compare the proposed edits with the current version before sharing.

Publish the update

When the review is complete, publish the update for your team.

Follow up

Check the activity log to see who has read the update.