Migration Guide

This page collects changes between documentation versions. The version selector opens the guide for the API you have installed.

From v1.2.1 to v1.3.0

Version 1.3.0 is published. Existing props remain available. One intentional visual default changes: a watermark with no layer is placed in the foreground. Set layer: 'background' to retain background placement.

The new optional media controls are fonts (TTF or TrueType-outline OTF registration for selectable-text output), svgMode, and autoOptimize (DPI, JPEG quality, transparency and per-export cache settings). Watermark design presets and trusted mounted HTML stamps are also added. Font readiness and chart-canvas snapshots run during export preparation. Canvas and selectable-text rendering have different SVG and background-watermark behavior. Read the media and typography guide and watermark API before changing output settings. No new setting is required for existing consumers.

From v1 (up to 1.1.1) to v2 (1.2.0)

The v1 documentation retains the original direct-prop header and footer examples. Those settings can remain in an older installation. For the current API, group layer options in header and footer objects or provide Vue slots.

<!-- 1.1.1 and earlier -->
<Html2Pdf :inject-header="true" header-text="Quarterly report"
  :inject-footer="true" footer-mode="text" footer-template="Page {n} of {total}">
  <template #pdf-content><article>Report</article></template>
</Html2Pdf>

<!-- 1.2.0 and later -->
<Html2Pdf :header="{ enabled: true, text: 'Quarterly report' }"
  :footer="{ enabled: true, useHtml: false, template: 'Page {n} of {total}' }"
  :manual-pagination="true">
  <template #pdf-content><article>Report</article></template>
</Html2Pdf>

The current component still accepts direct header and footer props. For each corresponding field, an explicitly supplied header or footer object value takes priority; an omitted object value falls back to the direct prop. For example, header: { text: 'New title' } keeps a direct injectHeader setting, while header: { enabled: false } disables the built-in header. A Vue slot activates its layer and owns its visible markup, even when the object sets enabled: false; object height and header pages still apply.

You can keep an existing direct-prop configuration while upgrading. The object API groups new work more clearly, so migrate at your own pace and inspect a generated PDF when you change a header or footer. The v1 guides remain available for projects using the earlier release.

Next: headers, footers, smart pagination, composition, paper formats, and full API reference.