OnThisPage

Un panel de navegación de tabla de contenidos que muestra y resalta los encabezados de la página actual.

El componente OnThisPage renderiza un panel de navegación flotante que lista los encabezados del documento actual, resaltando dinámicamente las secciones activas mientras el usuario hace scroll.

La primitiva OnThisPage es neutra de estilo: aporta estructura, el seguimiento de scroll con IntersectionObserver, la matemática del indicador de pista activa y atributos de estado data-*. Todo lo visual pertenece a tu tema — colores, bordes, sangrías, el resaltado activo. Estiliza los estados con variantes de Tailwind v4 (data-active:text-primary-500) o CSS puro ([data-active] { ... }).

Ejemplo de Rastreador de Scroll ComponibleLink

Usando los módulos de la primitiva OnThisPage, puedes ensamblar una tabla de contenidos totalmente personalizada. El siguiente ejemplo muestra cómo componer un layout con títulos personalizados, contenedores de lista, líneas indicadoras de actividad y comportamientos de scroll suaves:

tsx
// docs/components/CustomTOC.tsx
import { 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

  // Convierte la base de datos de encabezados a una estructura TOC estándar
  const tocItems = headings.map((h) => ({
    title: h.text,
    url: `#${h.id}`,
    depth: h.level,
  }))

  return (
    <OnThisPage className="hidden xl:block w-toc py-4 pl-6 pr-4">
      {/* 1. Encabezado de título estático */}
      <OnThisPage.Header className="text-xs font-bold uppercase tracking-wider text-muted mb-4">
        Tabla de Contenidos
      </OnThisPage.Header>

      {/* 2. Proveedores de contexto de seguimiento de scroll */}
      <AnchorProvider toc={tocItems} single={false}>
        <ScrollProvider containerRef={scrollContainerRef}>
          {/* 3. Viewport con scroll */}
          <OnThisPage.Content
            ref={scrollContainerRef}
            className="max-h-[80vh] pb-12"
            fadeClassName="bg-linear-to-b from-transparent to-main"
          >
            {/* 4. Lista + indicador de pista activa */}
            <OnThisPage.List className="relative border-l border-subtle space-y-0.5 text-sm">
              <OnThisPage.Indicator className="-left-px w-0.5 rounded-full bg-primary-500" />
              {headings.map((h) => (
                <OnThisPage.Item
                  key={h.id}
                  level={h.level}
                  className="data-[level=3]:pl-3"
                >
                  <OnThisPage.Link
                    href={`#${h.id}`}
                    className="block py-0.5 pl-4 text-[13px] transition-colors text-muted hover:text-body data-active:text-primary-500"
                  >
                    {h.text}
                  </OnThisPage.Link>
                </OnThisPage.Item>
              ))}
            </OnThisPage.List>
          </OnThisPage.Content>
        </ScrollProvider>
      </AnchorProvider>
    </OnThisPage>
  )
}

[!TIP] Si no quieres mapear los elementos manualmente, puedes usar el envoltorio de alto nivel <OnThisPage.Tree headings={headings} /> para montar automáticamente los observadores, indicadores y enlaces dentro de un layout activo. Tree acepta los slots className (lista), itemClassName, linkClassName, indicatorClassName, contentClassName y fadeClassName.


Atributos de Estado (data-*)Link

Las primitivas de OnThisPage exponen su estado a través de atributos data-*, presentes solo cuando son verdaderos. Decide tus propios colores y tratamientos desde CSS.

AtributoSe Emite EnPresente Cuando
data-activeenlace OnThisPage.LinkEl encabezado es la sección activa actual
data-levelOnThisPage.ItemProfundidad de jerarquía del encabezado (p. ej. 2, 3) — usa data-[level=3]:pl-3 para sangría
data-otp-rootOnThisPage.RootSiempre
data-otp-contentOnThisPage.ContentSiempre
data-otp-listOnThisPage.ListSiempre
data-otp-fadeelemento de fundido inferior del ContentSiempre
data-otp-indicatorOnThisPage.IndicatorSiempre
aria-currentenlace OnThisPage.Link"true" cuando está activo
tsx
<OnThisPage.Tree
  headings={headings}
  className="space-y-0.5 text-sm border-l border-subtle"
  itemClassName="data-[level=3]:pl-3"
  linkClassName="block py-0.5 pl-4 text-[13px] transition-colors text-muted hover:text-body data-active:text-primary-500"
  indicatorClassName="-left-px w-0.5 rounded-full bg-primary-500"
  fadeClassName="bg-linear-to-b from-transparent to-main"
