React PDF Kit Custom Layout

react-pdf-kit-custom-layout

Use this skill when: the developer asks to replace the default viewer layout entirely with their own. Examples: embedded inline preview, a sidebar-only minimal reader, an enterprise UI with a custom toolbar on the side instead of the top. For small toolbar tweaks while keeping the default layout, use react-pdf-kit-toolbar-customization.

The viewer is composable. RPProvider and RPPages are the minimum required. Everything else (RPLayout, RPTheme, individual toolbar tools) can be swapped or omitted. State and actions are exposed via documented hooks.

Gotchas

• RPProvider and RPPages are required. RPProvider mounts the document and makes the contexts available. RPPages renders the virtualized page list. Removing either breaks the viewer.
• Use only documented hooks. Reaching into internal contexts via React.useContext(InternalContext) is unsupported and will break on minor releases. Documented hooks: useDocumentContext, useZoomContext, usePaginationContext, useSearchContext, useHighlightContext, useRotationContext, useViewModeContext, useDarkModeContext, plus feature hooks under utils/hooks/ re-exported from the public entry.
• Do not break virtualization. Wrapping RPPages in any ancestor that doesn't have a measurable height (no flex: 1 / min-height: 0, no fixed height) makes the virtualizer mount with 0 rows. Always give it a real viewport.
• Provider order matters. RPConfig must be outermost, then RPProvider, then RPTheme (optional but harmless) inside that. Anywhere inside RPProvider you can call the hooks.
• RPTheme is still recommended even in custom layouts. It provides CSS custom properties that built-in components (page layers, text selection highlight) read. Skipping it works visually but loses dark-mode and theming.
• Note on RPLayout vs RPDefaultLayout: this skill replaces the default layout component, so neither appears in the final composition. Older code that imports RPDefaultLayout should migrate to RPLayout first (RPDefaultLayout is deprecated in v2) before headless migration, so the two refactors don't get tangled.

Procedure

1. Compose the minimum chain

// src/HeadlessPdfViewer.tsx
import {
  RPConfig,
  RPProvider,
  RPTheme,
  RPPages,
} from '@react-pdf-kit/viewer'
import { CustomShell } from './CustomShell'

export function HeadlessPdfViewer({ src }: { src: string }) {
  return (
    <RPConfig>
      <RPProvider src={src}>
        <RPTheme>
          <CustomShell />
        </RPTheme>
      </RPProvider>
    </RPConfig>
  )
}

CustomShell (next step) is where YOU place RPPages next to your own toolbar, sidebar, or status bar.

2. Build the shell using documented hooks

// src/CustomShell.tsx
import {
  RPPages,
  useDocumentContext,
  useZoomContext,
  usePaginationContext,
  useDarkModeContext,
} from '@react-pdf-kit/viewer'

export function CustomShell() {
  const { numPages, isLoading } = useDocumentContext()
  const { zoom, setZoom } = useZoomContext()
  const { currentPage, goToPage } = usePaginationContext()
  const { isDarkMode, toggleDarkMode } = useDarkModeContext()

  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: '240px 1fr',
        gridTemplateRows: '48px 1fr',
        height: '100%',
      }}
    >
      <header
        style={{
          gridColumn: '1 / -1',
          display: 'flex',
          alignItems: 'center',
          gap: 12,
          padding: '0 16px',
          borderBottom: '1px solid var(--rp-border, #e5e7eb)',
        }}
      >
        <span>{isLoading ? 'Loading...' : `${numPages} pages`}</span>
        <button
          type="button"
          => setZoom(zoom + 0.1)}
          aria-label="Zoom in"
        >
          +
        </button>
        <button
          type="button"
          => setZoom(zoom - 0.1)}
          aria-label="Zoom out"
        >
          -
        </button>
        <span style={{ flex: 1 }} />
        <button
          type="button"
         
          aria-pressed={isDarkMode}
        >
          {isDarkMode ? 'Light' : 'Dark'}
        </button>
      </header>

      <aside
        style={{
          overflow: 'auto',
          borderRight: '1px solid var(--rp-border, #e5e7eb)',
          padding: 8,
        }}
      >
        {Array.from({ length: numPages }, (_, i) => i + 1).map(p => (
          <button
            key={p}
            type="button"
            => goToPage(p)}
            aria-current={p === currentPage ? 'page' : undefined}
            style={{ display: 'block', width: '100%', textAlign: 'left' }}
          >
            Page {p}
          </button>
        ))}
      </aside>

      <main style={{ overflow: 'hidden', minHeight: 0 }}>
        <RPPages />
      </main>
    </div>
  )
}

The <main> ancestor of RPPages MUST have min-height: 0 (combined with the parent grid's 1fr row) so the virtualizer's parent has a measurable height.

3. Memoize where it matters

If you compute derived state to pass into RPProvider (for example, a file-loading callback or options object), memoize it. The provider re-renders all children on identity changes, so a new object every render disables virtualization gains.

const options = useMemo(() => ({ withCredentials: true }), [])
return <RPProvider src={src} options={options}>...</RPProvider>

4. (Optional) Add search, rotation, view modes

Same pattern: import the hook, call it, render UI bound to its state and actions. useSearchContext, useHighlightContext, useRotationContext, useViewModeContext are all documented.

Verify

pnpm install
pnpm build
pnpm dev

Open the page. Confirm:

• The PDF renders inside your custom shell.
• The page-jump sidebar updates currentPage (verify the aria-current indicator).
• Zoom buttons resize pages without remounting the viewer.
• Dark-mode toggle flips the theme.
• Scrolling still virtualizes. Only mounted pages should be in the DOM (DevTools, Elements panel: RPPages should render a windowed subset, not all pages at once).

References

• Companion skills:
  • react-pdf-kit-setup: first-time setup.
  • react-pdf-kit-toolbar-customization: for keeping the default layout but tweaking toolbar contents.