API
KViewer
API reference for the KViewer component
KViewer is the main component for rendering a single PDF document with annotation editing, form fields, and search.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
source | string | Uint8Array | object | required | PDF source: URL string, raw bytes, or pdfjs-dist document init params |
textLayer | boolean | false | Enable text selection overlay and text-based annotation tools |
userName | string | undefined | Author name attached to new annotations |
stamps | StampDefinition[] | undefined | Custom stamp definitions for the stamp tool |
signatureHandlers | SignatureHandlers | undefined | Callbacks for loading, saving, and deleting signatures |
viewMode | ViewMode | 'fit-width' | Initial fit mode: 'fit-width', 'fit-page', or 'fit-height' |
zoom | number | 1 | Initial zoom multiplier (0.25 to 2) |
readonly | boolean | false | Disable all annotation and form editing |
shapeDetection | boolean | false | Auto-detect checkbox shapes and create interactive form fields |
active | boolean | true | Whether this viewer captures global keyboard shortcuts (used internally by KViewerTabs) |
Slots
| Slot | Default | Description |
|---|---|---|
header | Built-in ViewerBar toolbar | Replace the entire top toolbar |
footer | Empty | Add content below the viewer |
Default Header (ViewerBar)
The default header includes: menu (download), page settings (rotation, layout, fullscreen), zoom controls, hand tool, marquee tool, page info, search, tool properties (color, stroke), drawing tools, and action tools (undo/redo/eraser).
Methods
Access these through a template ref:
<template>
<KViewer ref="viewer" :source="pdfUrl" />
</template>
<script setup lang="ts">
const viewer = ref()
</script>
getAnnotations()
Returns all current annotations as a serializable array.
const annotations: IAnnotationStore[] = viewer.value?.getAnnotations()
importAnnotations(annotations, options?)
Restores previously saved annotations.
const result = await viewer.value?.importAnnotations(annotations, {
mode: 'replace', // 'replace' | 'merge'
})
// result: { loaded: number, skipped: number }
| Option | Type | Default | Description |
|---|---|---|---|
mode | 'replace' | 'merge' | 'replace' | replace clears existing annotations first. merge adds alongside existing, skipping collisions. |
exportPdf(options?)
Exports the PDF with annotations as a Uint8Array.
const bytes = await viewer.value?.exportPdf({
flatten: true,
download: false,
preserveOriginalAnnotations: false,
})
See ExportPdfOptions for all options.
getFormFieldValues()
Returns all form field values.
const fields: FormFieldValue[] = viewer.value?.getFormFieldValues()
setFormFieldValue(fieldName, value)
Sets a form field value by field name.
viewer.value?.setFormFieldValue('email', 'user@example.com')
viewer.value?.setFormFieldValue('agree_terms', true)
getKonvaCanvasState()
Returns the raw Konva canvas state for each page (page number to serialized Konva JSON).
const state: Record<number, string> = viewer.value?.getKonvaCanvasState()
Usage Example
pages/editor.vue
<template>
<div class="h-screen">
<KViewer
ref="viewer"
:source="pdfUrl"
text-layer
user-name="Jane Doe"
:stamps="stamps"
:signature-handlers="signatureHandlers"
/>
</div>
</template>
<script setup lang="ts">
const viewer = ref()
const pdfUrl = '/documents/contract.pdf'
const stamps = [
{ id: 'approved', name: 'Approved', imageUrl: '/stamps/approved.svg', width: 48, height: 48 },
]
const signatureHandlers = {
onLoad: () => fetch('/api/signatures').then(r => r.json()),
onSave: (imageUrl: string) => fetch('/api/signatures', {
method: 'POST',
body: JSON.stringify({ imageUrl }),
headers: { 'Content-Type': 'application/json' },
}).then(r => r.json()),
onDelete: (id: string) => fetch(`/api/signatures/${id}`, { method: 'DELETE' }).then(() => {}),
}
</script>