# Printing This page covers building PDF documents with `@nxgt/material/print`, turning them into a download, a new tab or a server response in one call, and shipping them from a browser or from a server bundle that must not crash. ```bash bun add @react-pdf/renderer@^4.9 react-pdf-tailwind ``` Both are **optional peers**: only the app that prints installs them. Since 2.2.0 the renderer's floor is 4.9.0; an older copy already in your lockfile makes the install complain (see [troubleshooting](../troubleshooting.md#conflicting-peer-dependency-react-pdfrenderer)). ```tsx import { formatAmount, formatDate, PrintDocument, PrintHeader, PrintInfoRow, PrintSection, PrintTable, PrintTableCell, PrintTableHeader, PrintTableRow, PrintTotalRow, PrintTotals, } from '@nxgt/material/print'; type Line = { label: string; quantity: number; unitPrice: number }; type Invoice = { number: string; issuedAt: string; customer: string; currency: string; lines: Line[] }; export function InvoiceDocument({ invoice, language }: { invoice: Invoice; language?: string }) { const total = invoice.lines.reduce((sum, l) => sum + l.quantity * l.unitPrice, 0); return ( } > Item Qty Amount {invoice.lines.map((line, index) => ( {line.label} {line.quantity} {formatAmount(line.quantity * line.unitPrice, invoice.currency)} ))} ); } ``` The lines, the details and the total can also come from column definitions instead of cells written by hand: see [Tables from columns and rows](#tables-from-columns-and-rows). To save it, open it or return it from a server route, pass it to `downloadPdf`, `openPdf` or `pdfResponse` ([Rendering the document](#rendering-the-document)); to write the same document as plain data instead of JSX, see [Documents as data](#documents-as-data). ## The page shell: `PrintDocument` `PrintDocument` takes the place of react-pdf's `Document` and `Page`: hand it to [`downloadPdf`, `pdfResponse`](#rendering-the-document) and the other output functions, or to `pdf()`, `renderToBuffer()` or `PDFViewer` the same way. Its children flow over as many pages as they need, and what should appear on every page is a prop. ```tsx import { PrintDocument, PrintHeader } from '@nxgt/material/print'; } footer={({ pageNumber, totalPages }) => `INV-42 · ${pageNumber}/${totalPages}`} pageNumbers={{ align: 'right' }} watermark="BROUILLON" > {/* the body */} ``` | Prop | Default | Effect | | --- | --- | --- | | `size` | `'A4'` | `'A3'`, `'A4'`, `'A5'`, `'LETTER'`, `'LEGAL'`, or `[width, height]` in points. | | `orientation` | `'portrait'` | `'landscape'` swaps width and height. | | `margins` | `{ top: 21, right: 24, bottom: 21, left: 24 }` | Points: one number for every side, or `top` / `right` / `bottom` / `left` / `x` / `y` (a side wins over its axis). | | `header` | — | Repeated at the top of every page, in the flow, so the body starts below it on each page. | | `footer` | — | Repeated at the bottom of every page, in a band of `footerHeight` points above the bottom margin. A function returns the text for each page (see below). | | `footerHeight` | `24` | Height of that band. Raise it for a footer of several lines. | | `pageNumbers` | off | `true` prints "Page 2 of 5" centred in the footer band, in the document's language. `{ align: 'left' \| 'center' \| 'right', format: 'page-of' \| 'page' }`; `'page'` prints "Page 2". | | `watermark` | — | Large rotated text behind the content: a string, or `{ text, opacity (0.08), angle (35), color, fontSize (72) }`. | | `title`, `author`, `subject`, `keywords` | — | Document information, as PDF readers show it. | | `creator` | `'@nxgt/material'` | The application that made the file. | | `producer` | `creator` | The software that wrote the PDF. | | `language` | the `I18nProvider` around the document, then `'en'` | The built-in strings ("Page 2 of 5") and the PDF's language. | | `locale`, `timeZone` | `language`, the runtime's | How the data blocks format amounts and dates. | Nothing but `children` is required: `{…}` is an A4 page with the margins the blocks were designed for. ### Translating built-in strings in a PDF The strings `PrintDocument` and `PrintDataTable` print themselves come from this package's `material.print.*` keys, in English and French. `pdf()`, `renderToBuffer()` and the [output functions](#rendering-the-document) render a tree of their own, so **your app's `I18nProvider` does not reach the document**. Give the language one of two ways: ```tsx import { pdf } from '@react-pdf/renderer'; import { I18nProvider } from '@nxgt/material/i18n'; // a prop: works the same on a server await pdf().toBlob(); // or a provider inside the pdf() call await pdf( , ).toBlob(); ``` (`InvoiceDocument` passes its `language` on to `PrintDocument`.) A language the bundle does not have prints the English text; a regional tag reads its language (`'fr-CA'` prints French). To translate one of the package's keys yourself outside a component, `translateMaterial(language, key, fallback, values)` from `@nxgt/material/i18n` does what `useMaterialTranslation()` does, without a hook. ### Headers and footers `header` and a `footer` element are rendered once and repeated on each page; they can hold any print block, or be a plain string (printed as text, since react-pdf drops a string outside ``). A **`footer` function** is different: react-pdf calls it for each page while it lays the pages out, outside React. It returns text, and it cannot call a hook (`Invalid hook call`): compute what it needs in your component and use it from the function. ```tsx function InvoiceDocument({ invoice }: { invoice: Invoice }) { const issued = formatDate(invoice.issuedAt, { locale: 'fr-FR' }); // here, not in the footer return ( `${invoice.number} · ${issued} · ${pageNumber}/${totalPages}`}> {/* … */} ); } ``` The footer and the page number share one row in that band, so they never draw over each other: the footer takes the free width and the number follows it, or comes first with `pageNumbers={{ align: 'left' }}`. Alone, the number is placed by `align` (centred by default). A footer taller than `footerHeight` runs up into the body; raise `footerHeight` for a footer of several lines. ## The building blocks These render `@react-pdf/renderer` primitives (`View`, `Text`), not DOM, so they only work inside a `PrintDocument` (or a react-pdf ``). `PrintDataTable`, `PrintKeyValue` and `PrintMetric` take the language and locale of the `PrintDocument` around them; under a plain `` they print English strings ("Total", "No rows") and `en` amounts and dates. | Component | Props | Renders | | --- | --- | --- | | `PrintHeader` | `title: string`, `subtitle?: string`, `reference?: string`, `referencePrefix?: string` (`'#'`), `logo?: string \| { src, width?, height? }`, `logoText?: string`, `qrDataUrl?: string \| null` | The title block: the logo (a PNG or JPEG URL or data URL, 72×48 pt unless you size it) or `logoText` in a box on the left, the title, subtitle and `#reference` centred, the QR image on the right. A side you leave empty draws nothing, and the title stays centred | | `PrintSection` | `title: string`, `className?: string`, `children` | A titled block (`className` is a `tw` string, default `mb-3.5`) | | `PrintInfoRow` | `label: string`, `value?: ReactNode` | A label / value line. A `string` or `number` value is wrapped in `Text`; anything else is rendered as-is | | `PrintCard` | `className?: string`, `children` | A bordered row of fields | | `PrintCardField` | `label: string`, `value?: string \| null` | A label over a value. **Renders nothing when `value` is empty** | | `PrintTable`, `PrintTableHeader` | `children` | Table section and its header row | | `PrintTableRow` | `isAlt?: boolean`, `children` | A row; `isAlt` shades it | | `PrintTableCell` | `isHeader?: boolean`, `flex?: number` (`1`), `textAlign?: 'left' \| 'right' \| 'center'` (`'left'`) | A cell. Empty `children` print `—` | | `PrintTotals`, `PrintTotalRow` | `label: string`, `value: string`, `last?: boolean` | The totals block; `last` is the bold grand-total row | | `PrintBadge` | `color?: string`, `className?: string`, `children` | A pill; `color` is a CSS colour for its background | | `PrintDataTable` | `columns`, `rows`, `currency?`, `totalLabel?`, `striped?`, `repeatHeader?`, `keepRowsWhole?`, `emptyText?`, `hideWhenEmpty?` | A whole table from column definitions: header repeated on each page, rows kept whole, a totals row. See [Tables from columns and rows](#tables-from-columns-and-rows) | | `PrintKeyValue` | `items`, or `data` + `fields` (+ `currency?`); `columns?: 1 \| 2`, `keepEmpty?` | Label and value pairs in one or two columns; empty values skipped. See [`PrintKeyValue`](#printkeyvalue-one-record-as-label-and-value-pairs) | | `PrintMetric`, `PrintMetrics` | `label`, `value`, `format?`, `currency?`, `hint?`, `delta?` | One figure with its label, hint and change; `PrintMetrics` lines several up. See [`PrintMetric`](#printmetric-and-printmetrics-figures) | **Changed in 2.2.0:** `PrintHeader` no longer draws a grey `LOGO` placeholder when you pass neither `logo` nor `logoText`, nor an empty box where the QR code goes when you pass no `qrDataUrl`. Pass `logoText="LOGO"` to keep the placeholder. `tw` is a `react-pdf-tailwind` instance for your own `style`s, with the colours the components use (`primary`, `secondary`, `muted`, `border`, `headerBg`, `headerText`, `rowAlt`, `white`, `logoBg`, `qrBg`) and pdfkit's built-in fonts (`font-sans` = Helvetica, `font-serif` = Times-Roman, `font-mono` = Courier). `commonPrintStyles` holds the `tw` class strings the components are built from, so your own blocks can match them. ### `formatAmount` and `formatDate` ```ts function formatAmount( value: number | null | undefined, currency?: string | null, options?: { locale?: string; fractionDigits?: number }, ): string; function formatDate( value: string | number | Date | null | undefined, options?: { locale?: string; timeZone?: string; dateStyle?: 'full' | 'long' | 'medium' | 'short'; timeStyle?: 'full' | 'long' | 'medium' | 'short' }, ): string; ``` ```ts import { formatAmount, formatDate } from '@nxgt/material/lib'; formatAmount(1234.5, 'EUR', { locale: 'fr-FR' }); // '1 234,50 €' formatAmount(1234.5, 'JPY', { locale: 'en-US' }); // '¥1,235' (the yen has no decimals) formatAmount(1.5, 'KWD', { locale: 'en-US' }); // 'KWD 1.500' (three) formatAmount(1234.5, 'JPY', { fractionDigits: 2 }); // '¥1,234.50', two decimals whatever the currency formatAmount(1234.5); // '1,234.50' (no currency: two decimals) formatAmount(null); // '—' formatAmount(1234.5, 'EURO'); // '1234.50 EURO' (malformed currency code) formatDate('2026-03-01', { locale: 'en-US' }); // 'Mar 1, 2026', in every time zone formatDate('2026-03-01T23:30:00Z', { locale: 'fr-FR', timeZone: 'Europe/Paris' }); // '2 mars 2026' formatDate(new Date(), { timeStyle: 'short' }); // date and time formatDate(undefined); // '—' formatDate('not a date'); // 'not a date' ``` | Option | Default | Effect | | --- | --- | --- | | `locale` | the runtime's locale | BCP 47 tag (`'fr-FR'`), for both functions. | | `fractionDigits` | the currency's own (ISO 4217), or 2 without a currency | `formatAmount` decimals, clamped to 0–20 (the range every `Intl` accepts; engines before ES2023 throw above 20). `NaN` or `Infinity` counts as not given, as in `CurrencyField`. Pass `2` to keep the pre-2.2.0 output. | | `timeZone` | the runtime's time zone | `formatDate`, for values with a time. A date-only string (`YYYY-MM-DD`) always keeps its calendar day. | | `dateStyle` / `timeStyle` | `'medium'` / none | `formatDate` styles; `timeStyle` is ignored for a date-only value. | They are pure `Intl` helpers, also exported from `@nxgt/material` and `@nxgt/material/lib`, so a screen that formats amounts does not need this entry. **Server rendering.** Without `locale` and `timeZone` they use the runtime's, so a server and a French browser print different strings. Pass both, or bind them once: ```ts // a server route, or any code outside React import { createFormatters } from '@nxgt/material/lib'; const { formatAmount, formatDate } = createFormatters({ locale: 'fr-FR', timeZone: 'Europe/Paris' }); formatAmount(1234.5, 'EUR'); // '1 234,50 €' ``` ```tsx // a component: bound to the I18nProvider language ('en' without a provider) import { useFormatters } from '@nxgt/material/hooks'; function InvoiceTotal({ total, issuedAt }: { total: number; issuedAt: string }) { const { formatAmount, formatDate } = useFormatters({ timeZone: 'Europe/Paris' }); return

