ui/hooks/active-heading

Active Heading

hookscrolltocheading

Configurable active heading detection for table of contents. Tracks which heading is currently active based on scroll position, with top-line or viewport-center activation modes and a programmatic scrollTo helper.

tsx

1 const { activeId, scrollTo } = useActiveHeading({2   ids: ["intro", "features", "api"],3   activation: "top-line",4   topOffset: 96,5 });

Installation

$pnpm exec dgadd add ui/active-heading

[Installs to]src/hooks/use-active-heading.ts[Item]ui/active-heading

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Parameters

Name	Type	Default	Description
idsrequired	string[]	—	Ordered list of heading element IDs to observe. Elements are resolved via document.getElementById.
containerId	string	—	ID of a scrollable container element. When omitted, the window is used as the scroll target.
activation	"top-line" \| "viewport-center" \| number	"top-line"	How headings activate. "top-line" activates when crossing topOffset from container top. "viewport-center" activates at the vertical center. A number (0–1) sets a custom viewport fraction.
topOffset	number	96	Pixel offset from the container top used by the "top-line" activation mode.
scrollOffset	number	topOffset	Pixel offset applied when scrollTo programmatically scrolls to a heading. Defaults to topOffset.
bottomMargin	number	0	Fraction of viewport height used as bottom margin for bottomLock detection.
threshold	number	0	Fraction (0–1) of the heading element's height that must cross the activation line before it becomes active. 0 = top edge, 1 = bottom edge.
bottomLock	boolean	true	When true, the last heading is always activated when the user scrolls to the bottom of the container. Ignored while the container has nothing to scroll.
enabled	boolean	true	Set to false to disable scroll observation. When disabled, activeId is set to null.
settleDelay	number	150	Milliseconds to wait after a programmatic scrollTo before resuming scroll tracking. Prevents flickering during smooth scroll animation.
observe	boolean	true	Watch for DOM changes via MutationObserver. Disable for static content.

Returns

{ activeId: string | null; scrollTo: (id: string) => void }Object with the currently active heading ID and a function to programmatically scroll to a heading.

Name	Type	Default	Description
activeIdrequired	string \| null	—	ID of the currently active heading, or null when disabled or no headings are found.
scrollTorequired	(id: string) => void	—	Scrolls to the heading with the given ID. Immediately sets activeId to prevent flickering during the scroll animation.

Examples

Basic Table of Contents

Preview

tsx

