Client Document Export

Libraries

npm install html-to-image jspdf

PNG capture (html-to-image)

import { toPng } from "html-to-image";

export async function captureElement(el: HTMLElement): Promise<string> {
  return toPng(el, {
    pixelRatio: 2,
    cacheBust: true,
    width: resolveExportWidth(el),
    style: { overflow: "visible" },
  });
}

Width strategy

const EXPORT_MIN = 1280;
const EXPORT_MAX = 1440;

function resolveExportWidth(el: HTMLElement): number {
  const measured = Math.ceil(el.scrollWidth);
  return Math.min(EXPORT_MAX, Math.max(EXPORT_MIN, measured));
}

Prevents clipped desktop layouts and oversized mobile captures.

Scroll / overflow fixes

Before capture, temporarily flatten scroll containers:

1. Query all descendants with overflow: auto|scroll|hidden or max-height
2. Set overflow: visible, maxHeight: none, expand height to scrollHeight
3. Restore styles in finally block

Also wait two animation frames before capture:

await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));

Export mode CSS

Add a data attribute during capture for layout overrides:

<div data-export="true" ref={ref}>...</div>

[data-export="true"] .scroll-area { overflow: visible !important; max-height: none !important; }
[data-export="true"] .responsive-stack { flex-direction: column !important; }
[data-export="true"] .hide-on-export { display: none !important; }

Hide interactive controls (buttons, tooltips) during export.

Download trigger

function downloadDataUrl(dataUrl: string, filename: string) {
  const a = document.createElement("a");
  a.href = dataUrl;
  a.download = filename;
  a.click();
}

Filename: {app-slug}-{date}.png.

PDF generation (jsPDF)

Two approaches:

A. From PNG (simple, WYSIWYG)

const png = await captureElement(el);
const pdf = new jsPDF({ orientation: "portrait", unit: "px", format: [width, height] });
pdf.addImage(png, "PNG", 0, 0, width, height);
const blob = pdf.output("blob");

B. Programmatic (smaller files, multi-page)

Build PDF from data structures — better for long reports, worse for styled dashboards.

Email PDF attachment

Client generates PDF → base64 → POST to API route → Resend attachment.

const base64 = pdf.output("datauristring").split(",")[1];
await fetch("/api/send-report", {
  method: "POST",
  body: JSON.stringify({ toEmail, pdfBase64: base64, filename }),
});

For large PDFs, generate server-side instead.

UX checklist

- [ ] Loading spinner during capture (can take 1–3s)
- [ ] Disable export button while running
- [ ] Track analytics: export_start, export_success, export_error
- [ ] Toast on failure with retry
- [ ] Test with charts (Recharts SVG), custom fonts, dark backgrounds

Known issues

Print alternative

For simple cases, @media print CSS + window.print() may suffice without libraries. Use export libs when users need shareable files.

Server-side alternative

When client capture quality/size is insufficient, generate PDF on the server with Playwright — see server-pdf-playwright. Keep client jsPDF as fallback when server route returns 503.

Anti-patterns

• Screenshot via html2canvas when html-to-image is already in stack
• Capturing document.body instead of scoped dashboard root
• Forgetting to restore DOM styles after failed capture (use try/finally)