pdfOptions & printOptions explained

pdfOptions.paperFormat — layout stage

Allowed values

Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 (default A4).

Use width + height (px / in / cm / mm) instead—mutually exclusive with paperFormat. 80mm receipts, 100×60mm labels, etc.

printOptions.paperFormat — print stage

Allowed values

Built-in: A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledger, Statement (current printer’s default paper). Stock not in the list (thermal, labels, etc.)—see Scenario 2 below: use getPrinterPapers for that printer’s name; do not invent names.

const printers = await webPrintPdf.utils.getPrinterList();
const target = printers.find(p => p.isDefault) || printers[0];
const papers = await webPrintPdf.utils.getPrinterPapers(target);
// papers[].name → printOptions.paperFormat
console.log(papers.map(p => p.name));

How to pair both sides

Scenario 1: office paper. These names exist on both sides—use the same string: A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledger. Example: pdfOptions.paperFormat: 'A4', printOptions.paperFormat: 'A4' (use Letter the same way in North America). Never mix pdf A4 with print Letter—physical sizes differ and content may clip.

Scenario 2: receipts, labels, custom stock. pdf uses width + height (e.g. 80mm) and omits pdfOptions.paperFormat. print should usually set paperFormat too: call getPrinterPapers on the target printer and pick the name whose physical size matches pdf (e.g. 80mm Series); strings may differ. Use action: 'preview' to verify before printing.

// pdf side: 80mm receipt — omit paperFormat
const pdfOptions = { width: '80mm', height: '200mm', margin: { top: '0', bottom: '0', left: '0', right: '0' } };

// print side: pick a driver paper name that matches physical size
const papers = await webPrintPdf.utils.getPrinterPapers('Thermal printer');
const printOptions = {
  printerName: 'Thermal printer',
  paperFormat: papers.find(p => p.name.includes('80'))?.name ?? papers[0].name
  // When you know the exact name: paperFormat: '80mm Series'
};

Also note: A0, A1 are pdf-only—on print, use getPrinterPapers for the closest stock; Statement is print-only—do not use on pdf (use Letter or width/height). Re-query paper names when the printer changes.

Default rules