/>

Subcomponentes ComponiblesLink

La primitiva OnThisPage proporciona los siguientes subcomponentes para personalizar la estructura:

ComponenteEtiqueta HTMLDescripciónProps
OnThisPage.Root / OnThisPage<nav>Envoltorio exterior que representa el área de navegación fija de la columna derecha.ComponentBaseProps
OnThisPage.Header<div>Bloque de título tipográfico para etiquetar la tabla de contenidos.ComponentBaseProps
OnThisPage.Content<div>Contenedor viewport con scroll (el límite del scroll-spy).OnThisPage.Content Props
OnThisPage.List<ul>Envoltorio de lista que envuelve los anchors.ComponentBaseProps
OnThisPage.Item<li>Envoltorio de celda individual. Expone data-level.OnThisPage.Item Props
OnThisPage.Link<a>Enlace anchor que intercepta clicks para hacer scroll suave al viewport.OnThisPage.Link Props
OnThisPage.Indicator<div>Indicador de pista vertical flotante que muestra el anchor activo.ComponentBaseProps
OnThisPage.ItemsVariesHelper de bucle que renderiza enlaces e indicadores automáticamente.OnThisPage.Items Props
OnThisPage.Tree<nav>Componente automatizado de alto nivel que agrupa todos los proveedores, observadores y elementos.OnThisPage.Tree Props

Props de los ComponentesLink

ComponentBaseProps (Común)Link

PropiedadTipoDefaultDescripción
childrenReactNodeundefinedElementos hijos.
classNamestringundefinedClases CSS personalizadas.
styleCSSPropertiesundefinedEstilos en línea.

Props de OnThisPage.ContentLink

PropiedadTipoDefaultDescripción
refRef<HTMLDivElement>undefinedRef del elemento contenedor.
scrollRefRefObject<HTMLElement>undefinedRef del contenedor principal del viewport para seguimiento de scroll.
fadeClassNamestringundefinedClases del elemento de fundido inferior (propiedad del tema).

Props de OnThisPage.ItemLink

PropiedadTipoDefaultDescripción
levelnumberundefinedProfundidad de jerarquía del encabezado — se expone vía data-level.
PropiedadTipoDefaultDescripción
hrefstringRequeridoId de anchor de destino (p. ej., '#installation').
activebooleanfalseOverride del resaltado activo — se expone vía data-active + aria-current.
onClick(event) => voidundefinedCallback personalizado de intercepción de click.

Props de OnThisPage.ItemsLink

PropiedadTipoDefaultDescripción
headingsTOCItemType[]RequeridoDatos de encabezados de página para mapear.
classNamestringundefinedClases para el <ul>.
itemClassNamestringundefinedClases para cada <li>.
linkClassNamestringundefinedClases para cada <a> (estiliza estados vía data-active).
indicatorClassNamestringundefinedClases para el indicador de pista activa.

Props de OnThisPage.TreeLink

PropiedadTipoDefaultDescripción
headingsTOCItemType[]RequeridoArreglo de encabezados para renderizado activo.
classNamestringundefinedClases para el <ul> (pasado a Items).
itemClassNamestringundefinedClases para cada <li>.
linkClassNamestringundefinedClases para cada <a>.
indicatorClassNamestringundefinedClases para el indicador de pista activa.
contentClassNamestringundefinedClases para el contenedor con scroll.
fadeClassNamestringundefinedClases para el elemento de fundido inferior.

Contextos InternosLink

Si estás construyendo un rastreador totalmente personalizado, puedes importar y envolver tu layout en los proveedores de contexto React expuestos a través de OnThisPage:

Proveedor de ContextoDescripciónProps
AnchorProviderObserva eventos de scroll con IntersectionObserver y rastrea el encabezado activo.AnchorProviderProps
ScrollProviderAuto-scrollea las listas de la tabla de contenidos para mantener el elemento activo centrado.ScrollProviderProps

AnchorProviderPropsLink

PropiedadTipoDefaultDescripción
tocTOCItemType[]RequeridoArreglo de encabezados de la tabla de contenidos a observar.
singlebooleanfalseCuando es true, solo activa un elemento a la vez.
observerOptionsIntersectionObserverInitundefinedOverride de opciones de IntersectionObserver.

ScrollProviderPropsLink

PropiedadTipoDefaultDescripción
containerRefRefObject<HTMLElement>RequeridoRef del contenedor de scroll que contiene la lista de enlaces.
Last updated on October 18, 2026

Was this page helpful?