1 "use client";2 3 import { useId } from "react";4 import { useActiveHeading } from "@/hooks/use-active-heading";5 6 const sections = [7   { id: "overview", title: "Overview" },8   { id: "installation", title: "Installation" },9   { id: "usage", title: "Usage" },10   { id: "api", title: "API Reference" },11 ];12 13 export default function ActiveHeadingBasic() {14   // useActiveHeading resolves headings with document.getElementById, which15   // returns the first match in the whole page. Bare slugs like "installation"16   // would resolve to the host page's own anchor instead of this demo's heading,17   // so every id here is namespaced per instance.18   const uid = useId();19   const headingId = (id: string) => `${uid}-${id}`;20   const ids = sections.map((s) => headingId(s.id));21   const containerId = `${uid}-pane`;22   const { activeId, scrollTo } = useActiveHeading({ ids, containerId, topOffset: 24 });23 24   return (25     <div className="flex gap-8">26       <nav className="flex w-48 shrink-0 flex-col gap-1 self-start">27         {sections.map((section) => (28           <button29             key={section.id}30             type="button"31             className={`px-3 py-1 text-left text-sm transition-colors ${32               activeId === headingId(section.id)33                 ? "border-l-2 border-success-border text-foreground"34                 : "border-l-2 border-transparent text-muted-foreground hover:text-foreground"35             }`}36             onClick={() => scrollTo(headingId(section.id))}37           >38             {section.title}39           </button>40         ))}41       </nav>42 43       <div44         id={containerId}45         className="h-64 min-w-0 flex-1 overflow-y-auto border border-border p-4"46       >47         <div className="flex flex-col gap-16 pb-40">48           {sections.map((section) => (49             <section key={section.id}>50               <h2 id={headingId(section.id)} className="mb-4 text-lg font-medium text-foreground">51                 {section.title}52               </h2>53               <p className="text-sm text-muted-foreground">54                 Content for the {section.title.toLowerCase()} section. Scroll to see the active55                 heading update in the sidebar navigation.56               </p>57             </section>58           ))}59         </div>60       </div>61     </div>62   );63 }64

Activation Modes

Preview

tsx

1 "use client";2 3 import { useId, useState } from "react";4 import { type ActiveHeadingActivation, useActiveHeading } from "@/hooks/use-active-heading";5 6 const sections = [7   { id: "intro", title: "Introduction" },8   { id: "setup", title: "Setup" },9   { id: "config", title: "Configuration" },10   { id: "deploy", title: "Deployment" },11 ];12 13 export default function ActiveHeadingModes() {14   const [mode, setMode] = useState<ActiveHeadingActivation>("top-line");15   const uid = useId();16   const headingId = (id: string) => `${uid}-${id}`;17   const ids = sections.map((s) => headingId(s.id));18   const containerId = `${uid}-pane`;19 20   const { activeId, scrollTo } = useActiveHeading({21     ids,22     containerId,23     topOffset: 24,24     activation: mode,25   });26 27   return (28     <div className="flex flex-col gap-6">29       <div className="flex items-center gap-3">30         <span className="text-xs text-muted-foreground">Activation mode:</span>31         {(["top-line", "viewport-center"] as const).map((m) => (32           <button33             key={m}34             type="button"35             className={`border px-2 py-1 text-xs transition-colors ${36               mode === m37                 ? "border-success-border bg-success-subtle text-success-text"38                 : "border-border text-muted-foreground hover:text-foreground"39             }`}40             onClick={() => setMode(m)}41           >42             {m}43           </button>44         ))}45       </div>46 47       <div className="flex gap-8">48         <nav className="flex w-48 shrink-0 flex-col gap-1 self-start">49           {sections.map((section) => (50             <button51               key={section.id}52               type="button"53               className={`px-3 py-1 text-left text-sm transition-colors ${54                 activeId === headingId(section.id)55                   ? "border-l-2 border-success-border text-foreground"56                   : "border-l-2 border-transparent text-muted-foreground hover:text-foreground"57               }`}58               onClick={() => scrollTo(headingId(section.id))}59             >60               {section.title}61             </button>62           ))}63         </nav>64 65         <div66           id={containerId}67           className="h-64 min-w-0 flex-1 overflow-y-auto border border-border p-4"68         >69           <div className="flex flex-col gap-16 pb-40">70             {sections.map((section) => (71               <section key={section.id}>72                 <h2 id={headingId(section.id)} className="mb-4 text-lg font-medium text-foreground">73                   {section.title}74                 </h2>75                 <p className="text-sm text-muted-foreground">76                   Content for {section.title.toLowerCase()}. Switch between top-line and77                   viewport-center modes to see how the active heading detection changes.78                 </p>79               </section>80             ))}81           </div>82         </div>83       </div>84     </div>85   );86 }87

Notes

Disabled state

When enabled is false, activeId is null from the first render, including server rendering. Enabling observation later starts from the first available heading; disabling it again clears activeId.

Activation Modes

Use "top-line" (default) for fixed-header layouts where headings activate near the top. Use "viewport-center" for centered reading experiences. Pass a number (0–1) for a custom viewport fraction.

Scroll Settling

When scrollTo is called, scroll-listener updates are suppressed until the animation settles (150ms after the last scroll event). This prevents the active heading from flickering through intermediate headings during programmatic scrolls.

Bottom Lock

When bottomLock is true (default), the last heading is always highlighted when scrolled to the bottom — without it, a last section shorter than the viewport never becomes active. It never fires on a container that cannot scroll, so a static pane keeps its first heading active.

Source

Highlighted source loads after this disclosure opens. Browse the source repository.

Active Heading

Installation

Parameters

Returns

Examples

Basic Table of Contents

Activation Modes

Notes

Disabled state

Activation Modes

Scroll Settling

Bottom Lock

Source

View hook source