PageNav
Previous/next page navigation buttons rendered at the bottom of pages.
The PageNav component displays navigation controls at the bottom of pages, pointing readers to the logically preceding or following chapters.
It walks the sidebar routes tree to find the previous and next sibling — same logic that powers most docs sites — and hands them to your layout via the usePageNav() hook. You decide what they look like: pill buttons, full-width cards with descriptions, or just plain chevrons.
Import
import { PageNav } from 'boltdocs/primitives'
import { usePageNav } from 'boltdocs/client'
The usePageNav hook resolves the previous and next routes relative to currentRoute in the sidebar tree. Note the field names: the hook returns { prev, next }, not { prevPage, nextPage } — older docs sometimes carry the longer name, double-check if you're copy-pasting.
Composable Page Navigation Example
Using the primitive PageNav sub-components, you can compose a custom footer pager. The example below shows how to retrieve active page sibling metadata via usePageNav and structure the links with custom borders and layout styles:
// docs/components/CustomFooterNav.tsx
import React from 'react'
import { PageNav } from 'boltdocs/primitives'
import { usePageNav } from 'boltdocs/client'
export default function CustomFooterNav() {
const { prev, next } = usePageNav()
if (!prev && !next) return null
return (
<PageNav.Root className="border-t border-subtle pt-8 mt-12 grid grid-cols-2 gap-4">
{/* 1. Previous Page Direction */}
{prev ? (
<PageNav.Link
to={prev.path}
direction="prev"
className="group p-4 rounded-xl border border-zinc-200 dark:border-zinc-800 hover:border-primary-500 transition-colors"
>
<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">
{prev.title}
</PageNav.Description>
</PageNav.Link>
) : (
<div /> // Column offset spacer
)}
{/* 2. Next Page Direction */}
{next ? (
<PageNav.Link
to={next.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"
>
<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">
{next.title}
</PageNav.Description>
</PageNav.Link>
) : (
<div /> // Column offset spacer
)}
</PageNav.Root>
)
}
Common pitfalls
usePageNavis route-aware, not block-aware. It does not match byfrontmatter.tagsor any other field — strictly the order in the sidebar tree. If you need richer "related pages" behaviour, build it manually withuseRoutes()+currentRoute.frontmatter.tags.prevPage/nextPageare nullable at the boundaries of the route graph. Don't render a<PageNav.Link>for a missing direction — render an empty<div />(as in the example) so the surviving link doesn't lose its grid column.- The dispatch event is SPA, not hard navigation. Boltdocs routes the click through React Router — clicking next-page works without a full reload.
Composable Sub-Components
The PageNav primitive provides the following sub-components for structure customization:
| Component | HTML Tag | Description | Props |
|---|---|---|---|
PageNav.Root / PageNav | <nav> | The main outer flex grid container holding pager links. | ComponentBaseProps |
PageNav.Link | <a> | An optimized anchor element linking to adjacent pages. Renders chevron arrows automatically. | PageNav.Link Props |
PageNav.Title | <span> | Directional helper label text (e.g. "Next" or "Previous"). | ComponentBaseProps |
PageNav.Description | <div> | Heading title text of the target sibling page document. | ComponentBaseProps |
PageNav.Icon | <span> | A layout container used to house custom arrow or caret graphics. | ComponentBaseProps |
Component Props
ComponentBaseProps (Common)
| Property | Type | Default | Description |
|---|---|---|---|
children | ReactNode | undefined | Children content elements. |
className | string | undefined | Custom CSS utility classes. |
style | CSSProperties | undefined | Inline style settings. |
PageNav.Link Props
| Property | Type | Default | Description |
|---|---|---|---|
to | string | Required | Sibling routing destination path. |
direction | 'prev' | 'next' | Required | Direction indicator to control flex ordering and chevrons. |
className | string | undefined | Custom utility classes. |