TOC
Table of contents primitives for rendering section links with depth indentation and active states.
Installation
dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.
UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.
Usage
Examples
Nested Depth (h2/h3/h4) + Active State
Active Heading Tracking (scroll container)
API Reference
Toc
TocList
TocItem
Accessibility
Notes
Current-location mark
The library spells "you are here" one way: a 2px left rail in --primary (registry/lib/marker-rail.ts). Full-bleed inversion is reserved for the TRANSIENT keyboard highlight; a row that is both the current location and the highlight keeps the inversion and flips its rail to --primary-foreground so the mark survives. The rail is reserved transparently in the resting state and pulled back by its own width, so a row's label never shifts horizontally when it becomes current — that anti-shift geometry is the contract, and it is why the rail costs 0px of label width at 375/390 where a full-bleed fill reads as a solid slab. Toc is the reference implementation of that rail.
Headless-friendly
Toc/TocList/TocItem are presentation primitives. Pair them with your own heading tracking logic (e.g. IntersectionObserver or Fumadocs AnchorProvider).
Depth
Use the depth prop on TocItem to indent nested headings consistently (h2/h3/h4).
Page Layout
Toc renders the nav landmark and its heading only. Width, sticky offset, and page padding are call-site decisions — pass them via className (the docs site uses w-56 shrink-0 py-8 pr-4).
Active Marker
An active TocItem bolds its label and paints a 2px rail segment over the TocList hairline, matching the sidebar bar/terminal marker language.
Source
Install via CLI: pnpm exec dgadd add ui/toc.
Highlighted source loads after this disclosure opens. Browse the source repository.