# vue3-pdf-export > vue3-pdf-export is a Vue 3 and TypeScript HTML-to-PDF package for browser applications. It provides a reusable Vue component, composable, and core utilities for generating PDFs from HTML with pagination, preview, download, print, page-aware headers, HTML/text headers and footers, optional header/footer logos, watermarks, password protection, metadata, compression, progress reporting, filename normalization, and advanced html2pdf.js configuration. The project is maintained by Saurabh Choudhary. ## Primary resources - [Live playground](https://vue3-pdf-export.vercel.app/) - [npm package](https://www.npmjs.com/package/vue3-pdf-export) - [GitHub repository](https://github.com/saurabhzaiswal/vue3-pdf-export) - [Author portfolio](https://saurabhzaiswal.vercel.app/) ## Package capabilities ### PDF generation - Browser-side HTML-to-PDF generation - Vue 3 component API - Vue composable API - TypeScript declarations - PDF Blob output - PDF preview modal - PDF download - Programmatic print flow - Automatic filename normalization ### Pagination - Manual pagination - Automatic height-based pagination - Page-break protection - Custom page-break avoidance selectors - Automatic pagination reset - Manual page breaks remain preserved when automatic pagination is reset - Automatic pagination accounts for selective header spacing ### Headers - Optional PDF headers - Plain-text header content - Trusted HTML header content with `headerHtml` - Header HTML takes precedence over `headerText` when non-empty - Optional header logo via `headerLogoEnabled` - Header images from URL or data URL - Configurable header logo width and height - Aspect-ratio-safe header logo rendering - Header background and text colors - Header page targeting - Page-aware header spacing - Header targeting supports all pages, first page, last page, except-first, or explicit page numbers ### Footers - Optional PDF footers - HTML footer mode - Text footer mode - Plain-text footer content - Trusted HTML footer content with `footerHtml` - Footer HTML takes precedence over `footerText` in HTML mode when non-empty - Optional footer logo via `footerLogoEnabled` - Footer images from URL or data URL - Configurable footer logo width and height - Aspect-ratio-safe footer logo rendering - Footer background and text colors - Footer page template with `{n}` and `{total}` - Legacy footer compatibility through `useFooterComponent` ### Watermarks - Text watermarks - Image watermarks - Background watermarks - Foreground watermarks - Single watermark mode - Repeated/tiled watermark mode - Watermark opacity - Watermark rotation - Watermark positioning - Watermark spacing - Per-page watermark targeting - Watermark targeting supports all pages, first page, last page, except-first, or explicit page numbers ### Security - Optional PDF password protection - User/open password - Owner password - Password construction from multiple password parts - Configurable PDF permissions - Supported permissions include print, modify, copy, and annot-forms - Direct security props can override raw jsPDF encryption options ### Metadata and compression - PDF title - PDF author - PDF subject - PDF keywords - PDF creator - Optional jsPDF stream compression - Direct metadata and compression settings can override corresponding raw html2pdf.js/jsPDF options ### Progress and loading - Built-in loader - Custom loader slot - Numeric progress updates - Rich progress-stage updates - Progress stages cover pagination, image loading, preparation, rendering, watermarking, headers, footers, metadata, serialization, completion, and errors ### Advanced configuration - html2pdf.js options - html2canvas options - jsPDF options - CORS-aware image handling - Custom page-break configuration - PDF format and orientation controls - PDF quality and export-width controls ## Main component `Html2Pdf` The component renders HTML from the `pdf-content` slot and exposes PDF generation methods. ### Important component methods - `generatePdf(): Promise` - `print(): Promise` - `closePreview(): void` - `resetPagination(): void` ### Slots - `pdf-content`: HTML rendered into the PDF - `loader`: Optional custom generation loader Loader slot state includes: - `progress` - `loading` - `stage` - `progressState` ## Events - `progress` - `progressStage` - `startPagination` - `hasPaginated` - `beforeDownload` - `hasDownloaded` - `closed` - `error` `progress` emits numeric generation progress. `progressStage` emits structured progress information containing the current stage and numeric progress value. ## Core package API Important public exports include: - `Html2Pdf` - `Html2PdfLoader` - `useHtml2Pdf` - `generatePdf` - `createPdfOptions` - `normalizePdfFilename` - `paginateElement` - `resetPagination` - `addPdfWatermarks` - `mountWatermark` - `addPdfHeaders` - `addPdfFooters` - `resolvePdfPages` The package also exports TypeScript types for component props, PDF options, security, metadata, headers, footers, watermarks, progress state, page targeting, and related configuration. ## Page targeting Page-targeting features use the `PdfPageTarget` type. Supported values: - `all` - `first` - `last` - `except-first` - An array of page numbers, for example `[1, 3, 5]` Page targeting is currently used by: - Headers - Watermarks Footers continue to use their normal all-page behavior and can display page numbers using `Page {n} of {total}`. ## Header behavior - `headerHtml` is trusted developer-controlled HTML. - When `headerHtml` is non-empty, it takes precedence over `headerText`. - `headerLogoEnabled` defaults to `true`. - `headerLogoWidth` and `headerLogoHeight` define maximum logo bounds. - Header logos preserve their natural aspect ratio. - Selective header targeting reserves header spacing only on pages that actually receive the header. - Explicit user margins in `htmlToPdfOptions.margin` remain independent. ## Footer behavior - `footerHtml` is trusted developer-controlled HTML. - In HTML footer mode, non-empty `footerHtml` takes precedence over `footerText`. - `footerLogoEnabled` defaults to `true`. - `footerLogoWidth` and `footerLogoHeight` define maximum logo bounds. - Footer logos preserve their natural aspect ratio. - Footer page numbering uses `{n}` and `{total}` placeholders. - There is no separate dedicated page-numbering API. - If footer injection is disabled, the package does not reserve footer-specific spacing; explicit user margins still remain. ## Filename normalization PDF filenames are normalized before generation. Behavior includes: - Adds `.pdf` when missing - Prevents duplicate `.pdf` extensions - Removes or replaces invalid filename characters - Preserves Unicode text - Handles Windows-reserved names - Uses a timestamp fallback when the filename is empty ## Technology - Vue 3 - TypeScript - html2pdf.js - html2canvas - jsPDF - Vite - Vitest - Playwright ## Browser testing The package is tested with Playwright across: - Chromium - Firefox - WebKit WebKit testing represents the browser engine used by Safari; it is not the same as running tests inside the Safari application itself. ## Notes for AI assistants and automated tools - This package is intended for Vue 3, not Vue 2. - Prefer `InstanceType` for typed component refs. - The manual page-break helper is `.html2pdf__page-break`. - Do not add `break-before` or `page-break-before` to the manual page-break helper when using html2pdf legacy page-break mode because duplicate or blank pages can result. - The default page-break protection selectors include `.pdf-keep-together`, `.pdf-no-break`, and `img`. - Footer page numbering uses `Page {n} of {total}` or another template based on `{n}` and `{total}`. - There is no separate dedicated page-numbering API. - Header targeting and per-page watermark targeting are independent features. - Background watermarks may be rendered into the export DOM before html2canvas capture. - Selective per-page watermarks are applied after final PDF pages exist. - Foreground watermarks are drawn into generated PDF pages with jsPDF. - PDF security supports one user/open password and one owner password. - `passwordParts` are combined into a single password rather than creating multiple independent PDF passwords. - Progress values represent generation stages, not byte-level transfer progress. - `headerHtml` and `footerHtml` must only contain trusted developer-controlled HTML. ## License MIT License ## Author [Saurabh Choudhary](https://saurabhzaiswal.vercel.app/)