---
name: jspdf-pdf-export
description: Generate, download, print, and export multi-page PDFs as images in Vite/React/TypeScript apps using jsPDF + pdfjs-dist — PDF construction, page-break logic, and PNG conversion.
---

# jsPDF PDF Export

Generate professional multi-page PDFs (quotes, invoices, repair orders) and optionally export every page as a separate PNG image.

## When to Load

- Building a PDF generator with jsPDF in a Vite/React/TypeScript app
- Adding "Download PDF", "Print", or "Export as Images" buttons
- Converting PDF pages to PNG images client-side
- Setting up pdfjs-dist in a Vite environment

## Key Techniques

### 1. Multi-Page PDF Construction (jsPDF)

**Page units**: Use `'pt'` (points) for pixel-precise layout. Letter = 612×792 pt.

```typescript
const doc = new jsPDF('p', 'pt', 'letter');
const PAGE_W = 612, PAGE_H = 792, MARGIN = 40;
const CW = PAGE_W - MARGIN * 2;  // content width
const CONTENT_BOTTOM = PAGE_H - MARGIN;
```

**Page-break logic** — measure content height before drawing, add a new page if it won't fit:

```typescript
function newPage(doc: jsPDF, currentY: number): number {
  doc.addPage();
  return MARGIN;  // reset Y to top of new page
}

// Before drawing a block, check:
if (y + estimatedBlockHeight > CONTENT_BOTTOM - FOOTER_HEIGHT) {
  y = newPage(doc, y);
  // Redraw section header if needed
}
```

**Footers** — draw on every page via `drawFooter()`, using `doc.setPage(pageNum)` to target each one. The `doc.getNumberOfPages()` call at the end tells you the total.

**Footer layout** — structure the footer area with clear vertical zones. Define a `FOOTER_HEIGHT` constant that accommodates all elements plus inter-line gaps; values between 45–55pt work for most layouts. Content page-break guards check `CONTENT_BOTTOM - FOOTER_HEIGHT`, so the footer zone starts at that boundary:

```
y = PAGE_H - MARGIN - FOOTER_HEIGHT    (footer zone begins, e.g. 702pt on letter)
  ┌─ Payment terms      (y ≈ +4)    — last page only, right-aligned
  ├─ Separator line      (y ≈ +12)
  ├─ Footer message      (y ≈ +27)   — centered
  ├─ Quote note / expiry  (y ≈ +39)  — centered
  └─ Page number         (y = PAGE_H - 10)
```

Example setup:
```typescript
const CONTENT_BOTTOM = PAGE_H - MARGIN; // 752
const FOOTER_HEIGHT = 50;               // reserved for all footer elements
// Content page-break threshold: CONTENT_BOTTOM - FOOTER_HEIGHT (702)
```

**Payment terms in footer** — render on the **last page only**, right-aligned, above the separator. This keeps them visible regardless of content page count:

```typescript
if (pageNum === totalPages && settings.paymentTerms) {
  const label = 'Payment Terms: ';
  const full = label + settings.paymentTerms;
  const py = PAGE_H - MARGIN - FOOTER_HEIGHT + 4;
  doc.setTextColor(...MG); doc.setFont('helvetica', 'normal'); doc.setFontSize(9);
  doc.text(full, PAGE_W - MARGIN, py, { align: 'right' });
}
```

### 2. PDF → PNG Conversion (pdfjs-dist)

**Install**:
```bash
npm install pdfjs-dist
```

**Worker configuration** in your app entry point (`main.tsx`):
```typescript
import * as pdfjsLib from 'pdfjs-dist';
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.mjs',
  import.meta.url,
).toString();
```

**Dual-input pattern** — accept either a `jsPDF` instance or a `Blob` in the image-export function, so callers can pass the result of `generateQuotePDF()` (which returns a Blob) without rebuilding the doc:

```typescript
export async function downloadPdfAsImages(
  pdfInput: jsPDF | Blob,
  customerName: string,
): Promise<void> {
  let arrayBuffer: ArrayBuffer;
  if (pdfInput instanceof Blob) {
    arrayBuffer = await pdfInput.arrayBuffer();
  } else {
    arrayBuffer = pdfInput.output('arraybuffer');
  }

  const pdf = await pdfjsLib.getDocument({ data: arrayBuffer }).promise;

  for (let pageNum = 1; pageNum <= pdf.numPages; pageNum++) {
    const page = await pdf.getPage(pageNum);
    const viewport = page.getViewport({ scale: 2 });  // 2× for Retina

    const canvas = document.createElement('canvas');
    canvas.width = viewport.width;
    canvas.height = viewport.height;
    const ctx = canvas.getContext('2d')!;

    await page.render({ canvasContext: ctx, viewport }).promise;

    const blob = await new Promise<Blob>(resolve =>
      canvas.toBlob(b => resolve(b!), 'image/png'),
    );

    // Trigger download
    const fileName = `${customerName.replace(/\s+/g, '_')}_Page${pageNum}.png`;
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url; a.download = fileName;
    document.body.appendChild(a); a.click();
    document.body.removeChild(a);
    URL.revokeObjectURL(url);
    page.cleanup();
  }
}
```

