OnThisPage

The OnThisPage component renders a floating navigation panel listing headings from the current document, dynamically highlighting active sections as the user scrolls.

It uses an IntersectionObserver under the hood (via AnchorProvider) and a small linear-interpolation trick to glide a highlight indicator between the active anchors. The behavior is automatic for the most common cases — usually you pass headings and you're done.

For 95% of custom layouts, <OnThisPage.Tree headings={headings} /> is enough. Reach for the lower-level pieces only when you want full control over the positioning math.

Import

import { OnThisPage } from 'boltdocs/primitives'

Composable Scroll-Spy Example

Using the primitive OnThisPage modules, you can assemble a fully custom table of contents. The example below shows how to compose a layout with custom titles, list containers, active indicator lines, and smooth scroll behaviors:

// docs/components/CustomTOC.tsx
import React, { useRef } from 'react'
import { OnThisPage, AnchorProvider, ScrollProvider } from 'boltdocs/primitives'
import { useRoutes } from 'boltdocs/client'

export default function CustomTOC() {
  const { currentRoute } = useRoutes()
  const scrollContainerRef = useRef<HTMLDivElement>(null)

  const headings = currentRoute?.headings || []
  if (headings.length === 0) return null

  // Convert headings database to standard TOC structure
  const tocItems = headings.map((h) => ({
    title: h.text,
    url: `#${h.id}`,
    depth: h.level,
  }))

  return (
    <OnThisPage className="border-l border-subtle pl-6 py-6 bg-transparent">
      {/* 1. Static Title Header */}
      <OnThisPage.Header className="text-xs font-bold uppercase tracking-wider text-zinc-400 mb-4">
        Table of Contents
      </OnThisPage.Header>

      {/* 2. Scroll-Spy Context Wrapper Providers */}
      <AnchorProvider toc={tocItems} single={false}>
        <ScrollProvider containerRef={scrollContainerRef}>
          
          {/* 3. Masked Scrollable Viewport */}
          <OnThisPage.Content ref={scrollContainerRef} className="max-h-[80vh]">
            <OnThisPage.List className="relative border-l border-zinc-200 dark:border-zinc-800">
              
              {/* 4. Active Section Accent Indicator */}
              <OnThisPage.Indicator className="bg-primary-500" />
              
              {/* 5. Hierarchical Link Mapping */}
              {headings.map((h) => (
                <OnThisPage.Item key={h.id} level={h.level}>
                  <OnThisPage.Link href={`#${h.id}`}>
                    {h.text}
                  </OnThisPage.Link>
                </OnThisPage.Item>
              ))}

            </OnThisPage.List>
          </OnThisPage.Content>

        </ScrollProvider>
      </AnchorProvider>
    </OnThisPage>
  )
}

[!TIP] If you don't want to map items manually, you can use the high-level primitive wrapper <OnThisPage.Tree headings={headings} /> to automatically mount the observers, indicators, and list links inside an active layout.

When to use Tree vs the lower-level provider

Tree is what you want unless you have a strong reason. The internals are eight lines of code total — reach for them only when you're building a sidebar that isn't a list of headings.

Pitfalls

• headings must include id. The rehype-slug pipeline assigns IDs to every heading at build time, but if you're rendering on the fly (editor previews, an inline CMS injection), make sure each heading has an anchor ID matching OnThisPage.Link's href.
• ScrollProvider needs a stable ref. Pass a containerRef={useRef(null)} — don't create a new ref every render, or the auto-scroll will jump on every update.
• single=true switches the scroll-spy to "first matching heading wins" mode. Useful when you have lots of h3 underneath one h1 and want the parent — not the child — to highlight.

Composable Sub-Components

The OnThisPage primitive provides the following sub-components for structure customization:

Component Props

ComponentBaseProps (Common)

OnThisPage.Content Props

OnThisPage.Item Props

OnThisPage.Link Props

OnThisPage.Items Props

OnThisPage.Tree Props

Under-the-Hood Contexts

If you are constructing a fully bespoke tracker, you can import and wrap your layout in the custom React context providers exposed via OnThisPage:

AnchorProviderProps

ScrollProviderProps