{formatAmount(total, 'EUR')} · {formatDate(issuedAt)}

; } ``` A `@react-pdf/renderer` document is rendered outside your React tree (by `pdf()` or `renderToBuffer`), so it does not see your `I18nProvider`: call `createFormatters` there, or pass the formatted strings in as props (see [Translating built-in strings in a PDF](#translating-built-in-strings-in-a-pdf)). Amounts formatted for French keep printing correctly: the narrow no-break space `Intl` puts in `1 234,50 €` is not in the PDF standard fonts, and the print blocks replace it with one that is. **Changed in 2.2.0:** amounts use their currency's own decimals (JPY and KRW show none, KWD, BHD and OMR show three) where every currency used to get two, and a date-only string keeps its day instead of showing the previous day west of UTC. Pass `{ fractionDigits: 2 }` to keep two decimals. ## Tables from columns and rows `PrintDataTable` prints a list of plain objects through a list of columns, so you describe the table once instead of writing every cell. New in 2.2.0; the `PrintTable` blocks above keep working as they are. ```tsx import { definePrintColumns, PrintDataTable, PrintDocument } from '@nxgt/material/print'; type Line = { description: string; quantity: number; unitPrice: number; amount: number }; const lineColumns = definePrintColumns([ { key: 'description', label: 'Item', flex: 3 }, { key: 'quantity', label: 'Qty', format: 'number', width: 40, total: 'sum' }, { key: 'unitPrice', label: 'Unit price', format: 'amount' }, { key: 'amount', label: 'Amount', format: 'amount', total: 'sum' }, ]); export function InvoiceLines({ lines, language }: { lines: Line[]; language: string }) { return ( ); } ``` With `language="fr"`, an amount of 1200 prints `1 200,00 €`, the last row reads `Total` followed by the summed quantity and amount, and the header row is printed again at the top of each page the table runs onto. ### The table's props | Prop | Type | Default | Effect | | --- | --- | --- | --- | | `columns` | `PrintColumn[]` | — | Required. What each column shows; see [the column fields](#the-column-fields) | | `rows` | `T[]` | — | Required. Plain objects, one per line | | `currency` | `string` | — | ISO 4217 code for `format: 'amount'` columns that name none | | `totalLabel` | `string` | `material.print.table.total` ("Total") | Text in the first cell of the totals row, when the first column has no `total` of its own | | `striped` | `boolean` | `true` | Shades every other row | | `repeatHeader` | `boolean` | `true` | Prints the header row again at the top of each page the table crosses | | `keepRowsWhole` | `boolean` | `true` | A row moves to the next page rather than splitting across two | | `emptyText` | `string` | `material.print.table.empty` ("No rows") | With no rows: the header, then one muted row with this text | | `hideWhenEmpty` | `boolean` | `false` | With no rows, print nothing at all, header included | The totals row appears only when a column has a `total`, and it is kept in one piece after the last row. It prints for an empty table too, at zero; pass `hideWhenEmpty` if an empty table should leave no trace: ```tsx ``` The built-in texts follow the `PrintDocument`'s `language` (`Aucune ligne` in French); their keys are listed in [i18n](i18n.md#the-material-namespace). ### The column fields `definePrintColumns()` returns its argument unchanged; it is there so TypeScript checks every `key` against `T`. | Field | Type | Default | Effect | | --- | --- | --- | --- | | `key` | `keyof T & string` | — | The row property to print. Its name is also the column's id | | `id` + `accessor` | `string` + `(row: T, index: number) => unknown` | — | Instead of `key`: a computed value, such as `quantity * unitPrice` | | `label` | `string` | — | Required. The header text, and the label in a [`PrintKeyValue`](#printkeyvalue-one-record-as-label-and-value-pairs) | | `width` | `number \| '%'` | — | A fixed width in points (`40`) or a share of the table (`'25%'`) | | `flex` | `number` | `1` | Share of the width the fixed columns leave. Ignored when `width` is set | | `align` | `'left' \| 'center' \| 'right'` | `'right'` for `amount`, `number` and `percent`, else `'left'` | Header and cells | | `format` | `'amount' \| 'date' \| 'number' \| 'percent' \| (value, row) => string` | none | How the value prints (below) | | `currency` | `string \| (row: T) => string \| null \| undefined` | the table's `currency` | ISO 4217 code for `format: 'amount'`, for the column or per row | | `total` | `'sum' \| (rows: T[]) => number \| string \| null` | none | A figure in the totals row: the sum of the column, or your own | What each `format` prints, in the document's locale: | `format` | Value you pass | Prints (English) | | --- | --- | --- | | none | `'ACME'`, `1234.5` | `ACME`, `1,234.5` | | `'amount'` | `1234.5` with currency `'EUR'` | `€1,234.50`, in the currency's own decimals | | `'number'` | `1234.5678` | `1,234.568` (at most three decimals) | | `'percent'` | `0.2` (a fraction) | `20%` | | `'date'` | `'2026-03-01'`, an ISO date-time, epoch milliseconds, or a `Date` | `Mar 1, 2026` | | a function | anything | exactly the string it returns | `null`, `undefined` and `''` print `—`, whatever the format. ```tsx type Order = { reference: string; placedAt: string; quantity: number; unitPrice: number; discount: number; currency: string; status: 'paid' | 'open'; }; const orderColumns = definePrintColumns([ { key: 'reference', label: 'Order', width: '20%' }, { key: 'placedAt', label: 'Placed', format: 'date' }, { id: 'total', label: 'Total', accessor: (order) => order.quantity * order.unitPrice, format: 'amount', currency: (order) => order.currency, // one currency per row }, { key: 'discount', label: 'Discount', format: 'percent' }, { key: 'status', label: 'Status', format: (status) => (status === 'paid' ? 'Paid' : 'Open'), align: 'center' }, { key: 'quantity', label: 'Paid qty', format: 'number', total: (orders) => orders.filter((o) => o.status === 'paid').reduce((n, o) => n + o.quantity, 0), }, ]); ``` A few things the totals do that you may not expect: - **`'sum'` adds numbers only.** A cell whose value is not a finite `number` counts as zero. Amounts must be numbers: a string such as `'12.50'` prints `—` in its cell and adds nothing to the total (see [troubleshooting](../troubleshooting.md#an-amount-column-prints--instead-of-the-amount)). Convert decimal strings from your API with `Number()` first. - **The sum is floating point, rounded when printed.** `0.1 + 0.2` is `0.30000000000000004`; an `amount` or `number` column prints it rounded (`€0.30`), but the figure is not an exact decimal sum. When the total must match your accounting to the cent, compute it yourself in integer cents and return it from a `total` function (below). - **A per-row currency is not converted.** When the rows of an `amount` column name more than one currency, `'sum'` prints `—` rather than a figure in the wrong currency. Keep one currency per table, or compute your own totals and return a string from `total`. - **A `format` function formats the total too**, called with the total and the first row. A `total` function that returns a string prints it as is. ```tsx const centColumns = definePrintColumns<{ label: string; cents: number }>([ { key: 'label', label: 'Item' }, { id: 'amount', label: 'Amount', accessor: (row) => row.cents / 100, format: 'amount', total: (rows) => rows.reduce((sum, row) => sum + row.cents, 0) / 100, }, ]); ``` **Page breaks.** `keepRowsWhole` moves a row to the next page rather than cut it, which works for any row shorter than a page. A single row taller than a whole page, such as a cell holding several paragraphs, cannot stay whole; shorten that cell or print its text below the table. With `repeatHeader`, the header comes back on each page the table crosses, and is not left alone at the foot of a page. ### From a screen `DataTable` The TanStack column definitions of a `DataTable` on screen are not reused: they carry React cells, sorting and filters that mean nothing on paper. Copy the key and the header text across: ```ts // on screen const screenColumns = [ { accessorKey: 'reference', header: 'Order' }, { accessorKey: 'placedAt', header: 'Placed' }, ]; // on paper const printColumns = definePrintColumns([ { key: 'reference', label: 'Order' }, { key: 'placedAt', label: 'Placed', format: 'date' }, ]); ``` ### `PrintKeyValue`: one record as label and value pairs The detail block above a table ("Customer", "Issued", "Due"), in one or two columns. Pass `items`, or pass `data` with `fields`, which are the same column definitions as a `PrintDataTable`: ```tsx import { PrintKeyValue } from '@nxgt/material/print'; type Customer = { name: string; since: string; email: string | null; balance: number }; ``` | Prop | Type | Default | Effect | | --- | --- | --- | --- | | `items` | `{ label: string; value: PrintValue }[]` | — | The pairs, already built. A value is text, a number, or `{ amount, currency }`, `{ date }`, `{ number }` | | `data` + `fields` | `T` + `PrintColumn[]` | — | Instead of `items`: one record, read through column definitions (`width`, `flex`, `align` and `total` are ignored) | | `currency` | `string` | — | With `data`: the currency of `amount` fields that name none | | `columns` | `1 \| 2` | `1` | Two columns fill the left one first, then the right | | `keepEmpty` | `boolean` | `false` | Print a pair whose value is empty, as `—`, instead of skipping it | With every value empty and no `keepEmpty`, it prints nothing. ### `PrintMetric` and `PrintMetrics`: figures A figure with its label, and optionally a hint and a change: the printed counterpart of a `StatCard`. `PrintMetrics` lines several up, sharing the width. ```tsx import { PrintMetric, PrintMetrics } from '@nxgt/material/print'; ``` | Prop | Type | Default | Effect | | --- | --- | --- | --- | | `label` | `string` | — | Required. Above the figure | | `value` | `PrintValue` | — | Required. A number, text, or `{ amount, currency }` / `{ date }` / `{ number }` | | `format` | `'amount' \| 'date' \| 'number' \| 'percent'` | — | Applied when `value` is a number (or an ISO string for `'date'`), as for a column | | `currency` | `string` | — | ISO 4217 code for `format="amount"` | | `hint` | `string` | — | A caption under the figure | | `delta` | `number` | — | A change **in percent**: `4` prints `+4%` in the success colour, `-2.5` prints `-2.5%` in the error colour, in the document's locale (`+4 %` in French) | ### Your own blocks The helpers behind these blocks are exported from `@nxgt/material/print`, for a block of your own that reads the same column definitions: ```ts function definePrintColumns(columns: PrintColumn[]): PrintColumn[]; function resolvePrintTable( columns: PrintColumn[], rows: T[], options?: { currency?: string; totalLabel?: string }, ): { columns: { id: string; label: string; align: 'left' | 'center' | 'right'; width?: number | `${number}%`; flex?: number }[]; rows: PrintValue[][]; footer: PrintValue[][]; // one totals row, or none empty: boolean; }; function resolvePrintFields(fields: PrintColumn[], row: T, options?: { currency?: string }): { label: string; value: PrintValue }[]; function toPrintValue(column: PrintColumn, value: unknown, row: T | undefined, options?: { currency?: string }): PrintValue; function formatPrintValue(value: PrintValue, options?: { locale?: string; timeZone?: string; empty?: string }): string; function isEmptyPrintValue(value: PrintValue): boolean; ``` A cell comes out as a `PrintValue`, still data (`{ amount: 12, currency: 'EUR' }`), and `formatPrintValue` turns it into text. Your block does not see the `PrintDocument`'s locale, so pass it: ```tsx import { Text, View } from '@react-pdf/renderer'; import { formatPrintValue, type PrintColumn, resolvePrintTable } from '@nxgt/material/print'; export function PrintCompactList({ columns, rows, locale }: { columns: PrintColumn[]; rows: T[]; locale: string }) { const table = resolvePrintTable(columns, rows); return ( {table.rows.map((cells, index) => ( {cells.map((cell) => formatPrintValue(cell, { locale })).join(' · ')} ))} ); } ``` French amounts from `formatPrintValue` carry a narrow no-break space the PDF fonts lack; replace it as shown in [troubleshooting](../troubleshooting.md#french-amounts-print-with-a-slash-as-in-123450) before printing them in your own `Text`. ## Rendering the document One call turns a document into a file, a download, a new tab or a server response. Each function takes a react-pdf `` element, such as a ``, or a [document model](#documents-as-data): ```tsx import { downloadPdf } from '@nxgt/material/print'; import { Button } from '@nxgt/material/components'; import { InvoiceDocument } from './invoice-document'; import type { Invoice } from './types'; export function DownloadInvoice({ invoice }: { invoice: Invoice }) { return ( ); } ``` | Function | Returns | Where | | --- | --- | --- | | `downloadPdf(doc \| blob, options?)` | `Promise`: the file is saved | browser | | `openPdf(doc \| blob, options?)` | `Promise`: the file opens in a new tab | browser | | `usePdfFile(doc \| null, options?)` | `{ blob, url, loading, error, refresh }` | browser (a React hook) | | `pdfResponse(doc, options?)` | `Promise` with the PDF and its headers | Node 18+, Bun | | `renderPdfBuffer(doc, options?)` | `Promise` | browser, Node 18+, Bun | | `renderPdfBlob(doc, options?)` | `Promise` of type `application/pdf` | browser, Node 18+, Bun | | `renderPdfStream(doc, options?)` | `Promise>` (a Web stream) | Node 18+, Bun | They render outside your React tree, like `pdf()`: give a `PrintDocument` its `language` as a prop (see [Translating built-in strings in a PDF](#translating-built-in-strings-in-a-pdf)). When one fails, the promise rejects with react-pdf's error; `usePdfFile` returns it as `error`. ### In the browser: `downloadPdf` and `openPdf` `downloadPdf` renders the document and saves it; `openPdf` opens it in a new tab, where the browser's own viewer shows it. Call both from a click handler. ```tsx import { downloadPdf, openPdf } from '@nxgt/material/print'; import { Button, ButtonGroup } from '@nxgt/material/components'; import { InvoiceDocument } from './invoice-document'; import type { Invoice } from './types'; export function InvoiceActions({ invoice }: { invoice: Invoice }) { const doc = ; return ( ); } ``` | Option | Type | Default | Effect | | --- | --- | --- | --- | | `fileName` | `string` | `'document.pdf'` | The saved file's name, and the name the tab offers when saving; `.pdf` is added when missing (`'INV-42'` saves `INV-42.pdf`) | | `custom` | `Record` | — | Renderers for a model's custom nodes; see [Custom nodes](#custom-nodes) | - **A `Blob` is saved as it is**, without rendering again: pass the `blob` from `usePdfFile` or `renderPdfBlob`. A `File` keeps its own name when you pass no `fileName`. - **`openPdf` opens the tab first**, before the rendering starts, while the browser still counts the click as the user's; a popup blocker then lets it through. When a blocker stops it all the same, **the file is downloaded instead**. If the rendering fails, the empty tab is closed and the promise rejects. - **Nothing leaks.** The object URL behind a download or a tab is revoked 60 seconds later: long enough for Firefox and Safari, which read it after the click returns. ```tsx // a user action: tell them when it fails async function onDownload() { try { await downloadPdf(, { fileName: invoice.number }); } catch (error) { console.error(error); // or your toast } } ``` ### Showing it before it is saved: `usePdfFile` `usePdfFile` renders the document in the browser and keeps the file current: the `Blob`, an object URL for it, and the loading and error states. Build the element with `useMemo`: a JSX element is a new value on every render, and the hook renders again for every new value. ```tsx import { useMemo } from 'react'; import { PdfReader, Spinner } from '@nxgt/material/components'; import { usePdfFile } from '@nxgt/material/print'; import { InvoiceDocument } from './invoice-document'; import type { Invoice } from './types'; export function InvoicePreview({ invoice }: { invoice: Invoice }) { const doc = useMemo(() => , [invoice]); const { blob, loading, error, refresh } = usePdfFile(doc); if (error) return ; if (loading && !blob) return ; return (
); } ``` | Field | Type | What it is | | --- | --- | --- | | `blob` | `Blob \| null` | The rendered PDF; the previous one stays while a new render runs | | `url` | `string \| null` | An object URL of `blob`, for an `