### 3. UI Integration

Import the functions and add a button that generates the PDF in-memory then calls the image export:

```typescript
import { downloadQuotePDF, printQuotePDF, generateQuotePDF } from '../lib/pdf';
import { downloadPdfAsImages } from '../lib/pdf-to-images';
import { Image } from 'lucide-react';

const handlePdf = async (mode: 'download' | 'print' | 'images') => {
  setGenerating(true);
  try {
    if (mode === 'download') await downloadQuotePDF(quote, settings);
    else if (mode === 'print') await printQuotePDF(quote, settings);
    else {
      const blob = await generateQuotePDF(quote, settings);
      await downloadPdfAsImages(blob, customerInfo.name);
    }
  } finally {
    setGenerating(false);
  }
};

<button onClick={() => handlePdf('images')} disabled={generating}>
  <Image className="h-4 w-4" /> Export as Images
</button>
```

### 4. Settings-Aware PDF Customization

When your PDF quote generator reads from a `ShopSettings` object, use these patterns:

**Hex color for accents** — parse user-chosen hex colors safely:

```typescript
type ColorTuple = [number, number, number];

function hexToRgb(hex: string): ColorTuple {
  if (!/^#[0-9a-fA-F]{6}$/.test(hex)) return [22, 163, 74]; // fallback green
  const c = hex.replace('#', '');
  const r = parseInt(c.substring(0, 2), 16);
  const g = parseInt(c.substring(2, 4), 16);
  const b = parseInt(c.substring(4, 6), 16);
  if (isNaN(r) || isNaN(g) || isNaN(b)) return [22, 163, 74];
  return [r, g, b];
}

// Usage:
const ACCENT = settings.pdfAccentColor ? hexToRgb(settings.pdfAccentColor) : GR;
// Then use ACCENT wherever you'd use the hardcoded accent color
```

**Dynamic expiry in footer** — use a `{days}` placeholder so settings override works naturally:

```typescript
const qfn = (settings.quoteFooterNote || 'This quote is valid for {days} days from the date above.')
  .replace('{days}', String(settings.quoteExpiryDays || 30));
```

**Custom tax label** — pass through from settings:

```typescript
doc.text(settings.taxLabel || 'Tax', sumX, y);
```

**Payment terms** — render in the footer on the last page only (see "Footer layout" above for the recommended pattern). Avoid rendering payment terms inline after the pricing summary — that position is vulnerable to page-break boundary overlap and won't survive multi-page documents.

**Logo on page 1** — render from a base64 data-URL when configured:

```typescript
if (settings.logoUrl && settings.showLogoOnPdf) {
  doc.addImage(settings.logoUrl, 'PNG', MARGIN, y, 50, 20);
  y += 24; // image height + gap
}
```

**Corollary: DEFAULT_SETTINGS must include `{days}` in the default footer note.** If the default `quoteFooterNote` doesn't contain `{days}`, the expiry feature silently does nothing for users who never customize the footer. Always set:
```typescript
quoteFooterNote: 'This quote is valid for {days} days from the date above.',
```

### 5. PDF Construction Helpers

For professional-looking PDFs:

