Boltdocs Logo
GuidesIntegrationsAPIPluginsComponentsReleases

PageNav

Previous/next page navigation buttons rendered at the bottom of pages.

The PageNav component displays navigation controls at the bottom of pages, directing readers to the logically preceding or following chapters.

Composable Page Navigation ExampleLink

Using the PageNav primitive subcomponents, you can compose a custom paginator footer. The following example shows how to fetch active sibling page metadata via usePageNav, provide the directional arrows through PageNav.Icon, and structure the links with custom borders and layout styles:

tsx
// docs/components/CustomFooterNav.tsx
import React from 'react'
import { ChevronLeft, ChevronRight } from 'lucide-react'
import { PageNav } from 'boltdocs/primitives'
import { usePageNav } from 'boltdocs/client'

export default function CustomFooterNav() {
  const { prevPage, nextPage } = usePageNav()

  if (!prevPage && !nextPage) return null

  return (
    <PageNav.Root className="border-t border-subtle pt-8 mt-12 grid grid-cols-2 gap-4">
      {/* 1. Previous Page Direction */}
      {prevPage ? (
        <PageNav.Link
          to={prevPage.path}
          direction="prev"
          className="group p-4 rounded-xl border border-zinc-200 dark:border-zinc-800 hover:border-primary-500 transition-colors"
        >
          <PageNav.Icon className="shrink-0 text-zinc-400 dark:text-zinc-500 group-hover:text-primary-500 transition-colors">
            <ChevronLeft />
          </PageNav.Icon>
          <div className="flex flex-col">
            <PageNav.Title className="text-xs uppercase font-bold text-zinc-400 dark:text-zinc-500 group-hover:text-primary-500 transition-colors">
              Previous Chapter
            </PageNav.Title>
            <PageNav.Description className="text-sm font-semibold text-zinc-800 dark:text-zinc-200 mt-1">
              {prevPage.title}
            </PageNav.Description>
          </div>
        </PageNav.Link>
      ) : (
        <div /> // Column offset spacer
      )}

      {/* 2. Next Page Direction */}
      {nextPage ? (
        <PageNav.Link
          to={nextPage.path}
          direction="next"
          className="group p-4 rounded-xl border border-zinc-200 dark:border-zinc-800 hover:border-primary-500 transition-colors text-right"
        >
          <div className="flex flex-col">
            <PageNav.Title className="text-xs uppercase font-bold text-zinc-400 dark:text-zinc-500 group-hover:text-primary-500 transition-colors">
              Next Chapter
            </PageNav.Title>
            <PageNav.Description className="text-sm font-semibold text-zinc-800 dark:text-zinc-200 mt-1">
              {nextPage.title}
            </PageNav.Description>
          </div>
          <PageNav.Icon className="shrink-0 text-zinc-400 dark:text-zinc-500 group-hover:text-primary-500 transition-colors">
            <ChevronRight />
          </PageNav.Icon>
        </PageNav.Link>
      ) : (
        <div /> // Column offset spacer
      )}
    </PageNav.Root>
  )
}

Composable SubcomponentsLink

The PageNav primitive provides the following subcomponents for structure customization:

ComponentHTML TagDescriptionProps
PageNav.Root / PageNav<nav>The main outer flex grid container holding the pagination links.ComponentBaseProps
PageNav.Link<a>An optimized anchor element linking to adjacent pages. The directional arrow is supplied by the theme through PageNav.Icon.PageNav.Link Props
PageNav.Title<span>Directional helper label text (e.g., "Next" or "Previous").ComponentBaseProps
PageNav.Description<div>The target sibling page's document header title text.ComponentBaseProps
PageNav.Icon<span>The slot for the directional arrow or caret graphic (e.g., a chevron pointing to the adjacent page).ComponentBaseProps

Component PropsLink

ComponentBaseProps (Common)Link

PropertyTypeDefaultDescription
childrenReactNodeundefinedChild content elements.
classNamestringundefinedCustom utility CSS classes.
styleCSSPropertiesundefinedInline style settings.

PageNav.Link PropsLink

PropertyTypeDefaultDescription
tostringRequiredTarget sibling page path.
direction'prev' | 'next'RequiredDirection indicator controlling flex alignment.
classNamestringundefinedCustom utility classes.

Customization & statesLink

The PageNav primitive is style-neutral: the root renders a <nav>, PageNav.Link renders a plain router <a>, and the directional arrow is passed by the theme through PageNav.Icon. Every visual decision (colors, borders, spacing) belongs to the theme through its className slots. It emits no data-* state attributes — current-page and hover treatments are styled from CSS in your theme.

State / SlotMechanism
PageNav (root)<nav> with a baked-in grid sm:grid-cols-2 gap-4 layout; borders and spacing via className
PageNav.LinkPlain router <a> — no state attributes; hover and focus treatments via className
directionprev / next controls flex alignment; place PageNav.Icon first for prev and last for next
PageNav.Icon<span> slot for the arrow graphic; size and color via className, inherits currentColor
PageNav.Title / PageNav.DescriptionText slots; typography and color via className
tsx
<PageNav className="mt-12 grid gap-4 border-t border-subtle pt-8 sm:grid-cols-2">
  <PageNav.Link
    to={prevPage.path}
    direction="prev"
    className="group rounded-xl border border-subtle p-4 transition-colors hover:border-primary-500 hover:bg-surface"
  >
    <PageNav.Icon className="shrink-0 text-muted/60">
      <ChevronLeft />
    </PageNav.Icon>
    <div className="flex flex-col">
      <PageNav.Title className="text-xs font-semibold uppercase text-muted group-hover:text-primary-500">
        Previous
      </PageNav.Title>
      <PageNav.Description className="mt-1 text-sm font-medium text-body">
        {prevPage.title}
      </PageNav.Description>
    </div>
  </PageNav.Link>
</PageNav>
Jesús Alcalá
Last updated on October 18, 2026

Was this page helpful?