API reference

Functions

`exportToPDF(element, options?)`

function exportToPDF(
  element: HTMLElement,
  options?: ExportOptions,
): Promise<PDFExportResult>;

Exports a mounted DOM element to PDF.

`registerFont(descriptor)`

function registerFont(descriptor: FontDescriptor): Promise<void>;

Loads a TTF/OTF font into the browser via FontFace, caches the bytes, and makes it available for PDF embedding.

`getRegisteredFonts()`

function getRegisteredFonts(): ReadonlyMap<string, RegisteredFont>;

Returns the current font registry. Mainly useful for diagnostics and tests.

`clearFontRegistry()`

function clearFontRegistry(): void;

Clears registered fonts and removes matching FontFace entries from document.fonts when possible. Primarily a test helper.

`pageContentWidth(opts?)`

function pageContentWidth(opts?: PageGeometryOptions): number;

Returns the CSS pixel width of the printable area for the given format / orientation / margin. Use this to size your root exportable container so it fills the page without slack.

import { exportToPDF, pageContentWidth } from "react-print-pdf";

const width = pageContentWidth({ format: "A4", margin: "10mm" }); // 718

return (
  <div ref={ref} style={{ width }}>
    <Invoice />
  </div>
);

Defaults: format: "A4", orientation: "portrait", margin: 0.

`pageContentHeight(opts?)`

function pageContentHeight(opts?: PageGeometryOptions): number;

Like pageContentWidth but for height. Useful when authoring pageBreak: "single" documents that must fit one page.

Components

`<PageBreak />`

import { PageBreak } from "react-print-pdf";

<PageBreak />

Forces a page boundary in auto and manual pagination modes.

Constants

`PRINT_REPEAT_ATTR`

PRINT_REPEAT_ATTR === "data-print-repeat";

Marks a DOM region that should repeat at the top of continuation pages.

Errors

`PdfExportError`

class PdfExportError extends Error {
  readonly code: PdfExportErrorCode;
  readonly context?: PdfExportErrorContext;
}

Thrown by exportToPDF and registerFont for documented failure modes. The code field is stable and safe to switch on; the message is a human-readable summary that may change between releases. See Error handling for the full catalogue and recovery patterns.

`isPdfExportError(err)`

function isPdfExportError(err: unknown): err is PdfExportError;

Type guard for use in catch blocks.

Debug overlay

Passing debug: true to exportToPDF draws a thin colored outline around every emitted primitive's bounding box plus a small label in the top-left corner indicating the primitive kind. The overlay is drawn on top of the content so it sits above everything else, which is what you want when chasing a misaligned element or verifying that a region rasterized vs. drew vector.

await exportToPDF(ref.current, {
  filename: "debug.pdf",
  debug: true,
});

Color key:

blue — rect
magenta — border
red — text
green — image
olive — raster (rasterized region)
orange — link (one box per visual line)
teal — softRect / softRectSlice

This is a development aid; ship debug: false (the default) to your users.

Lifecycle hooks

`onProgress(stage, pct)`

Reports coarse pipeline progress. The five stages run in order: prepare → walk → paginate → emit → deliver. Each stage fires 0 at start and 1 at end.

`onPageRendered(pageNumber, totalPages)`

Fires once per page after the page is fully composed but before the document is serialized. Pages report in order, starting at 1. The totalPages value is consistent across calls. Throwing from this hook propagates to the caller of exportToPDF and aborts the export.

await exportToPDF(ref.current, {
  onPageRendered: (pageNumber, total) => {
    console.log(`rendered ${pageNumber}/${total}`);
  },
});

Hyperlinks

Any <a href> inside the exportable subtree becomes a clickable PDF Link annotation when the URI uses an allowed scheme (http, https, mailto, tel). The walker emits one annotation per visual line via el.getClientRects() so wrapped links stay clickable across multiple lines. Internal anchors (href="#section") and unsafe schemes (javascript:, data:, blob:, protocol-relative //, empty) are dropped at walk time — the visible text and underline still render. There is no opt-out flag; if you want a non-clickable styled link, render a <span> with the same classes.

Types

type PageFormat = "A4" | "A3" | "A5" | "Letter" | "Legal" | [number, number];

type Orientation = "portrait" | "landscape";

type Margin =
  | string
  | number
  | {
      top: string | number;
      right: string | number;
      bottom: string | number;
      left: string | number;
    };

type PageBreakMode = "auto" | "manual" | "single";

type PageContext = {
  pageNumber: number;
  totalPages: number;
};

type FontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;

type FontStyle = "normal" | "italic";

type Align = "left" | "center" | "right";

type PageGeometryOptions = {
  format?: PageFormat;
  orientation?: Orientation;
  margin?: Margin;
};

type FontDescriptor = {
  family: string;
  src: string;
  weight?: FontWeight;
  style?: FontStyle;
};

type RegisteredFont = Required<FontDescriptor> & {
  bytes: ArrayBuffer;
};

type ExportOptions = {
  filename?: string;
  format?: PageFormat;
  orientation?: Orientation;
  margin?: Margin;
  align?: Align;
  pageBreak?: PageBreakMode;
  header?: (ctx: PageContext) => ReactElement;
  footer?: (ctx: PageContext) => ReactElement;
  title?: string;
  author?: string;
  onProgress?: (stage: ExportStage, pct: number) => void;
  onPageRendered?: (pageNumber: number, totalPages: number) => void;
  debug?: boolean;
};

type ExportStage = "prepare" | "walk" | "paginate" | "emit" | "deliver";

type PDFExportResult = {
  bytes: () => Uint8Array;
  blob: () => Blob;
  save: (filename?: string) => void;
  preview: () => Window | null;
};

type PdfExportErrorCode =
  | "INVALID_ELEMENT"
  | "FONT_FETCH_FAILED"
  | "FONT_INVALID_BYTES"
  | "FONT_LOAD_FAILED"
  | "RENDER_DETACHED";

type PdfExportErrorContext = {
  family?: string;
  src?: string;
  status?: number;
  cause?: unknown;
};