- **Color constants** as tuples: `type ColorTuple = [number, number, number];`
- **Footer**: separator line + message + page number (`Page X of Y`)
- **Rounded rectangles**: `doc.roundedRect(x, y, w, h, r, r, 'FD')` for fill + stroke
- **Text wrapping**: `doc.splitTextToSize(text, maxWidth)` returns an array of lines
- **Dynamic import for code-splitting**: Use static imports when the module is already pulled in by other exports (prevents Vite's `INEFFECTIVE_DYNAMIC_IMPORT` warning)

### Multi-Layer Data Flow (UI vs PDF Discrepancy)

When the same computed values (totals, subtotals, taxes) appear in both the **UI component** and the **PDF generator**, they often have **independent computation paths** through different helper functions. This creates a class of bug: the UI shows correct numbers but the PDF shows different ones, or vice versa.

**Root cause pattern:** UI components call helper A (e.g. `computeQuoteTotals` → `billableServices`), while the PDF generator has its own inline computation or calls the same helper through a different chain. If the helper has context-sensitive filtering (e.g., filters out pending services when mixed), the PDF and UI can diverge without any explicit bug in either.

**Fix pattern — extract shared computation:**

1. Identify the exact computation both layers need (e.g., "total of all non-declined services with discount")
2. Create a dedicated helper function in a **shared lib module** that both the UI and the PDF import
3. Give the helper a name that describes the *specific view* it computes, not a generic one — e.g. `computeCombinedTotals` or `computeSplitQuoteTotals`, not a modified `computeQuoteTotals`
4. Bypass intermediate filtering functions in the shared helper when they'd suppress data the other layer needs

```typescript
// BAD: UI calls computeQuoteTotals → billableServices (filters out pending when mixed)
// PDF calls computeQuoteTotals → billableServices (same filter, same wrong result for "if all approved")

// GOOD: dedicated helper that computes on all non-declined services
export function computeCombinedTotals(services, discount, settings) {
  const allNonDeclined = services.filter(s => s.customerDecision !== 'declined');
  // ... compute totals directly, no billableServices filter ...
}
```

**Verification:** Generate a PDF with mixed-status services and compare the numbers against the UI display. If they differ, trace the computation chain in each layer — they're almost certainly diverging at a filter function.

### Filter-Context Pitfall (billableServices Pattern)

A filtering function that's correct for one presentation context can silently break a different one:

- **Customer-facing quote**: Only show totals for what the customer has already approved → filter out pending services ✅
- **Internal "what if" estimate**: Show what everything would cost if approved → include ALL non-declined services

**Fix:** Don't reuse the filtered result variable (`servicesTotal` computed from `billableIds`) for the "what if" view. Compute the combined total separately with a purpose-built function that doesn't share the filter context. Use `computeSplitQuoteTotals()` to get approved, pending, and combined breakdowns from a single call.

### Dynamic Pricing Summary Layout

When the PDF pricing summary needs to show different layouts based on data (split totals for mixed-status services vs simple totals for uniform services):

1. **Compute all values first** using a shared helper, before any drawing
2. **Test for the layout condition** (e.g., `hasMixed = approved && pending services exist`)
3. **Render conditionally** — one branch for the full split layout, another for the simple layout
4. **Account for row count** in page-break height calculations — the split layout is significantly taller

```typescript
// Compute upfront
let sumRows = 0;
if (hasMixed) {
  sumRows += 4 + 4 + 1; // approved + pending + combined sections
  if (discount > 0) sumRows++;
  sumRows += 2; // separator + grand total
} else {
  sumRows = 1; // subtotal
  if (discount > 0) sumRows++;
  if (shopCharge > 0) sumRows++;
  if (tax > 0) sumRows++;
  sumRows += 2; // separator + total
}
const sumTotalH = bp + (sumRows * lineHeight + padding) + bp;
// Use sumTotalH for page-break check and rect sizing
```

### Content Overflow Past the Page-Break Threshold

Every block drawn after the pricing summary — shop charge explanation, travel fee note, warranty disclaimer — must have its own page-break guard. Unguarded text can extend `y` past `CONTENT_BOTTOM - FOOTER_HEIGHT` and overlap the footer zone. Even though `drawFooter()` redraws on top, the overlap causes visual artifacts. The pattern: measure the block before drawing, add a page if it won't fit before the footer zone.

### FOOTER_HEIGHT Too Small

If `FOOTER_HEIGHT < 35pt` on a letter page, payment terms position at `PAGE_H - MARGIN - FOOTER_HEIGHT - 2` falls inside the content zone rather than the footer zone, making it vulnerable to content overlap. Always set `FOOTER_HEIGHT` to the tallest possible footer stack plus a few points of breathing room (45–55pt).

## Pitfalls (legacy — consolidated above)

- **pdfjs-dist worker**: If `GlobalWorkerOptions.workerSrc` isn't set, pdf.js blocks the main thread on each `getDocument()`. The `new URL(..., import.meta.url)` Vite pattern copies the worker as a static asset.
- **canvas.toBlob null**: Usually means the canvas was tainted by cross-origin data. In pdfjs this shouldn't happen since we're rendering from a same-origin ArrayBuffer.
- **Font selection**: jsPDF's built-in fonts are limited. For extended character sets (VINs with special chars, non-Latin text), use `doc.addFileToVFS()` and `doc.addFont()` to embed custom fonts.
- **Page number discrepancy**: `doc.getNumberOfPages()` must be called AFTER all content is written. Footer loops should happen last.
- **Content overflow past the page-break threshold**: Every block drawn after the pricing summary — shop charge explanation, travel fee note, warranty disclaimer — must have its own page-break guard. Unguarded text can extend `y` past `CONTENT_BOTTOM - FOOTER_HEIGHT` and overlap the footer zone. Even though `drawFooter()` redraws on top, the overlap causes visual artifacts. The pattern: measure the block before drawing, add a page if it won't fit before the footer zone.
- **FOOTER_HEIGHT too small**: If `FOOTER_HEIGHT < 35pt` on a letter page, payment terms position at `PAGE_H - MARGIN - FOOTER_HEIGHT - 2` falls inside the content zone rather than the footer zone, making it vulnerable to content overlap. Always set `FOOTER_HEIGHT` to the tallest possible footer stack plus a few points of breathing room (45–55pt).

## Verification

1. Build: `npx tsc --noEmit && npx vite build`
2. Check console for `INEFFECTIVE_DYNAMIC_IMPORT` warnings — prefer static imports
3. In the browser, verify download triggers N files for N pages

## Reference Files

- `references/pdf-to-images-full-code.md` — The complete `downloadPdfAsImages` implementation with full JSDoc, error handling, and memory cleanup.