API

Loader, Progress, Metrics, Events & Slots

Build custom vue-pdf-export UI with loaders, progress state, generation metrics, component events and slots for PDF content and user-defined loading experiences.

Built-in loader

<Html2Pdf :show-loader="true" loader-text="Generating PDF..." />

Disable it:

<Html2Pdf :show-loader="false" />

Numeric progress

<Html2Pdf @progress="onProgress" />

function onProgress(value: number) {
  console.log(value)
}

This is generation-stage progress, not byte-level network progress.

Rich progress stages

<Html2Pdf @progress-stage="onProgressStage" />

import type { PdfProgressState } from 'vue-pdf-export'

function onProgressStage(state: PdfProgressState) {
  console.log(state.stage, state.progress)
}

Current stages:

idle
pagination
images
preparing
rendering
watermark
header
footer
metadata
serializing
complete
error

Generation metrics

Metrics are opt-in. When disabled, metrics collection does not add generation work.

<Html2Pdf
  :collect-metrics="true"
  @generation-complete="onGenerationComplete"
/>

import type { PdfGenerationCompletePayload } from 'vue-pdf-export'

function onGenerationComplete(payload: PdfGenerationCompletePayload) {
  console.log(payload.metrics)
}

A completed generation can expose total generation time, stage timings, per-page timings, render mode, page count, and generated Blob size.

interface GeneratePdfResult {
  pdf: jsPDF
  blob: Blob
  url: string
  metrics?: PdfGenerationMetrics
}

Use timing data for profiling and regression checks rather than as a hard real-time performance guarantee.

Custom loader

<Html2Pdf>
  <template #loader="{ progress, loading, stage, progressState }">
    <div v-if="loading">
      {{ stage }} - {{ progress }}%
    </div>
  </template>
</Html2Pdf>

Slot values:

Value	Type
`progress`	`number`
`loading`	`boolean`
`stage`	`PdfProgressStage`
`progressState`	`PdfProgressState`

Events

<Html2Pdf
  @progress="onProgress"
  @progress-stage="onProgressStage"
  @generation-complete="onGenerationComplete"
  @startPagination="onStartPagination"
  @hasPaginated="onPaginated"
  @beforeDownload="onBeforeDownload"
  @hasDownloaded="onDownloaded"
  @closed="onClosed"
  @error="onError"
/>

Event	Payload	Description
`progress`	`number`	Numeric generation progress.
`progressStage` / `@progress-stage`	`PdfProgressState`	Named stage and progress.
`generationComplete` / `@generation-complete`	`PdfGenerationCompletePayload`	Generation finished; includes opt-in metrics when enabled.
`startPagination`	none	Pagination started.
`hasPaginated`	none	Pagination completed.
`beforeDownload`	`BeforeDownloadPayload`	Emitted before generation.
`hasDownloaded`	`Blob`	Generated Blob is available.
`closed`	none	Preview/generation flow closed.
`error`	`Error`	Generation or print error.
`paginationBreak` / `@pagination-break`	`PdfPaginationDiagnostic`	A planned break; emitted with `paginationDebug`.
`paginationWarning` / `@pagination-warning`	`PdfPaginationDiagnostic`	An oversized or other planning warning; debug only.
`paginationComplete` / `@pagination-complete`	`PdfPaginationDiagnostic[]`	All decisions for this planning pass; debug only.

Slots

Slot	Required	Description
`pdf-content`	yes	HTML converted to PDF.
`loader`	no	Custom loader with `{ progress, loading, stage, progressState }`.
`pdf-header`	no	Vue markup for each targeted header page; `{ pageNumber, totalPages, orientation }`.
`pdf-footer`	no	Vue markup for each generated footer page; same context.

The layer slots activate their layers, own visible content and render differently in Canvas versus text mode. Give the slot root full width and explicit padding. header.height, header.pages and footer.height still apply. See copyable header and footer examples, and pagination diagnostics.

Programmatic API

Use vue-pdf-export programmatically to generate Blob, ArrayBuffer and Base64 output, print PDFs, close previews, reset pagination and cancel generation.

TypeScript

Use the TypeScript declarations and public types shipped by vue-pdf-export for PDF outputs, component options, events, headers, footers and watermark configuration.