1. Home
  2. ChevronRightLayout
  3. ChevronRightOnThisPage

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 a medida que el usuario se desplaza.


ImportaciónLink

import { OnThisPage } from 'boltdocs/primitives'

Ejemplo de Rastreador de Scroll ComponibleLink

Usando los módulos primitivos de OnThisPage, puedes ensamblar una tabla de contenidos completamente personalizada. El siguiente ejemplo muestra cómo componer un diseño con títulos personalizados, contenedores de listas, líneas indicadoras de actividad y comportamientos de scroll suave:

// 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

  // Convierte la base de datos de encabezados a una estructura estándar de TOC
  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. Encabezado de Título Estático */}
      <OnThisPage.Header className="text-xs font-bold uppercase tracking-wider text-zinc-400 mb-4">
        Tabla de Contenidos
      </OnThisPage.Header>

      {/* 2. Proveedores de Envoltorio de Contexto de Rastreador de Scroll */}
      <AnchorProvider toc={tocItems} single={false}>
        <ScrollProvider containerRef={scrollContainerRef}>
          
          {/* 3. Viewport Desplazable con Máscara */}
          <OnThisPage.Content ref={scrollContainerRef} className="max-h-[80vh]">
            <OnThisPage.List className="relative border-l border-zinc-200 dark:border-zinc-800">
              
              {/* 4. Indicador de Acento de Sección Activa */}
              <OnThisPage.Indicator className="bg-primary-500" />
              
              {/* 5. Mapeo Jerárquico de Enlaces */}
              {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] Si no quieres mapear los elementos manualmente, puedes usar el envoltorio de primitiva de alto nivel <OnThisPage.Tree headings={headings} /> para montar automáticamente los observadores, indicadores y enlaces de lista dentro de un diseño activo.


Subcomponentes ComponiblesLink

La primitiva OnThisPage proporciona los siguientes subcomponentes para la personalización de la estructura:

ComponenteEtiqueta HTMLDescripciónProps
OnThisPage.Root / OnThisPage<nav>El envoltorio contenedor exterior que representa el área de navegación de la columna derecha fija de escritorio.ComponentBaseProps
OnThisPage.Header<div>Un bloque tipográfico de título para etiquetar la tabla de contenidos.ComponentBaseProps
OnThisPage.Content<div>Contenedor de viewport desplazable con barras de desplazamiento ocultas.OnThisPage.Content Props
OnThisPage.List<ul>Envoltorio de elemento de lista que envuelve los anclajes de elementos.ComponentBaseProps
OnThisPage.Item<li>Envoltorio individual de celda de lista. Indenta elementos H3.OnThisPage.Item Props
OnThisPage.Link<a>Elemento de enlace de anclaje que intercepta eventos de clic para realizar desplazamientos suaves de viewport.OnThisPage.Link Props
OnThisPage.Indicator<div>Un indicador de pista de resaltado vertical flotante que muestra el enlace de anclaje activo.ComponentBaseProps
OnThisPage.ItemsVaríaAyuda de bucle que renderiza enlaces activos e indicadores automáticamente basándose en las configuraciones de encabezado.OnThisPage.Items Props
OnThisPage.Tree<nav>Componente automatizado de alto nivel que agrupa todos los proveedores, observadores y elementos.OnThisPage.Tree Props

Props del ComponenteLink

ComponentBaseProps (Común)Link

PropiedadTipoPredeterminadoDescripción
childrenReactNodeundefinedElementos de contenido hijos.
classNamestringundefinedClases CSS utilitarias personalizadas.
styleCSSPropertiesundefinedSobrescrituras de estilo en línea.

Props de OnThisPage.ContentLink

PropiedadTipoPredeterminadoDescripción
refRef<HTMLDivElement>undefinedInstancia de Ref para el elemento contenedor.
scrollRefRefObject<HTMLElement>undefinedRef del elemento de contenido principal del viewport para rastrear el desplazamiento.

Props de OnThisPage.ItemLink

PropiedadTipoPredeterminadoDescripción
levelnumberundefinedLa profundidad de la jerarquía de encabezados. Una profundidad de 3 activa relleno interno.
PropiedadTipoPredeterminadoDescripción
hrefstringRequeridoID de anclaje objetivo del elemento (por ejemplo, '#installation').
activebooleanfalseInterruptor de sobrescritura de resaltado activo.
onClick(event) => voidundefinedCallback de interceptación de clic personalizado.

Props de OnThisPage.ItemsLink

PropiedadTipoPredeterminadoDescripción
headingsTOCItemType[]RequeridoDatos sin procesar de encabezados de página a mapear.

Props de OnThisPage.TreeLink

PropiedadTipoPredeterminadoDescripción
headingsTOCItemType[]RequeridoArreglo de encabezados para renderizado activo.

Contextos InternosLink

Si estás construyendo un rastreador completamente personalizado, puedes importar y envolver tu diseño en los proveedores de contexto React personalizados expuestos a través de OnThisPage:

Proveedor de ContextoDescripciónProps
AnchorProviderObserva eventos de desplazamiento usando IntersectionObserver y rastrea el encabezado activo de la página.AnchorProviderProps
ScrollProviderDesplaza automáticamente las listas de la tabla de contenidos para mantener el elemento activo alineado en el centro del viewport.ScrollProviderProps

AnchorProviderPropsLink

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

ScrollProviderPropsLink

PropiedadTipoPredeterminadoDescripción
containerRefRefObject<HTMLElement>RequeridoRef del elemento contenedor de desplazamiento que contiene la lista de enlaces.
Last updated on July 27, 2026

Was this page helpful?