Troubleshooting

Selectable text is not pixel-identical to the browser

Use render-mode="canvas" for maximum CSS fidelity.

Selectable-text mode intentionally prioritizes real PDF text and vector output.

Link looks like text but is not clickable

Make sure links are enabled:

const htmlToPdfOptions = {
  enableLinks: true,
}

Also verify the source element is a real anchor with a valid href.

Link text looks stretched

Reduce large letter-spacing, transforms, and tight fixed widths in selectable-text mode.

Logo looks stretched

Header/footer logo dimensions are maximum bounds and preserve the source aspect ratio.

For normal content images:

img {
  width: auto;
  height: auto;
  max-width: 100%;
  object-fit: contain;
}

Header/footer overlaps content

Increase headerHeight / footerHeight, or reduce content size.

For selectively targeted headers, only target pages receive the extra header space. If excluded pages still have top spacing, check explicit htmlToPdfOptions.margin.

Header or footer image is missing

Check:

• URL accessibility
• CORS
• data URL validity
• headerLogoEnabled
• footerLogoEnabled

For v1.3.0, a large source logo displayed at a small size is capped to a proportional raster size during selectable-text header/footer preparation. The source file and caller options remain unchanged.

HTML header/footer is not visible

Check that:

• related header/footer is enabled
• HTML string is non-empty
• footer uses footer-mode="html"
• content fits inside configured height

Blank page around a manual break

Use only:

.html2pdf__page-break {
  display: block;
  height: 0;
  clear: both;
}

Do not add break-before or page-break-before to the same helper.

Background watermark is hidden

Opaque PDF content can cover a DOM background watermark.

In v1.3.0, selectable-text mode draws a requested background watermark behind PDF content; opaque cards can cover it. Canvas pages are opaque images, so a requested background mark uses a light foreground fallback. Choose an explicit layer and inspect both renderers. An omitted layer defaults to foreground in v1.3.0.

PDF is blurry

In canvas mode, increase pdfQuality or htmlToPdfOptions.html2canvas.scale carefully.

Selectable-text body text remains vector text and does not depend on html2canvas resolution.

Large document generation is slow

Reduce:

• canvas scale where relevant
• image dimensions
• document complexity
• simultaneous PDF generation

Large encrypted Canvas PDFs can show substantially higher memory retention than unencrypted Canvas PDFs in Chromium. Raw jsPDF-only isolation reproduced the same encrypted-raster retention pattern outside the Vue lifecycle, so this is tracked as an upstream/dependency concern rather than described as a confirmed permanent Vue memory leak. Selectable-text mode did not show the same severe raster-memory pattern in the package benchmarks.

A header or footer is empty after upgrading

The component accepts direct props. An explicitly set field in a header or footer object takes priority, while omitted fields fall back to the matching direct prop. Check the enabled flag, slot content, object precedence and page targeting using the migration mapping.

Table heading repeats twice, or a row crosses a page cut

Use one semantic <thead> and normal <tbody> rows. Avoid manually duplicated headings. Try smart pagination and its diagnostic overlay. Large rowspans, oversized rows and unusual CSS need manual review in both renderers.

Canvas PDF appears to have selectable text

Chrome can OCR page images. Foreground text watermarks or some numbering paths may also add native text. Inspect extracted PDF text or text-showing operators rather than relying only on mouse selection. Use render-mode="text" for native selectable body text.